ShulCloud Mobile Payments App v1.0 - Preliminary Documentation

Introduction

ShulCloud Mobile Payments empowers ShulCloud clients in the USA to swiftly and effortlessly gather and record both online (credit card) and offline (cash, paper check) payments via mobile devices. A ShulCloud Integrated Payments merchant account is required. Payments are seamlessly recorded in ShulCloud. Credit card details may originate from the payer's ShulCloud account or a card presented in person (read using Tap to Pay or the Stripe Reader M2, or entered manually). Additionally, 'Bill to Account' is available if desired. Clients can choose how to manage payments from non-account holders, if permissible (create a new account, allocate to a catch-all account, or generate a standard 'public payment' in ShulCloud). Optionally, clients can gather payer information such as name and address for lead generation purposes. Additionally, clients can decide whether to collect an optional or mandatory payment processing fee. Finally, clients can create a team of ordinary ShulCloud users empowered to collect payments at specific events, without the need to assign permissions or grant broader data access.

Getting Started

Download the App

ShulCloud Mobile Payments is available for iOS and Android phones and tablets:

Web App Permission Setup

To create a mobile payment event or to administer all mobile payment events, you need a new permission:

IMPORTANT: Only the master admin starts with it, meaning only the master admin can assign it at first (in ShulCloud, even if you have the "Permissions" permission, you can't assign to others what you don't have yourself.)

While on the topic of permissions, anyone in your organization with family login permission and password can log into this app. They will only see active events to which they have been added by a mobile event admin as a Team Member, if any. A Team Member can also be made admin of the specific event. This approach is similar to how on the web app a forms admin can allow a person to administer a specific form without having the full forms permission. 

Logging In

To log into the app, you need to provide:

1. ShulCloud URL (the URL you use to access ShulCloud, not necessarily xyz.shulcloud.com)
2. ShulCloud login name
3. ShulCloud login password

At this time, site MFA settings are not followed when logging into the app.

Initial App Setup

Please complete a one-time payment type mapping that will apply to all app users and all mobile payment events in your organization. This includes mappings for avenues not yet supported but in the works, as mentioned above.

Tap the hamburger menu top left (three horizontal lines) to open the side menu Tap Settings Tap Payment Type Mappings Choose a payment type for each mode Tap Save This is information will be used by the app when creating payment transactions.  As you will see in a few other instances, this app will use the gateway you choose, but some settings in the mobile event will be used instead of the gateway's settings. That goes for these global settings.  NOTE: Bank Account / eCheck payments via the app not yet available.

List Views

Events Dashboard

After logging in, the user will see a listing of active events - the Events Dashboard (status is based on the event date/time as described further below). How it looks depends on what admin permissions the user has, if any. An admin with the web-assigned permission will see bottom navigation buttons used to switch between the Events Dashboard and the Administration Dashboard.

Web-Permission Admin Select button Edit Event button Dashboard button Administration button	Event Admin Team Member Select button Edit Event button	Regular Team Member Select button

 

Events Admin

Only an admin with the web-assigned mobile payments app permission can access the Events Administration view and see the bottom navigation buttons. Event-specific admins see and can edit only active events.   The Administration view header has these features: A + button, top right, to create a mobile payment event A search bar to search existing mobile payment events by name A filter button to filter mobile payment events by date and/or status (draft/active/upcoming/past) For each listed event, the admin has two button actions: Duplicate Edit Settings

Event Settings

Overview

Event Settings fall into five categories:

General	Event name, date time, default transaction memo, instructions to team
Checkout	Gateway, fee settings, payment methods allowed
Guest Checkout	Whether public payments are allowed, how they are handled, data collected
Tiles	Items to be purchased, donations to be collected
Event Team	Who besides full admins can see, work, and optionally admin the event

When you create a mobile payment event, you first complete the General settings. On save, you are taken to the Events Settings menu featuring the above five areas. Some areas are required in order for an event to be active and worked by users. Until those areas have been saved for a first time, they are called out on the Event Settings Menu and status remains DRAFT even if the current date/time mean it would otherwise be ACTIVE.

General Settings

