> ## Documentation Index
> Fetch the complete documentation index at: https://docs.centryos.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Withdrawal Widget

> Generate a withdrawal widget (application token/link) for withdrawals and account linking.

## 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

```bash theme={null}
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

| Field                          | Type    | Description                                                                                  | Required |
| ------------------------------ | ------- | -------------------------------------------------------------------------------------------- | -------- |
| `expiredAt`                    | string  | Expiration datetime (ISO 8601 format)                                                        | Yes      |
| `tokenType`                    | string  | Must be `ACCOUNT_WIDGET`                                                                     | Yes      |
| `currency`                     | string  | Currency code (e.g., `USD`)                                                                  | Yes      |
| `feeHidden`                    | boolean | true or false                                                                                | No       |
| `redirectTo`                   | string  | URL to redirect the user after payout completion (e.g., `https://yoursite.com/success`)      | No       |
| `extra`                        | object  | Additional options                                                                           | No       |
| `extra.accountOptions`         | array   | Allowed payout methods: `bank`, `card`, `international_bank`. Defaults to `["bank", "card"]` | No       |
| `extra.withdrawalSource`       | string  | Must be `MERCHANT_WALLET`                                                                    | Yes      |
| `extra.amount`                 | number  | Amount tied to the application token                                                         | Yes      |
| `extra.counterparty`           | object  | Counterparty info                                                                            | Yes      |
| `extra.counterparty.firstName` | string  | Counterparty first name                                                                      | Yes      |
| `extra.counterparty.lastName`  | string  | Counterparty last name                                                                       | Yes      |
| `extra.counterparty.email`     | string  | Counterparty email                                                                           | Yes      |

## Response (200)

```json theme={null}
{
  "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

| Field                        | Type    | Description                           |
| ---------------------------- | ------- | ------------------------------------- |
| `data.url`                   | string  | Shareable withdrawal widget URL       |
| `data.application.id`        | string  | Application ID                        |
| `data.application.token`     | string  | Application token (use for API calls) |
| `data.application.tokenType` | string  | Token type: `ACCOUNT_WIDGET`          |
| `data.application.expiredAt` | string  | Expiration datetime (ISO 8601)        |
| `data.application.valid`     | boolean | Whether 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