Endpoint
POST:https://sandboxapi.me-cash.com/v2/payout
Supported Payment Channels
USD payouts support three SWIFT-based payment channels. All use the same recipient fields — the only difference is who bears the transfer charges.| Channel | Charge Bearer | Description |
|---|---|---|
SWIFT_OUR | Sender | The sending customer bears all transfer charges. |
SWIFT_SHARED | Both parties | Transfer charges are shared between sender and beneficiary. |
SWIFT_BENEFICIARY | Beneficiary | The beneficiary bears all transfer charges. |
Request Details
Headers
Include these headers in your request:| Header | Value | Required |
|---|---|---|
Content-Type | application/json | ✅ Yes |
x-api-key | YOUR_API_KEY | ✅ Yes |
Sample Requests
- INDIVIDUAL
- BUSINESS
curl --location --request POST 'https://sandboxapi.me-cash.com/v2/payout' \
--header 'x-api-key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"recipient": {
"name": "James Wilson",
"nickName": "Blue",
"gender": "M",
"occupation": "business entrepreneur",
"type": "BUSINESS",
"account": {
"sortCode": "02090",
"swiftCode": "GTBINGLA",
"bankCity": "Atlanta",
"accountNumber": "885406******",
"bankName": "DBS Bank Limited",
"intermediarySwiftCode": "CHASUS33XXX"
}
},
"sender": {
"type": "PERSON",
"name": "Jane James",
"idNumber": "A123456",
"dateOfBirth": "2000-12-12",
"relationship": "Friend",
"gender": "F",
"nationality": "NG",
"address": "12 Main Street",
"mobileNumber": "080993773777",
"occupation": "Employee"
},
"paymentChannel": "SWIFT_OUR",
"currency": "USD",
"quoteId": "859b19e8-8a00-4d59-9970-xxxxxxxxxxxxx",
"reason": "Gift",
"remark": "Testing"
}'
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({
"recipient": {
"name": "James Wilson",
"nickName": "Blue",
"gender": "M",
"occupation": "business entrepreneur",
"type": "BUSINESS",
"account": {
"sortCode": "02090",
"swiftCode": "GTBINGLA",
"bankCity": "Atlanta",
"accountNumber": "885406******",
"bankName": "DBS Bank Limited",
"intermediarySwiftCode": "CHASUS33XXX"
}
},
"sender": {
"type": "PERSON",
"name": "Jane James",
"idNumber": "A123456",
"dateOfBirth": "2000-12-12",
"relationship": "Friend",
"gender": "F",
"nationality": "NG",
"address": "12 Main Street",
"mobileNumber": "080993773777",
"occupation": "Employee"
},
"paymentChannel": "SWIFT_OUR",
"currency": "USD",
"quoteId": "859b19e8-8a00-4d59-9970-xxxxxxxxxxxxx",
"reason": "Gift",
"remark": "Testing"
})
};
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
import json
url = "https://sandboxapi.me-cash.com/v2/payout"
payload = {
"recipient": {
"name": "James Wilson",
"nickName": "Blue",
"gender": "M",
"occupation": "business entrepreneur",
"type": "BUSINESS",
"account": {
"sortCode": "02090",
"swiftCode": "GTBINGLA",
"bankCity": "Atlanta",
"accountNumber": "885406******",
"bankName": "DBS Bank Limited",
"intermediarySwiftCode": "CHASUS33XXX"
}
},
"sender": {
"type": "PERSON",
"name": "Jane James",
"idNumber": "A123456",
"dateOfBirth": "2000-12-12",
"relationship": "Friend",
"gender": "F",
"nationality": "NG",
"address": "12 Main Street",
"mobileNumber": "080993773777",
"occupation": "Employee"
},
"paymentChannel": "SWIFT_OUR",
"currency": "USD",
"quoteId": "859b19e8-8a00-4d59-9970-xxxxxxxxxxxxx",
"reason": "Gift",
"remark": "Testing"
}
headers = {
"x-api-key": "YOUR_API_KEY",
"Content-Type": "application/json"
}
try:
response = requests.post(url, headers=headers, data=json.dumps(payload))
response.raise_for_status()
print(response.json())
except requests.exceptions.HTTPError as err:
print(f"HTTP Error: {err}")
curl --location --request POST 'https://sandboxapi.me-cash.com/v2/payout' \
--header 'x-api-key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"recipient": {
"name": "James Wilson",
"nickName": "Blue",
"gender": "M",
"occupation": "business entrepreneur",
"type": "BUSINESS",
"account": {
"sortCode": "02090",
"swiftCode": "GTBINGLA",
"bankCity": "Atlanta",
"accountNumber": "885406******",
"bankName": "DBS Bank Limited",
"intermediarySwiftCode": "CHASUS33XXX"
}
},
"sender": {
"type": "BUSINESS",
"name": "ABC Limited",
"dateOfIncorporation": "2026-07-02",
"relationship": "Business Partner",
"icNumber": "12345",
"nationality": "NG",
"address": {
"line1": "12 Main Street"
},
"occupation": "Employee"
},
"paymentChannel": "SWIFT_OUR",
"currency": "USD",
"quoteId": "859b19e8-8a00-4d59-9970-xxxxxxxxxxxxx",
"reason": "Gift",
"remark": "Testing"
}'
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({
"recipient": {
"name": "James Wilson",
"nickName": "Blue",
"gender": "M",
"occupation": "business entrepreneur",
"type": "BUSINESS",
"account": {
"sortCode": "02090",
"swiftCode": "GTBINGLA",
"bankCity": "Atlanta",
"accountNumber": "885406******",
"bankName": "DBS Bank Limited",
"intermediarySwiftCode": "CHASUS33XXX"
}
},
"sender": {
"type": "BUSINESS",
"name": "ABC Limited",
"dateOfIncorporation": "2026-07-02",
"relationship": "Business Partner",
"icNumber": "12345",
"nationality": "NG",
"address": {
"line1": "12 Main Street"
},
"occupation": "Employee"
},
"paymentChannel": "SWIFT_OUR",
"currency": "USD",
"quoteId": "859b19e8-8a00-4d59-9970-xxxxxxxxxxxxx",
"reason": "Gift",
"remark": "Testing"
})
};
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
import json
url = "https://sandboxapi.me-cash.com/v2/payout"
payload = {
"recipient": {
"name": "James Wilson",
"nickName": "Blue",
"gender": "M",
"occupation": "business entrepreneur",
"type": "BUSINESS",
"account": {
"sortCode": "02090",
"swiftCode": "GTBINGLA",
"bankCity": "Atlanta",
"accountNumber": "885406******",
"bankName": "DBS Bank Limited",
"intermediarySwiftCode": "CHASUS33XXX"
}
},
"sender": {
"type": "BUSINESS",
"name": "ABC Limited",
"dateOfIncorporation": "2026-07-02",
"relationship": "Business Partner",
"icNumber": "12345",
"nationality": "NG",
"address": {
"line1": "12 Main Street"
},
"occupation": "Employee"
},
"paymentChannel": "SWIFT_OUR",
"currency": "USD",
"quoteId": "859b19e8-8a00-4d59-9970-xxxxxxxxxxxxx",
"reason": "Gift",
"remark": "Testing"
}
headers = {
"x-api-key": "YOUR_API_KEY",
"Content-Type": "application/json"
}
try:
response = requests.post(url, headers=headers, data=json.dumps(payload))
response.raise_for_status()
print(response.json())
except requests.exceptions.HTTPError as err:
print(f"HTTP Error: {err}")
Request Body Breakdown
- INDIVIDUAL
- BUSINESS
curl --location --request POST 'https://sandboxapi.me-cash.com/v2/payout' \
--header 'x-api-key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"recipient": {
"name": "James Wilson",
"nickName": "Blue",
"gender": "M",
"occupation": "business entrepreneur",
"type": "BUSINESS",
"account": {
"sortCode": "02090",
"swiftCode": "GTBINGLA",
"bankCity": "Atlanta",
"accountNumber": "885406******",
"bankName": "DBS Bank Limited",
"intermediarySwiftCode": "CHASUS33XXX"
}
},
"sender": {
"type": "PERSON",
"name": "Jane James",
"idNumber": "A123456",
"dateOfBirth": "2000-12-12",
"relationship": "Friend",
"gender": "F",
"nationality": "NG",
"address": "12 Main Street",
"mobileNumber": "080993773777",
"occupation": "Employee"
},
"paymentChannel": "SWIFT_OUR",
"currency": "USD",
"quoteId": "859b19e8-8a00-4d59-9970-xxxxxxxxxxxxx",
"reason": "Gift",
"remark": "Testing"
}'
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({
"recipient": {
"name": "James Wilson",
"nickName": "Blue",
"gender": "M",
"occupation": "business entrepreneur",
"type": "BUSINESS",
"account": {
"sortCode": "02090",
"swiftCode": "GTBINGLA",
"bankCity": "Atlanta",
"accountNumber": "885406******",
"bankName": "DBS Bank Limited",
"intermediarySwiftCode": "CHASUS33XXX"
}
},
"sender": {
"type": "PERSON",
"name": "Jane James",
"idNumber": "A123456",
"dateOfBirth": "2000-12-12",
"relationship": "Friend",
"gender": "F",
"nationality": "NG",
"address": "12 Main Street",
"mobileNumber": "080993773777",
"occupation": "Employee"
},
"paymentChannel": "SWIFT_OUR",
"currency": "USD",
"quoteId": "859b19e8-8a00-4d59-9970-xxxxxxxxxxxxx",
"reason": "Gift",
"remark": "Testing"
})
};
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
import json
url = "https://sandboxapi.me-cash.com/v2/payout"
payload = {
"recipient": {
"name": "James Wilson",
"nickName": "Blue",
"gender": "M",
"occupation": "business entrepreneur",
"type": "BUSINESS",
"account": {
"sortCode": "02090",
"swiftCode": "GTBINGLA",
"bankCity": "Atlanta",
"accountNumber": "885406******",
"bankName": "DBS Bank Limited",
"intermediarySwiftCode": "CHASUS33XXX"
}
},
"sender": {
"type": "PERSON",
"name": "Jane James",
"idNumber": "A123456",
"dateOfBirth": "2000-12-12",
"relationship": "Friend",
"gender": "F",
"nationality": "NG",
"address": "12 Main Street",
"mobileNumber": "080993773777",
"occupation": "Employee"
},
"paymentChannel": "SWIFT_OUR",
"currency": "USD",
"quoteId": "859b19e8-8a00-4d59-9970-xxxxxxxxxxxxx",
"reason": "Gift",
"remark": "Testing"
}
headers = {
"x-api-key": "YOUR_API_KEY",
"Content-Type": "application/json"
}
try:
response = requests.post(url, headers=headers, data=json.dumps(payload))
response.raise_for_status()
print(response.json())
except requests.exceptions.HTTPError as err:
print(f"HTTP Error: {err}")
curl --location --request POST 'https://sandboxapi.me-cash.com/v2/payout' \
--header 'x-api-key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"recipient": {
"name": "James Wilson",
"nickName": "Blue",
"gender": "M",
"occupation": "business entrepreneur",
"type": "BUSINESS",
"account": {
"sortCode": "02090",
"swiftCode": "GTBINGLA",
"bankCity": "Atlanta",
"accountNumber": "885406******",
"bankName": "DBS Bank Limited",
"intermediarySwiftCode": "CHASUS33XXX"
}
},
"sender": {
"type": "BUSINESS",
"name": "ABC Limited",
"dateOfIncorporation": "2026-07-02",
"relationship": "Business Partner",
"icNumber": "12345",
"nationality": "NG",
"address": {
"line1": "12 Main Street"
},
"occupation": "Employee"
},
"paymentChannel": "SWIFT_OUR",
"currency": "USD",
"quoteId": "859b19e8-8a00-4d59-9970-xxxxxxxxxxxxx",
"reason": "Gift",
"remark": "Testing"
}'
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({
"recipient": {
"name": "James Wilson",
"nickName": "Blue",
"gender": "M",
"occupation": "business entrepreneur",
"type": "BUSINESS",
"account": {
"sortCode": "02090",
"swiftCode": "GTBINGLA",
"bankCity": "Atlanta",
"accountNumber": "885406******",
"bankName": "DBS Bank Limited",
"intermediarySwiftCode": "CHASUS33XXX"
}
},
"sender": {
"type": "BUSINESS",
"name": "ABC Limited",
"dateOfIncorporation": "2026-07-02",
"relationship": "Business Partner",
"icNumber": "12345",
"nationality": "NG",
"address": {
"line1": "12 Main Street"
},
"occupation": "Employee"
},
"paymentChannel": "SWIFT_OUR",
"currency": "USD",
"quoteId": "859b19e8-8a00-4d59-9970-xxxxxxxxxxxxx",
"reason": "Gift",
"remark": "Testing"
})
};
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
import json
url = "https://sandboxapi.me-cash.com/v2/payout"
payload = {
"recipient": {
"name": "James Wilson",
"nickName": "Blue",
"gender": "M",
"occupation": "business entrepreneur",
"type": "BUSINESS",
"account": {
"sortCode": "02090",
"swiftCode": "GTBINGLA",
"bankCity": "Atlanta",
"accountNumber": "885406******",
"bankName": "DBS Bank Limited",
"intermediarySwiftCode": "CHASUS33XXX"
}
},
"sender": {
"type": "BUSINESS",
"name": "ABC Limited",
"dateOfIncorporation": "2026-07-02",
"relationship": "Business Partner",
"icNumber": "12345",
"nationality": "NG",
"address": {
"line1": "12 Main Street"
},
"occupation": "Employee"
},
"paymentChannel": "SWIFT_OUR",
"currency": "USD",
"quoteId": "859b19e8-8a00-4d59-9970-xxxxxxxxxxxxx",
"reason": "Gift",
"remark": "Testing"
}
headers = {
"x-api-key": "YOUR_API_KEY",
"Content-Type": "application/json"
}
try:
response = requests.post(url, headers=headers, data=json.dumps(payload))
response.raise_for_status()
print(response.json())
except requests.exceptions.HTTPError as err:
print(f"HTTP Error: {err}")
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": "274fd8a4-38f1-43c9-bf74-ae7744a0dba5",
"remark": "User-friendly",
"reason": "Gift",
"referenceNumber": "0XCGU0EYFEK0Y",
"invoice": {
"fileName": "image.png"
},
"type": "SEND",
"state": "PENDING",
"quote": {
"id": "4da9d52d-618b-4683-b408-8844d1b520cd",
"paymentChannel": "SWIFT_OUR",
"source": {
"currency": "USD",
"country": "US",
"amount": 10.00
},
"target": {
"currency": "USD",
"country": "US",
"amount": 10.00
},
"rate": 1.00000000,
"fee": {
"amount": 100.00,
"stampDuty": 0
},
"summary": {
"total": 110.00
},
"settlement": "1hr",
"quoteCurrency": "USD"
},
"recipient": {
"name": "Crystal Strosin",
"nickName": "magenta",
"gender": "M",
"type": "BUSINESS",
"account": {
"bankName": "DBS Bank Limited",
"sortCode": "02090",
"accountNumber": "885406477269",
"bankCity": "Atlanta",
"swiftCode": "GTBINGLA"
},
"occupation": "business enterpreneur"
},
"sender": {
"name": "Test Limited",
"icNumber": "96671733919",
"nationality": "NG",
"address": {
"line1": "12 main st"
},
"mobileNumber": "+234872272808",
"occupation": "HEALTHCARE",
"type": "BUSINESS"
},
"created": "2026-04-23T18:06:41.022734019Z",
"processed": "2026-04-23T18:06:41.022734019Z"
}
}
Response Breakdown
| Field | Type | Description |
|---|---|---|
message | String | A confirmation message indicating the result of the request. |
status | String | The overall status of the request, e.g., success. |
data | Object | A container for all the transaction data. |
data.id | String | The unique identifier for this payout transaction. |
data.remark | String | An optional, additional note about the transaction. |
data.reason | String | The reason for the payout (e.g., Gift). |
data.referenceNumber | String | A unique reference number generated for the payout. |
data.invoice | Object | Details of the uploaded invoice. |
data.invoice.fileName | String | The name of the invoice file. |
data.type | String | The type of transaction, e.g., SEND. |
data.state | String | The current state of the payout (PENDING, COMPLETED, etc.). |
data.quote.id | String | The unique ID of the quote used for the transaction. |
data.quote.paymentChannel | String | The payment channel used (e.g., SWIFT_OUR, SWIFT_SHARED, SWIFT_BENEFICIARY). |
data.quote.source.currency | String | Source currency code. |
data.quote.source.amount | Number | Total source amount before fees. |
data.quote.target.currency | String | Destination currency code. |
data.quote.target.amount | Number | The converted amount that the recipient receives. |
data.quote.rate | Number | The exchange rate applied to the transaction. |
data.quote.fee.amount | Number | The transaction fee charged. |
data.quote.fee.stampDuty | Number | Applied stamp duty (if any). |
data.quote.summary.total | Number | Total amount (amount + fees) deducted from wallet. |
data.quote.settlement | String | The estimated time for settlement. |
data.quote.quoteCurrency | String | The currency in which the quote is priced. |
data.recipient.name | String | The full name of the recipient. |
data.recipient.nickName | String | Recipient’s nickname. |
data.recipient.gender | String | Gender (M or F). |
data.recipient.type | String | The type of recipient entity (INDIVIDUAL, PERSON, BUSINESS). |
data.recipient.account.bankName | String | Name of the recipient’s bank. |
data.recipient.account.accountNumber | String | Recipient’s bank account number. |
data.recipient.account.swiftCode | String | SWIFT/BIC code of the bank. |
data.recipient.occupation | String | Occupation of the recipient. |
data.sender.name | String | Full name of the sender. |
data.sender.icNumber | String | Sender’s ID number. |
data.sender.nationality | String | ISO country code of the sender’s nationality. |
data.sender.address.line1 | String | Primary address line of the sender. |
data.sender.mobileNumber | String | International mobile number of the sender. |
data.sender.occupation | String | Occupation of the sender. |
data.sender.type | String | Type of the sender. |
data.created | String | ISO 8601 timestamp of when the transaction was created. |
data.processed | String | ISO 8601 timestamp of when the transaction was processed. |
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 | 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
SWIFT_OUR when the sender bears all transfer charges, SWIFT_SHARED when charges are split, or SWIFT_BENEFICIARY when the beneficiary bears all charges.✅ 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.