quoteId.
Endpoint
POST:https://sandboxapi.me-cash.com/v2/payout
Request Details
Headers
Include these headers in your request:| Header | Value | Required |
|---|---|---|
Content-Type | application/json | β Yes |
x-api-key | YOUR_API_KEY | β Yes |
Request Examples
curl --location --request POST 'https://sandboxapi.me-cash.com/v2/payout' \
--header 'x-api-key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
"remark": "Testing",
"reason": "Gift",
"invoice": "4b9b6d30-a2ed-421a-bd69-xxxxxxxxxxxx",
"quoteId": "91e58c2d-ef14-4777-906b-xxxxxxxxxxxxx",
"recipient": {
"name": "Adeolu Adebayo",
"paymentChannel": "BANK_TRANSFER",
"currency": "NGN",
"country": "NG",
"account": {
"bankName": "GT Bank",
"accountNumber": "001040XXXXX",
"sortCode": "058"
}
}
}'
const url = 'https://sandboxapi.me-cash.com/v2/payout';
const options = {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-api-key': 'YOUR_API_KEY'
},
body: JSON.stringify({
remark: 'Testing',
reason: 'Gift',
invoice: '4b9b6d30-a2ed-421a-bd69-xxxxxxxxxxxx',
quoteId: '91e58c2d-ef14-4777-906b-xxxxxxxxxxxxx',
recipient: {
name: 'Adeolu Adebayo',
paymentChannel: 'BANK_TRANSFER',
currency: 'NGN',
country: 'NG',
account: {
bankName: 'GT Bank',
accountNumber: '001040XXXXX',
sortCode: '058'
}
}
})
};
fetch(url, options)
.then(res => {
if (!res.ok) {
throw new Error(`HTTP error! status: ${res.status}`);
}
return res.json();
})
.then(data => console.log(data))
.catch(error => console.error('Error:', error));
import requests
url = "https://sandboxapi.me-cash.com/v2/payout"
payload = {
"remark": "Testing",
"reason": "Gift",
"invoice": "4b9b6d30-a2ed-421a-bd69-xxxxxxxxxxxx",
"quoteId": "91e58c2d-ef14-4777-906b-xxxxxxxxxxxxx",
"recipient": {
"name": "Adeolu Adebayo",
"paymentChannel": "BANK_TRANSFER",
"currency": "NGN",
"country": "NG",
"account": {
"bankName": "GT Bank",
"accountNumber": "001040XXXXX",
"sortCode": "058"
}
}
}
headers = {
"x-api-key": "YOUR_API_KEY"
}
try:
response = requests.post(url, headers=headers, json=payload)
response.raise_for_status() # Raises an HTTPError for bad responses (4xx or 5xx)
print(response.json())
except requests.exceptions.HTTPError as err:
print(f"HTTP Error: {err}")
except requests.exceptions.RequestException as e:
print(f"Request Error: {e}")
const axios = require('axios');
const url = 'https://sandboxapi.me-cash.com/v2/payout';
const data = {
remark: 'Testing',
reason: 'Gift',
invoice: '4b9b6d30-a2ed-421a-bd69-xxxxxxxxxxxx',
quoteId: '91e58c2d-ef14-4777-906b-xxxxxxxxxxxxx',
recipient: {
name: 'Adeolu Adebayo',
paymentChannel: 'BANK_TRANSFER',
currency: 'NGN',
country: 'NG',
account: {
bankName: 'GT Bank',
accountNumber: '001040XXXXX',
sortCode: '058'
}
}
};
const config = {
headers: {
'Content-Type': 'application/json',
'x-api-key': 'YOUR_API_KEY'
}
};
axios.post(url, data, config)
.then(response => {
console.log(response.data);
})
.catch(error => {
console.error('Error:', error.response ? error.response.data : error.message);
});
Note: Recipientβs name and Bank name must match the details in the Bank list endpoint and Account enquiry endpoint.
Request Body
The following fields are required when making an NGN payout request:| Field | Type | Description |
|---|---|---|
remark | String | Additional note about the transaction. |
reason | String | Purpose of the transfer (e.g., Gift). |
invoice | String | Optional identifier for the invoice (returned from file upload endpoint). |
quoteId | String | Unique Quote ID for the payout. |
recipient.name | String | Full name of the recipient. |
recipient.paymentChannel | String | Payment method (BANK_TRANSFER). |
recipient.currency | String | ISO currency code (NGN). |
recipient.country | String | ISO country code (NG). |
recipient.account.bankName | String | Name of the recipientβs bank. |
recipient.account.accountNumber | String | Recipientβs bank account number. |
recipient.account.sortCode | String | The 3-digit bank unique code (e.g., 058 for GTBank). |
Success Response (200 OK)
If the payout is successfully created, the API returns the following response:copy
{
"message": "Transaction created successfully",
"status": "success",
"data": {
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"remark": "Testing",
"invoice": "4b9b6d30-a2ed-421a-bd69-xxxxxxxxxxxx",
"reason": "Gift",
"referenceNumber": "TXYZD6RWSQMKF",
"type": "SEND",
"state": "COMPLETED",
"quote": {
"id": "91e58c2d-ef14-4777-906b-xxxxxxxxxxxxx",
"source": {
"currency": "NGN",
"country": "NG",
"amount": 100000
},
"target": {
"currency": "NGN",
"country": "NG",
"amount": 100000
},
"rate": 1,
"fee": {
"amount": 100
}
},
"recipient": {
"name": "Adeolu Adebayo",
"firstName": "Adeolu",
"lastName": "Adebayo",
"relationship": "SELF",
"type": "BUSINESS",
"account": {
"bankName": "GT Bank",
"accountNumber": "001040XXXXX",
"sortCode": "058"
},
"paymentChannel": "BANK_TRANSFER",
"currency": "NGN",
"country": "NG"
},
"created": "2025-08-22T10:55:48.038044",
"processed": "2025-08-22T10:58:49.712685"
}
}
Response Breakdown
| Field | Type | Description |
|---|---|---|
message | String | Confirmation message indicating the result of the request. |
status | String | Overall status of the request (success). |
data | Object | Container for the payout transaction details. |
data.id | String | Unique identifier for the payout transaction. |
data.remark | String | Optional note about the transaction, as provided in the request. |
data.invoice | String | Optional identifier for the invoice, as provided in the request. |
data.reason | String | Reason for the payout, as provided in the request. |
data.referenceNumber | String | Unique reference number generated for the payout. |
data.type | String | Type of transaction (e.g., SEND). |
data.state | String | Current state of the payout (COMPLETED, PENDING, FAILED, REFUNDED). |
data.quote.id | String | Unique ID of the quote used for the transaction. |
data.quote.source.currency | String | Currency of the source funds (NGN). |
data.quote.source.country | String | ISO country code of the source (NG). |
data.quote.source.amount | Number | Amount debited from the source. |
data.quote.target.currency | String | Currency received by the recipient (NGN). |
data.quote.target.country | String | ISO country code of the recipient (NG). |
data.quote.target.amount | Number | Amount credited to the recipient. |
data.quote.rate | Number | Conversion rate applied (1 for NGN β NGN). |
data.quote.fee.amount | Number | Fee charged for the payout. |
data.recipient.name | String | Full name of the recipient. |
data.recipient.firstName | String | Recipientβs first name. |
data.recipient.lastName | String | Recipientβs last name. |
data.recipient.relationship | String | Relationship to account holder (e.g., SELF). |
data.recipient.type | String | Recipient type (BUSINESS). |
data.recipient.account.accountNumber | String | Recipientβs bank account number. |
data.recipient.account.sortCode | String | Bank unique code (e.g., 058 for GTBank). |
data.recipient.account.bankName | String | Name of the recipientβs bank. |
data.recipient.paymentChannel | String | Payment method used (BANK_TRANSFER). |
data.recipient.currency | String | Currency of the recipientβs account (NGN). |
data.recipient.country | String | Recipientβs ISO country code (NG). |
data.created | String | ISO 8601 timestamp when the transaction was created. |
data.processed | String | ISO 8601 timestamp when the transaction was processed. |
Error Handling
| Status Code | Meaning | Example Response |
|---|---|---|
400 | Insufficient Balance | Insufficient Balance |
401 | Unauthorized | Invalid API key provided. |
403 | Forbidden | IP not whitelisted |
404 | Not Found | The requested endpoint does not exist. |
422 | Unprocessable Entity | Invalid quote ID provided. |
500 | Internal Server Error | An internal error occurred. |
Best Practices
β EnsurequoteId 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.
Testing Failed Payouts: In the sandbox environment, you can simulate a failed payout by setting
"remark": "fail" in your request. This triggers a payout.failed webhook, allowing you to test your error handling.
