Link Card Account

​

Overview

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).

​

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

​

Request Body

​

CARD – data fields

​

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"
  }
}

• 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

​

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}.