Square Integration

Overview

Integrating SalesPad Desktop with Square allows you to run credit card transactions from within SalesPad Desktop and greatly enhances the user experience with electronic payment processing. 

Square moves the point of entry, storage, and transmission of credit card information and other data away from SalesPad Desktop and into a secure cloud location. 

The process is simple: SalesPad Desktop sends transaction information to Square who then processes this information and sends back the necessary information to create/edit/delete a payment in SalesPad Desktop and Microsoft Dynamics GP.

Settings

In SalesPad Desktop, go to Modules -> System -> Settings, and filter to ‘Square’:

General

Credit Card Type Mappings - Mapping of Credit Card Types to Dynamics.

_{Supported Types: AmericanExpress, Discover, MasterCard, and Visa}

Default Wallet Selection - Sets the default wallet selection on the Square Payment tab.

Include Authorization When Calculating Default Amount - When true, SalesPad will include existing authorizations when calculating the default amount for new Square transactions.

Square Environment Type - Determines if a sandbox or a production environment should be used. Defaults to Sandbox.

Permissions

Allow Authorize - Allows a user to authorize a payment on sales document.

Allow Capture - Allows a user to capture a payment on a sales document.

Allow Charge - Allows a user to charge a payment on a sales document.

Allow Create GP Payment - Allows a user to create a GP payment on a sales document for an existing Square transaction that was not written to GP.

Allow Credit - Allows a user to credit a payment on a sales document.

Allows Over-Charge - Allows a user to make a payment greater than the remaining document total.

Allow Terminal Charge - Allows a user to charge a payment on a sales document using the Square Terminal.

Allow Void - Allows a user to void a payment on a sales document.

Square Terminal

Allow Tipping - When true, terminal checkout will allow tipping. Defaults to false.

Checkout Attempts - The number of attempts SalesPad will perform when sending a checkout request to the Square Terminal before canceling. Defaults to 10.

Checkout Duration - The duration, in minutes, after which the terminal checkout will be automatically canceled by Square. Defaults to 5.

Checkout Polling Frequency - The frequency, in seconds, that will be used when polling the Square Terminal to determine checkout completion. Defaults to 3.

Show Checkout Cancellation Reason - When true, SalesPad will show a cancellation reason message after terminal checkout is canceled. Defaults to false.

Skip Checkout Receipt Screen - When true, the Square Terminal will skip the receipt screen during checkout. Defaults to false.

Square Configuration

Square configuration in SalesPad is done entirely in Settings. There are two categories: Sandbox and Production. Sandbox is mainly used for testing purposes and Production is used when you are ready to go live with Square. The majority of the information that goes into these settings comes from Square.

First, open the Square Developer Dashboard and create a new application using the ‘+’ in the Application section of the webpage. If you are new to Square, you will need to register first before you can access the Developer Dashboard.

Give your application a name and click "Save".

From here open the application. Across the top, you will see a toggle for 'Sandbox' and 'Production'. Leave it in "Sandbox" for now. 

Click the OAuth menu option on the left side of the page.

You will be presented with a page similar to the screenshot above. Copy the "Sandbox Application ID" value from the box, in SalesPad go to Settings, and filter for ‘square sandbox’. 

Paste the value into the Square Application ID setting. Be sure you are under the ‘Square - Sandbox’ category. 

Do the same for the Square Application Secret (you will likely need to click "Show") and paste it into the Square Application Secret setting in SalesPad under the ‘Square - Sandbox’ category.

The Sandbox Redirect URL needs to be a URL that is listenable by SalesPad. By default, SalesPad listens on the http://127.0.0.1/squarecallback/ URL but this can technically be whatever you would like. The only stipulation is that whatever is set in Square needs to also be set in SalesPad. If you’ve changed the URL, be sure to update the setting in SalesPad as well.

Once all of this is complete, click "Save" in Settings and now you’re ready to get an access token.

In your browser, go back to the Square Developer Dashboard and click "Open" on a Sandbox Test Account. It is likely labeled as ‘Default Test Account’ but it could be named something else. This will log you into the account. This is required when using Sandbox Mode and attempting to get an access token. In production, this is not required because you will be prompted to login every time. 

