Implementing Codat's no-code merchant configuration

🚧

Sync for Commerce: beta testing

Note that Sync for Commerce is in beta testing.

Before you start

Before you start, retrieve the following details:

  • The key of the accounting integration selected by the merchant which you obtained at Accounting platform selection stage.
  • The ID that you use to identify the merchant in your internal system, hereafter referred to as ‘yourMerchantId’.
  • The clientId of the client (Codat instance) that you wish to use to implement the no-code merchant configuration. Contact your account manager to get the clientId.

These details are used to form the no-code merchant configuration flow URL.

You should also ensure that the redirect URL in your Link settings is configured to https://sync-flow.codat.io/{clientId}/link/{companyId}.

📘

Use our Swagger to follow this guide

All the endpoints mentioned in this guide are available in our Sync for Commerce Swagger. You can use it to try the API requests from this guide directly in your browser. Before you use Swagger, make sure to authenticate.

Redirecting the merchant to the no-code solution

  1. After the merchant selects their accounting platform, they should be immediately redirected to a secure URL leading them to the Sync for Commerce flow. To retrieve the secure URL, make the following request:
GET config/sync/commerce/lqai/{key}/start?merchantIdentifier={yourMerchantId}

Example response:

{ 
    "url":”https://sync-flow.codat.io/{clientId}/lqai/gbol/start?otp={6digitOneTimePassword}”
}

Codat expects the merchantIdentifier to always be unique.

For example, if a merchant has successfully completed the configuration journey, and you create another syncFlowUrl using the same merchant identifier, the redirect will take the user back to the sync settings page where they would be able to alter their preferences.

🚧

One-time password

The URL that you will receive in response includes a one-time password which will expire after 30 seconds. Using a one-time password eliminates the possibility of malicious third parties accessing the Sync Flow and ensures a high level of security for your merchants.

  1. Redirect the merchant to the constructed URL. Note that the URL has a 30-second limit of validity, so make sure the merchant accesses the URL within that limit. Otherwise, their access will be restricted with a 401 error. In this scenario, generate a new URL with a new one-time password and direct the merchant to it.
  2. After the merchant follows the provided link, they are redirected to the previously selected accounting platform for authorization.
  3. Upon successful authorization, the merchant is presented with Codat’s white-labeled configuration flow and is prompted to configure the data sync. For the best experience, we recommend that you set up your logo and primary color.

Every time a user goes through the no-code Sync flow, the following happens:

  • A Codat company is created. Its name value is populated with the merchant ID value provided via the Sync flow URL query parameters.
  • Commerce and accounting data connections are established.
  1. To allow the merchants to review their connection, present them with the same URL as the one used for the original setup (see step 1 of this guide). It will direct the merchant to the Sync settings page where they will be able to review the details of the last sync or sever the connection to their accounting platform. In case the merchant severs the connection, the next scheduled data sync will fail, and no further data syncs will be attempted.
  2. Before you move on to the next stage, Data pushing, the configuration must be complete. You can check the configuration status following the steps below.

Checking the configuration status

To establish whether a merchant has successfully completed their commerce data configuration, perform the following steps:

  1. Retrieve the ID of the company created for your merchant:
GET companies?page=1&pageSize=100?query=name={yourMerchantId}

This request returns information about the company. It should have both accounting and commerce data connections present and with the linked status. Retain the value of the company id which we will refer to as the companyId.

  1. Using the companyId, view the status of the merchant's configuration:
GET config/companies/{companyId}/sync/commerce

If the merchant has successfully configured their preferences and has enabled sync, then both the enabled and configured parameters will be set to true. This means you can start pushing the commerce data to this company.

Customizing your no-code solution

Sync for Commerce no-code flow is a white-labeled solution that can be tailored to fit the needs of your clients.

To create a branded experience, you can:

  • Set up your company name, logo, and icon via the Link settings.
  • Update the text fields of the flow. Updating the text fields helps ensure that your users clearly understand what they are sharing via the Sync for Commerce flow and which accounts they should choose to ensure it works correctly.

How to update the text values

You can update every text field of the Sync for Commerce no-code flow, including:

  • Feature title, feature description, and required field indicator description (Sales, Fees, Payments)
  • Feature categories title, feature categories title description, and feature categories (Sales, Fees, Payments)

Keep in mind that this update will only affect the UI.

📘

Don't use this process to change the visibility of feature categories. Follow the process described in How to change the visibility of feature categories instead.

To get a complete list of all the customizable text fields and their values perform the following request:

GET sync/commerce/config/ui/text

To update, remove or reset a text value, use the following request:

PATCH sync/commerce/config/ui/text

Request body:

// Updates the text value to the specified string
{
   "data-textkey": "A new value"
}

// Removes the value from the UI
{
   "data-textkey": ""
}

// Resets the value to default
{
   "data-textkey": null
}

In the request above, the data-textkey is the key of the field that you want to configure.

You can find the data-textkey values in the tables below.

🚧

Update the text fields consistently

We recommend grouping your updates to ensure that related values are updated consistently. A feature name (e.g., Sales) appears as a check box item in the left pane (Set up sales) and as the main title on the right side of the window (Sales), so it is important to update both configure-setupSidebar-checkboxes-sales and configure-content-sales-title.

Main title

Default value

data-textkey value

Set up Sync to {platform name}

configure-setupSidebar-title

Checkbox captions

Default value

data-textkey value

Connect to {Commerce platform name}

configure-setupSidebar-checkboxes-connectToCommerce

Connect to {Accounting platform name}

configure-setupSidebar-checkboxes-connectToAccounting

Set up sales

configure-setupSidebar-checkboxes-sales

Set up fees

