Payout API

The Payout API allows users to create and process payouts to recipients using different payment channels. This guide explains how to use the API effectively, including request parameters, responses, and error handling.

Endpoint

POST {{baseURL}}/v1/payout

Description

This endpoint processes a payout transaction by transferring funds to a specified beneficiary. The request must include recipient details, bank information, and payout amounts.

Sample `cURL` Request (NGN to NGN via BANK_TRANSFER)

ℹ️

Payout Request body uses form data multipart/form-data.

curl --location '{{baseURL}}/v1/payout' \
--header 'x-api-key: API_KEY:YOUR_API_KEY' \
--header 'Content-Type: multipart/form-data' \
--form 'transaction={
  "recipient": {
    "name": "CHRIS TIANA",
    "account": {
      "bankName": "Guaranty Trust Bank",
      "sortCode": "05x",
      "accountNumber": "0712617XXX"
    },
    "paymentChannel": "BANK_TRANSFER",
    "country": "NG",
    "stored": false
  },
  "quoteId": "453eeu-567j-6tr3d-xxxxxxxxxxxxx",
  "reason": "Bills",
  "remark": ""
}'

Request Details

Headers

Include these headers in your request:

Header	Value	Required	Description
`x-api-key`	`API_KEY:YOUR_API_KEY`	✅ Yes	API key for authenticating the request
`Content-Type`	`multipart/form-data`	✅ Yes	Specifies that the body contains form data

Recipient Object

Field	Type	Required	Description
name	String	✅ Yes	Full name of the recipient
paymentChannel	String	✅ Yes	Payment method, e.g. BANK_TRANSFER
country	String	✅ Yes	Recipient's 2-letter country code (e.g., `NG`)
stored	Boolean	✅ Yes	Indicates if recipient info is stored for future use (true/false)

Recipient Account Object

Field	Type	Required	Description
bankName	String	✅ Yes	Name of the recipient’s bank
sortCode	String	✅ Yes	Bank sort code (e.g., `058`)
accountNumber	String	✅ Yes	Recipient's bank account number

Other Fields

Field	Type	Required	Description
quoteId	String	✅ Yes	ID of the quote related to the payout
reason	String	✅ Yes	Reason for payout (e.g. "Bills")
remark	String	❌ No	Optional remark or note for the payout

Responses

Success Response

response.json

{
    "message": "transaction created successfully",
    "status": "success",
    "data": {
        "id": "453eeu-567j-6tr3d-xxxxxxxxxxxxx",
        "remark": "",
        "reason": "Bills",
        "referenceNumber": "O0XUZKKXXXXXX",
        "type": "SEND",
        "state": "COMPLETED",
        "quote": {
            "id": "456babd4-2951-48ff-89c9-xxxxxxxxxxxxx",
            "source": {
                "currency": "NGN",
                "country": "NG",
                "amount": 150000.00
            },
            "target": {
                "currency": "NGN",
                "country": "NG",
                "amount": 150000.00
            },
            "rate": 1.00000000,
            "fee": {
                "amount": 100.00
            },
            "summary": {
                "total": 150100.00
            },
            "expiresInSeconds": 0
        },
        "recipient": {
            "name": "CHRIS TIANA",
            "account": {
                "bankName": "Guaranty Trust Bank",
                "sortCode": "05x",
                "accountNumber": "0712617XXX"
            },
            "paymentChannel": "BANK_TRANSFER",
            "country": "NG"
        },
        "created": "2025-05-12T12:28:12.971714504",
        "processed": "2025-05-12T12:28:12.971714504"
    }
}

Response Breakdown

General Information

Field	Type	Description
`message`	String	Transaction status message
`status`	String	Operation status (`success`/`error`)

Transaction Data

Field	Type	Description
`id`	String	Unique transaction ID
`remark`	String	Optional remarks/notes
`reason`	String	Transaction purpose (`Bills`)
`referenceNumber`	String	Unique tracking reference
`type`	String	Transaction type (`SEND`)
`state`	String	Current status (`COMPLETED`)
`created`	String	ISO 8601 creation timestamp
`processed`	String	ISO 8601 processing timestamp

Quote Details

Field	Type	Description
`quote.id`	String	Unique quote identifier
`quote.rate`	Number	FX rate used
`quote.expiresInSeconds`	Number	Quote validity

Source Funds

Field	Type	Description
`quote.source.currency`	String	`NGN`
`quote.source.country`	String	`NG`
`quote.source.amount`	Number	Original amount

Target Funds

Field	Type	Description
`quote.target.currency`	String	`NGN`
`quote.target.country`	String	`NG`
`quote.target.amount`	Number	Received amount

Fees & Summary

Field	Type	Description
`quote.fee.amount`	Number	Transaction fee
`quote.summary.total`	Number	Total deducted

Recipient Details

Field	Type	Description
`recipient.name`	String	Account holder name
`recipient.paymentChannel`	String	`BANK_TRANSFER`
`recipient.country`	String	Recipient country (`NG`)

Bank Account Details

Field	Type	Description
`recipient.account.bankName`	String	Bank name
`recipient.account.sortCode`	String	Bank branch code
`recipient.account.accountNumber`	String	Bank account number

Error Handling

Status Code	Meaning	Example Response	How to Handle
400	Bad Request	Invalid parameters	Check request payload for missing or malformed fields
401	Unauthorized	Invalid API key	Ensure the API key is correct and authorized
403	Forbidden (Non-whitelisted IP)	Your IP address is not allowed to access this service	Whitelist your IP address in the API Management settings on the dashboard
422	Unprocessable Entity	Invalid quote ID	Confirm quoteId is valid and hasn't expired
500	Internal Server Error	An internal error occurred	Retry later or contact support if error persists

Best Practices

✅ Include a valid x-api-key in the request headers for authentication.
✅ Ensure that all recipient information is accurate and properly formatted.
✅ Validate that the quoteId is correctly provided and linked to an existing quote.
✅ Handle errors appropriately to ensure robust API usage.

How Payouts works in meCash Supported Payment Channels and Currencies