Create Linked Account Widget

​

Overview

​

Prerequisites

• Valid access token

​

Endpoint

• POST {{LIQUIDITY_URL}}/v1/ext/application-token
• Auth: Bearer {{accessToken}}

​

Request

curl -X POST "{{LIQUIDITY_URL}}/v1/ext/application-token" \
  -H "Authorization: Bearer {{accessToken}}" \
  -H "Content-Type: application/json" \
  -d '{
    "tokenType": "ACCOUNT_WIDGET",
    "currency": "USD",
    "useLinkAccountPath": true,
    "redirectTo": "https://your-merchant.com/thank-you",
    "extra": {
      "withdrawalSource": "MERCHANT_WALLET",
      "counterparty": {
        "firstName": "Jane",
        "lastName": "Doe",
        "email": "jane@example.com"
      }
    }
  }'

​

Request Body Fields

​

Response (200)

{
  "data": {
    "url": "https://sandbox.accounts.centryos.xyz/link-account/sATkWLobCODYbvJCC7asBYuCFVyvVI?t=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "application": {
      "id": "4c1c5cc2-2ada-4ecd-a49c-9db1d0094079",
      "token": "sATkWLobCODYbvJCC7asBYuCFVyvVI",
      "tokenType": "ACCOUNT_WIDGET",
      "expiredAt": "2027-02-07T13:07:54.520Z",
      "valid": true
    },
    "customerId": "MDMxNzMxZmQtOTAzMC00OTIxLTk3NmQtNjk3ZWU3Y2JjYzZi"
  },
  "success": true
}

​

Response Fields

​

Important: Append entityId to the URL

• url: https://sandbox.accounts.centryos.xyz/link-account/sATkWLobCODYbvJCC7asBYuCFVyvVI?t=...
• customerId: MDMxNzMxZmQtOTAzMC00OTIxLTk3NmQtNjk3ZWU3Y2JjYzZi

https://sandbox.accounts.centryos.xyz/link-account/sATkWLobCODYbvJCC7asBYuCFVyvVI?t=...&entityId=MDMxNzMxZmQtOTAzMC00OTIxLTk3NmQtNjk3ZWU3Y2JjYzZi

​

Usage Flow

1. Create linked account widget: Call this endpoint with useLinkAccountPath: true.
2. Append entityId: Add entityId={{customerId}} to the returned url.
3. Share or redirect: Redirect your end user to the final URL so they can link their bank, card, or international bank account.
4. Post-linking: After linking, users can be redirected to your redirectTo URL, and you can use the linked account for payouts via Withdraw to Linked Account.

​

Notes

• useLinkAccountPath: true ensures the URL goes directly to the account-linking flow (no withdrawal step).
• Store customerId and use it to append entityId before redirecting users.
• The link expires at data.application.expiredAt; create new links as needed.
• Use redirectTo to send users to a thank-you or confirmation page after linking.