Skip to main content

​
Overview

Create a linked account widget—a shareable URL that directs end users to link their payout method (bank, card, or international bank). Use this when you want users to add a linked account without initiating a withdrawal. The integration obtains an application token and URL, then redirects users to complete account linking.

​
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

FieldTypeDescriptionRequired
tokenTypestringMust be ACCOUNT_WIDGETYes
currencystringCurrency code (e.g., USD)Yes
useLinkAccountPathbooleanWhen true, the generated URL goes directly to the link-account flowYes
redirectTostringURL to redirect the user after they complete account linkingNo
extraobjectAdditional optionsNo
extra.withdrawalSourcestringMust be MERCHANT_WALLETNo
extra.counterpartyobjectCounterparty info for the linked accountNo
extra.counterparty.firstNamestringCounterparty first nameNo
extra.counterparty.lastNamestringCounterparty last nameNo
extra.counterparty.emailstringCounterparty emailNo

​
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

FieldTypeDescription
data.urlstringShareable linked-account widget URL
data.application.idstringApplication ID
data.application.tokenstringApplication token
data.application.tokenTypestringToken type: ACCOUNT_WIDGET
data.application.expiredAtstringExpiration datetime (ISO 8601)
data.application.validbooleanWhether the token is currently valid
data.customerIdstringCustomer/entity ID associated with this widget

​
Important: Append entityId to the URL

Before redirecting your end user to the widget, you must add the customerId from the response to the URL as the entityId query parameter. Example: If the response returns:
  • url: https://sandbox.accounts.centryos.xyz/link-account/sATkWLobCODYbvJCC7asBYuCFVyvVI?t=...
  • customerId: MDMxNzMxZmQtOTAzMC00OTIxLTk3NmQtNjk3ZWU3Y2JjYzZi
Then the final URL you redirect the user to should be: 
https://sandbox.accounts.centryos.xyz/link-account/sATkWLobCODYbvJCC7asBYuCFVyvVI?t=...&entityId=MDMxNzMxZmQtOTAzMC00OTIxLTk3NmQtNjk3ZWU3Y2JjYzZi
Use entityId={{customerId}} — append &entityId= followed by the customerId value from the response. Without this, the widget cannot associate the linked account with the correct customer.

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