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

# Transfers

> Move money instantly to merchant accounts and PrimePay wallets.

A transfer moves money from **the account that owns the API key** to another PrimePay account. The money stays inside PrimePay, so a transfer is **instant and final**: it either succeeds straight away or is refused, never pending.

| You want to send to | Endpoint |
| - | - |
| One of your own accounts, or another merchant's account | `POST /v1/transfers/merchant-account` |
| A PrimePay wallet (by phone number) | `POST /v1/transfers/wallet` |
| An Airtel Money or TNM Mpamba number, or a bank account | [Payouts](https://docs.primepay.mw/api-reference/payouts-overview.md) |

Only the **available** balance can be sent (not money still pending settlement). Transfers need a full secret key; payments-only keys are refused.

Always show your user the recipient's name before sending. Look it up first with the merchant account or wallet recipient endpoint.

## Limits and fees

| Transfer | Most per transfer | Fee |
| - | - | - |
| Between your own accounts | No limit | Free |
| To another merchant's account | MWK 5,000,000 | Free |
| To a PrimePay wallet | MWK 1,000,000 | Free |

PrimePay can change limits and fees. Any fee is paid by the sender on top of the amount and shown in the response as `fee`; the receiver always gets `amount`.

## Transfer 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 transfer. |
| `invalid_amount` | 400 | Zero, negative or more than 2 decimal places. |
| `amount_over_limit` | 400 | Above the per-transfer limit for that kind of transfer. |
| `insufficient_funds` | 400 | Your available balance doesn't cover the amount and any fee. |
| `recipient_not_found` | 404 | No active account with that code. |
| `recipient_type_mismatch` | 400 | `recipientType` doesn't match the account's owner. Check the code. |
| `invalid_phone` | 400 | Not a Malawi number. |
| `wallet_not_found` | 404 | No PrimePay wallet on that number. |
| `wallet_inactive` | 400 | That wallet can't receive money right now. |
| `transfer_not_allowed` | 403 | This account type can't make that transfer (for example, agent tills). |
| `sandbox_recipient_not_allowed` | 400 | In sandbox, transfers can only go to your own sandbox accounts, a test merchant account or a test wallet. |
| `account_not_ready` | 409 | Your account can't send transfers yet. Contact PrimePay support. |


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