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

# Payouts

> Send money out of PrimePay to Airtel Money, TNM Mpamba and bank accounts.

A payout sends money from **the account that owns the API key** out of PrimePay, to an Airtel Money or TNM Mpamba number or to a bank account. The [dashboard](https://dashboard.primepay.mw/)'s payout page uses the same rules.

| You want to pay | Endpoint |
| - | - |
| An Airtel Money or TNM Mpamba number | `POST /v1/payouts/mobile-money` |
| A bank account | `POST /v1/payouts/bank` |

## How a payout works

Unlike a transfer, a payout depends on the network or bank, so it isn't always final straight away:

**1. Reserve**

PrimePay checks the request, then **reserves** the amount plus the fee from your available balance.

**2. Send**

The payout goes to the network or bank. Its `status` is `processing`.

**3. Result**

When they answer, the status becomes `success`, or `failed`. If a payout fails, the amount **and the fee** go back to your available balance.

An answer can take a few seconds or longer. PrimePay keeps checking a `processing` payout until it gets a clear answer, and never marks it `failed` just because the network was slow. If a network or bank isn't connected yet, the payout is still accepted: it waits as `processing` with the money reserved, and goes out as soon as the connection is live. Check the result with `GET /v1/payouts/{reference}`.

Payouts need a full secret key from a listed server address; payments-only keys are refused. Every `POST` needs an `Idempotency-Key` header (up to 64 characters). A repeat of the same payout returns `200` with `Idempotent-Replayed: true` and is never paid twice; the same key for a different payout returns `422 idempotency_key_reused`.

## Limits and fees

| Payout | Most per payout | Fee |
| - | - | - |
| To Airtel Money or TNM Mpamba | No limit | MWK 500 |
| To a bank account | No limit | MWK 1,000 |

PrimePay can change limits and fees. The fee is paid on top of the amount and shown in the response as `fee`; the recipient always gets `amount`.

## Payout errors

| Code | HTTP | Meaning |
| - | - | - |
| `idempotency_key_required` | 400 | Send an `Idempotency-Key` header (up to 64 characters). |
| `idempotency_key_reused` | 422 | That key was already used for a different payout. |
| `invalid_amount` | 400 | Zero, negative or more than 2 decimal places. |
| `amount_over_limit` | 400 | Above the per-payout limit. |
| `insufficient_funds` | 400 | Your available balance doesn't cover the amount and the fee. |
| `invalid_provider` | 400 | `provider` must be `airtel` or `tnm`. |
| `provider_not_supported` | 400 | That operator is switched off right now (live only). Try again later. |
| `invalid_phone` | 400 | Not a Malawi number. |
| `invalid_recipient` | 400 | The number or bank details aren't valid for that network or bank. |
| `invalid_bank` | 400 | Unknown `bankCode`. |
| `invalid_account_number` | 400 | The account number must be 6 to 20 digits. |
| `invalid_account_name` | 400 | Send the name on the bank account. |
| `duplicate_reference` | 409 | That `reference` is already being paid or was paid. |
| `account_disabled` | 403 | Your account is disabled. |
| `payout_not_allowed` | 403 | This account type can't make payouts (for example, agent tills). |
| `sandbox_recipient_not_allowed` | 400 | In sandbox, payouts can only go to a test phone number or test bank account. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.