Square for SAP Business One
Beta release
This is pre-release documentation for an API in public beta and is subject to change.
This guide shows you how to integrate your SAP Business One and Square accounts by creating an integration in Square Bridge. The guide walks you through the required steps in Square Bridge and describes how to find the SAP Business One values with which you need to configure the Square Bridge integration.
Important
You need to strictly follow these steps to ensure that your integration meets test requirements. Square estimates it can take 4 to 8 hours for a first-time integrator and this estimate depends on your experience with SAP Business One systems.
Review any relevant appendices for feature-specific configurations.
You might need help from your IT department for this step.
Open any firewalls to the following IP allowlist on these ports:
Outbound TCP ports 80 and 443
Inbound TCP port 8888 for a SQL instance
The following IP addresses are used by the Square cloud integration service to connect to your SAP Business One instance:
35.225.215.132
35.226.72.209
54.146.136.40
54.196.97.125
Important
If your SAP Business One server is behind a router, you must set up port forwarding on port 8888 (or whichever port you run Windows Connector (SQL) from your router to the IP address of the server running Service Layer / Windows Connector.
You must install SQL on your SAP Business One server for the Square Bridge integration.
The following requirements must be met before you install SQL:
You have Administrator access to install software on your computer.
The
hostnameof the license server and SQL server is properly configured in your DNS/host file.The SAP 32-bit DI API is installed on the server that Square is connecting to.
The SQL user whom you designate in Section 10.1 must have read/write permissions to both the SBOCommon DB and the Company DB.
The correct version of SQL Server Native Client is installed on the server running SQL Server.
Install Java SE Runtime Environment v1.8 (JRE 32-bit version, Windows x86 offline) and Microsoft SQL Native Client for your installed version of SQL.
Send an email to [email protected] with the following .jar file attachments, found in the following directories:
(32-bit) C:\Program Files (x86)\SAP\SAP Business One DI API\JCO\LIB
(64-bit) C:\Program Files\SAP\SAP Business One DI API\JCO\LIB
Important
Upload the .jar files to Dropbox, Google Drive, Microsoft One Drive, or a similar service. Include a link in your email because most email systems block .jar files sent as attachments.
The .jar files are used by Square to create a Windows Connector build for your integration. Square sends you a Dropbox link for the build within one business day.
Download the Square Monitor build from the Dropbox link and extract files to a new folder such as C:\square.
For the purposes of this guide, it is assumed that you have installed these files in C:\square.
Start Square Monitor from Command Prompt and make sure there are no errors. Do not start it by double-clicking SquareMonitor.exe.
You might need to adjust the Java path in your .ini file inside your Square Monitor folder if Java cannot be found. Square recommends that you open this file in Notepad++ due to line break issues in Windows.
Square Monitor should say something similar to "Started Windows Application in 6.075 seconds (JVM running for 6.793)" if it starts properly.
Square recommends that you use a signed SSL certificate from a certificate authority in
keystore.p12. Replace the certificate in the Square Monitor folder with your signed SSL certificate. You need to enable SSL in the ERP settings as shown in SSL validation. If you do not use an SSL certificate, you need to use a self-signed certificate at your own risk. Square does not provide support in setting up SSL certificates.Square has auto-generated a certificate, but it is recommended that you regenerate this certificate on your own. Replace your certificate in the .ini file in the Square Monitor folder.
After you have verified that Square Monitor starts, install NSSM (SQL only). NSSM is a tool that allows you to run Square Monitor as a Windows service, increasing reliability.
Download NSSM from the link above. No "installation" of NSSM is needed. Place it in your
C:\square\folder \Open Command Prompt as System Administrator.
Did you know?
Right-click Command Prompt in the Windows search results and then choose Run as Administrator.
Enter a change directory command to the folder where NSSM is installed by typing the following command:
Install the SquareMonitor service as System Administrator by typing the following command into the command prompt:
The NSSM service installer (with the correct service name entered) GUI should open so you can configure your application path, startup directory, and other fields.
Install the SquareMonitor service.
Choose the square-monitor.exe.
Choose Install Service. NSSM should show “Service ‘SquareMonitor’ installed successfully”.
Choose OK.
Start Square Monitor as System Administrator by typing the following in the command prompt while inside the folder where NSSM is located:
nssm start SquareMonitor.You should now be able to see SquareMonitor in Task Manager, Services.
Install SQL Management Studio from Microsoft.
If you are new to SAP to Square integrations, you must create a demo Square account on your own (non-client) infrastructure.
Important
Use the SBODEMO database for the country of your Square account (for example, SBODEMOUS for a US Square account and SBODEMOCA for a Canadian Square account). This is required for approved installers.
You can perform seller installations if you are:
A value-added reseller (VAR).
An approved seller working without a VAR but working with a Square staff member who has extensive SAP Business One experience.
Square requires you to create a test account on your VAR infrastructure with the SBODEMO database. After you create the test account, Square approves you to perform seller installations. This requirement ensures that:
You are familiar with the installation in a controlled environment.
Client installations are done faster.
You are able to identify seller-specific problems that did not occur in your environment.
Each VAR employee who plans to perform seller installations needs to complete at least one test setup, regardless of the installation experience of other VAR employees. Square estimates this to take 2 to 4 hours.
The seller needs to create two Square accounts: one as a sandbox to be synced with recent production data and one to be synced with the current production data for production usage. The seller should also create two email addresses to administer the integration.
[email protected][seller domain]
[email protected][seller domain]
These accounts can be used by the seller's IT person responsible for maintaining the day-to-day operations of Square Bridge. The VAR should also use these email addresses during the integration setup phase.
This step is appropriate for production setup.
The Square to SAP integration requires that the seller catalog is entirely managed in SAP. This includes items, variations, categories and groups, taxes, prices, and inventory.
Important
Sellers and their employees should not create or edit any items, categories, taxes, or prices in Square. These changes must be made in SAP and then synced to the Square account by the integration.
This integration uses specific naming conventions. Transactions do not sync for items that deviate from this naming convention in any respect.
Square Bridge requires that you enable the Team Management application to get access to the team member permissions you need to eliminate field edits and reduce human error.
Open the Team Management page and choose Get started free. Read the instructions in Setting up Team Management in SPOS to complete the seller team setup at a cost of $5 per month, per employee and free with a Square for Retail subscription.
Each team member using the POS should be created with their own team member and passcode. Team members should have the minimum necessary permissions for their role and team members should not have the following permissions:
Edit ItemsTaxesManage Inventory
Granting these permissions gives a team member access to category item fields and potentially breaking the catalog sync.
For a full list of permissions and descriptions, see Custom Permission Sets.
In Google Chrome, open Square Bridge.
Sign in and authorize the requested permissions.
Your Square Bridge account is not initially approved.
If you are a VAR employee or contractor creating your first account (for the SBODEMOUS database), email the Square Bridge team at [email protected] and let them know. Send the email from your individual VAR email account. Create the Square Bridge account using your own personal information or your company's employer identification number (EIN).
If you are a VAR, have completed the previous step, and are ready to set up a Square Bridge seller account, email the Square Bridge team at [email protected] to confirm that you have completed the previous step and to ask them to approve the account.
If you are a seller, Square requires that you use an approved VAR to set up your account. If you do not have a VAR, email the Square Bridge team at [email protected] for a list of approved VARs.
The Square Bridge to SAP Business One integration depends on a specific set of SAP objects that need to be created prior to the first integration.
If no customer is attached to a Square transaction (for example, an anonymous, walk-up, or one-time customer), Square Bridge assigns the default business partner to the transaction. Some sellers prefer to have a single business partner shared among all of their locations. Others prefer to have a unique partner for each location.
On the SAP main menu, choose Business Partners and then choose Business Partner Master Data. Choose the Add icon to add a default business partner. Enter a card code (for example, cSqNewYork), provide a name, and assign the type as Customer. Set the following values:
Choose the Payment Terms tab, choose Payment Terms, and then choose cash.
Drill down with the yellow arrow (Open Incoming Payment) and set the value to No.
Choose Addresses, choose Ship To, and then enter a tax code.
On the SAP main menu, choose Administration, Setup, Banking, and Credit Cards.
Under Credit Card Name, enter Square. Use the same G/L Account as other credit card entries.
On the SAP Administration page, choose Setup, Banking, and Credit Card Payment Methods and then create a payment method code for Square.
Set Min. Credit Voucher to zero and Min. Payment to zero.
Create a Payment Code for Square that has a payment after zero days and zero months.
Record the line number of this new payment method code in the line number in the Payment Method Code field.
Create separate items for Square gift cards and gift card discounts with the item codes iSqGiftCard and iSqGiftCardDiscount. Provide item descriptions such as "Square Gift Card" and "Square Gift Card Discount". Square recommends that you assign each to its own item group.
On the SAP main menu, choose Inventory, choose Item Master Data, and then choose the Create icon. When creating the item, clear the Inventory and purchase item checkbox and then use a new ItemGroup called "Square Gift Card" or "Square Gift Card Discount".
Configure an Advanced G/L Account Determination rule for when something from the gift card item group is sold (or reloaded). You might need to consult the seller accounting staff for the appropriate G/L code. To learn how to find G/L codes in SAP Business OneView, see Advanced GL Account Determination in SAP Business One 9.0.
Create an item for Square custom amounts. Square suggests that you use the item number of iSqCustomAmount. Give this item a description of "Square Custom Amount".
On the SAP main menu, choose Inventory, choose Item Master Data,and then choose the Create icon.
Select only the Sales Item checkbox (clear the Inventory Item and Purchase Item checkboxes) and then save the new item.
Create an object for tips. Square suggests that you use the item code of iSqTip. Give this item the description of "Square Tip".
On the SAP main menu, choose Inventory, choose Item Master Data, and then choose the Create icon.
Select only the Sales Item checkbox (clear the Inventory Item and Purchase Item checkboxes) and then save the new item.
Create an object for rounding corrections. This item code must be iSqRounding. Give this item a description of "Square Rounding Correction".
On the SAP main menu, choose Inventory, choose Item Master Data, and then choose the Create icon.
Select only the Sales Item checkbox (clear the Inventory Item and Purchase Item checkboxes) and then save the new item.
Square recommends that you place this item in its own Item Group so that Advanced G/L Determination Rules can be applied later if needed (for example, to allocate rounding differences to Sales Tax).
Add the following user-defined fields (UDFs) in SAP.
Important
Due to an SAP defect with certain Business One versions, the Square Bridge team does not update the UDF characteristics (field type and character limit) in SAP Business One if you accidentally misconfigure your field (for example, too few characters). If you want to correct configuration errors in UDFs, first create a backup of your database. Then delete the UDF and recreate the UDF rather than updating it.
On the SAP Tools menu, choose Customization Tools and then choose User Defined Fields Management.
Add the following fields as 100-character alphanumeric characters:
Marketing Documents, Title:
SqTransactionId,SqRefundId, andSqReferenceIdPayments, Title:
SqTransactionId,SqTenderId,SqRefundId, andSqReferenceIdMaster Data, then Business Partner, then Business Partner:
SqCustomerIdandSqReferenceIdAccounting, then Journal Transactions, then Header:
SqSettlementIdandSqReferenceId
Add this example
code block to the database SBO_SP_TransactionNotification stored procedure where the ADD YOUR CODE HERE placeholder appears (see SAP ONE Support launchpad).
The code block should prevent duplicates on the SqReferenceId for any individual object (A/R Invoices, A/R Credit Memos, Sales Orders, A/R Downpayment Invoices, Incoming Payments, and Outgoing Payments). It should also prevent duplicates on SqCustomerId for Business Partners. Ask your VAR for assistance about how to set up a stored procedure.
Note
Because this code is specific to your version of SAP Business One and your database version, Square does not provide setup assistance. Square has provided example code for a specific version of SAP Business One for SQL but does not provide it for all versions. It is up to your VAR to help modify the sample to work in your environment.
In Square Bridge, the Integration Wizard uses the External Source, Confirm Integration, Configure Integration, Configure Location, and Next Steps pages to walk you through the configuration of an integration. The following sections document the configuration fields on each of the wizard pages.
The External Source page asks for connection strings and credentials that allow Square Bridge to connect to your SAP Business One environment.
Database Type. The SQL Server version/year (for example, MS SQL 2016).
SQL Configuration
Square Bridge field | SAP field value |
|---|---|
| External Address | IP address, port, and URL suffix of the server running Square Monitor (if behind a router, use the router's address and make sure the port is forwarded). Example: https://34.214.172.5:8888/v1.2/ |
| Server Name | Enter the name of your SQL Server. Example: sqlb1 |
| Company Username | SAP company username. Example: manager |
| Company Password | SAP password. Example: 1234 |
| Database name | SAP database name. Example: DunderMifflinProd |
| License Server Address | Enter the license server hostname and port on your network. Example: sqlb1:30000 |
| Database Username | SQL username. Example: saIMPORTANT: This user must have appropriate permissions on both SBOCommon (read) and the Company Database (read/write). |
| Database Password | Company database password. Example: B1manager |
In SAP BusinessOne, choose Orders & Payments. This window has the fields that you need to complete the orders and payments mapping section of the wizard location settings.
Square Bridge field | Sync behavior |
|---|---|
| Always Create Sales Order | When selected, a sales order is created for every transaction. |
| Always Use Default Square Customer | When selected, documents requiring a business partner (such as sales orders and invoices) are attributed to the default customer set for each location. |
Square Bridge field | SAP Business One field |
|---|---|
| Exempt Tax Code | The SAP Sales Tax Code for tax exempt items.Example: Exempt |
| Square Credit/Debit Code | The line number of the payment code, see 7.2 Credit Card Code.Example: 4 |
| Cash Payment Terms Group Code | The group number for the Cash payment group, see Cash Payment Terms.Example: -1 |
| Payment Method Code | The payment method code for credit card payments through Square, see 7.3 - Payment Method Code.Example: 3 |
Square Bridge field | Value |
|---|---|
| Default Region | The default region to apply to business partner phone numbers when applying validation. Typically, this is “US” for other phone regions (see RegionCode).Example: US |
| Square Currency | The currency of your Square account (US, CAD, JPY, or GBP).Example: USD |
| SAP Currency | The currency code in SAP must match exactly.Example: USDExample USExample: $ |
Square Bridge field | Value |
|---|---|
| Tip Item Code | The item code for tipping (see 7.6 - Tip Item Code). |
| Custom Item Code | The custom item code (see 7.5 - Custom Amount Item Code). |
| Gift Card Item Code | The gift card item code (see 7.4 - Gift Card Item). |
For each location configured to sync with SAP, choose Add Location, choose the Square location in the drop-down list, and then choose Create.
Square Bridge field | Value |
|---|---|
| Warehouse Code | The warehouse holding the inventory for this location.Example: 01 |
| Price List ID | The price list to determine the prices of items at this location and warehouse.Example:1 |
Square Bridge field | Value |
|---|---|
| Default Business Partner | The default business partner for this location (see 7.1 Default business partner).Example: C99999 |
Square Bridge field | Value |
|---|---|
| Square GL Code | The code to attribute debit/credit card sales (see G/L Codes). |
| Return GL Code | The code to attribute returns (see G/L Codes). |
| Cash GL Code | The code to attribute cash (see G/L Codes). |
| Other GL Code | The code to attribute other tender types (see G/L Codes). |
| Gift Card GL Code | The code to attribute gift cards (see G/L Codes). |
Square Bridge field | Value |
|---|---|
| Bank GL Code | The code for your bank account where you receive Square settlements (see G/L Codes). |
| Transaction Fees G/L Code | The code for routing transaction fees (see G/L Codes). |
| Subscription Fees G/L Code | The code for routing Square subscription fees (see G/L Codes). |
| Chargebacks G/L Code | The code for chargeback holds (see G/L Codes). |
| Square Capital G/L Code | The code for repayments to Square Capital loans (see G/L Codes). |
Square Bridge field | Value |
|---|---|
| Aggregation Type See next page for examples | Aggregation type refers to rolling up multiple transactions into a single SAP A/R invoice.None: One Square transaction/refund maps to one SAP invoice/credit memo.Itemized: All Square transactions for a given calendar day are aggregated into one SAP invoice/credit memo. Aggregation is done at the line-item level only, such that every Square line item is represented on the aggregated invoice.Category: All Square transactions for a given calendar day are aggregated into one SAP invoice/credit memo. Aggregation is done at the category level only, using non-inventory items. |
| Aggregation Categories | Only applicable to the Category aggregation type. Mapping is between a Square category name and its respective SAP item code (such as Square category: “Beverages” and SAP item code: “iBeverages”). Create the SAP items as non-inventory items. Contact your VAR for further guidance. |
| Aggregation Taxes | Only applicable to the Category aggregation type. Mapping is between a Square tax name and its respective SAP tax item code (such as Square tax name: “California”, SAP tax item code: “iSqTaxCa”). Create the SAP items as non-inventory items. Contact your VAR for further guidance. |
Aggregation Type examples
This is an example of the "None" aggregation type:
Each Square transaction has a separate A/R invoice. This is the only option available with itemized refunds and customer attribution.
This is an example of "Itemized" daily aggregation type:
One invoice is generated for all of the day's transactions. Each line item on each transaction is represented as one line item on the daily aggregated invoice. Itemized refunds are not available in this mode.
As you can see, all the line items for the three transactions have been placed on the single daily invoice.This is an example of "Category" daily aggregation type:
The following shows the Square transactions, total up category sums, and using the Category -> Item mapping in Square Bridge to create a Category aggregation invoice. Itemized refunds are not available in this mode.
As you can see, a single invoice is created for all 13 transactions, with only category level details reported (uncategorized, taxes, gift cards, and tips are also distinct line items). Category and tax mappings are performed using Bridge-defined location settings.
As you can see, all the line items for the three transactions have been placed on the single daily invoice.
Square Bridge field | Value |
|---|---|
| Tax Codes | Tax codes to apply to items at this location (see Warehouse Tax Codes).Example: NY If you are using invoice aggregation the Category type, this step is not applicable. |
This section documents the tasks you need to complete in your SAP Business One account.
This step is required for syncing settlements.
In SAP Business One, choose Administration, System Initialization, and Document Settings.
Choose the Per Document tab and then choose the Document "Journal Entry Document".
Clear Block Posting Date Editing per Row.
This step is required if you use Sales BOM items.
To ensure that any Sales BOM items are processed correctly, please check the following setting:
In SAP Business One, choose Document Setting, and then choose General.
In the open window, check for a "Sales BOM" in Documents Display that the setting Price and Total for Parent Item only is set.
Failing to set this properly results in sales BOMs having all line items with a $0 value in SAP.
Restart the server running Square Monitor.
Test the connection in Square Bridge (see the Integration Walkthrough). If you are unable to get a connection, review the following tips:
SQL
If you are using a router, do the following:
Ensure that the IP address defined in Square Bridge matches the external IP address of your router and that the port defined in Square Bridge is accessible to the Square IP addresses defined in the setup guide.
Ensure that the router uses port forwarding to the internal IP address of your server running Square Monitor.
Ensure that the forwarded port on the router matches the Square Monitor port in the square-config.ini file.
Verify that NSSM has successfully started Square Monitor.
If you are not using a router, do the following:
Ensure that the IP address defined in Square Bridge matches the external IP address of your server and the port is accessible to the Square IP addresses defined in the setup guide.
Ensure that the port matches the Square Monitor port in the square-config.ini file (typically 8888).
Verify that NSSM has successfully started Square Monitor.
Important
If you receive a response with an error message, see Appendix 2 - Common errors.
When a connection is successfully established, Initiate Catalog, Inventory, Transactions, and Business Partners sync from Square Bridge.
In the Square Bridge to SAP Business One integration settings, choose Auto Syncing, and then choose the data you want to automatically sync to SAP. Syncs run every hour.
A summary report is emailed to the Square account owner each morning detailing any issues encountered during the sync.
Square highly recommends that you purchase a public SSL certificate. If you have a public SSL certificate, set it to true. Enter false if you have a self-signed certificate.
Set the time zone of your SAP server. To find the current time that SAP is using, look at the bottom of the SAP client.
Next, find the alphabetical Java time zone ID that corresponds to this time.
Some common US time zones are as follows:
America/New_York. If your server time zone is set to East Coast Time and follows Daylight Savings Time.America/Chicago. If your server time zone is set to Central Time and follows Daylight Savings Time.America/Denver. If your server time zone is set to Mountain Time and follows Daylight Savings Time.America/Los_Angeles. If your server time zone is set to West Coast Time and follows Daylight Savings Time.America/Phoenix. If your server is in Phoenix, which does not observe Daylight Savings Time.UTC. If your server time zone is set to Universal Coordinated Time (UTC).
For other time zones, see the TimeZoneID page.
In SAP Business One, choose Main Menu, Administration, Setup, Inventory, and Warehouses.
Choose the binoculars icon (find) and search for Warehouse Codes.
In SAP Business One, choose Main Menu, Administration, Setup, Inventory, and Warehouses.
Double-click the warehouse to view its setup and determine its tax code.
In SAP Business One, choose Main Menu, Inventory, and Price Lists.
Choose the price lists mapped to each location by using the line number (#) in the first column of the Price Lists table.
In SAP Business One, choose Main Menu, Financials, and Chart of Accounts.
For each mapped location and per the tender type, choose a code where funds are routed.
In the Name field, choose the globe icon to open the Translations dialog box. Populate the Square Bridge configuration field with the G/L account Code found in the dialog box.
Open SQL Server Management Studio and enter the following query:
Find the GroupNum for PymntGroup Cash. Typically, this is -1.
You need the database name you will associate with this Square account. To get this value, in SAP Business One, choose Administration, Setup, Financials, and Currencies. Find the code of the currency, typically “$”.
Be sure to round by the selected currency (see Round by Currency? Check The Options).
If you need more assistance, contact Developer Support or ask for help in the Developer Forums.