Skip to main content
POST
/
development
/
accounts
/
link
curl --request POST \
  --url https://development.knotapi.com/development/accounts/link \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "external_user_id": "abc123",
  "merchant_id": 19,
  "card_switcher": true,
  "card_id": "81n9al10a0ayn13"
}
'
{
  "message": "Success"
}

Documentation Index

Fetch the complete documentation index at: https://docs.knotapi.com/llms.txt

Use this file to discover all available pages before exploring further.

Before using this endpoint, it is recommended to setup a webhook for the development environment in the Knot Dashboard if you have not done so already.

​
Overview

This endpoint is used to manually link a user’s merchant account in the development environment for testing purposes without the need to install or invoke the client-side SDK. Calling this endpoint will generate a linked merchant account on the Knot platform for a specific user & merchant and optionally simulate the card switcher flow (by passing card_switcher: true) or generate new transactions (by passing the transactions object in the request).

​
Usage

You can test all of the following without use of the client-side SDK:
  1. Link a merchant account to the Knot platform.
  2. Receive notification of the link via the AUTHENTICATED event to your webhook, then POST card data to the Send Card (JWE) or Send Card endpoint.
  3. Receive notification of the result via the CARD_UPDATED or CARD_FAILED event.
The card_id parameter is required when card_switcher is true. The card_switcher parameter is mutually exclusive with the transactions parameter. You cannot use both in the same request.

Authorizations

​
Authorization
string
header
required

Basic authentication header of the form Basic <encoded-value>, where <encoded-value> is the base64-encoded string username:password. Use your client_id as the username and your secret as the password value.

Body

application/json

The input parameters required for linking a merchant account in development.

​
external_user_id
string
required

Your unique identifier for the user.

Example:

"abc123"

​
merchant_id
integer
required

Unique identifier for the merchant.

Example:

19

​
card_switcher
boolean
required

When set to true, simulates the card switcher flow.

Example:

true

​
card_id
string
required

Your unique identifier for a specific card. Required when card_switcher is true.

Example:

"81n9al10a0ayn13"

​
metadata
object

Optional key-value pairs to include in webhook payloads. Maximum 10 keys, 500 characters per value.

Example:
{
  "reference_token": "abc123",
  "trace_id": "def456"
}

Response

Successful request.

​
message
string

Success message.

Example:

"Success"