Introduction

Merchant Link is the client-side component that your customers interact with to link their merchant accounts.

Merchant Link handles credential validation, multi-factor authentication, and error handling for each merchant that Subtotal supports.

Check out our demo of Merchant Link to see how it works.

Merchant Link is the only available method for connecting merchant accounts and is required for all Subtotal integrations.

Configuration

Sign into the Subtotal Dashboard to configure each of the items below.

  • Logo - Upload your logo to brand the Merchant Link experience for your customers.
  • Link URL - The default URL for Merchant Link is link.subtotal.com. Configuring a subdomain of your primary domain is recommended.
  • Merchants - Specify a list of merchants that customers may link for your project.

The flow

The flow begins when a customer chooses to connect their merchant account to your app or website. We’ll guide you through each step to ensure a smooth integration.

Step 1. Create a new connection

Connections represent links between customers’ merchant accounts and your system.

To create a connection, send a POST /connection request. Include a customer_id and merchant_id in the request body to specify which customer is establishing a connection to which merchant.

Request body

{
   "customer_id": "8a46e581-48ba-498a-9ad0-2ee72582e1af",
   "merchant_id": "01J7SC0NN73R6F5AVSP3XKPDV2"
}

A successful response will include a 201 Created status code and a connection_id.

The connection_id is a unique identifier that you’ll store on your system and use in future API requests.

Response body

{
   "connection_id": "01ARZ3NDEKTSV4RRFFQ69G5FAV"
}

New connections have a Pending Link status. You can view the status of any connection you have created by sending a GET /connection/{connection_id} request.

Step 2. Request a connection token

Connection tokens are short-lived JWTs that are used to authorize access to Merchant Link or other resources in the Subtotal API.

To create a connection token, send a POST /connection/{connection_id}/token request. Include the connection_id from the previous step as a URL parameter to specify which connection you’re creating a token for.

Set the scope to link in the request body to specify that this connection token will be used with Merchant Link.

Request body

{
  "scope": "link"
}

A successful response will include a 201 Created status code and a connection_token.

You’ll pass the connection_token to Merchant Link in the next step.

Response body

{
   "connection_token": "eyJhbGciOiAiUlMyNTYiLCAidHlwIjogIkpXVCJ9.eyJpc3MiOiAiYXV0aC50eXBlY2FzdGxlLmNvbSIsICJzdWIiOiAiMDFKN1M5VFEyOENRSkQ1WTVaTlZQR0NTNkgiLCAiYXVkIjogInR5cGVjYXN0bGVfYXBpIiwgImV4cCI6IDE3MzkyNDM2MjYsICJpYXQiOiAxNzM5MjQxODI2LCAianRpIjogIjAxSktTRThBRzU4SFlCQkE2UDkwMTBWMjRIIiwgImNsaWVudF9pZCI6ICIwMUo3UzlUUTI4Q1FKRDVZNVpOVlBHQ1M2SCIsICJjb25uZWN0aW9uX2lkIjogIjAxSktTRTdRMU4xS1IxQUFBUEJCQVA0M0I1IiwgInNjb3BlIjogImFjY2VzcyJ9.OdAuJiA9sLyMyffIXhkg721bB-yRizmRTs0C-gmtGzlBplJq7qvOoxxcunfDNQw2PdU8zFMlBvwLUbuQsjthX1wcbGO0TsPgcS0-_MoAZ-WR5ZdbP4qTemZfmirMjVXXdA4oUtQwc-zxJwrZ0hn0Lb1ctKLmtnJhXoXVXRfGeby_0VmHhVJiUuzLSxnKsYnrrcTn9V8zR4BlMNmWWmr_rL5FomTgCCrj0xD_dsOZcg12rhWv4A3S7oOsJAL9-0poXSMdj9k5o0zT3-HdrFgHbbQIkGbHwcaz5KvwgPl35xZG-fTBZH0J-azQDZBC-aX59mFxxrTI_mJb8OUgtsSsbA"
}

From your front-end application, redirect your users to the Link URL configured for your project. Include the connection_token as a query parameter in the URL.

Additionally, include redirect_url as a query parameter in the URL. Customers will be redirected to this URL after their session with Merchant Link is complete.

Connections move to an Active status when a customer successfully verifies their credentials and links their account.

Next steps

Take a look at our recommended next steps.