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

# Payouts

> Send money from your wallet to a bank account or mobile money wallet.

A payout moves money from one of your wallets to a recipient. You get `202` at once and the outcome by webhook.

**Before you start:** a funded wallet in the source currency, and a key with the `payouts:write` scope.

## Send a payout

`POST /v1/payouts`

**Idempotency-Key** `string` *required*

A unique key for this payout, up to 255 characters. Reuse it on every retry. See [Idempotency](/essentials/idempotency.md).

**sourceCurrency** `string` *required*

The wallet to pay from: `NGN`, `GHS` or `KES`.

**destinationCurrency** `string` *required*

The currency the recipient gets. If it differs from `sourceCurrency`, Payve converts first.

**amount** `integer` *required*

The amount in `sourceCurrency`, in minor units. The fee is charged on top.

**method** `string` *required*

`bank_transfer` or `mobile_money`.

**beneficiary** `object` *required*

The recipient.

**beneficiary fields**

**type** `string` *required*

`bank_account` or `mobile_money`.

**country** `string` *required*

Two-letter country code: `NG`, `GH` or `KE`.

**accountNumber** `string`

The bank account number. Needed for `bank_account`.

**bankCode** `string`

The bank's code, from [`GET /v1/payouts/institutions`](/guides/name-check#list-institutions). Needed for `bank_account`.

**mobileNumber** `string`

The mobile money number. Needed for `mobile_money`.

**holderName** `string`

The account holder's name.

**quoteId** `string`

A [quote](/guides/quotes.md) for the same currencies and amount. Fixes the rate and fee.

**merchantReference** `string`

Your own reference, up to 255 characters. If you leave it out, Payve uses the payout's public id.

**narration** `string`

A description for the transfer, up to 255 characters.

**metadata** `object`

Your own key-value data. Stored with the payout.

```bash cURL
curl -X POST "$PAYVE_API_URL/v1/payouts" \
  -H "x-api-key: $PAYVE_API_KEY" \
  -H "Idempotency-Key: 7f3d2b1a-0c4e-4f8a-9b6d-5e2a1c3f4b70" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceCurrency": "NGN",
    "destinationCurrency": "NGN",
    "amount": 5000000,
    "method": "bank_transfer",
    "merchantReference": "invoice-1042",
    "narration": "Invoice 1042",
    "beneficiary": {
      "type": "bank_account",
      "accountNumber": "0123456789",
      "bankCode": "058",
      "holderName": "Ngozi Adeyemi",
      "country": "NG"
    }
  }'
```

```javascript Node
const res = await fetch(`${process.env.PAYVE_API_URL}/v1/payouts`, {
  method: 'POST',
  headers: {
    'x-api-key': process.env.PAYVE_API_KEY,
    'Idempotency-Key': order.payveIdempotencyKey, // created once, stored with the order
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    sourceCurrency: 'NGN',
    destinationCurrency: 'NGN',
    amount: 5000000,
    method: 'bank_transfer',
    merchantReference: 'invoice-1042',
    narration: 'Invoice 1042',
    beneficiary: {
      type: 'bank_account',
      accountNumber: '0123456789',
      bankCode: '058',
      holderName: 'Ngozi Adeyemi',
      country: 'NG',
    },
  }),
});

if (res.status !== 202) throw new Error(`Payout not accepted: ${res.status}`);
const { data: payout } = await res.json();
```

```python Python
import os, requests

res = requests.post(
    f"{os.environ['PAYVE_API_URL']}/v1/payouts",
    headers={
        "x-api-key": os.environ["PAYVE_API_KEY"],
        "Idempotency-Key": order.payve_idempotency_key,  # created once, stored with the order
    },
    json={
        "sourceCurrency": "NGN",
        "destinationCurrency": "NGN",
        "amount": 5000000,
        "method": "bank_transfer",
        "merchantReference": "invoice-1042",
        "narration": "Invoice 1042",
        "beneficiary": {
            "type": "bank_account",
            "accountNumber": "0123456789",
            "bankCode": "058",
            "holderName": "Ngozi Adeyemi",
            "country": "NG",
        },
    },
    timeout=30,
)
res.raise_for_status()
payout = res.json()["data"]
```

```json Response · 202
{
  "data": {
    "id": 1842,
    "publicId": "pyt_9c2e41b7a05d3f68",
    "status": "pending",
    "subStatus": null,
    "isCrossCurrency": false,
    "sourceCurrency": "NGN",
    "destinationCurrency": "NGN",
    "sourceAmount": "5000000",
    "destinationAmount": "5000000",
    "feeAmount": "5000",
    "feeCurrency": "NGN",
    "rate": "1.0000000000",
    "conversion": null,
    "method": "bank_transfer",
    "merchantReference": "invoice-1042",
    "narration": "Invoice 1042",
    "userMessage": null,
    "beneficiary": {
      "type": "bank_account",
      "accountNumber": "0123456789",
      "bankCode": "058",
      "holderName": "Ngozi Adeyemi",
      "country": "NG"
    },
    "quoteId": "qte_4b1f0c9d2e7a6835",
    "createdAt": "2026-11-18T10:00:12.000Z"
  }
}
```

> [!WARNING]
>
> `202` means accepted, not paid. Wait for `payout.successful` before you tell anyone the money has
> arrived.

