Learn how to integrate your SAP Business One environment into your Square account using Square Bridge.
Square Bridge

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.

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.132

  • 35.226.72.209

  • 54.146.136.40

  • 54.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 hostname of the license server and SQL server are properly configured on your DNS/host file

  • The 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

  1. 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.

  2. 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.

  1. 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\.

    1. Start the Square Monitor from Command Prompt and make sure there are no errors. Do not start it by double clicking SquareMonitor.exe

    2. 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

    3. Square Monitor should say something similar to "Started WindowsApplication in 6.075 seconds (JVM running for 6.793)"if it starts properly.

    4. 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.

  2. 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.

    1. Download nssm from the link above. No "installation" of nssm is needed. Place it in your C:\square\folder \

    2. 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:

  3. 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.

  1. Install the Square Monitor service.

    1. Choose the square-monitor.exe.

    2. Choose Install Service. NSSM should show “Service ‘SquareMonitor’ installed successfully”.

    3. Choose OK. The following figure shows the Microsoft NSSM service installer with an arrow pointing at the Install service button

  2. 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

  1. 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 Items

  • Taxes

  • Manage 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.

  1. In Google Chrome, open Square Bridge.

  2. Sign in and authorize the requested permissions

  3. Your Square Bridge account will not be initially approved.

    1. 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).

    2. 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.

    3. 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 cash

  • Drill down with the yellow arrow (Open Incoming Payment) and set the value to No

  • Choose 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.

An image showing the SAP Credit Card Payment Methods - Setup page

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.

  1. 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".

  2. 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".

  1. From the SAP main menu, choose Inventory, then Item Master Data,and then choose the Create icon.

  2. Choose Sales Item only (de-select Inventory Item and Purchase Item) and then save the new item. This image shows the SAP Business One Item Master Data dialog for a new catalog item

Create an object for tips. Square suggests the item code of iSqTip. Give this item the description of "Square Tip".

  1. From the SAP main menu, choose Inventory, then Item Master Data,and then choose the Create icon.

    1. 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".

  1. From the SAP main menu, choose Inventory, then Item Master Data,and then choose the Create icon.

    1. 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.

  1. In the SAP Tools context menu, choose Customization Tools and then User Defined Fields Management.

  2. Add the following fields as 100 character alphanumeric:

    • Marketing Documents, Title: SqTransactionId, SqRefundId, and SqReferenceId

    • Payments, Title: SqTransactionId, SqTenderId, SqRefundId, and SqReferenceId

    • Master Data, then Business Partner, then Business Partner: SqCustomerId and SqReferenceId

    • Accounting, then Journal Transactions, then Header: SqSettlementId and SqReferenceId

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 AddressIP 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 NameEnter the name of your SQL Server
Example: sqlb1
Company UsernameSAP company username
Example: manager
Company PasswordSAP password
Example: 1234
Database nameSAP database name
Example: DunderMifflinProd
License Server AddressEnter the license server hostname and port on your network
Example: sqlb1:30000
Database UsernameSQL username
Example: sa
IMPORTANT: this user must have appropriate permissions on both SBOCommon (read) and the Company Database (read/write)
Database PasswordCompany 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 OrderWhen checked, a sales order will be created for every transaction.
Always Use Default Square CustomerWhen 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 CodeSAP Sales Tax Code for tax exempt items.

Example Exempt

Square Credit/Debit CodeThe line number of the payment code, see 7.2 Credit Card Code

Example: 4

Cash Payment Terms Group CodeThe group number for the Cash payment group, see Cash Payment Terms

Example: -1

Payment Method CodeThe payment method code for credit card payments through Square, see 7.3 - Payment Method Code

Example: 3

Square Bridge field
Value
Default RegionDefault 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 CurrencyThe currency of your Square Account (US, CAD, JPY, or GBP)

Example: USD

SAP CurrencyThe currency code in SAP- see SAP Currency and 12.1 - Rounding in Currencies Setup - must match exactly, check your configuration

Example: USD

Example US

Example: $

Square Bridge field
Value
Tip Item CodeThe item code for tipping- see 7.6 - Tip Item Code
Custom Item CodeThe custom item code- see 7.5 - Custom Amount Item Code
Gift Card Item CodeThe 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 CodeThe warehouse holding inventory for this location- see Warehouse Codes

Example: 01

Price List IDPrice list to determine the prices of items at this location and warehouse- see Price Lists

Example:1

Square Bridge field
Value
Default Business PartnerDefault business partner for this location

Example C99999

See 7.1 - Default Business Partner(s)

Square Bridge field
Value
Square GL CodeCode to attribute debit/credit card sales - see G/L Codes
Return GL CodeCode to attribute returns - see G/L Codes
Cash GL CodeCode to attribute cash - see G/L Codes
Other GL CodeCode to attribute other tender types - see G/L Codes
Gift Card GL CodeCode to attribute gift cards - see G/L Codes

Square Bridge field
Value
Bank GL CodeCode for your bank account where you recieve Square Settlements - see G/L Codes
Transaction Fees G/L CodeCode for routing transaction fees - see G/L Codes
Subscription Fees G/L CodeCode for routing Square subscription fees - see G/L Codes
Chargebacks G/L CodeCode for Chargeback holds - see G/L Codes
Square Capital G/L CodeCode 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 memo

Itemized: 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 invoice

Category: 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 CategoriesNote: Only applicable to Category aggregation type

Mapping 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 TaxesNote: Only applicable to Category aggregation type

Mapping 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

  1. This is an example of "None" aggregation type: This is an image showing SAP Business One, A/R Invoice page, 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.

  1. This is an example of "Itemized" daily aggregation type This is an image showing SAP Business One, A/R Invoice page, Itemized 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.

This is a an image showing the Square Dashboard, Transactions list

As you can see, all the line items for the three transactions have been placed on the single daily invoice.

  1. This is an example of "Category" daily aggregation type: This is an image showing SAP Business One, A/R Invoice page, daily category 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. This is an image showing the Square Dashboard, Transactions list with category level aggregation 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 CodesTax codes to apply to items at this location - see Warehouse Tax Codes

Example 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:

  1. 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

  2. check that the router uses port forwarding to the internal IP address of your server running Square Monitor

  3. check that port forwarded on the router matches the Square Monitor port in the square-config.ini file

  4. check that NSSM has successfully started Square Monitor

If you are not using a router, please do the following:

  1. 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

  2. the port matches the Square Monitor port square-config.ini file, (typicaly 8888)

  3. 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 Time

  • America/Chicagoif your server time zone is set on US Central and follows Daylight Savings Time

  • America/Denverif your server time zone is set on US Mountain and follows Daylight Savings Time

  • America/Los_Angeles if your server is on the is set on West Coast and follows Daylight Savings Time

  • America/Phoenix if 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:

This screen image shows the SAP Business One Warehouses setup window

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:

This is an image showing SAP Business One, Chart of Accounts list

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.