configure-setupSidebar-checkboxes-fees

Set up payments

configure-setupSidebar-checkboxes-payments

Set up sync schedule

configure-setupSidebar=checkboxes-syncSchedule

Buttons

Default value

data-textkey value

Previous

configure-misc-previousButton

Next

configure-misc-nextButton

Required field indicator description

Default value

data-textkey value

Indicates a required field

configure-required-indicator

Sales title and description

Default value

data-textkey value

Sales

configure-content-sales-title

Sales title description:
no value by default.

configure-content-sales-description

Sales feature categories title and description

Default value

data-textkey value

Accounts

configure-content-sales-accounts-title

Configure accounts mapping from
{commerce platform name} to
{accounting platform name}.

configure-content-sales-accounts-description

Tax rates

configure-content-sales-taxRates-title

Configure tax rates mapping from
{commerce platform name} to
{accounting platform name}.

configure-content-sales-accounts-description

Other

configure-content-sales-other-title

Other title description: no value by default.

configure-content-sales-other-description

Sales feature categories

Default value

data-textkey value

Sales

configure-content-sales-accounts-entries-sales

Refunds

configure-content-sales-accounts-entries-refund

Gratuity

configure-content-sales-accounts-entries-gratuity

Prepaid

configure-content-sales-accounts-entries-prepaid

0% tax rate

configure-content-sales-accounts-taxRates-entries-0

5% tax rate

configure-content-sales-accounts-taxRates-entries-10

10% tax rate

configure-content-sales-accounts-taxRates-entries-15

20% tax rate

configure-content-sales-accounts-taxRates-entries-20

Invoice status

configure-content-sales-other-entries-invoiceStatus

Grouping period

configure-content-sales-other-entries-groupingPeriod

Fees title and description

Default value

data-textkey value

Fees

configure-content-sales-title

Fees title description:
no value by default.

configure-content-fees-description

Fees feature categories title and description

Default value

data-textkey value

Accounts

configure-content-fees-accounts-title

Configure accounts mapping from
{commerce platform name} to
{accounting platform name}.

configure-content-fees-accounts-description

Fees feature categories

Default value

data-textkey value

Payment fee

configure-content-fees-accounts-entries-paymentFee

Payment fee refund

configure-content-fees-accounts-entries-paymentFeeRefund

Loan

configure-content-fees-accounts-entries-loan

Loan payment

configure-content-fees-accounts-entries-loanPayment

Loan fee

configure-content-fees-accounts-entries-loanFee

Cashback

configure-content-fees-accounts-entries-cashback

Payments title and description

Default value

data-textkey value

Payments

configure-content-payments-title

Payments title description:
no value by default.

configure-content-payments-description

Payments feature categories

Default value

data-textkey value

Card

configure-content-payments-accounts-entries-card

Cash

configure-content-payments-accounts-entries-cash

Invoice

configure-content-payments-accounts-entries-invoice

Online card

configure-content-payments-accounts-entries-onlineCard

Payout

configure-content-payments-accounts-entries-payout

Custom

configure-content-payments-accounts-entries-custom

Store credit

configure-content-payments-accounts-entries-storeCredit

Paypal

configure-content-payments-accounts-entries-paypal

Paypal qr

configure-content-payments-accounts-entries-paypalQr

Mobile

configure-content-payments-accounts-entries-mobile

Vipps

configure-content-payments-accounts-entries-vipps

Swish

configure-content-payments-accounts-entries-swish

Prepaid pyment

configure-content-payments-accounts-entries-prepaidPayment

Manual

configure-content-payments-accounts-entries-manual

How to change the visibility of feature categories

To update the visibility of accounts for a commerce platform, perform the following request:

POST sync/commerce/config/ui/accounts/platform/{commerceKey}

//Request body:
//To update the visible feature categories to the ones provided in the request body:
{
    "visibleAccounts": [
         "account-key-1",
         "account-key-2"
    ]
}

//To revert to the default settings and show all feature categories:
{}

//To show only the fields that are required:
{
  "visibleAccounts": []
}

In the request above, the commerceKey is the Codat platform key of the selected commerce platform. You can find a list of keys for the supported platforms in the Accounting platform selection section.
To find the account-key, consult the tables below. Note that fields marked with an '*' cannot be removed.

Sales feature categories

Default value

account-key

Sales*

sales-accounts-sales

Refund*

sales-accounts-refunds

Gratuity

sales-accounts-gratuity

Prepaid

sales-accounts-prepaid

0% tax rate*

sales-taxRates-0

5% tax rate*

sales-taxRates-5

10% tax rate*

sales-taxRates-10

20% tax rate*

sales-taxRates-20

Invoice status*

sales-other-invoiceStatus

Grouping period*

sales-other-groupingPeriod

Fees feature categories

Default value

account-key

Payment fee

fees-accounts-paymentFee

Payment fee refund

fees-accounts-paymentFeeRefund

Loan

fees-accounts-loan

Loan payment

fees-accounts-loanPayment

Loan fee

fees-accounts-loanFee

Cashback

fees-accounts-cashback

Payments feature categories

Default value

account-key

Card*

payments-accounts-card

Cash

payments-accounts-cash

Invoice

payments-accounts-invoice

Online card

payments-accounts-onlineCard

Payout

payments-accounts-payout

Custom

payments-accounts-custom

Store credit

payments-accounts-storeCredit

Paypal

payments-accounts-paypal

Paypal qr

payments-accounts-paypalQr

Mobile

payments-accounts-mobile

Vipps

payments-accounts-vipps

Swish

payments-accounts-swish

Prepaid payment

payments-accounts-prepaidPayment

Manual

payments-accounts-manual


Did this page help you?