Link Bank Account

Overview

Link a payout destination (US bank account) for an entity using an application token. The token is passed in the URL; no Bearer auth is required for this endpoint. Typical flow:

Obtain an application token (e.g. account-widget token).
Call this endpoint with the token, currency, option BANK, step (e.g. 1), and the required body.
On success, use the returned data.id for payouts (e.g. Withdraw to Linked Account).

Supported (USD): BANK – US bank account (ACH / RTP / wire).

Endpoint

POST {{LIQUIDITY_URL}}/v1/ext/application-token/:token/linked-accounts/:currency/link/:option/:step
Auth: None (token is in the URL). Do not send Authorization header.
Headers: Content-Type: application/json required.

Path Parameters

Parameter	Type	Required	Description
`token`	string	Yes	Application token (e.g. account-widget token).
`currency`	string	Yes	Currency. For this doc: `USD`.
`option`	string	Yes	Link type: `BANK`.
`step`	string	Yes	Step in the flow; typically `1`.

Request Body

Every request must include:

Field	Type	Required	Description
`label`	string	Yes	Nickname for this linked account (e.g. “My checking”).
`option`	string	Yes	Must match path: `BANK`.
`data`	object	Yes	Payload for BANK; see below.

BANK – data fields

Field	Type	Required	Description
`recipientType`	string	Yes	`"personal"` or `"business"`.
`name`	string	Yes if business	Legal business name. Omit or leave empty for personal.
`firstName`	string	Yes if personal	Account holder first name.
`lastName`	string	Yes if personal	Account holder last name.
`email`	string	Yes	Valid email.
`accountNumber`	string	Yes	Bank account number.
`routingNumber`	string	Yes	9-digit US routing number (leading zero allowed).
`type`	string	Yes	Account type: `CHECKING`, `SAVINGS`, or `BUSINESS`.
`bankName`	string	Yes	Name of the bank.
`recipientAddress`	string	Yes	Street address.
`recipientCity`	string	Yes	City.
`recipientState`	string	Yes	2-letter US state code (e.g. NY, CA).
`recipientPostalCode`	string	Yes	US ZIP (e.g. 10001 or 10001-1234).
`routingType`	string	Yes	`ACH`, `RTP`, or `WIRE`.
`nickName`	string	No	Nickname for this linked account (e.g. “MayetopsC”). If omitted, top-level `label` is used.

Request Examples

Personal bank account (ACH)

curl -X POST "{{LIQUIDITY_URL}}/v1/ext/application-token/{{token}}/linked-accounts/USD/link/BANK/1" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "My checking",
    "option": "BANK",
    "data": {
      "recipientType": "personal",
      "firstName": "Jane",
      "lastName": "Doe",
      "email": "jane.doe@example.com",
      "accountNumber": "7400244922",
      "routingNumber": "021002220",
      "type": "CHECKING",
      "bankName": "Chase",
      "recipientAddress": "123 Main St",
      "recipientCity": "New York",
      "recipientState": "NY",
      "recipientPostalCode": "10001",
      "routingType": "ACH",
      "nickName": "MayetopsC"
    }
  }'

Business bank account (RTP)

{
  "label": "Company operating account",
  "option": "BANK",
  "data": {
    "recipientType": "business",
    "name": "Acme Inc",
    "email": "payments@acme.com",
    "accountNumber": "9876543210",
    "routingNumber": "021002220",
    "type": "BUSINESS",
    "bankName": "Chase",
    "recipientAddress": "456 Business Ave",
    "recipientCity": "New York",
    "recipientState": "NY",
    "recipientPostalCode": "10002",
    "routingType": "RTP",
    "nickName": "MayetopsC"
  }
}

Response

Success (200)

{
  "success": true,
  "message": "Account successfully linked!",
  "data": {
    "id": "845a276a-3c5a-45ff-9aa9-6b266a77f92a"
  }
}

Field	Type	Description
`success`	bool	`true` on success
`message`	string	`"Account successfully linked!"`
`data.id`	string	Linked account ID — use this for withdrawal requests

Use data.id when calling the withdrawal endpoint:
POST /v1/ext/linked-accounts/{currency}/{linkedAccountId}/withdrawal

Error (4xx / 5xx)

{
  "success": false,
  "message": "<error detail or validation messages>",
  "fatal": true
}

Typical Error Cases

Situation	HTTP	Notes
Invalid/expired token	400	”Invalid or expired application token”.
Wrong token type	400	Token must be account-widget type.
Validation error	400	Missing/invalid fields (e.g. email, state, routingType).
Personal account	400	`firstName` and `lastName` required when `recipientType` is personal.
Business account	400	`name` required when `recipientType` is business.
recipientState	400	Must be 2-letter uppercase (e.g. NY).
recipientPostalCode	400	Must be US ZIP (5 or 5+4).
routingType	400	Must be ACH, RTP, or WIRE.
Duplicate nickname	400	”Nickname already exists, please choose a different nickname”.
No platform account	400	No wallet found for entity/currency.
Processing error	500	Message may reflect processing or server error.

Validation Summary

label – Required, any non-empty string.
option – Required, BANK (must match path).
data – Required; structure as above.
recipientType – Required; personal or business; drives requirement for name vs firstName/lastName.
routingType – Required; one of ACH, RTP, WIRE.

Notes for Integrators

Obtain a valid application token (account-widget type) before calling this endpoint.
Use the returned data.id when calling the external withdrawal API.
For BANK, choose ACH, RTP, or WIRE via routingType.
Same endpoint is used for non-external path with token in URL; external path is POST /v1/ext/application-token/{token}/linked-accounts/{currency}/link/{option}/{step}.

Getting Started

Authentication

Account

Wallets

Transactions

Payin

Payout

Linked Accounts

Webhooks

Link Bank Account

Overview

Endpoint

Path Parameters

Request Body

BANK – data fields

Request Examples

Personal bank account (ACH)

Business bank account (RTP)

Response

Success (200)

Error (4xx / 5xx)

Typical Error Cases

Validation Summary

Notes for Integrators

​Overview

​Endpoint

​Path Parameters

​Request Body

​BANK – data fields

​Request Examples

​Personal bank account (ACH)

​Business bank account (RTP)

​Response

​Success (200)

​Error (4xx / 5xx)

​Typical Error Cases

​Validation Summary

​Notes for Integrators

Overview

Endpoint

Path Parameters

Request Body

BANK – data fields

Request Examples

Personal bank account (ACH)

Business bank account (RTP)

Response

Success (200)

Error (4xx / 5xx)

Typical Error Cases

Validation Summary

Notes for Integrators