> ## Documentation Index > Fetch the complete documentation index at: https://developer.me-cash.com/llms.txt > Use this file to discover all available pages before exploring further. # πŸ‡ΊπŸ‡Έ USD Payout This endpoint allows you to process payouts in **US Dollars (USD)** to recipients with a bank account in the United States. *** ## 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_CUSTOMER` | 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 Use `SWIFT_CUSTOMER` when the **sender bears all transfer charges**. Replace `paymentChannel` with `SWIFT_SHARED` if charges should be split with the beneficiary, or `SWIFT_BENEFICIARY` if the beneficiary bears all charges. All SWIFT channels use identical request fields β€” only the `paymentChannel` value changes. ```bash cURL theme={null} 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": { "name": "Test Limited", "icNumber": "96671******", "nationality": "NG", "address": { "line1": "12 main st" }, "mobileNumber": "+234872******", "occupation": "HEALTHCARE" }, "paymentChannel": "SWIFT_CUSTOMER", "currency": "USD", "quoteId": "859b19e8-8a00-4d59-9970-xxxxxxxxxxxxx", "reason": "Gift", "invoice": "4b9b6d30-a2ed-421a-bd69-xxxxxxxxxxxx", "remark": "Testing" }' ``` ```javascript JavaScript (Fetch) theme={null} 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: { name: "Test Limited", icNumber: "96671******", nationality: "NG", address: { line1: "12 main st" }, mobileNumber: "+234872******", occupation: "HEALTHCARE" }, paymentChannel: "SWIFT_CUSTOMER", currency: "USD", quoteId: "859b19e8-8a00-4d59-9970-xxxxxxxxxxxxx", reason: "Gift", invoice: "4b9b6d30-a2ed-421a-bd69-xxxxxxxxxxxx", 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)); ``` ```python Python (Requests) theme={null} 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": { "name": "Test Limited", "icNumber": "96671******", "nationality": "NG", "address": { "line1": "12 main st" }, "mobileNumber": "+234872******", "occupation": "HEALTHCARE" }, "paymentChannel": "SWIFT_CUSTOMER", "currency": "USD", "quoteId": "859b19e8-8a00-4d59-9970-xxxxxxxxxxxxx", "reason": "Gift", "invoice": "4b9b6d30-a2ed-421a-bd69-xxxxxxxxxxxx", "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 | **Field** | **Type** | **Description** | **Required** | | :-------------------------------- | :------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------- | | `paymentChannel` | String | The SWIFT channel to use. `SWIFT_CUSTOMER` β€” sender bears all charges; `SWIFT_SHARED` β€” charges split; `SWIFT_BENEFICIARY` β€” beneficiary bears all charges. | βœ… Yes | | `currency` | String | The ISO currency code. Must be `USD`. | βœ… Yes | | `quoteId` | String | The unique ID of the quote for this payout. | βœ… Yes | | `reason` | String | The purpose of the transfer (e.g., `Gift`, `Payment for services`). | βœ… Yes | | `invoice` | String | Optional identifier for the invoice (returned from file upload). | ❔ No | | `remark` | String | An optional, additional note about the transaction. | ❔ No | | `recipient` | Object | An object containing all details about the person receiving the funds. | βœ… Yes | | `recipient.name` | String | The full name of the recipient or business. | βœ… Yes | | `recipient.nickName` | String | A nickname or alias for the recipient. | ❔ No | | `recipient.gender` | String | Gender of the recipient. Enum: `M`, `F`. | ❔ No | | `recipient.occupation` | String | The recipient's occupation or profession. | ❔ No | | `recipient.type` | String | The type of recipient. Enum: `INDIVIDUAL`, `BUSINESS`. | βœ… Yes | | `recipient.account` | Object | An object containing the recipient's bank account details. | βœ… Yes | | `recipient.account.accountNumber` | String | The recipient's bank account number. | βœ… Yes | | `recipient.account.swiftCode` | String | The SWIFT/BIC code of the recipient's bank. | βœ… Yes | | `recipient.account.sortCode` | String | The bank sort code. | ❔ No | | `recipient.account.bankName` | String | The name of the recipient's bank. | βœ… Yes | | `recipient.account.bankCity` | String | The city where the bank is located. | ❔ No | | `sender` | Object | An object containing details about the person initiating the transfer. | βœ… Yes | | `sender.name` | String | The full name of the sender or business. | βœ… Yes | | `sender.icNumber` | String | The sender's identification/IC number. | βœ… Yes | | `sender.nationality` | String | The sender's two-letter ISO nationality code (e.g., `NG`). | βœ… Yes | | `sender.address` | Object | An object containing the sender's address details. | βœ… Yes | | `sender.address.line1` | String | The first line of the sender's address. | βœ… Yes | | `sender.mobileNumber` | String | The sender's mobile number in international format (e.g., `+234...`). | βœ… Yes | | `sender.occupation` | String | The sender's occupation or industry (e.g., `HEALTHCARE`). | βœ… Yes | | `sender.name` | String | The full name of the sender. | βœ… Yes | | `sender.icNumber` | String | The IC number of the sender. | βœ… Yes | | `sender.nationality` | String | The ISO nationality code of the sender. | βœ… Yes | | `sender.address` | String | The address of the sender. | βœ… Yes | | `sender.mobileNumber` | String | The phone number of the sender. | βœ… Yes | | `sender.occupation` | String | The occupation of the sender. | βœ… Yes | *** ## Success Response (200 OK) If the payout is successfully created, the API returns the following response: ```json copy theme={null} { "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_CUSTOMER", "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" }, "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_CUSTOMER`, `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, e.g., `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.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** βœ… Ensure `quoteId` is valid and linked to an existing quote.\ βœ… Confirm that the recipient's **bank account number** and **bank code** are correct.\ βœ… Use `SWIFT_CUSTOMER` 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.