Payout API Documentation

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: Create a 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.

URL: https://{{baseURL}}/v1/payout

Request Details

Headers

Include these headers in your request:

Body

The API requires the following fields when making a payout request:

Sample cURL Request

curl --location 'https://{{baseURL}}/v1/payout' \
--header 'x-api-key: API_KEY:YOUR_API_KEY' \
--header 'Content-Type: multipart/form-data' \
--form 'transaction="{
  \"recipient\": {
    \"id\": \"ef2503ff-aec9-40e5-bfcf-73167ba8077e\",
    \"name\": \"John Benjamin\",
    \"firstName\": \"John\",
    \"lastName\": \"Benjamin\",
    \"type\": \"BUSINESS\",
    \"account\": {
      \"accountNumber\": \"8612343562723\",
      \"sortCode\": \"0919202\",
      \"branchCode\": \"\",
      \"routingNumber\": \"342672\"
    },
    \"paymentChannel\": \"BANK_TRANSFER\",
    \"currency\": \"USD\",
    \"country\": \"US\",
    \"stored\": true
  },
  \"quoteId\": \"859b19e8-8a00-4d59-9970-85395006cc13\",
  \"reason\": \"Gift\"
}"

Success Response (200k)

If the payout is successfully processed, the API returns the following response:

{
  "message": "Payout successfully created",
  "status": "success",
  "data": {
    "recipient": {
      "id": "ef2503ff-aec9-40e5-bfcf-73167ba8077e",
      "name": "John Benjamin",
      "firstName": "John",
      "lastName": "Benjamin",
      "type": "BUSINESS",
      "account": {
        "accountNumber": "8612343562723",
        "sortCode": "0919202",
        "branchCode": "",
        "routingNumber": "342672"
      },
      "paymentChannel": "BANK_TRANSFER",
      "currency": "USD",
      "country": "US",
      "stored": true
    },
    "quoteId": "859b19e8-8a00-4d59-9970-85395006cc13",
    "reason": "Gift"
  },
}

Payout Transaction States

The payout transaction can have one of the following states:

Error Handling

Webhooks for Payout API

To stay informed about the status of payouts initiated via this API, you should configure your webhook endpoint (opens in a new tab) to listen for the following events:

• payout.completed (SEND): Sent when a payout initiated through the Payout API has been successfully completed.
• payout.failed (SEND): Sent when a payout initiated through the Payout API has failed.
• payout.pending (SEND): Sent when a payout request has been successfully created but is still awaiting final processing.

Refer to the Supported Webhook Events section in the main Webhooks documentation for detailed information on the payload structure for each of these events. By subscribing to these webhooks, your system will receive real-time updates on the progress and final status of your payout transactions.

Example Scenario:

When you initiate a payout using the "POST: Create a Payout" endpoint, you might first receive a payout.pending webhook. Subsequently, you will receive either a payout.completed webhook if the transaction is successful or a payout.failed webhook if it encounters an issue.

The payload for each of these events would look like this:

• payout.completed (SEND)

  {
    "event": "payout.completed",
    "data": {
      "id": "79d3acd4-1465-87hj-xft6-cf5t3b12a56b",
      "referenceNumber": "RRT6ADX1KLFOP",
      "remark": null,
      "type": "SEND",
      "state": "COMPLETED",
      "quote": {
        "id": "79d3acd4-1465-87hj-xft6-cf5t3b12a56b",
        "sourceCurrency": "NGN",
        "sourceAmount": 30000,
        "targetCurrency": "CNY",
        "targetAmount": 136.15,
        "rate": 220.3431138,
        "fees": [
          {
            "paymentChannel": "WECHAT",
            "amount": 5
          }
        ]
      },
      "recipient": {
        "name": "Zui len",
        "firstName": "Zui",
        "lastName": "len",
        "relationship": "SELF",
        "account": {
          "sortCode": "",
          "accountNumber": "8612343562723",
          "branchCode": ""
        },
        "currency": "CNY",
        "country": "CN",
        "stored": false
      },
      "created": "2025-05-13T15:23:15.258847784",
      "processed": "2025-05-13T15:23:16.258847784"
    }
  }

  Refer to the Example: payout.completed (NGN to CNY) (opens in a new tab) section in the main Webhooks documentation for a detailed breakdown of this payload.

• payout.failed (SEND) The payload structure is similar to payout.completed, but the "state" field will be "FAILED".

  {
    "event": "payout.failed",
    "data": {
      "id": "your-unique-payout-id",
      "referenceNumber": "your-payout-reference",
      "remark": "Reason for failure (if available)",
      "type": "SEND",
      "state": "FAILED",
      "quote": {
        "id": "related-quote-id",
        "sourceCurrency": "NGN",
        "sourceAmount": 1000,
        "targetCurrency": "USD",
        "targetAmount": 2.17,
        "rate": 460.829493,
        "fees": []
      },
      "recipient": {
        "name": "Jane Doe",
        "firstName": "Jane",
        "lastName": "Doe",
        "relationship": "FRIEND",
        "account": {
          "sortCode": "123456",
          "accountNumber": "9876543210",
          "branchCode": ""
        },
        "currency": "USD",
        "country": "US",
        "stored": false
      },
      "created": "2025-04-23T00:55:00.000000",
      "processed": "2025-04-23T00:56:00.000000"
    }
  }

  The specific fields and their values in the payout.failed payload will depend on the details of the failed transaction. The "state" field will always indicate "FAILED".

• payout.pending (SEND) The payload structure is similar to payout.completed, but the "state" field will be "PENDING".

  {
    "event": "payout.pending",
    "data": {
      "id": "another-unique-payout-id",
      "referenceNumber": "yet-another-reference",
      "remark": null,
      "type": "SEND",
      "state": "PENDING",
      "quote": {
        "id": "another-quote-id",
        "sourceCurrency": "NGN",
        "sourceAmount": 5000,
        "targetCurrency": "EUR",
        "targetAmount": 11.50,
        "rate": 434.782609,
        "fees": [
          {
            "paymentChannel": "BANK_TRANSFER",
            "amount": 10
          }
        ]
      },
      "recipient": {
        "name": "Luca Rossi",
        "firstName": "Luca",
        "lastName": "Rossi",
        "relationship": "BUSINESS",
        "account": {
          "sortCode": "IT0587",
          "accountNumber": "IT60X054281101000000123456",
          "branchCode": ""
        },
        "currency": "EUR",
        "country": "IT",
        "stored": true
      },
      "created": "2025-04-23T00:57:00.000000",
      "processed": "2025-04-23T00:57:00.000000"
    }
  }

  The payout.pending webhook provides an early notification that the payout process has begun.

By integrating with these webhooks and understanding their respective payloads, you can effectively monitor and manage the payouts initiated through the meCash Payout API in real-time.

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.