Technical Support Hours

M-F 8am to 8pm (EST)

Start a conversation

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 in Administrator mode 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.


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.


Square Authorization

The Square Authorization plugin is used to create an authorization when a sales document is forwarded through the workflow.

Security

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



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


Square Capture

The Square Capture plugin is used to capture any authorizations that are on a sales document when it is forwarded through the workflow.

Security

In SalesPad Desktop, go to Modules -> System -> Security Editor, and make sure the Square Capture 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.


Square Terminal
Overview

Square Terminal is an all-in-one credit card machine for payments and receipts. For more information please see: https://squareup.com/us/en/hardware/terminal 


Device Maintenance

The Square Device Maintenance screen allows you to view current Square devices or create and assign new devices, such as the Square Terminal. Devices added using the Square Dashboard will also appear on this screen.


Security

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



Can Add Device - Allows users to add Square devices, such as the Square Terminal. Defaults to false.

Can Assign Device - Allows users to assign Square devices to stores/drawers/users. Defaults to false.

Can Unassign Device - Allows users to unassign Square devices from stores/drawers/users. Defaults to false.

View Current Devices

Open the Square Device Maintenance screen by selecting Square on the ribbon and then selecting Device Maintenance.



The screen will show all available devices and their attributes, such as status, serial number, product type, and location. Click the "Refresh" button to refresh the devices.



Add a Device

To add a new device, click the "Add Device" button to open the New Device window.



Enter the name of the device, the location (leave blank for default location), and the product type and click the Add Device button to add the device. The device will be immediately created in the system.

Note: Adding a new device will create a virtual device in the system. The device cannot be used until it is paired with the corresponding physical device


Delete a Device

Currently, devices cannot be deleted in SalesPad Desktop. In order to delete a device, you will need to deactivate it using the Devices page in the Square Dashboard.


Pair a Device

After adding a new device, the device status will be "UNPAIRED" and you will need to pair it with a physical device.

To pair a physical device, such as a Square Terminal, make sure the device is turned on and on the login screen. Tap the "Sign In" button and select the "Use Device Code" option. Enter the device code from the Device Code column and tap the Sign In button in the upper right-hand corner to sign in.



Refresh the devices by clicking the Refresh button. The Device Status column should now say "PAIRED" and you should see a serial number in the Serial Number column.

The Square Terminal screen should look like this after you are signed in:



Assign a Device

You can assign a terminal device to a store/drawer. Make sure stores and drawers are configured in SalesPad Desktop by using the Store Setup screen. 

Please see the Store Setup section of the Counter Sales Guide (https://support.cavallo.com/article/1633-counter-sales-guide) for more information on how to do this.



Once the stores and drawers have been configured, select the desired device on the Square Device Maintenance screen and click the "Assign Device" button.



Select the store/drawer and the user and click the "Assign Device" button to assign the device to that store/drawer/user. You can verify device assignment by checking the Store Name, Drawer Name, and User Name columns on the grid:


Note: The User field on the Assign Device window will be automatically populated if the user is already assigned to the selected store/drawer. You can also leave the User field blank to skip assigning the user and just assign the device to the store/drawer


Unassign a Device

To unassign a device from a store/drawer/user, click the "Unassign Device" button. You will be prompted to confirm the decision:



Click "Yes" to unassign the device from the store/drawer. If the store/drawer is also assigned to a user, SalesPad will prompt to unassign from the user next:



Click "Yes" to unassign the user from the store/drawer or click No to leave the user assigned.


Terminal Checkout

You can check out using the Square Terminal on both sales document entry and counter sales screens.


New Terminal Checkout

To create a new terminal checkout, click the New Terminal Charge button on the Payments window.



If a terminal has been assigned to a store/drawer and that store/drawer is assigned to the current user, it will be automatically used during checkout. You can check which store/drawer is assigned to the current user by clicking the gears dropdown on the ribbon: 


If a terminal has not been assigned to a store/drawer, SalesPad will prompt you to select which terminal device you would like to use:



SalesPad will create a new terminal checkout, send it to Square for processing, and continuously poll the Square service to determine when the checkout is completed.



After the checkout is completed, SalesPad will create a payment in Dynamics GP.

Note: If a checkout doesn’t show up on the Square Terminal in some time, you can tap the screen to force the terminal to poll the Square service for the checkout


Cancel Terminal Checkout

To cancel the current checkout request, click the "Cancel" button. You will only be able to cancel the checkout request if it hasn’t been sent to the Square Terminal yet. Once the checkout request shows up on the terminal, you will only be able to cancel it from the terminal.

If you attempt to cancel a checkout that was already sent to the terminal, you will get the following error:


Choose files or drag and drop files
Was this article helpful?
Yes
No
  1. Christian Hartford

  2. Posted
  3. Updated

Comments

  1. Maggie Joseph

    Nice article. It would be great to see integrate square payment gateway https://www.bestdesign2hub.com/how-to-integrate-square-payment-gateway/ .