Merchant Link
Customers use Merchant Link to verify credentials and connect accounts.
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
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
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
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
Step 3. Initialize Merchant Link
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.