Skip to main content

​
Overview

Create a withdrawal widget (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 withdrawal 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 '{
    "expiredAt": "{{$randomDateFuture}}",
    "tokenType": "ACCOUNT_WIDGET",
    "currency": "USD",
    "extra": {
        "withdrawalSource": "MERCHANT_WALLET",
        "amount": 10,
        "counterparty": {
            "firstName": "{{$randomFirstName}}",
            "lastName": "{{$randomLastName}}",
            "email": "makindetimi+87@gmail.com"
        }
    }
  }'

​
Request Body Fields

FieldTypeDescriptionRequired
expiredAtstringExpiration datetime (ISO 8601 format)Yes
tokenTypestringMust be ACCOUNT_WIDGETYes
currencystringCurrency code (e.g., USD)Yes
feeHiddenbooleantrue or falseNo
redirectTostringURL to redirect the user after payout completion (e.g., https://yoursite.com/success)No
extraobjectAdditional optionsNo
extra.accountOptionsarrayAllowed payout methods: bank, card, international_bank. Defaults to ["bank", "card"]No
extra.withdrawalSourcestringMust be MERCHANT_WALLETYes
extra.amountnumberAmount tied to the application tokenYes
extra.counterpartyobjectCounterparty infoYes
extra.counterparty.firstNamestringCounterparty first nameYes
extra.counterparty.lastNamestringCounterparty last nameYes
extra.counterparty.emailstringCounterparty emailYes

​
Response (200)

{
  "data": {
    "url": "https://sandbox.accounts.centryos.xyz/sATjgfpPo1QyfoSFJSQHWTr9Gr3cow?t=eyJhbGciOiJIUzI1NiIsI...",
    "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 withdrawal widget URL
data.application.idstringApplication ID
data.application.tokenstringApplication token (use for API calls)
data.application.tokenTypestringToken type: ACCOUNT_WIDGET
data.application.expiredAtstringExpiration datetime (ISO 8601)
data.application.validbooleanWhether the token is currently valid

​
Usage Flow

  1. Create Withdrawal Widget: Use this endpoint to generate a withdrawal widget 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 withdrawal widget 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