🇲🇼 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

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:

{
    "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.

Overview

Wallets

Quotes

Payouts

Virtual Accounts

Ramp

Transactions

Webhooks

Endpoint

Request Details

Headers

Sample cURL Request

Request Body

Success Response (200 OK)

Success Response Breakdown (200 OK)

Payout Transaction States

Error Handling

Best Practices

​Endpoint

​Request Details

​Headers

​Sample cURL Request

​Request Body

​Success Response (200 OK)

​Success Response Breakdown (200 OK)

​Payout Transaction States

​Error Handling

​Best Practices

Endpoint

Request Details

Headers

Sample cURL Request

Request Body

Success Response (200 OK)

Success Response Breakdown (200 OK)

Payout Transaction States

Error Handling

Best Practices