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

# Payouts

> Send wallet funds to a bank account or crypto wallet

Send money from your NGN or USD wallet to a bank account or a USDC/USDT address.

Check `available` with [`GET /wallets`](/api-reference/wallets/list-wallet-balances) before you create a payout.

## Create a payout

`POST /payouts` debits `amount` from the wallet matching `currency` and sends it to `destination`. Amounts are **minor units**.

|        | Wallet (`currency`) | Sent (`destination.currency`) |
| ------ | ------------------- | ----------------------------- |
| Bank   | `ngn` or `usd`      | `ngn` or `usd`                |
| Crypto | `ngn` or `usd`      | `usdc` or `usdt`              |

Every payout needs a unique `reference`. Reusing one returns `409`.

### Bank transfer

NGN requires `bank_code`. Use [`GET /misc/banks/ng`](/api-reference/misc/list-banks-by-country) and [`POST /misc/banks/ng/resolve`](/api-reference/misc/resolve-bank-account-by-country) before you send.

```bash theme={"theme":{"light":"min-light","dark":"poimandres"}}
curl -X POST https://api.puplar.com/payouts \
  -H "Authorization: Bearer sk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "wd_order_98234",
    "amount": 500000,
    "currency": "ngn",
    "method": "bank_transfer",
    "destination": {
      "currency": "ngn",
      "bank_transfer": {
        "account_number": "0123456789",
        "bank_code": "058",
        "account_name": "ADA OBI"
      }
    }
  }'
```

### Crypto

Pass a `chain` from [`GET /crypto/tokens`](/guides/crypto#list-supported-tokens) for that token. Do not send `contract_address`.

```bash theme={"theme":{"light":"min-light","dark":"poimandres"}}
curl -X POST https://api.puplar.com/payouts \
  -H "Authorization: Bearer sk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "wd_crypto_98234",
    "amount": 10000,
    "currency": "usd",
    "method": "crypto",
    "destination": {
      "currency": "usdc",
      "crypto": {
        "wallet_address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
        "chain": "polygon-pos"
      }
    }
  }'
```

`description` and `metadata` are optional.

The payout’s `amount` / `currency` are what was sent (after FX). USD → USDC/USDT is 1:1.

## Quote

Preview fee and rate without debiting. Use the same `amount`, `currency`, `method`, and `destination` as create.

```bash theme={"theme":{"light":"min-light","dark":"poimandres"}}
curl -X POST https://api.puplar.com/payouts/quote \
  -H "Authorization: Bearer sk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 10000,
    "currency": "usd",
    "method": "crypto",
    "destination": {
      "currency": "usdc",
      "crypto": {
        "wallet_address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
        "chain": "polygon-pos"
      }
    }
  }'
```

`fee` is in minor units of `fee_currency`.

## Retrieve

Look up by the `reference` you sent on create.

```bash theme={"theme":{"light":"min-light","dark":"poimandres"}}
curl https://api.puplar.com/payouts/wd_order_98234 \
  -H "Authorization: Bearer sk_live_your_key"
```

```bash theme={"theme":{"light":"min-light","dark":"poimandres"}}
curl "https://api.puplar.com/payouts?status=pending&currency=usdc" \
  -H "Authorization: Bearer sk_live_your_key"
```

## Cancel

Cancel a `pending` payout. The wallet is credited back.

```bash theme={"theme":{"light":"min-light","dark":"poimandres"}}
curl -X POST https://api.puplar.com/payouts/wd_order_98234/cancel \
  -H "Authorization: Bearer sk_live_your_key"
```

Listen for `payout.initiated`, `payout.completed`, `payout.failed`, and `payout.canceled`. See [Webhooks](/guides/webhooks).

```json theme={"theme":{"light":"min-light","dark":"poimandres"}}
{
  "id": "64f1a2b3c4d5e6f7a8b9c0d1",
  "type": "payout.completed",
  "timestamp": "2026-07-26T12:00:00.000Z",
  "payload": {
    "id": "64f9b3c4d5e6f7a8b9c0d1e2",
    "reference": "wd_order_98234",
    "amount": 500000,
    "currency": "ngn",
    "status": "paid",
    "destination": {
      "account_number": "0123456789",
      "bank_code": "058",
      "account_name": "ADA OBI"
    },
    "failure_message": null,
    "created_at": "2026-07-26T11:58:00.000Z",
    "arrival_date": "2026-07-26T12:00:00.000Z"
  }
}
```