Integration Guide - Dynamics 365 Business Central

This guide walks you through the steps to create a new Square to Dynamics 365 Business Central integration using Square Bridge. If you have not scheduled a consultation with your Square Bridge account executive yet, see Get Started with Square Integrations for information about getting started with a new Square integration with your ERP system.

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

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 Dynamics 365 Business Central sandbox account whose data is very similar to your production account data.

After gaining experience testing the integration and approving test results, you'll be ready to create a production integration that uses your production Square account and your production Dynamics 365 Business Central account.

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

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

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

Complete the following steps to start configuring an integration:

1. Start the Square Bridge Integration Wizard.

   1. In your browser, go to https://v2.squarebridge.com.
   2. Sign in using the Microsoft or Google account that you intend to associate with Square Bridge and that you can share with your colleagues if needed.
   3. Follow the prompt on the home page to begin the Integration Wizard.

2. If you've already authorized Square Bridge for a Square account with your Square Bridge account, choose your Square account from the drop-down menu. Otherwise, complete the next step.

3. If you haven't authorized Square Bridge yet, choose Link a Square Account to start linking your Sandbox Square account with your Dynamics 365 Business Central account.

   

   Important

   Don't create an integration between your live Square account and external system account until you've validated Square Bridge with test accounts and environments.

4. When prompted, sign in to your Sandbox Square account.

5. Review and authorize Square Bridge for all of the following Square account permissions so that it can act on your Sandbox Square account. Choose Allow to authorize account permissions and continue the Integration Wizard.

   

   At this point, Square Bridge is set up to access your Square account as shown in the following:

   

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

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

1. In the Select External Source drop-down menu, choose Business Central.

2. Choose Start Authentication to begin linking Square Bridge to Business Central.

   

   Note

   If your Business Central credentials don't give you administrator access, you're prevented from continuing until you receive the required credentials.

3. After authenticating with Business Central, you're redirected back to the Square Bridge External Source page.

   

4. Enter the Environment Name,Tenant ID, and Company ID from Business Central.

   • Environment Name - This value is the first part of the Environment Name field, as found on the Business Central Help and Support page, Report a problem section. For example, if the Azure environment is “Environment: sandbox (Sandbox)”, then the Environment Name field value should be “sandbox”.

     

   • Tenant ID - This value is the Azure AD tenant field, found in the Business Central Help and Support page, Report a problem section. The ID is normally a GUID as shown in the previous image.

   • Company ID - This value is the Company field, found in the Business Central Settings, My Settings dialog box. Business Central settings are accessed by selecting the gear icon on the toolbar. This is usually the same as the Business Name on the Business Central home page. The Settings.Company field is always correct.

     

This step confirms that you've configured account credentials correctly. There's 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.

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.

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 isn't the same as the company ID that you set in step 3. The company system ID is necessary to make requests to Business Central.

1. Visit the Companies page (page=357)
2. Select the correct company in the list
3. Choose the help ? to open the help center
4. Choose Help & Support to open the Help & Support page
5. Choose Inspect pages and data. Hint: it should be in the Troubleshooting section of the page.
6. Search for $systemId. Hint: The ID is formatted like 999999xx-99x9-xx99-99xx-999x9x99999x

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 don't 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 it's 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:

  

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 doesn't 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.

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 doesn't 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 doesn't 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.

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.

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're given a list of all known Business Central units. If the table has only a row for the Each measurement unit, you haven't added your Business Central measurement units to your Square account yet. For more information, see Add Units of Measure to Square.

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've 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.

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.

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 aren't 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.

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

• 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's 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.

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'll use a default customer, what is the ID of that customer within your Business Central account?
• Gift Card Item Code - If you'll sell Square gift cards or discount item prices when a Square gift card is used, 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