Event name is visible to users End date/time must be after Start date/time; generally you will want to set the start and end times earlier and later than actual (we are interested in how this "auto active" approach works for you, versus manual control over each event (turn it on/off) Default Transaction  Memo (Optional) works just like the memo option in the web app's Form Settings. It will appear on charge transaction memos unless the associated tile (see below) overrides it. Instructional Notes is where you can provide info about the event to people working it for you. Save is enabled when all required fields have been completed; user can also cancel or tap the back arrow in the header; all actions return user to the Event Settings menu

Checkout Settings

First chose a Shulware Integrated Gateway to collect electronic payments You can choose None and then have only "offline" methods like Bill to Account, Cash, Paper Check available. Choose whether you want to collect a transaction fee; if you require the fee, the Visa/Mastercard surcharge rules apply (maximum 3%/2.4% in USA/CAN, not charged to debit/credit cards etc) Make sure the fee charge type selected is consistent with your fee policy; you do not ever want to charge more than the applicable cap and use a charge type labelling it a surcharge Default rate comes from the gateway settings but can be changed; when we enable eCheck, there will be a separate rate setting for those payments Fee applies for all charges; in a later version may allow items to be set as exempt from the fee Choose how you will allow attendees to pay; select any combination of online and/or offline methods that suite you event and staffing needs (you might have a "cash bar" event that is cash only and at the same time take credit cards at the door for tickets). Save is enabled when all required fields have been completed; user can also cancel or tap the back arrow in the header; all actions return user to the Event Settings menu

 

Guest Checkout Settings

You can choose whether or not to allow non-account-holders to make payments When you do allow them, you next choose how to handle them: create a new account, post to a "catch-all" aka "dummy" account as some clients do on the web, or post as a standard "public payment" on the web (not recommended because you have to then go do something with them, like assign to a catch-call account) If you opt to create a new account, you get to set the Account type to use (you might want a add triage account type like "Event Attended" and move them later to the desired account type); because it is possible for someone to purchase only "No additional fields required" items (see the Tiles section for more), you also have to provide a Catch-call account as backup; this way you don't create accounts for the person buying a drink but you do for the generous new donor) If you opt to use a catch-all account, you will need to select that; all payments and charges will post against that account Choose what additional information you want collect; if you opted to create a new account, the app requires First and Last Name, and Email address; if posting to a catch-all account, additional field data (if any) shows on the transaction memo Save is enabled when all required fields have been completed; user can also cancel or tap the back arrow in the header; all actions return user to the Event Settings menu

 

Tiles

Tile Layout

Existing tiles are shown in a 2-column grid; press and hold the grid icon, upper right corner of each tile, then drag and drop to a new location in order to reorder the tiles Add a tile by clicking the +, top right (or if you have none, you can also tap the placeholder tile that appears) Tap the trash can to delete a tile Tap Edit to edit that tile's settings You can add as many tiles as you need; the screen scrolls (TIP: if you have a large number of tiles or will have users very focused on a specific task, such as refreshments, you can make more than event for the actual event, such as "Comedy Night - Refreshments" and "Comedy Night - Tickets/Donations" This view serves as a good representation of what the "Select Items" step of taking a payment will look like during the event. Tap the back arrow in the header to return to the Event Settings menu

 

Add/Edit Tile

Edit Tile screen shown; Add Tile is the same except for the heading.

Title appears to users Choose the charge type to use when the item is purchased or donation Choose Button Type Quantity tiles have a per unit price Amount Tiles present the user with an input box to enter any amount  Memo rule has three options: none, append, or replace; choose none to just use the default memo text set in General Settings; choose Append if you want to add additional text to the default memo text in General Settings; choose Replace if you want show other text instead of the default memo text in General settings NOTE: For quantity tiles, quantity and price are appended to memos of charge transactions (e.g. 3 @ $5.00) TIP: you can use the Quantity type to solicit donations in set amounts; you set a "price each" and have users choose quantity one (e.g. Bronze Sponsor has a price of $180, Silver $360, Gold $1800) Check "Additional fields not required" to skip asking/requiring during checkout when the purchase is only for this field or others with the box checked (e.g., you WANT more info from a ticket buyer or donor but not from the beer purchaser). Save is enabled when all required fields have been completed; user can also tap the back arrow in the header; all actions return user to the Tile listing screen

Event Team

Admins with the web permission are able to see/edit/select any event and therefore need not be added to the team.  Tap +, upper right, to search for a person or people (presently all people are shown) Each person you select will appear on a card on the Team Members screen In addition to name, the card shows account and email address, in case of people with similar or same names Tap the "Make Administrator of this Event" to give that person the ability to edit this event (presently only when event is active but that will change); this is similar to the web app's form administration option where a person without Forms permission can admin a particular form Tap the "-", upper right of the person's card, to remove a person from the team.

Taking Payments

NOTE: Before taking a payment, the user should connect to whatever reader will be used, if any. In a future release, we will add a reminder in the app.

 

Connecting to a Reader

If you want to use the Stripe Reader M2 it is essential to establish a connection with a card reader before you begin taking payments. You connect to Tap to Pay, by comparison, each time you choose utilize it, so it is present so long as the event allows it.

Reader M2 Connected

Reader M2 Not Connected

Connecting to a Reader M2

Power up the Reader M2 Tap the hamburger menu top left (three horizontal lines) to open the side menu Tap Connect Card Reader Tap "M2 Reader"* Wait for the app to find readers nearby - only unconnected readers will appear Tap the desired Reader M2 and then tap Connect

Connecting to a Device's "Tap to Pay" Built-in Reader

"Tap to Pay" is an option if (a) enabled for the Event and (b) the device supports it (move phones).

1. Tap "Built-in Tap" on the Checkout screen and tap "Continue"
2. Wait for the app to check for the requisite hardware and connect

Disconnecting from a card reader (M2 or built-in)

1. Tap the hamburger menu top left (three horizontal lines) to open the side menu
2. Tap Disconnect Card Reader 

Process Overview

Here is the basic workflow users follow after tap Select on an active mobile payment event.

1. Select Items
2. Check out
   • Associate an account OR complete additional fields related to the buyer, if any
   • Choose Payment Mode
   • Acquire payment method details and process the payment
3. Confirm payment

Once other payment modes are available, the above steps will change as needed. For example, if you "Bill to Account" you do not perform the payment-related steps. 

Item Selection

The first step to taking a payment determining what the payer is paying for. This step is a bit like "adding to cart" in the online shopping realm.

Quantity Items

Use the + button on a quantity tile to increase by one the quantity being purchased. Use the - button to decrease the quantity by one. As the quantity changes, so does the item total that is display on the tile.

Amount Items

Tap Amount and use the number pad that appears to enter the amount. Tap out of the tile to cancel. Tap Done to set the value.

Once all item quantities and/or amounts have been selected and/or entered, tap Checkout.

Checkout

Step 1: Account Association or Additional Fields Entry

This step will depend on a combination of event settings and for what the payer is paying. 

• If Account Association is required, meaning that in Guest Checkout settings allowing public payments is ON, the user will need to look up and choose an account in all cases 
•  If Account Association is not required, meaning that in Guest Checkout settings allowing public payments is ON, the user will need to enter any required additional fields shown; no fields will be shown if (a) none of the items bought require additional fields or (b) the handling option in Guest Checkout settings is something other than Create Account.

Step 2: Payment Mode

The user taps one of the allowed payment modes enabled in Checkout settings. 

NOTE: if you enable both Reader M2 and Built-In Tap to Pay, both buttons show. You can only be connected to one. If a future release you will just see Reader if one is connected.

When a method is selected, the screen will show fee information if a transaction fee of some kind has been set up in Checkout settings. If the fee is a surcharge (mandatory), the details are shown and the user should review with the payer. If the fee is a donation (voluntary), the details are shown along with a checkbox and the user should ask the payer whether or not to collect the fee. Tapping the checkbox toggles the fee on and off. 

NOTE: Visa surcharge rules apply to all transactions. This means that if the card is a debit or prepaid card, no mandatory fee will be collected in the USA or Canada. Furthermore, in Canada, a mandatory fee will only be collected if the brand is Visa or Mastercard (and again, credit only, not debit nor prepaid).

ShulCloud recommends using a reader over manual, as reader transactions are much more difficult to dispute (a machine has read the card info). However, manual mode is a helpful fallback if (a) you are using an tablet with a built-in reader, (b) you have no Reader M2's available or (c) you Reader M2 cannot connect or is out of battery.

If you do use manual mode, you will see that manual entry has been streamlined and is still relatively quick.

Step 3: Method Payment Details and Processing

• If using a reader, tap Continue and then read the card using the connected reader
• If using manual, enter the information, and tap Pay Now

NOTE: At the bottom of the Checkout Screen is a Summary that shows the payment total, including a fee as applicable. Tap the View button to view a detailed description of the items being paid. This is handy if you want your team to review in depth with the payer the transaction before processing the payment.

Confirmation

After the payment successfully processes, the user will see a confirmation screen. When an account is associated, a payment confirmation email is sent automatically, either to people on the account with Family Billing permission, just like happens with the web app. Presently, this is not shown on the confirm screen.

At this point, the user can also send a confirm to any other email address by entering into the box and tapping the Send button. 

At this point, the user can tap the button at the bottom of the screen to start a new payment.

On the Web

Payments taken through the app appear on ShulCloud. Card payments show on the Online Payments Page with a label of SMP Transaction Add (SMP representing ShulCloud Mobile Payments). A separate charge for the fee, if any, will be created - or not - based on your site settings.

Transaction memos will reflect the mobile event settings, such as a default memo, a default memo plus a tile memo, just the tile memo. It will also include quantity and price info in the case of quantity tiles. For example, suppose the payer paid for two $50 tickets. In the memo, you would see "Ticket 2 @ $50". Each item is separated by a "/". If the payment is public and posted to a catch-all account or treated like a regular public payment, any additional field information collected will also appear in the memo.