Now make sure that SalesPad is running as a Windows Administrator and then go to Settings and click the ellipses button in the Square Application Access Token setting (make sure you’re using the ‘Square - Sandbox’ category). A browser will open asking you to accept the privileges for the SalesPad Desktop application. Click "Yes". You should now see a message saying everything was successful.

The last thing you need to do is make sure that the Square Environment Type setting is set to Sandbox. After confirming this, go ahead and click "Save".

You are ready to begin processing test transactions through Square in SalesPad Desktop!

When you have completed testing and are ready to begin using Square in Production, you simply need to go back to the OAuth menu again for the application you created in Square Developer Dashboard and switch the toggle from Sandbox to Production.

After moving from Sandbox to Production, simply repeat the process above but for the Production settings. Be sure to switch the Square Environment Type setting to Production when you’re finished.

Revoke A Square Access Token

In the event a Square Access Token needs to be revoked from the Square Production or Sandbox settings follow the steps below:

1. Navigate to Settings and filter on "Square Token"
2. Hold down the CTRL and SHIFT keys on your keyboard and left-click the ellipses "..." button for the Application Access Token (Production or Sandbox) you wish to revoke.
   
3. Confirm that the Square Token should be revoked by selecting Yes or cancel the process by selecting No.
   

Sales Document Payments

Overview

The Square Payments tab found in the Sales Document Payments screen is used to process authorizations, charges, and credits. It also allows users to void authorizations when required.

Security

In SalesPad Desktop, go to Modules -> System -> Security Editor, and make sure the Sales Document Payments plugin is enabled:

The access security for this tab is controlled by the Sales Document Payments security found in the Security Editor. Within this security, the Enable Square Payments sub security must also be enabled.

The majority of the permissions within this tab are controlled through the settings defined above. Most of these can be defined per security group, allowing them to be used much like a security would.

Using the Screen

New Auth

The New Auth button is used to create a new authorization. Before clicking the button two things should be checked: Wallet and Amount. 

You can use the wallet dropdown to choose any existing wallet for the user or choose ‘New Wallet’ if you need to create a new wallet for a new card. If you choose ‘New Wallet’ you will be redirected to a webpage where you can enter in the card information. 

This information will be used to create a new wallet for the customer and will automatically be used to create the authorization. 

The Amount field is used to determine the amount that will be used to create the authorization. The new authorization will appear in the Line Transactions grid.

New Charge

The New Charge button is used to create a new charge. Before clicking the button three things should be checked: Wallet, Payment Type and Amount. 

You can use the wallet dropdown to choose any existing wallet for the user or choose ‘New Wallet’ if you need to create a new wallet for a new card. If you choose ‘New Wallet’ you will be redirected to a webpage where you can enter in the card information. 

This information will be used to create a new wallet for the customer and will automatically be used to create the authorization. 

The Payment Type will determine what type of Gp payment will be created. For invoices, the only selection will be Payment but on an Order you will be able to choose between Deposit or Payment. 

The Amount field is used to determine the amount that will be used to create the authorization. Once a charge is complete, a charge transaction will appear in the Line Transactions grid and a payment will be created for the document.

Capture

This button will only be activated when an authorization line is selected in the Line Transactions grid. Using this button will capture the full amount authorized. Only the full amount authorized can be captured because Square does not allow partial captures.

Void

This button will only be activated when an authorization line is selected in the Line Transactions grid. Using this button will void the authorization and it can no longer be captured.

Credit

This button will only be activated when a capture or charge line is selected in the Line Transactions grid. When clicking this button, you will be presented with a prompt to determine the refund amount. Once you’ve determined the amount, click OK and the card will be refunded for the amount. 

When complete, a Credit type line will appear in the Line Transactions grid and any payments on the document will be reduced by the specified value. If you are doing this on a Return, a credit type payment will be applied to the return for the amount.

Note: If a return or credit is made on a transaction directly from Square, this will not be synced back to SalesPad. If you intended to process a return or credit, be sure to process the Square transaction via SalesPad.

