Create Withdrawal 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 '{
    "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

​

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

​

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