Integration Guide - Dynamics 365 Business Central Beta release

This is pre-release documentation for an API in public beta and is subject to change.

This guide walks you through the steps to create a new Square to integration using Square Bridge.

Before you start the integration steps in this guide, you need to complete the steps in the following guides:

• Add Units of Measure to Square

• Install the Square Bridge Extension

Link to section

Sandbox testing accounts

The first integration that you create should always be treated as a Sandbox testing integration. The Sandbox lets you and the Square Bridge team test your configuration by synchronizing data between the Sandbox accounts that you set up. Use the Sandbox to review and fix any errors if they occur. You should synchronize from a sandbox account whose data is very similar to your production account data.

After gaining experience testing the integration and approving test results, you will be ready to create a production integration that uses your production Square account and your production account.

Link to section

Get ready

You need to have your environment open in another browser tab or window to complete some of the steps in this guide. You are asked to find and copy values from the Business Central tab and paste them into fields on a Square Bridge configuration page.

Link to section

Step 1: Create an integration

To create an integration, you need to authorize Square Bridge to access your Square and accounts. After you have created the integration, you can start it to synchronize data between Business Central and your Square account.

When the Integration Wizard is complete, you have configured Square Bridge to get your Business Central data. You can now synchronize data between Square and .

Complete the following steps to start configuring an integration:

Link to section

Step 2: Connect Square Bridge to

Square Bridge must be configured with the Business Central credentials needed to access your Business Central sandbox environment.

Link to section

Set the external source of data

In the Integration Wizard, set the External Source of data to synchronize. This is your Business Central environment.

Note

If your Business Central credentials do not give you administrator access, you are prevented from continuing until you receive the required credentials.

Link to section

Confirm connectivity in the integration

This step confirms that you have configured account credentials correctly. There is nothing to do in this step of the Integration Wizard other than to confirm that you want to integrate the Square and Business Central accounts displayed.

Choose Continue to confirm that Square Bridge can connect to Square and Business Central.

Link to section

Step 3: Provide integration settings

Use this step to provide information about your Business Central account, map Business Central attributes to Square attributes, and set default values for your integration.

Read the placeholders and tips for each form field for more information about how to configure Square Bridge. This section of the documentation provides more details about each form section.

The following sections explain where Business Central holds the values that you provide to Square Bridge integration settings fields.

Link to section

General settings

The general configuration page holds values that apply globally across all your Square account locations.

• Integration Name. You can change the default name of your integration in Square Bridge. The name of your integration is arbitrary and has no effect on data synchronization. The value in this setting is shown in the Square Bridge integration list on the Square Bridge home page.

  Did you know?

  If you have multiple integrations such as a test integration and a production integration, you should prepend "Test" or "Prod" to the integration name so that the integration list shows unique entries. For example, "Test - Business Central (CRONUS USA, Inc.)" and "Prod - Business Central (CRONUS USA, Inc.)".

• Company system ID. The company system ID is not the same as the company ID that you set in step 3. The company system ID is necessary to make requests to Business Central.

Link to section

Batch names

Your Business Central administrator might have already created cash receipt, general journal batch names, and item journal batches for this integration. If you need to create a new batch name, be sure that a batch name that you set in Square Bridge exactly matches the Batch Name that is set in Business Central.

• Cash receipt journal batch name. The cash receipt journal (page=255) batch name is used to create incoming and outgoing payment lines (payments portion of the order sync) through the Business Central "Cash Receipt Journals". These journal entries do not represent the actual settlement of funds from the Square Balance to seller's bank account.

  The following shows the GENERAL cash receipt journal batch name:

  

• General journal batch name. The general journal batch name is used to create bank transfer journal lines in the bank transfers synchronization through the Business Central "General Journals".
  These journal entries record the actual settlement of order payment funds out of the Square Balance and into seller's bank account. Typically, this payout is done three hours after the close of business for the day. Any instant settlements done during the business day are recorded with the end of day payout. For information about how your Square balance transfer works, see Transfer Options with Square.

  The following shows the DEFAULT general journal batch name:

  

• Item journal batch name. The item journal (page=40) batch name is used to create goods receipts and goods issues (the inventory adjustments portion of the inventory changes sync) through the Business Central "Item Journals".

  The following shows the DEFAULT item journal batch name:

  

• Transfer journal batch name. The transfer journal batch (page=393) name is used to create inventory transfers (the inventory transfer portion of the inventory changes sync) through the Business Central "Item Reclassification Journal".

The following shows the DEFAULT item reclassification journal:

• New Business Central sales pricing experience. If you want to sync more than 1,000 items from Business Central to Square, you must enable the Business Central sales pricing feature (if not already enabled). Enable the feature in Business Central using Feature Management (page=2610) and then look for Feature Update: New sales pricing experience. Make sure this is enabled for All Users before selecting the box in Square Bridge.

  The following shows how the new sales pricing experienced is enabled in Business Central Feature Management:

  

Link to section

Data types

Use these six on/off sliders to specify the data types you want to synchronize between Business Central and your Square accounts. If you turn on synchronization for a given data type, you can configure Square Bridge for that synchronization, run manual synchronizations, and schedule automatic synchronizations. Enabling a synchronization in the Integration Settings does not start an automatic synchronization. Automatic synchronization is managed on the Business Central Sync Schedules page.

