🇺🇸 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

SWIFT_CUSTOMER

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.

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"
}'

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));

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

SWIFT Fields

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:

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_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.

Overview

Wallets

Quotes

Payouts

Virtual Accounts

Ramp

Transactions

Webhooks

Endpoint

Supported Payment Channels

Request Details

Headers

Sample Requests

Request Body Breakdown

Success Response (200 OK)

Response Breakdown

Payout Transaction States

Error Handling

Best Practices

​Endpoint

​Supported Payment Channels

​Request Details

​Headers

​Sample Requests

​Request Body Breakdown

​Success Response (200 OK)

​Response Breakdown

​Payout Transaction States

​Error Handling

​Best Practices

Endpoint

Supported Payment Channels

Request Details

Headers

Sample Requests

Request Body Breakdown

Success Response (200 OK)

Response Breakdown

Payout Transaction States

Error Handling

Best Practices