> ## Documentation Index > Fetch the complete documentation index at: https://developer.me-cash.com/llms.txt > Use this file to discover all available pages before exploring further. # 🇲🇼 MWK Payout This endpoint allows users to **send payouts in Malawian Kwacha (MWK)** to recipients in **Malawi**. The request must include recipient details, payment method, and payout amounts. ## Endpoint **Post:** `https://sandboxapi.me-cash.com/v2/payout` ## **Request Details** ### Headers Include these headers in your request: | **Header** | **Value** | **Required** | | -------------- | ------------------ | ------------ | | `Content-Type` | `application/json` | ✅ Yes | | `x-api-key` | `YOUR_API_KEY` | ✅ Yes | *** ## **Sample cURL Request** ```bash theme={null} curl --location --request POST 'https://sandboxapi.me-cash.com/v2/payout' \ --header 'x-api-key: YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "recipient": { "id": "5925d918-b459-4009-8f42-xxxxxxxxxxxx", "name": "John Doe", "account": { "bankName": "National Bank of Malawi", "accountNumber": "123456***" }, "paymentChannel": "BANK_TRANSFER", "currency": "MWK", "country": "MW" }, "quoteId": "d19a64f9-5a47-4bda-b7c2-xxxxxxxxxx", "invoice": "4b9b6d30-a2ed-421a-bd69-xxxxxxxxxxxx", "reason": "Invoice Payment" }' ``` ### **Request Body** The following fields are required when making an **NGN payout request**: | **Field** | **Type** | **Description** | **Required** | | --------------------------------- | -------- | ------------------------------------------------------- | ------------ | | `recipient.name` | String | Full name of the recipient | ✅ Yes | | `recipient.type` | String | Recipient type (e.g, `BUSINESS`) | ✅ Yes | | `recipient.account.accountNumber` | String | Recipient’s **bank account number** | ✅ Yes | | `recipient.account.bankCode` | String | Bank code of the recipient's bank | ✅ Yes | | `recipient.paymentChannel` | String | Payment method (`BANK_TRANSFER`, `MOBILE_WALLET`) | ✅ Yes | | `recipient.currency` | String | `MWK` (Malawian kwacha) | ✅ Yes | | `recipient.country` | String | `MW` (Malawi) | ✅ Yes | | `quoteId` | String | Unique Quote ID for the payout | ✅ Yes | | `invoice` | String | Unique identifier for the invoice (optional) | ❌ No | | `reason` | String | Reason for the payout (e.g., `Gift`, `Invoice Payment`) | ✅ Yes | *** ## **Success Response (200 OK)** If the payout is successfully created, the API returns the following response: ```json theme={null} { "message": "Transaction created successfully", "status": "success", "data": { "id": "a1b2c3d4-e5f6-7890-abcd-xxxxxxxxxxxxx", "remark": "Gift", "invoice": "4b9b6d30-a2ed-421a-bd69-xxxxxxxxxxxx", "reason": "Gift", "referenceNumber": "TXYZD6RWSQMKF", "type": "SEND", "state": "PENDING", "quote": { "id": "d19a64f9-5a47-4bda-b7c2-xxxxxxxxxxxxx", "source": { "currency": "MWK", "country": "MK", "amount": 100 }, "target": { "currency": "MWK", "country": "MW", "amount": 147000 }, "rate": 1, "fee": { "amount": 100 } }, "recipient": { "id": "5925d918-b459-4009-8f42-c29206b11940", "name": "John Doe", "account": { "bankName": "National Bank of Malawi", "accountNumber": "123456***" }, "paymentChannel": "BANK_TRANSFER", "currency": "MWK", "country": "MW" } "created": "2025-07-24T14:17:48.038044", "processed": "2025-07-24T14:20:49.712685" } } ``` *** ## Success Response Breakdown (200 OK) | **Field** | **Type** | **Description** | | :------------------------------------- | :------- | :-------------------------------------------------------------------------- | | `message` | String | Confirmation message indicating the result of the request. | | `status` | String | Overall status of the request (`success`). | | `data` | Object | Container for the payout transaction details. | | `data.id` | String | Unique identifier for the payout transaction. | | `data.remark` | String | Optional note about the transaction (e.g., `Gift`). | | `data.invoice` | String | Optional identifier for the invoice. | | `data.reason` | String | Reason for the payout (e.g., `Gift`). | | `data.referenceNumber` | String | Unique reference number generated for the payout. | | `data.type` | String | Type of transaction (e.g., `SEND`). | | `data.state` | String | Current state of the payout (`PENDING`, `COMPLETED`, `FAILED`, `REFUNDED`). | | `data.quote.id` | String | Unique ID of the quote used for the transaction. | | `data.quote.source.currency` | String | Currency of the source funds (`MWK`). | | `data.quote.source.country` | String | ISO country code of the source (`MW`). | | `data.quote.source.amount` | Number | Amount debited from the source. | | `data.quote.target.currency` | String | Currency received by the recipient (`MWK`). | | `data.quote.target.country` | String | ISO country code of the recipient (`MW`). | | `data.quote.target.amount` | Number | Amount credited to the recipient. | | `data.quote.rate` | Number | Conversion rate applied. | | `data.quote.fee.amount` | Number | Fee charged for the payout. | | `data.recipient.id` | String | Unique identifier for the recipient. | | `data.recipient.name` | String | Full name of the recipient. | | `data.recipient.account.bankName` | String | Name of the recipient’s bank. | | `data.recipient.account.accountNumber` | String | Recipient’s bank account number. | | `data.recipient.paymentChannel` | String | Payment method used (`BANK_TRANSFER`). | | `data.recipient.currency` | String | Currency of the recipient’s account (`MWK`). | | `data.recipient.country` | String | Recipient’s ISO country code (`MW`). | | `data.created` | String | ISO 8601 timestamp when the transaction was created. | | `data.processed` | String | ISO 8601 timestamp when the transaction was processed. | *** ## **Payout Transaction States** The payout transaction can have one of the following states: | **State** | **Description** | | ----------- | ---------------------------------------- | | `COMPLETED` | The payout was successfully processed. | | `PENDING` | The payout is still being processed. | | `FAILED` | The payout failed to process. | | `REFUNDED` | The payout has been sent back to sender. | *** ## Error Handling | **Status Code** | **Meaning** | **Example Response** | | :-------------- | :-------------------- | :------------------------------------- | | `400` | Insufficient Balance | Insufficient Balance | | `401` | Unauthorized | Invalid API key provided. | | `403` | Forbidden | IP not whitelisted | | `404` | Not Found | The requested endpoint does not exist. | | `422` | Unprocessable Entity | Invalid quote ID provided. | | `500` | Internal Server Error | An internal error occurred. | *** ## **Best Practices** ✅ Ensure `quoteId` is valid and linked to an existing quote.\ ✅ Confirm that the recipient’s **bank account number** and **bank code** are correct.\ ✅ Use a valid API key in the headers.\ ✅ Handle error responses correctly in your integration.