The following shows the six data type selectors:

For information about how your Square balance transfer works, see Transfer Options with Square.

Link to section

Codes

Codes are objects created in Business Central that are applied to catalog items for the purpose of inventory syncing. You might need to create one of these codes if it does not exist in your Business Central environment.

• Exempt tax code. For Business Central, this is likely the tax group NONTAXABLE. This is used when a line item on an order has a $0 tax. To confirm, open Business Central Tax Setup (page=485) and use the value of the Non-Taxable Tax Group code.

• Rounding item code. The rounding item should be a custom non-inventory item that you create in Business Central (page=30). The rounding item code is used when Square Bridge is syncing Square orders to Business Central and encounters a discrepancy on an order or credit memo of less than 5 cents. Use the No. (SQ_ROUNDING) of the item to enter in this field. If this code does not exist, create a new item with the following values:

  • No. SQ_ROUNDING

  • Description Square Rounding

  • Type Non-Inventory

• Unknown item code. Similar to the rounding item, for unknown items a custom non-inventory item should also be created in Business Central. Create an item with the following values:

  • No. SQ_UNKNOWN

  • Description Square Unknown

  • Type Non-Inventory

  The SQ_UNKNOWN code is used by Square Bridge for your Square account non-inventory items that are to be synced to Business Central.

Link to section

Currency mappings

You can find the currency codes supported by your instance of Business Central by choosing Finance, and then choosing Currencies. The ISO Code column in the currency table maps to the Square currency used for a given Square account.

Choose the corresponding Business Central currency code for each Square currency.

Link to section

Measurement unit mappings

The measurement unit table has a row for each Square account measurement unit that you added in a previous step. To complete the mapping, choose the Business Central unit of measure that corresponds to each Square unit. In choosing a unit, you are given a list of all known Business Central units. If the table has only a row for the Each measurement unit, you have not added your Business Central measurement units to your Square account yet. For more information, see Add Units of Measure to Square

Link to section

Step 4: Configure your locations

Square Bridge lets you set up synchronization for each of your locations to account for differences that each of your locations might have. For example, you might not use the same catalog items in each location or might not use inventory tracking in one location.

For each location, you need to select the data types that you want to enable, the Business Central warehouse and time zone that corresponds to a Square location, and catalog settings that are applied to the location.

The list of Square seller locations is blank until you choose Sync Locations. When you have synchronized the Square Bridge locations list with your Square account locations, you can individually configure each location with the appropriate location-specific Business Central values.

Link to section

Data types

Choose which types of Square and Business Central account data that you want to sync with Square Bridge by sliding the on/off toggle for each data type. Each data type has an associated set of mapping properties. When you turn on data sync for a given type, the associated mappings are shown in following sections of the Location Settings page.

Link to section

Bank transfer adjustment types

Bank transfer adjustment mapping requires that you have the list of Business Central GL codes used to categorize asset transactions that affect Business Central asset balances. If you are not sure which GL codes to use, you should consult with your accounting team. Square Bridge bank transfer syncing records ledger entries in Business Central, which could put your ledger out of balance if the incorrect GL codes are configured in Square Bridge.

The following shows the Square Bridge bank transfer adjustment type mappings that you configure with Business Central GL codes:

You can find the general ledger (GL) codes in Business Central by choosing the Chart of Accounts page.

Link to section

Payment type mappings

Similar to the bank transfer mappings, you can find the GL codes for payment mappings on the Business Central Chart of Accounts page.

Link to section

Catalog

• Price list ID. The price list ID maps to a code in a Business Central Customer Price Group. To find the code, go to Business Central, and then choose Customer Price Groups under Go to Pages and Tasks. The Code (Sales Code) column corresponds to the price list ID.

• Tax area code. The tax area determines the tax charged for items at this location. To find the tax area code, go to Business Central, and then enter 'Tax area' in the general search field. Choose Tax areas from Go to pages and tasks in the search results.

Square Bridge synchronizes items whose customer price group Sales Code matches the price list ID that you set as the catalog Price List ID. The ID also determines the item price for a location. Square Bridge only synchronizes items set for unit prices greater than or equal to 0.00.

In the following example, item 1900-S syncs because it is assigned a customer price group code of SQUARE and it has a unit price of 130.00, which is a value greater than or equal to 0.00. Inventory levels on the item sync because the price group Variant Code is used in a Business Central stockkeeping unit for the item at this location.

Link to section

Orders

The following setting effect the way Square Bridge writes an Order into Business Central as a Sales Invoice. Order detail is synced as Sales Invoice detail.

• Always Use Square Default Customer. Select this option if you have a default customer specified in Business Central and you want all orders synced from your Square account to be attributed to that default customer.

• Default Customer ID. If you will use a default customer, what is the ID of that customer within your Business Central account?

• Gift Card Item Code. If you will sell Square Gift Cards or discount item prices when a Square Gift Card is used, then you need to create non-inventory

• Gift Card Discount Item Code.

• Tip Item Code.

• Custom Amount Item Code.

• Default Service Charge.

• Ad hoc Default Item.

• Aggregate Orders.

• Aggregation Window Start Time.

• Aggregation Window End Time.

• Default Uncategorized Item.

Link to section

Next steps