Create a NGN Payout Example

The Payout API allows users to process payouts in Nigerian Naira (NGN) to recipients in Nigeria via different payment channels such as Bank Transfer and Mobile Wallets.

Description

This endpoint allows users to send payouts in NGN to recipients in Nigeria. The request must include recipient details, payment method, and payout amounts.

Endpoint

Post: https://api.me-cash.com/v1/payout

Request Details

Headers

Header	Value	Required
`Content-Type`	`application/json`	✅ Yes
`x-api-key`	`API_KEY:YOUR_API_KEY`	✅ Yes

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.firstName`	String	First name of the recipient	✅ Yes
`recipient.lastName`	String	Last name of the recipient	✅ Yes
`recipient.type`	String	Recipient type (e.g., `INDIVIDUAL`, `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	`NGN` (Nigerian Naira)	✅ Yes
`recipient.country`	String	`NG` (Nigeria)	✅ Yes
`quoteId`	String	Unique Quote ID for the payout	✅ Yes
`reason`	String	Reason for the payout (e.g., `Gift`, `Invoice Payment`)	✅ Yes

Sample cURL Request

curl --location --request POST 'https://api.mecash.com/v1/payout' \
--header 'x-api-key: API_KEY_SANDBOX:YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
  "recipient": {
    "name": "Adeolu Adebayo",
    "firstName": "Adeolu",
    "lastName": "Adebayo",
    "type": "INDIVIDUAL",
    "account": {
      "accountNumber": "0123456789",
      "bankCode": "044"
    },
    "paymentChannel": "BANK_TRANSFER",
    "currency": "NGN",
    "country": "NG"
  },
  "quoteId": "d19a64f9-5a47-4bda-b7c2-0e8de5aeb13f",
  "reason": "Invoice Payment"
}'

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-ef1234567890",
        "remark": "Invoice Payment",
        "reason": "Invoice Payment",
        "referenceNumber": "TXYZD6RWSQMKF",
        "type": "SEND",
        "state": "PENDING",
        "quote": {
            "id": "d19a64f9-5a47-4bda-b7c2-0e8de5aeb13f",
            "source": {
                "currency": "USD",
                "country": "US",
                "amount": 100
            },
            "target": {
                "currency": "NGN",
                "country": "NG",
                "amount": 147000
            },
            "rate": 1470,
            "fee": {
                "amount": 500
            }
        },
        "recipient": {
            "name": "Adeolu Adebayo",
            "firstName": "Adeolu",
            "lastName": "Adebayo",
            "relationship": "SELF",
            "type": "BANK",
            "account": {
                "accountNumber": "0123456789",
                "bankCode": "044"
            },
            "paymentChannel": "BANK_TRANSFER",
            "currency": "NGN",
            "country": "NG"
        },
        "created": "2025-02-27T14:17:48.038044",
        "processed": "2025-02-27T14:20:49.712685"
    }
}

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`	Bad Request	`{ "message": "Invalid parameters" }`
`401`	Unauthorized	`{ "message": "Invalid API key" }`
`422`	Unprocessable Entity	`{ "message": "Invalid quote ID" }`
`500`	Internal Server Error	`{ "message": "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.

Create NGN - CNY Payout Example