# 1. Prepare a crypto payout

**POST** `/payout/withdraw/local/crypto/direct`

Base URL: `https://api.triple-a.io/api/v2`

Create a stablecoin payout request.

**Note** : This provides a quote that expires 60 seconds after creation. You can ask for a new quote before the previous one expires for a seamless front-end experience.

## Authorization

- bearer_auth (http, bearer)

## Body

Content type: `application/json`

- `merchant_key` (string, required)
  Unique key that identifies a merchant
- `email` (string, required)
  Email address of the payout recipient
- `withdraw_currency` (string, required)
  The currency to be withdrawn. This should be a
  [3-character ISO 4217](https://en.wikipedia.org/wiki/ISO_4217)
  currency code
- `withdraw_amount` (number<float>, required)
  Amount of the local currency to be withdrawn and converted into cryptocurrency.
  _Is required unless the `crypto_amount` is specified instead._
- `payout_destination_type` ("onchain-wallet" | "binance")
  Default value is `onchain-wallet`. `binance` represents sending cryptocurrency through Binance Pay.

  As of June 2026, this Binance payout feature is only enabled upon request. Please contact our support team.
- `crypto_currency` (string, required)
  Cryptocurrency that will be paid out.
  If the `payout_destination_type` is `binance`, the supported values are `BTC` and `USDC` only.
- `crypto_amount` (number<float>)
  You can use this to request a payout for a precise crypto amount (for example, ask a payout for a value of 0.0324 ETH rather than 72 USD).
- `remarks` (string)
  Remarks for the payout
- `address` (string, required)
  The crypto wallet address of your customer.
  If the `payout_destination_type` is `binance`, this value should be a valid Binance ID of the recipient.
- `name` (string, required)
  The merchant's name
- `id_number` (string)
  The merchant’s business registration number or national id if an individual
- `country` (string, required)
  The merchant’s domiciled country. It must be a [2-character ISO 3166](https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes) country code.
- `ip_address` (string)
  IP address of the merchant
- `order_id` (string)
  The merchant's system unique order id. It has to be unique and has never been used for a payout previously.
- `notify_url` (string<uri>)
  The URL to send the webhook notification. The webhook URL given
  in your account setup will be used if this is not provided.
  For testing you can use [webhook.site](https://webhook.site)
- `notify_secret` (string)
  The shared secret that will be used to sign the notification.
  This secret can be at most 64 characters long.
  If this is not provided in the payment request, the system will
  create a random secret just for that payment.

Example:

```json
{
  "merchant_key": "mkey-ck9e0srok0000zumg7vx3hpkh",
  "email": "alice.tan@triple-a.io",
  "withdraw_currency": "SGD",
  "withdraw_amount": 12.75,
  "payout_destination_type": "onchain-wallet",
  "crypto_currency": "testBTC",
  "crypto_amount": 0,
  "remarks": "Payout for wages earned",
  "address": "mtzozh***************xZ18Ggc00hbf",
  "name": "The Best Company Plc",
  "id_number": "<your_id_number>",
  "country": "US",
  "ip_address": "203.116.172.50",
  "order_id": "<your_order_id>",
  "notify_url": "https://webhook.site/1a2d24e8-1594-4569-bc35-079049e4d805",
  "notify_secret": "Cf9mx4nAvRuy5vwBY2FCtaKr"
}
```

## Responses

### 200

Success

- `order_id` (string)
  The merchant's system unique order id.
- `payout_reference` (string)
  Unique payout reference number
- `type` ("refund" | "withdraw")
  The type of payout:

  1. `refund` - A partial or complete refund of a prior successful payment.

  2. `withdraw` - A withdrawal (or payout) of the merchant's accumulated local currency balance in cryptocurrency.
- `account_type` ("local")
  Account type the funds are drawn from: `local` - Funds are drawn
  from a local currency account
- `convert_type` ("local-local" | "local-crypto")
  Type of conversion the funds underwent:

  1. `local-local` - Funds are drawn from a local currency account and paid out as local currency.

  2. `local-crypto` - Funds are drawn from a local currency account and paid out as cryptocurrency.
- `payout_destination_type` ("onchain-wallet" | "binance")
  This indicates the type of wallet the payout goes to, either a Binance wallet or other onchain-wallet.
- `local_currency` (string)
  The local currency equivalent of the payout. This should be a
  [3-character ISO 4217](https://en.wikipedia.org/wiki/ISO_4217)
  currency code. Please ignore if the payout is in cryptocurrency.
- `local_amount` (number<float>)
  The local currency amount to be paid out. Please ignore if the
  payout is in cryptocurrency.
- `crypto_currency` (string)
  Cryptocurrency that will be paid out. Please ignore if the payout
  is in local currency.
- `crypto_amount` (number<float>)
  Amount of cryptocurrency to be paid out if the payout is in
  cryptocurrency.
- `network_fee_crypto_amount` (number<float>)
  Amount of cryptocurrency representing the network fee. This is denominated in `crypto_currency`.
- `net_crypto_amount` (number<float>)
  Amount of cryptocurrency after deduction of the `network_fee_crypto_amount`.
- `crypto_address` (string)
  Address that recipient will receive the payout at.
  This could either be a unique wallet address hash or Binance ID, depending on the field - `payout_destination_type`.
- `exchange_rate` (number<float>)
  The exchange rate that will be used to exchange local currency to
  cryptocurrency or vice-versa.
- `status` ("new" | "confirm" | "cancel" | "done")
  The current status of the payout:

  1. `new` - The payout has just been created or refreshed, but has not been confirmed or cancelled yet. This status will appear if you call the [Create Crypto Payout via API](#operation/CreateCryptoPayouts).

  2. `confirm` - The payout has been confirmed. This status will appear if you call the [Confirm Crypto Payout via API](#operation/ConfirmCryptoPayouts).

  3. `done` - The payout has been broadcasted to the blockchain and successfully paid out to the recipient.

  4. `cancel` - The payout has been cancelled. This status will appear if you call the [Cancel Crypto Payout via API](#operation/CancelCryptoPayouts) and successfully cancel the payout.
- `status_date` (string<date-time>)
  Date and time the status was updated
- `merchant_name` (string)
  Name of the merchant
- `remarks` (string)
  Remarks for the payout
- `notify_url` (string<uri>)
  The URL to send the webhook notification. The webhook URL given
  in your account setup will be used if this is not provided.
  For testing you can use [webhook.site](https://webhook.site)
- `notify_secret` (string)
  The shared secret that will be used to sign the notification.
  This secret can be at most 64 characters long.
  If this is not provided in the payment request, the system will
  create a random secret just for that payment.

Example:

```json
{
  "order_id": "<your_order_id>",
  "payout_reference": "AGJ-937870-PYT",
  "type": "withdraw",
  "account_type": "local",
  "convert_type": "local-crypto",
  "payout_destination_type": "onchain-wallet",
  "local_currency": "SGD",
  "local_amount": 10,
  "crypto_currency": "testBTC",
  "crypto_amount": 0.001067203,
  "network_fee_crypto_amount": 0.000007203,
  "net_crypto_amount": 0.00106,
  "crypto_address": "1NcAyv8YVCnQGCrDb4kiUm1jj6GLyowxER",
  "exchange_rate": 10277.49,
  "status": "new",
  "status_date": "2020-01-26T03:57:22Z",
  "merchant_name": "A to Z Toys and Games",
  "remarks": "Refund for a water pistol",
  "notify_url": "https://webhook.site/1a2d24e8-1594-4569-bc35-079049e4d805",
  "notify_secret": "Cf9mx4nAvRuy5vwBY2FCtaKr"
}
```

### 401

Unauthorized

- `message` (string)
  1. `unauthorized` - refers to no access token is used for authentication.
  2. `Invalid token: access token is invalid` - refers to the invalid or incorrect access token used.

Example:

```json
{
  "message": "unauthorized"
}
```

### 403

No permission to create payout

- `message` (string)
  `no_permission` - refers to when trying to confirm, cancel or refresh the payout that has been confirmed or cancelled. Or access token has expired.

Example:

```json
{
  "message": "no_permission"
}
```

### 409

Exchange Rate has expired

- `message` (string)
  `rate_expire` - refers to confirming the payout after the exchange rate expired.

Example:

```json
{
  "message": "rate_expire"
}
```

### 422

Validation Error - There are 1 or more errors in the request body

- `message` (string)
  Main error message
- `errors` (any[])
  - `message` (string)
    Additional error message
  - `path` (string)
    One of the JSON object key in the request body that has the error. It could be `merchant_key`, `address`, etc.

Example:

```json
{
  "message": "validation_error",
  "errors": [
    {
      "message": "invalid",
      "path": "merchant_key"
    }
  ]
}
```