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 gives you all of the information that you need to integrate your SAP Business One and Square accounts by creating an integration configuration in Square Bridge. The guide walks you through the required steps in Square Bridge and how to find the SAP Business One values that you will configure the Square Bridge integration with.
Warning
This guide needs to be strictly followed to ensure an integration that meets test requrements. Square estimates that it can take four to eight hours for a first time integrator and depends on your experience with SAP Business One systems.
Please review any relevant appendicies for feature-specific configuration.
On this page
You may need help from your IT department for this step.
Open any firewalls to the following IP whitelist on these ports:
Outbound TCP ports 80 and 443
Inbound TCP ports 8888 for SQL instance.
The following IP addresses are used by the Square cloud integration service to connect to your Business One instance:
35.225.215.13235.226.72.20954.146.136.4054.196.97.125
Important
If your 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 Business One server for the Square Bridge integration.
SQL installation requirements All of 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 are properly configured on your DNS/host fileThe SAP 32-bit DI API is installed on the server that Square is connecting to.
A SQL user with permissions to read/write to Both the SBOCommon DB and the Company DB.
The correct version of Microsoft SQL Client is installed on the server for your SQL Server.
SQL Installation instructions
Install the Java SE Runtime Environment v1.8 (JRE 32-bit version, Windows x86 offline) and Microsoft SQL Native Client for your version of SQL installed.
Send an email to sapb1-integration@squareup.com with the following .jar file attachments, found in the these 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 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 will send 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, we will assume that you have installed this in the folder
C:\square\.Start the Square Monitor from Command Prompt and make sure there are no errors. Do not start it by double clicking SquareMonitor.exe
You may need to adjust the Java Path in your .ini file inside your Square Monitor folder if Java cannot be found. It is recommended that you open this file in Notepad++ due to line break issues on Windows
Square Monitor should say something similar to
"Started WindowsApplication 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 the keystore.p12. Replace the certificate in the Square Monitor folder with your signed SSL certificate. You will need to enable SSL in the ERP settings as shown here. 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.
We have auto-generated one but it is recommended you re-generate this certificate on your own. Replace your certificate in the .ini file in the Square Monitor folder.
Once you have verified Square Monitor starts, Install NSSM (SQL only). NSSM is a tool that allows you to run SquareMonitor 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 click Run as Administrator
In the command prompt, 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 filled out) GUI should open so you can configure your application path, startup directory, and other fields.
Install the Square Monitor service.
Choose the square-monitor.exe.
Choose Install Service. NSSM should show “Service ‘SquareMonitor’ installed successfully”.
Choose OK.
Start the Square Monitor as System Administrator by typing the following into 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 then you must create a demo account.
Set up a demo Square account on your own (non-client) infrastructure.
Important
Please use the SBODEMO database for the country of your Square Account (for example SBODEMOUS for a US Square account, SBODEMOCA for a Canadian Square Account). This is required for approved installers.
If you are:
A value added reseller (VAR)
An approved seller working without a VAR but with a Square staff member who has extensive SAP B1 experience
Square requires you to create a test account on VAR infrastructure with the SBODEMO database. After you create the test account, Square will approve you to perform seller installations. This requirement insures that:
You are familiar with the installation in a controlled environment.
Client installations are done faster
You will be able to identify seller-specific problems that did not occur in your environment.
Each VAR employee who will do seller installations needs to do at least one test setup, regardless of the installation experience of other VAR employees. Square estimates this will take two to four hours.
The seller needs to create two Square accounts, one as a sandbox that will be synced with recent production data. The other Square account will be synced with current production data for production usage. The seller should also create two email addresses to administer the integration.
SquareAdmin-Production@[seller domain]
SquareAdmin-Sandbox@[seller domain]
These accounts can be used by the seller's information technology (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 set up.
The Square - SAP integration requires that the seller catalog is entirely managed in SAP. This includes items, variations, categories & 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.
The use of Square Bridge requires that you enable the Team Managment application in the Square Dashboard to get access to the team member permissions that you need to eliminate field edits and reduce human error.
Open the Team Managment page and choose Get Started. Read the instructions in Team Management to complete the seller team set up at a cost of $5 per month, per employee and free with a Square for Retail subscription.
Open the Team Managment page and choose Get Started. Read the instructions in Team Management to complete the seller team set up.
Each team member using the POS should be created with their own team member/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 will not be initially approved.
If you are a VAR employee/contractor creating your first account (for the SBODEMOUS database), let the Square Bridge team know by emailing them at sapb1-integration@squareup.com. Send the email message from your individual VAR email account. Create the Square Bridge account using your own personal information or your company employer identification number (EIN).
If you are a VAR and you have completed the previous step and are ready to set up a seller Square Bridge account, please email the Square Bridge team at sapb1-integration@squareup.com to confirm you have completed the previous step and to ask them to approve the account.
If you are a seller, we require you to use an approved VAR to set up your account. If you don’t have a VAR, email the Square Bridge team at sapb1-integration@squareup.com for a list of approved VARs.
The Square Bridge to SAP Business One integration depends on a specific set of SAP objects 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.
From the SAP main menu, choose Business Partners and then 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. Choose
cashDrill down with the yellow arrow (Open Incoming Payment) and set the value to
NoChoose Addresses, Ship To and enter a tax code.
From SAP main menu, choose Administration, then Setup, then Banking, and then Credit Cards.
Add a new entry. Credit Card Name is Square. Use the same G/L Account as other credit card entries.
From the SAP Administration page, choose Setup, then Banking, and then Credit Card Payment Methods, create a payment method code for Square. Set the 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 into 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.
From the SAP main menu, choose Inventory, then Item Master Data, and then choose the Create icon. When creating the item, un-check Inventory and purchase item 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 re-loaded) - you may need to consult the seller accounting staff for the appropriate G/L code. View Youtube video - Advanced GL Account Determination in SAP Business One 9.0 to learn how to find G/L codes in SAP Business One.
Create an Item for Square custom amounts. Square suggests the item number of iSqCustomAmount. Give this item a description of "Square Custom Amount".
From the SAP main menu, choose Inventory, then Item Master Data,and then choose the Create icon.
Choose Sales Item only (de-select Inventory Item and Purchase Item) and then save the new item.
Create an object for tips. Square suggests the item code of iSqTip. Give this item the description of "Square Tip".
From the SAP main menu, choose Inventory, then Item Master Data,and then choose the Create icon.
Choose Sales Item only (de-select Inventory Item and Purchase Item) 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".
From the SAP main menu, choose Inventory, then Item Master Data,and then choose the Create icon.
Choose Sales Item only (de-select Inventory Item and Purchase Item) 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 (UDF) in SAP.
Important
Due to a SAP defect with certain Business One versions, the Square Bridge team does not update the UDF characteristics (field type, character limit) in SAP Business One if you accidentaly misconfigure your field (for example, too few characters). If you want to correct configuration errors in UDFs, take a backup of your database first and delete the UDF and recreate it rather than updating.
In the SAP Tools context menu, choose Customization Tools and then User Defined Fields Management.
Add the following fields as 100 character alphanumeric:
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
code block to the database SBO_SP_TransactionNotification Stored Procedure where the ADD YOUR CODE HERE placeholder appears (see the SAP ONE Support launchpad article for more info)
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, Outgoing Payments). It should also prevent duplicates on SqCustomerId for Business Partners. Please ask your VAR with assistance on how to set up a stored procedure.
Note
Because this code is specific to your version of SAP B1 and your database version, Square does not provide assistance in setting this up. We have provided example code for a specific version of SAP B1 for SQL but we do 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, an integration wizard uses 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 checked, a sales order will be created for every transaction. |
| Always Use Default Square Customer | When checked, documents requiring a business partner (Sales Orders, Invoices, etc) will be attributed to the default customer set for each location |
Square Bridge field | SAP Business One field |
|---|---|
| Exempt Tax Code | 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 CodeExample: 4 |
| Cash Payment Terms Group Code | The group number for the Cash payment group, see Cash Payment TermsExample: -1 |
| Payment Method Code | The payment method code for credit card payments through Square, see 7.3 - Payment Method CodeExample: 3 |
Square Bridge field | Value |
|---|---|
| Default Region | Default Region to apply to Business Partner phone numbers when applying validation. Typically this will be “US” for other phone regions, see here.Example: US |
| Square Currency | The currency of your Square Account (US, CAD, JPY, or GBP)Example: USD |
| SAP Currency | The currency code in SAP- see SAP Currency and 12.1 - Rounding in Currencies Setup - must match exactly, check your configurationExample: 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, click Add Location (top right corner) and select the Square location in the dialog dropdown- then click Create.
Square Bridge field | Value |
|---|---|
| Warehouse Code | The warehouse holding inventory for this location- see Warehouse CodesExample: 01 |
| Price List ID | Price list to determine the prices of items at this location and warehouse- see Price ListsExample:1 |
Square Bridge field | Value |
|---|---|
| Default Business Partner | Default business partner for this locationExample C99999See 7.1 - Default Business Partner(s) |
Square Bridge field | Value |
|---|---|
| Square GL Code | Code to attribute debit/credit card sales - see G/L Codes |
| Return GL Code | Code to attribute returns - see G/L Codes |
| Cash GL Code | Code to attribute cash - see G/L Codes |
| Other GL Code | Code to attribute other tender types - see G/L Codes |
| Gift Card GL Code | Code to attribute gift cards - see G/L Codes |
Square Bridge field | Value |
|---|---|
| Bank GL Code | Code for your bank account where you recieve Square Settlements - see G/L Codes |
| Transaction Fees G/L Code | Code for routing transaction fees - see G/L Codes |
| Subscription Fees G/L Code | Code for routing Square subscription fees - see G/L Codes |
| Chargebacks G/L Code | Code for Chargeback holds - see G/L Codes |
| Square Capital G/L Code | 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 onto a single SAP A/R Invoice.None: One square transaction/refund maps to one sap invoice/credit memoItemized: All square transactions for a given calendar day will be aggregated into one sap invoice/credit memo. Aggregation will be done at the line item level only, such that every Square line item will be represented on the aggregated invoiceCategory: All square transactions for a given calendar day will be aggregated into one sap invoice/credit memo. Aggregation will be done at the Category level only, using non-inventory items. |
| Aggregation Categories | Note: Only applicable to Category aggregation typeMapping between a Square category name and it’s respective sap item code (i.e. square category: “Beverages”, SAP item code: “iBeverages”)Please create the SAP Items as non-inventory items. Please contact your VAR for further guidance. |
| Aggregation Taxes | Note: Only applicable to Category aggregation typeMapping between a square tax name and it’s respective sap tax item code (i.e. square tax name: “California”, SAP tax item code: “iSqTaxCa”)Please create the SAP Items as non-inventory items.Please contact your VAR for further guidance. |
Aggregation Type examples
This is an example of "None" aggregation type:
Each Square transaction will have 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 will be generated for all of the day's transactions. Each line item on each transaction will be 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:
Here we look at the Square transactions, total up category sums, and using the Category -> Item mapping in Bridge create a Category Aggregation invoice. Itemized refunds are not available in this mode.
As you can see, a single invoice was created for all 13 transactions above, 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, a single invoice was created for all 13 transactions above, 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.Square Bridge field | Value |
|---|---|
| Tax Codes | Tax codes to apply to items at this location - see Warehouse Tax CodesExample NY If using invoice aggregation type Category, 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 Settlements sync.
In SAP Business One, choose Administration, then System Initialization, and then Document Settings
Select the Per Document Tab and then select the Document "Journal Entry Document"
Uncheck “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, then 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 will result 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 Integration Walkthrough). If you are unable to get a connection, please review the following tips
SQL
If you are using a router, please do the following:
check that the IP address defined in Bridge is equal to the external IP address of your router, and the port defined in Bridge is accessible to the Square IP addresses defined in the setup guide
check that the router uses port forwarding to the internal IP address of your server running Square Monitor
check that port forwarded on the router matches the Square Monitor port in the square-config.ini file
check that NSSM has successfully started Square Monitor
If you are not using a router, please do the following:
make sure that the IP address in Bridge matches the external IP of your server and the port is accessible to the Square IP addresses defined in the setup guide
the port matches the Square Monitor port square-config.ini file, (typicaly 8888)
check that NSSM has successfully started Square Monitor
Important
Please see the Common Errors section in the Appendix if you receive a response with an error message.
Once a connection has been successfully established, Initiate Catalog, Inventory, Transactions and Business Partners sync from the Bridge
In the integration Bridge Sap Business One settings, select Auto Syncing and choose which data you wish to automatically sync to SAP. Syncs run every hour.
A summary email report is emailed to the Square account owner each morning detailing any issues encountered during the sync.
We highly recommend you purchase a public SSL certificate - if you have a public SSL certificate, set to true.Enter false if you have a self-signed certificate.
Set the time zone of your SAP Server. To find the current time SAP is using, look in the bottom middle of the SAP client.
Then, find the alphabetical Java time zone ID that corresponds to this
Some common US time zones are below:
America/New_Yorkif your server time zone is set on US East and follows Daylight Savings TimeAmerica/Chicagoif your server time zone is set on US Central and follows Daylight Savings TimeAmerica/Denverif your server time zone is set on US Mountain and follows Daylight Savings TimeAmerica/Los_Angelesif your server is on the is set on West Coast and follows Daylight Savings TimeAmerica/Phoenixif your server is in Phoenix which does not observe Daylight Savings Time
UTCif your server time zone is set on Universal Coordinated Time (UTC)
For other time zones, see this Oracle TimeZoneID page.
In SAP Business One, choose Main Menu, then Administration, then Setup, then Inventory, and then Warehouses. Choose the binoculars icon (find) and search for your Warehouse Codes.
In SAP Business One, choose Main Menu, then Administration, then Setup, then Inventory, and then Warehouses.
Double click the warehouse to view its setup and determine its tax code:
In SAP Business One, choose Main Menu, then Inventory, and then Price Lists. Choose price lists mapped to each location by using the line number (#) in the first column of the Price Lists table. In the example above, the Regular Purchase Price price list is line #3- therefore 3 is entered into the price list field.
In SAP Business One, choose Main Menu, then Financials, then Chart of Accounts
For each mapped location and per tender type, choose a code where funds are routed:
In the Name field, click the globe icon to open the Translations dialog. Populate the Square Bridge configuration field with the G/L account Code found in the dialog.
Open SQL Server Management Studio and enter the query:
Find the GroupNum for PymntGroup Cash. Typically this will be -1
You need the database name you will associate with this Square account. To get this value, in SAP Business One, choose Administration, then Setup, then Financials, and then Currencies. Find the Code of the currency, typically “$”.
Please also make sure round by currency is selected. See this blog post by Ari Schapira (Chief Product Owner - SAP Business One) - Round by Currency? Check The Options.
If you need more assistance, contact Developer Support or ask for help in the Developer Forums.