Skip to main content

​
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:
  1. Obtain an application token (e.g. account-widget token).
  2. Call this endpoint with the token, currency, option BANK, step (e.g. 1), and the required body.
  3. 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

ParameterTypeRequiredDescription
tokenstringYesApplication token (e.g. account-widget token).
currencystringYesCurrency. For this doc: USD.
optionstringYesLink type: BANK.
stepstringYesStep in the flow; typically 1.

​
Request Body

Every request must include:
FieldTypeRequiredDescription
labelstringYesNickname for this linked account (e.g. “My checking”).
optionstringYesMust match path: BANK.
dataobjectYesPayload for BANK; see below.

​
BANK – data fields

FieldTypeRequiredDescription
recipientTypestringYes"personal" or "business".
namestringYes if businessLegal business name. Omit or leave empty for personal.
firstNamestringYes if personalAccount holder first name.
lastNamestringYes if personalAccount holder last name.
emailstringYesValid email.
accountNumberstringYesBank account number.
routingNumberstringYes9-digit US routing number (leading zero allowed).
typestringYesAccount type: CHECKING, SAVINGS, or BUSINESS.
bankNamestringYesName of the bank.
recipientAddressstringYesStreet address.
recipientCitystringYesCity.
recipientStatestringYes2-letter US state code (e.g. NY, CA).
recipientPostalCodestringYesUS ZIP (e.g. 10001 or 10001-1234).
routingTypestringYesACH, RTP, or WIRE.
nickNamestringNoNickname 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"
  }
}
FieldTypeDescription
successbooltrue on success
messagestring"Account successfully linked!"
data.idstringLinked 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

SituationHTTPNotes
Invalid/expired token400”Invalid or expired application token”.
Wrong token type400Token must be account-widget type.
Validation error400Missing/invalid fields (e.g. email, state, routingType).
Personal account400firstName and lastName required when recipientType is personal.
Business account400name required when recipientType is business.
recipientState400Must be 2-letter uppercase (e.g. NY).
recipientPostalCode400Must be US ZIP (5 or 5+4).
routingType400Must be ACH, RTP, or WIRE.
Duplicate nickname400”Nickname already exists, please choose a different nickname”.
No platform account400No wallet found for entity/currency.
Processing error500Message 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}.