Counter Sales

Overview

Counter Sales is a quick order entry system that is useful for walk-in customers or off-site sales.

For more information on the Counter Sales screen, please see the documentation: https://support.cavallo.com/article/1633-counter-sales-guide

Using the Screen

Taking Square payments during checkout in Counter Sales functions the same as taking payments on the sales document entry screen. Select the Square tab on the Check Out tab and select "New Auth", "New Charge", or "New Terminal Charge".

Please see the Sales Document Entry section of this documentation for more information.

Sales Batch Processing

Square Batch Charge

Overview

The Square Batch Charge plugin on the Sales Batch Processing screen is used to process charges for a batch of sales documents.

For more information on Sales Batch Processing, please see the following documentation: https://support.cavallo.com/article/1963-sales-batch-processing 

Security

In SalesPad Desktop, go to Modules -> System -> Security Editor, and make sure the Square Batch Charge plugin is enabled:

Close Finished Window - Close Finished window after sales batch processing is completed. Defaults to false.

Create Credit Card Deposits For Orders - When enabled, credit card deposits will be created for orders instead of credit card payments. Defaults to false.

Forward After CC - Enables or disables automatic forwarding of sales documents after a Square charge is completed. Defaults to true.

Processing a Batch Charge

Open the Sales Batch Processing screen and select the sales documents you would like to charge. Select the Square Batch Charge plugin. If you do not see the plugin, you may need to select it from the Actions dropdown menu:  

You will be prompted to confirm. Select Yes to proceed.

SalesPad will charge the selected sales documents and display a summary afterward.

Square Batch Authorization (Delayed Capture)

Overview

The Square Batch Authorization plugin on the Sales Batch Processing screen is used to process authorizations for a batch of sales documents.

For more information on Sales Batch Processing, please see the following documentation: https://support.cavallo.com/article/1963-sales-batch-processing 

Security

In SalesPad Desktop, go to Modules -> System -> Security Editor, and make sure the Square Batch Authorization plugin is enabled:

Close Finished Window - Close Finished window after sales batch processing is completed. Defaults to false.

Create Credit Card Deposits For Orders - When enabled, credit card deposits will be created for orders instead of credit card payments. Defaults to false.

Forward After CC - Enables or disables automatic forwarding of sales documents after a Square authorization is completed. Defaults to true.

Processing an Authorization

Open the Sales Batch Processing screen and select the sales documents for which you would like to create authorizations. Select the Square Batch Authorization plugin. If you do not see the plugin, you may need to select it from the Actions dropdown menu:  

You will be prompted to confirm. Select Yes to proceed.

SalesPad will create authorizations for the selected sales documents and display a summary afterward.

Sales Batch Capture

Overview

The Square Batch Capture plugin on the Sales Batch Processing screen is used to capture authorizations for a batch of sales documents.

For more information on Sales Batch Processing, please see the following documentation: https://support.cavallo.com/article/1963-sales-batch-processing 

Security

In SalesPad Desktop, go to Modules -> System -> Security Editor, and make sure the Square Batch Capture plugin is enabled:

Close Finished Window - Close Finished window after sales batch processing is completed. Defaults to false.

Create Credit Card Deposits For Orders - When enabled, credit card deposits will be created for orders instead of credit card payments. Defaults to false.

Forward After CC - Enables or disables automatic forwarding of sales documents after a Square charge is completed. Defaults to true.

Processing a Batch Capture

Open the Sales Batch Processing screen and select the sales documents you would like to capture authorizations from. Select the Square Batch Capture plugin. If you do not see the plugin, you may need to select it from the Actions dropdown menu:  

You will be prompted to confirm. Select Yes to proceed.

SalesPad will capture any authorizations on the selected sales documents and display a summary afterward.

Cash Receipts

Overview

The Customer Cash Receipt screen now has an integration with Square.

For more information on Cash Receipts, please see the following documentation: https://support.cavallo.com/article/1596-cash-receipts 

Security

