Skip to main content

​
Overview

Link a payout destination (debit card) 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 CARD, 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): CARD – Debit card (push-to-card).

​
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: CARD.
stepstringYesStep in the flow; typically 1.

​
Request Body

Every request must include:
FieldTypeRequiredDescription
labelstringYesNickname for this linked account (e.g. “My debit card”).
dataobjectYesPayload for CARD; see below.

​
CARD – data fields

FieldTypeRequiredDescription
namestringYes if businessBusiness name.
firstNamestringYes if personalCardholder first name.
lastNamestringYes if personalCardholder last name.
emailstringYesValid email.
cardNumberstringYes16-digit card number.
cardExpirationDatestringYesExpiry in YYYY-MM (e.g. 2026-04).
recipientAddressstringYesStreet address.
recipientCitystringYesCity.
recipientStatestringYes2-letter state code.
recipientPostalCodestringYesUS ZIP.
nickNamestringNoNickname for this linked account (e.g. “MayetopsC”). If omitted, top-level label is used.

​
Request Example

​
Personal card

curl -X POST "{{LIQUIDITY_URL}}/v1/ext/application-token/{{token}}/linked-accounts/USD/link/CARD/1" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "My debit card",
    "data": {
      "recipientType": "personal",
      "firstName": "John",
      "lastName": "Smith",
      "email": "john.smith@example.com",
      "cardNumber": "5555555555554444",
      "cardExpirationDate": "2026-04",
      "recipientAddress": "789 Oak St",
      "recipientCity": "Los Angeles",
      "recipientState": "CA",
      "recipientPostalCode": "90001",
      "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.
Personal account400firstName and lastName required when recipientType is personal.
Business account400name required when recipientType is business.
card number400Exactly 16 digits.
expiration400Format YYYY-MM.
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, CARD (must match path).
  • data – Required; structure as above.
  • recipientType – Required; personal or business.
  • cardNumber – Exactly 16 digits.
  • cardExpirationDate – YYYY-MM.

​
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 CARD, payouts are push-to-card regardless of routing.
  • Do not send card number in logs or client-side storage; treat as sensitive.
  • 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}.