Skip to main content

​
Overview

Create a payout link (application token) tied to an end-user/business (externalId). This link enables users to link their accounts (bank, card, or international bank) and initiate withdrawals. The link can be shared with end users to complete payout flows.

​
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 '{
    "externalId": "{{$randomUUID}}",
    "expiredAt": "{{$randomDateFuture}}",
    "tokenType": "PAYOUT_LINK",
    "currency": "USD",
    "extra": {
      "accountOptions": ["bank", "card", "international_bank", "zelle", "venmo", "paypal", "prepaid_card"]
    }
  }'

​
Request Body Fields

FieldTypeDescriptionRequired
externalIdstringEnd-user/business identifier to tie the payoutYes
expiredAtstringExpiration datetime (ISO 8601 format)Yes
tokenTypestringUse PAYOUT_LINK (or configured payout token type)Yes
currencystringCurrency code (e.g., USD)Yes
extraobjectAdditional optionsOptional
extra.accountOptionsarrayArray of account types to allow: bank, card, international_bank, zelle, venmo, paypal, prepaid_cardOptional
extra.counterpartyobjectCounterparty information (name, email)Optional

​
Extra Fields (Optional)

The extra object can include:
FieldTypeDescriptionRequired
accountOptionsarrayAllowed account types: bank, card, international_bank, zelle, venmo, paypal, prepaid_cardNo
counterparty.namestringName of the counterpartyNo
counterparty.emailstringEmail of the counterpartyNo

​
Response (200)

{
  "data": {
    "url": "https://sandbox.accounts.centryos.xyz/sATjgfpPo1QyfoSFJSQHWTr9Gr3cow",
    "application": {
      "id": "d4c26920-7040-4b12-9ff1-5853f5977f20",
      "token": "sATjgfpPo1QyfoSFJSQHWTr9Gr3cow",
      "tokenType": "PAYOUT_LINK",
      "expiredAt": "2024-07-11T06:57:08.000Z",
      "valid": true
    }
  }
}

​
Response Fields

FieldTypeDescription
data.urlstringShareable payout link URL
data.application.idstringApplication ID
data.application.tokenstringApplication token (use for API calls)
data.application.tokenTypestringToken type: PAYOUT_LINK
data.application.expiredAtstringExpiration datetime (ISO 8601)
data.application.validbooleanWhether the token is currently valid

​
Usage Flow

  1. Create Payout Link: Use this endpoint to generate a payout link
  2. Share Link: Share the url with your end user
  3. Link Account: User uses the link to link their account (bank, card, or international bank)
  4. Withdraw: Use the linked account ID to initiate withdrawals via the withdrawal endpoint

​
Notes

  • Share the returned url as the payout link with your end users
  • Set appropriate expiredAt to limit link lifetime and security
  • Use externalId to correlate payouts to your user/business for tracking
  • The token from the response can be used in API calls to link accounts programmatically
  • Use extra.accountOptions to restrict which account types users can link
  • The link expires at the expiredAt datetime; create new links as needed
  • Store the application.id and token for tracking and follow-up operations