In order to view the Square option in the Receipt Details section of the screen it must be enabled. Go to Security Editor -> Cash Receipts and look for the Credit Card Payment Option sub-security. In the drop down, select Square.

Usage

Enter in your cash receipt as you normally would. When you get to the Receipt Details section select the Square option, specify the amount and make sure to choose an option from the Wallet dropdown, then select Submit Charge.

If you’ve chosen an existing wallet, the charge will automatically be applied to the card.

If you’ve chosen New Wallet, you will be redirected to a browser where you can enter in your Card Information.

Once this has been completed, the card will be charged and the cash receipt will be created.

Customer

Overview

The Square Transactions tab on the Customer Card allows you to view all credit card transactions for that customer.

Security

In SalesPad Desktop, go to Modules -> System -> Security Editor, and make sure the Customer Square Transactions tab is enabled:

Transactions

The Square Transactions tab will automatically load all transactions, but you can manually force a reload by clicking the "Refresh" button.

The default To Date is today’s date and the default From Date is one month before today’s date. 

Leaving the date fields blank will search all transactions.

Square Wallet

The Square Wallet tab on the customer card allows you to view, create, and delete wallets for that customer. If you make changes to the customer’s wallet in Square, those changes will appear in this tab and vice versa.

Security

In SalesPad Desktop, go to Modules -> System -> Security Editor, and make sure the Customer Square Wallet tab is enabled:

Can Create Wallet - Allows users to create a new customer wallet. Defaults to false.

Can Delete Wallet - Allows users to delete an existing customer wallet. Defaults to false.

Can Set Default Wallet - Allows users to set a default customer wallet. Defaults to false.

View Wallets

To view existing wallets, select the Square Wallet tab on the customer card. 

Existing wallets will automatically load when you select the tab, but you can manually refresh them by clicking the Refresh button.

Add New Wallet

To add a new wallet, click the New button. A separate web page will open where you can enter the credit card information.

_{Note: Credit cards used for payments on the sales document entry will automatically be added to the customer wallet and appear on the Square Wallet tab}

Delete Existing Wallet

To delete an existing account, click the "Delete" button. 

Click "Yes" on the prompt to delete the wallet.

Set Default Wallet

To set a default wallet for a customer, click the "Is Default" checkbox on the Square Wallet tab.

Only one default wallet can be set for each customer.

To use the default wallet for payment transactions, make sure the Default Wallet Selection setting is set to Customer Default Wallet:

Workflow

Workflow Setup

Open the Sales Document Workflow Setup screen by going to Modules -> Setup / Utilities -> Workflow Setup, select the Sales Document tab, then select the desired document type and document ID.

On the Sales Document Workflow Setup screen, select the desired Square plugin from the list of available workflow plugins and save your changes.

In the example above, the Square Charge plugin will run when a sales document is forwarded from the NEW ORDER queue to the PRINTING queue.

For more information on the Sales Document Workflow Setup screen, please see the documentation: https://support.cavallo.com/article/2215-desktop-workflow 

To run a Square plugin from the workflow, forward the sales document by clicking the Release button on the sales document entry (the button caption may differ depending on your workflow configuration).

In addition to workflow, you can run Square workflow plugins from the Actions dropdown menu:

Workflow Rules

There are three new workflow rules to help you evaluate a document’s Square transactions as it moves through workflow:

Has Square Auth - Check if the current document has a Square Authorization. Does not check related documents.

Square Auth Present - Check if the current document or any related documents have a Square Authorization.

Square Payment Exists - Check if there are Square captures or charges on the document.

Workflow Plugins

Square Charge

The Square Charge plugin is used to process a charge when a sales document is forwarded through the workflow.

Security

In SalesPad Desktop, go to Modules -> System -> Security Editor, and make sure the Square Charge plugin is enabled:

Create Credit Card Deposits For Orders - When enabled, credit card deposits will be created for orders instead of credit card payments. Defaults to false.

Failed Transaction Queue - Documents with failed credit card transactions will be moved to this queue. This security does not have a default value.

Please contact your Cavallo account executive to obtain licensing required to utilize this Square integration.