Skip to main content
This endpoint allows users to send payouts in MKW to recipients in Malawi. The request must include recipient details, payment method, and payout amounts.

​
Endpoint

Post: {{baseURL}}/v2/payout

​
Request Details

​
Headers

Include these headers in your request:
HeaderValueRequired
Content-Typeapplication/json✅ Yes
x-api-keyYOUR_API_KEY✅ Yes

​
Sample cURL Request

curl --location --request POST '{{baseURL}}/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": "123456789"
            },
            "paymentChannel": "BANK_TRANSFER",
            "currency": "MWK",
            "country": "MW"
        },
  "quoteId": "d19a64f9-5a47-4bda-b7c2-xxxxxxxxxx",
  "reason": "Invoice Payment"
}'

​
Request Body

The following fields are required when making an NGN payout request:
FieldTypeDescriptionRequired
recipient.nameStringFull name of the recipient✅ Yes
recipient.firstNameStringFirst name of the recipient✅ Yes
recipient.lastNameStringLast name of the recipient✅ Yes
recipient.typeStringRecipient type (e.g, BUSINESS)✅ Yes
recipient.account.accountNumberStringRecipient’s bank account number✅ Yes
recipient.account.bankCodeStringBank code of the recipient’s bank✅ Yes
recipient.paymentChannelStringPayment method (BANK_TRANSFER, MOBILE_WALLET)✅ Yes
recipient.currencyStringMKW (Malawian kwacha)✅ Yes
recipient.countryStringMK (Malamwi)✅ Yes
quoteIdStringUnique Quote ID for the payout✅ Yes
reasonStringReason 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",
        "reason": "Gift",
        "referenceNumber": "TXYZD6RWSQMKF",
        "type": "SEND",
        "state": "PENDING",
        "quote": {
            "id": "d19a64f9-5a47-4bda-b7c2-xxxxxxxxxxxxx",
            "source": {
                "currency": "MKW",
                "country": "MK",
                "amount": 100
            },
            "target": {
                "currency": "MKW",
                "country": "MKW",
                "amount": 147000
            },
            "rate": 1,
            "fee": {
                "amount": 100
            }
        },
    "recipient": {
            "id": "5925d918-b459-4009-8f42-c29206b11940",
            "name": "John Doe",
            "account": {
                "bankName": "National Bank of Malawi",
                "accountNumber": "123456789"
            },
            "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)

FieldTypeDescription
messageStringConfirmation message indicating the result of the request.
statusStringOverall status of the request (success).
dataObjectContainer for the payout transaction details.
data.idStringUnique identifier for the payout transaction.
data.remarkStringOptional note about the transaction (e.g., Gift).
data.reasonStringReason for the payout (e.g., Gift).
data.referenceNumberStringUnique reference number generated for the payout.
data.typeStringType of transaction (e.g., SEND).
data.stateStringCurrent state of the payout (PENDING, COMPLETED, FAILED, REFUNDED).
data.quote.idStringUnique ID of the quote used for the transaction.
data.quote.source.currencyStringCurrency of the source funds (MKW).
data.quote.source.countryStringISO country code of the source (MK).
data.quote.source.amountNumberAmount debited from the source.
data.quote.target.currencyStringCurrency received by the recipient (MKW).
data.quote.target.countryStringISO country code of the recipient (MW).
data.quote.target.amountNumberAmount credited to the recipient.
data.quote.rateNumberConversion rate applied.
data.quote.fee.amountNumberFee charged for the payout.
data.recipient.idStringUnique identifier for the recipient.
data.recipient.nameStringFull name of the recipient.
data.recipient.account.bankNameStringName of the recipient’s bank.
data.recipient.account.accountNumberStringRecipient’s bank account number.
data.recipient.paymentChannelStringPayment method used (BANK_TRANSFER).
data.recipient.currencyStringCurrency of the recipient’s account (MWK).
data.recipient.countryStringRecipient’s ISO country code (MW).
data.createdStringISO 8601 timestamp when the transaction was created.
data.processedStringISO 8601 timestamp when the transaction was processed.

​
Payout Transaction States

The payout transaction can have one of the following states:
StateDescription
COMPLETEDThe payout was successfully processed.
PENDINGThe payout is still being processed.
FAILEDThe payout failed to process.
REFUNDEDThe payout has been sent back to sender.

​
Error Handling

Status CodeMeaningExample Response
400Insufficient BalanceInsufficient Balance
401UnauthorizedInvalid API key provided.
403ForbiddenIP not whitelisted
404Not FoundThe requested endpoint does not exist.
422Unprocessable EntityInvalid quote ID provided.
500Internal Server ErrorAn 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.