> ## 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.
# Link Account
> Link a merchant account in development.
Before using this endpoint, it is recommended to setup a webhook for the development environment in the [Knot Dashboard](https://dashboard.knotapi.com/developers/webhooks) 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`](/link/webhook-events/authenticated) event to your webhook, then POST card data to the [`Send Card (JWE)`](/api-reference/products/card-switcher/switch-card-jwe) or [`Send Card`](/api-reference/products/card-switcher/switch-card) endpoint.
3. Receive notification of the result via the [`CARD_UPDATED`](/card-switcher/webhook-events/card-updated) or [`CARD_FAILED`](/card-switcher/webhook-events/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.
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`](/link/webhook-events/authenticated) event to your webhook.
3. Generate sample transactions.
4. Receive notification of the transactions via the [`NEW_TRANSACTIONS_AVAILABLE`](/transaction-link/webhook-events/new-transactions-available) event to your webhook.
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`](/link/webhook-events/authenticated) event to your webhook.
3. Begin making requests to [Sync Cart](/api-reference/products/shopping/sync-cart) and [Checkout](/api-reference/products/shopping/checkout).
## OpenAPI
````yaml POST /development/accounts/link
openapi: 3.1.0
info:
title: Knot API
description: An API to interact with the Knot merchant connectivity platform.
version: 1.0.0
servers:
- url: https://development.knotapi.com
description: Development server
security:
- basicAuth: []
paths:
/development/accounts/link:
post:
description: Link a merchant account in development.
operationId: development_accounts_link
requestBody:
description: >-
The input parameters required for linking a merchant account in
development.
required: true
content:
application/json:
schema:
oneOf:
- title: CardSwitcher
type: object
properties:
external_user_id:
type: string
description: Your unique identifier for the user.
example: abc123
merchant_id:
type: integer
description: Unique identifier for the merchant.
example: 19
card_switcher:
type: boolean
description: When set to true, simulates the card switcher flow.
example: true
card_id:
type: string
description: >-
Your unique identifier for a specific card. Required
when `card_switcher` is `true`.
example: 81n9al10a0ayn13
metadata:
type:
- object
- 'null'
additionalProperties:
type: string
maxLength: 500
maxProperties: 10
description: >-
Optional key-value pairs to include in webhook payloads.
Maximum 10 keys, 500 characters per value.
example:
reference_token: abc123
trace_id: def456
default: null
required:
- external_user_id
- merchant_id
- card_switcher
- card_id
- title: TransactionLink
type: object
properties:
external_user_id:
type: string
description: Your unique identifier for the user.
example: abc123
merchant_id:
type: integer
description: Unique identifier for the merchant.
example: 19
transactions:
type: object
description: >-
Configuration for whether to receive transactions when
linking the account.
properties:
new:
type: boolean
description: >-
Whether to generate new transactions and receive
notification of them via the
[`NEW_TRANSACTIONS_AVAILABLE`](/transaction-link/webhook-events/new-transactions-available)
event to your webhook for testing.
example: true
default: true
updated:
type: boolean
description: >-
Whether to update newly-generated transactions and
receive notification of them via the
[`UPDATED_TRANSACTIONS_AVAILABLE`](/transaction-link/webhook-events/updated-transactions-available)
event to your webhook for testing. You must pass
`new: true` in the request to use this parameter.
example: false
default: false
required:
- new
metadata:
type:
- object
- 'null'
additionalProperties:
type: string
maxLength: 500
maxProperties: 10
description: >-
Optional key-value pairs to include in webhook payloads.
Maximum 10 keys, 500 characters per value.
example:
reference_token: abc123
trace_id: def456
default: null
required:
- external_user_id
- merchant_id
- transactions
- title: Shopping
type: object
properties:
external_user_id:
type: string
description: Your unique identifier for the user.
example: abc123
merchant_id:
type: integer
description: Unique identifier for the merchant.
example: 19
metadata:
type:
- object
- 'null'
additionalProperties:
type: string
maxLength: 500
maxProperties: 10
description: >-
Optional key-value pairs to include in webhook payloads.
Maximum 10 keys, 500 characters per value.
example:
reference_token: abc123
trace_id: def456
default: null
required:
- external_user_id
- merchant_id
examples:
CardSwitcher:
summary: Card Switcher
value:
external_user_id: abc123
merchant_id: 19
card_switcher: true
card_id: 81n9al10a0ayn13
TransactionLink:
summary: Transaction Link
value:
external_user_id: abc123
merchant_id: 45
transactions:
new: true
updated: false
Shopping:
summary: Shopping
value:
external_user_id: abc123
merchant_id: 44
responses:
'200':
description: Successful request.
content:
application/json:
schema:
type: object
properties:
message:
type: string
description: Success message.
example: Success
'400':
description: Bad request.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
ExternalUserIdRequired:
summary: external_user_id is required
value:
error_type: INVALID_REQUEST
error_code: INVALID_FIELD
error_message: The external_user_id field is required.
MerchantIdRequired:
summary: merchant_id is required
value:
error_type: INVALID_REQUEST
error_code: INVALID_FIELD
error_message: The merchant_id field is required.
InvalidMerchantId:
summary: merchant_id is invalid
value:
error_type: INVALID_REQUEST
error_code: INVALID_FIELD
error_message: The selected merchant_id is invalid.
InvalidTransactions:
summary: transactions must be an array
value:
error_type: INVALID_REQUEST
error_code: INVALID_FIELD
error_message: The transactions must be an array.
InvalidTransactionsNew:
summary: transactions.new must be boolean
value:
error_type: INVALID_REQUEST
error_code: INVALID_FIELD
error_message: The transactions.new must be true or false.
InvalidTransactionsUpdated:
summary: transactions.updated must be boolean
value:
error_type: INVALID_REQUEST
error_code: INVALID_FIELD
error_message: The transactions.updated must be true or false.
UserNotFound:
summary: User not found when updating transactions
value:
error_type: USER_ERROR
error_code: USER_NOT_FOUND
error_message: >-
The user was not found. Cannot update transactions for a
non-existent user.
MerchantAccountNotFound:
summary: Merchant account not found when updating transactions
value:
error_type: MERCHANT_ACCOUNT_ERROR
error_code: MERCHANT_ACCOUNT_NOT_FOUND
error_message: >-
The merchant account does not exist. Cannot update
transactions for a non-existent merchant account.
NoTransactionsToUpdate:
summary: No transactions to update
value:
error_type: MERCHANT_ACCOUNT_ERROR
error_code: NO_TRANSACTIONS
error_message: >-
The merchant account does not have any transactions to
update.
'401':
description: Unauthorized request.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
AuthFailed:
summary: Auth failed
value:
error_type: INVALID_INPUT
error_code: INVALID_API_KEYS
error_message: Invalid client_id or secret provided.
'500':
description: Internal server error.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
InternalServerError:
summary: Unexpected server error
value:
message: Server Error
components:
schemas:
Error:
type: object
properties:
error_type:
type: string
description: Type of error.
enum:
- INVALID_INPUT
- INVALID_REQUEST
- USER_ERROR
- SESSION_ERROR
- MERCHANT_ACCOUNT_ERROR
- MERCHANT_ERROR
- SUBSCRIPTION_ERROR
- TRANSACTION_ERROR
- CART_ERROR
example: INVALID_REQUEST
error_code:
type: string
description: Error code.
enum:
- INVALID_API_KEYS
- INVALID_FIELD
- INVALID_JWE
- INVALID_CURSOR_FORMAT
- USER_NOT_FOUND
- MERCHANT_ACCOUNT_NOT_FOUND
- MERCHANT_ACCOUNT_DISCONNECTED
- SESSION_NOT_FOUND
- EXTEND_NOT_SUPPORTED
- MERCHANT_UNAVAILABLE
- NO_ACCESS
- TRANSACTION_NOT_FOUND
- NO_TRANSACTIONS
- SUBSCRIPTION_NOT_FOUND
- ONGOING_OPERATION
- CART_NOT_FOUND
- FULFILLMENT_NOT_FOUND
example: INVALID_FIELD
error_message:
type: string
description: Detailed error message.
example: The limit may not be greater than 10.
securitySchemes:
basicAuth:
type: http
scheme: basic
description: >-
Basic authentication header of the form `Basic `, where
`` is the base64-encoded string `username:password`. Use
your `client_id` as the `username` and your `secret` as the `password`
value.
````