Payment Providers: Square

Setting up the Square provider, 'square_terminal' payment method

Configuring your Square account

If you haven't already create an Square account and open a developer account with the same login.

Login into your Square development dashboard and create a new application.

You can enter any name you want but we will use "Btrz" in our example.

Click save

You will be redirected to the Applications page and the new application will be shown in this page now.

Get Square credentials

Click in the application we just created to open it and navigate to the Credentials page.

Make sure you are in the Production environment (see top toggle)

Save the Application ID and the Access token to configure your Square account in Betterez.

To see and copy the Access Token click the Show link at the right of the field.

Configure Square webhooks

Navigate to the Webhooks page.

Make sure you are in the Production environment (see top toggle)

Create a new endpoint for the Connect v2 Webhooks clicking in the Add Endpoint button at the bottom of the page.

Give the webhook a descriptive name for example, terminal-checkout.

Enter the webhooks url from the Square payments page in the URL field.

Make sure to enter the proper notification url for "YOUR" account and not the one in the image above.

Scroll to the bottom of the form and make sure to only select the following events.

terminal.checkout.created
terminal.checkout.updated
terminal.refund.created
terminal.refund.updated

Click the Save button.

You should now see the new event in the Webhooks page.

Click the name of the event and a details tab will open on the right hand of your browser. You should find and copy the Signature Key, you will need this to configure the Square payment type.

Setting the Square payment type

Navigate to admin>payments scroll to find the square payment type and click in the name. You can find more information about the 'square_terminal' method in the sales flow article

Once on the Edit payment method screen the user will be required to configure the following fields:

Display Name The name you would like displayed in the shopping cart list of payment methods.

Enabled If checked, this payment method will be available for those sales flow channels it'll be configured.

Sort Order The higher the number, the lower in the list of payment methods this payment method will appear.

Require address on Back end If checked, this payment method will require the address of the customer in the back end sales flow.

Require address on Web sales If checked, this payment method will require the address of the customer in the web sales sales flow.

Refundable and Changeable If checked, tickets purchased with this method of payment will be refundabled or changeable.

Include in the deposit totals If checked, this payment type will have documentation that is necessary to include with seller shift deposit before closing a shift.

If Allow to combine is checked, the payment method can be combined with any other payment method on the payment form. You can also set a list of payments which can't be part of that combination:

Make sure to select only the Back end channel since this method requires a Square terminal to be installed and it will not work in websales.

You should also configured the parameters for the payment method to allow it to connect to the Square gateway and receive web hooks from it.

In the Access token field you should enter the value saved before, described in the get square credentials section

Make sure to also configured a reasonable waiting time that can work well with Square, at least 1 minute, but we recommend 4, this doesn't mean that the UI will wait for 4 minutes, but that if no response from Square after 4 minutes the tickets will be released.

In the Application Id field enter the application Id saved before, described in the get square credentials section

In the Webhook signature key enter the values saved before in the configure square webhooks section.

Make sure to check the Wait for payment completion setting, the flow with Square will not work properly if this setting is off.

Copy the Webhooks URL as displayed in the right blue panel and double check is the one you used when setting up your webhook above

Maximum waiting time: Indicates the time Betterez will wait for the payment to be processed. After that time the referenced payment will expire. If the calculed expiration time exceeds the trip departure, then the payment will expire in the trip departure time.
If the sale time exceeds trip departure time, then the payment will expire from that moment plus maximum waiting time.
This parameter override the default behaviour.
The image below show three differents scenarios: before the trip departure time, near trip departure time and after trip departure time.

NOTE: Negative values have not effects.

Trip departure time offset: This value apply when the sale is made near of the trip departure time and override partially maximum waiting time behaviour.
If the sale is made between trip departure minus this offset, the expiration time will be set from that moment plus the offset. This feature set a time window where the system extends the expiration time beyond the trip departure. Also, it allow made sales after trip departure.
The next image shows two sales made within of time window.

NOTE: This option only works if "Maximum waiting time" has been set. Negative values have not effects.

If your account has custom subdomains you can also configure the domains this payment method will be available for.

Click Save to save your configuration settings.