Skip to main content
POST
/
v2
/
payout
curl --request POST \
  --url https://sandboxapi.me-cash.com/v2/payout \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
  "remark": "TESTING",
  "reason": "GIFT",
  "quoteId": "91e58c2d-ef14-4777-906b-xxxxxxxxxxxxx",
  "recipient": {
    "name": "Adeolu Adebayo",
    "paymentChannel": "BANK_TRANSFER",
    "currency": "NGN",
    "country": "NG",
    "account": {
      "bankName": "GT Bank",
      "accountNumber": "0010401234",
      "bankCode": "058"
    }
  }
}'
{
  "status": "success",
  "message": "Transaction created successfully.",
  "data": {
    "id": "c6611ad3-805a-415b-98b7-xxxxxxxxxxxxx",
    "remark": "Testing",
    "reason": "Gift",
    "referenceNumber": "L2TEZEHNXXXXXX",
    "type": "SEND",
    "state": "COMPLETED",
    "quote": {},
    "recipient": {},
    "created": "2023-11-07T05:31:56Z",
    "processed": "2023-11-07T05:31:56Z"
  }
}

​
Create Payout

The Payout API allows users to create and process payouts to recipients using different payment channels. This endpoint processes a payout transaction by transferring funds to a specified beneficiary.

​
Authentication

All requests to the Payout API require:
HeaderValueRequiredDescription
x-api-keyAPI_KEY:YOUR_API_KEY✅ YesAPI key for authentication
Content-Typemultipart/form-data✅ YesRequired for sending form data
Security Notes:
  • API keys can be obtained in your Dashboard → Developers → API Keys
  • Requests must originate from whitelisted IP addresses; non-whitelisted IPs will receive a 403 error
  • All requests are authenticated via API key — keep your key secure and never expose it in client-side code

​
Request Structure

The request body for the payout endpoint is sent as multipart/form-data with a single form field named transaction containing a JSON string. Transaction Object Parameters:
FieldTypeRequiredDescription
recipientObject✅ YesDetails of the recipient. See Recipient Object below.
quoteIdString✅ YesID of the quote related to the payout.
reasonString✅ YesReason for payout (e.g., “Bills”).
remarkString❌ NoOptional remark or note for the payout.

​
Recipient Object

FieldTypeRequiredDescription
nameString✅ YesFull name of the recipient.
accountObject✅ YesBank account details of the recipient. See Recipient Account Object below.
paymentChannelString✅ YesPayment method, e.g., BANK_TRANSFER.
countryString✅ YesRecipient’s 2-letter country code (e.g., NG).
storedBoolean✅ YesIndicates if recipient info is stored for future use (true/false).

​
Recipient Account Object

FieldTypeRequiredDescription
bankNameString✅ YesName of the recipient’s bank.
sortCodeString✅ YesBank sort code (e.g., 058).
accountNumberString✅ YesRecipient’s bank account number.

​
Example Request

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": ""
}'

​
Response Structure

{
    "message": "transaction created successfully",
    "status": "success",
    "data": {
        "id": "c6611ad3-805a-415b-98b7-xxxxxxxxxxxxx",
        "remark": "Testing",
        "reason": "Gift",
        "referenceNumber": "L2TEZEHNXXXXXX",
        "type": "SEND",
        "state": "PENDING",
        "quote": {
            "id": "b2eb702a-3f7c-4781-aa76-xxxxxxxxxxxxx",
            "source": {
                "currency": "NGN",
                "country": "NG",
                "amount": 1000.00
            },
            "target": {
                "currency": "NGN",
                "country": "NG",
                "amount": 1000.00
            },
            "rate": 1.00000000,
            "fee": {
                "amount": 100.00
            },
            "summary": {
                "total": 1100.00
            },
            "settlement": "1hr"
        },
        "recipient": {
            "name": "Nzan Christiana",
            "account": {
                "bankName": "Access Bank",
                "sortCode": "044",
                "accountNumber": "005606XXXXXX"
            },
            "paymentChannel": "BANK_TRANSFER",
            "currency": "NGN",
            "country": "NG"
        },
        "created": "2025-08-11T09:45:11.948586402Z",
        "processed": "2025-08-11T09:45:11.948586402Z"
    }
}

​
Response Breakdown

FieldTypeDescription
idStringUnique transaction ID
remarkStringNarration for transaction
reasonStringTransaction purpose (Bills)
referenceNumberStringUnique tracking reference
typeStringTransaction type (SEND)
stateStringCurrent status (PENDING)
createdStringISO 8601 creation timestamp
processedStringISO 8601 processing timestamp
FieldTypeDescription
quote.idStringUnique quote identifier
quote.rateNumberFX rate used
quote.settlementStringEstimated completion time (1hr)
quote.source.currencyStringSource currency (NGN)
quote.source.countryStringSource country (NG)
quote.source.amountNumberOriginal amount
quote.target.currencyStringTarget currency (NGN)
quote.target.countryStringTarget country (NG)
quote.target.amountNumberReceived amount
quote.fee.amountNumberTransaction fee
quote.summary.totalNumberTotal deducted
FieldTypeDescription
recipient.nameStringAccount holder name
recipient.paymentChannelStringBANK_TRANSFER
recipient.countryStringRecipient country (NG)
recipient.account.bankNameStringBank name
recipient.account.sortCodeStringBank branch code
recipient.account.accountNumberStringBank account number

​
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.
✅ Use the referenceNumber from the response for tracking and reconciliation.
✅ Monitor transaction states through webhooks for real-time updates.

Authorizations

​
x-api-key
string
header
required

Body

application/json
​
quoteId
string
required

The unique identifier for the quote.

​
recipient
object
required

Details of the recipient. The structure depends on the recipient's currency. Recipient details for a payout to Nigeria (NGN).

  • NGN Payout
  • USD Payout
  • EUR Payout
  • GBP Payout
  • CAD Payout
​
reason
enum<string>

The reason for the payout.

Available options:
FAMILY_SUPPORT,
GIFT,
SALARY_PAYMENT,
EDUCATIONAL_FEES,
BUSINESS_INVOICE,
OTHER
​
remark
string

A standardized remark for the transaction.

Response

Payout transaction created successfully.

​
status
string
Example:

"success"

​
message
string
Example:

"Transaction created successfully."

​
data
object
⌘I