### Response fields

**id** `integer`

Use this in URLs: `GET /v1/payouts/{id}`.

**publicId** `string`

The `pyt_` id. Show this to people and quote it to support.

**status** `string`

`pending`, `processing`, `successful` or `failed`. See [Statuses](/essentials/statuses.md).

**subStatus** `string | null`

Extra detail, such as `reversed`.

**sourceAmount** `string`

The amount sent, in minor units of `sourceCurrency`. Your wallet is debited this plus `feeAmount`.

**destinationAmount** `string`

What the recipient gets, in minor units of `destinationCurrency`.

**feeAmount** `string`

Payve's fee, in minor units of `feeCurrency`.

**rate** `string | null`

The exchange rate applied.

**isCrossCurrency** `boolean`

`true` when the two currencies differ. `conversion` then holds the converted amounts.

**userMessage** `string | null`

A plain-language explanation when something went wrong.

**quoteId** `string | null`

The quote that priced this payout.

## The lifecycle

| Step | Status | What is happening |
| - | - | - |
| 1 | `pending` | Payve has accepted the payout. |
| 2 | `processing` | Your wallet is debited and the payout is with the bank or operator. |
| 3 | `successful` | The money arrived. You get `payout.successful`. |
| 3 | `failed` | The money did not arrive and is back in your wallet. You get `payout.failed`. |

If a route fails and another is available, Payve tries the next one. The payout stays `processing` throughout.

## Cross-currency payouts

Set a `destinationCurrency` different from `sourceCurrency`. Payve converts from your source wallet, then pays out. Use a [quote](/guides/quotes.md) so the rate is fixed.

> [!NOTE]
>
> If a cross-currency payout fails after the conversion, the money returns to your
> **destination-currency** wallet, not the source one.

## Get a payout

`GET /v1/payouts/{id}` returns the payout plus `events`, a timeline of what happened to it.

```bash
curl "$PAYVE_API_URL/v1/payouts/1842" \
  -H "x-api-key: $PAYVE_API_KEY"
```

Each entry in `events` has `id`, `eventType`, `actor`, `payload` and `createdAt`.

## List payouts

`GET /v1/payouts` returns payouts newest first. Filter with `status`, `from`, `to` and `q`, and page with `cursor`. See [Pagination](/essentials/requests-and-responses.md#pagination).

```bash
curl "$PAYVE_API_URL/v1/payouts?status=failed&from=2026-11-01T00:00:00Z&limit=50" \
  -H "x-api-key: $PAYVE_API_KEY"
```

## Try a failed payout again

Create a new payout with the same recipient and amount, and a **new** `Idempotency-Key`. The failed payout stays as it is, for your records.

> [!WARNING]
>
> Send again only when the payout has reached `failed`. A payout that is `pending` or `processing`
> may still arrive, and a second one would pay the recipient twice.

## Cancelling a payout

The API has no cancel. A payout starts as soon as you create it, so check the recipient with a [name check](/guides/name-check.md) first. If a payout must be stopped or re-sent on your behalf, contact [support](/support.md).

## When it fails

Errors on the request itself:

| Status and code | Cause | Fix |
| - | - | - |
| `400 validation_idempotency_key_required` | No `Idempotency-Key` header. | Send one. |
| `401` | Bad or missing key. | See [Authentication](/get-started/authentication.md). |
| `403` `Insufficient scope` | The key lacks `payouts:write`. | Use a key with the scope. |
| `403 kyc_tier_insufficient` | Your business is not verified. | Finish verification. |
| `403 merchant_suspended` | Your account is suspended. | Contact [support](/support.md). |
| `403 forbidden` | Money movement by API key is switched off for your account. | Contact [support](/support.md). |
| `422 validation_missing_field` | A field is missing or malformed. | Fix the fields in `details.fields`. |
| `422 wallet_insufficient_funds` | The wallet cannot cover the amount plus the fee. | Fund the wallet. `details` shows `available` and `required`. |
| `422 merchant_limit_exceeded` | Over a per-transaction or daily limit. | Send less, or ask about your limits. |
| `422 quote_expired` | The quote is past its hold time. | Create a new quote. |
| `409 quote_already_consumed` | The quote was already used. | Create a new quote. |
| `409 idempotency_conflict` | The same key is still in flight. | Wait, then retry with the same key. |
| `422 idempotency_key_reused` | The key was used for a different request. | Fix your code. Do not retry. |
| `404 resource_not_found` | The quote, or a rate for the pair, does not exist. | Check the quote id and the currencies. |

Failures after `202`:

A payout can be accepted and then fail, for example when the recipient's bank is offline or the account does not exist. The payout becomes `failed`, the money returns to your wallet, and you receive `payout.failed` with a `user_message`.

## Cautions

> [!WARNING]
>
> **Check the recipient first.** A payout to a valid account that belongs to the wrong person cannot
> be pulled back by Payve. Run a [name check](/guides/name-check.md) and show the returned name to your
> user before you send.

> [!WARNING]
>
> **Never retry a timeout with a new idempotency key.** The first request may have gone through.
> Retry with the same key and Payve returns the original payout.

> [!TIP]
>
> Store the payout's `id` and `publicId` against your own record as soon as you get the `202`. You
> need `id` to fetch it and `publicId` to match webhooks.
