Create a USD Payout Example

The Payout API allows users to process payouts in US Dollars (USD) to recipients in the United States via Bank Transfer.

Endpoint

Post: {{baseURL}}/v1/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

Sample cURL Request

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

Request Body

The following fields are required when making an NGN payout request:

Request Body Breakdown

Field	Type	Description	Required
`recipient`	Object	Details of the payout recipient	✅ Yes
├─ `recipient.id`	String	Unique identifier for the recipient	Optional
├─ `recipient.name`	String	Full name of the recipient	✅ Yes
├─ `recipient.firstName`	String	First name of the recipient	✅ Yes
├─ `recipient.lastName`	String	Last name of the recipient	✅ Yes
├─ `recipient.type`	String	Recipient type (`INDIVIDUAL` or `BUSINESS`)	✅ Yes
├─ `recipient.account`	Object	Recipient’s bank account details	✅ Yes
│ ├─ `account.accountNumber`	String	Bank account number of the recipient	✅ Yes
│ ├─ `account.sortCode`	String	Sort code of the recipient's bank	✅ Yes
│ └─ `account.routingNumber`	String	Routing number for the recipient's bank	✅ Yes
├─ `recipient.paymentChannel`	String	Payment method (`BANK_TRANSFER`)	✅ Yes
├─ `recipient.currency`	String	Currency code (e.g., `USD`)	✅ Yes
├─ `recipient.country`	String	Country code (e.g., `US`)	✅ Yes
└─ `recipient.stored`	Boolean	Whether recipient info is stored for future use	✅ Yes
`quoteId`	String	Unique Quote ID for the payout	✅ Yes
`reason`	String	Reason for the payout (e.g., `Gift`, `Invoice Payment`)	✅ Yes

Success Response (200 OK)

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

{
  "message": "Transaction created successfully",
  "status": "success",
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-xxxxxxxxxxxxx",
    "remark": "Invoice Payment",
    "reason": "Invoice Payment",
    "referenceNumber": "TXYZD6RWSQMKF",
    "type": "SEND",
    "state": "COMPLETED",
    "quote": {
      "id": "d19a64f9-5a47-4bda-b7c2-xxxxxxxxxxxxx",
      "source": {
        "currency": "NGN",
        "country": "NG",
        "amount": 160000
      },
      "target": {
        "currency": "USD",
        "country": "US",
        "amount": 100
      },
      "rate": 1600,
      "fee": {
        "amount": 500
      }
    },
    "recipient": {
      "name": "Adeolu Adebayo",
      "type": "BANK",
      "account": {
        "accountNumber": "0123456789",
        "bankCode": "044"
      },
      "paymentChannel": "BANK_TRANSFER",
      "currency": "USD",
      "country": "US"
    },
    "created": "2025-02-27T14:17:48.038044",
    "processed": "2025-02-27T14:20:49.712685"
  }
}

Response Breakdown

Field	Type	Description
`message`	String	Transaction creation message
`status`	String	Status of the transaction
`data`	Object	Details of the transaction
├─ `id`	String	Unique ID of the transaction
├─ `remark`	String	Remark provided for the transaction
├─ `reason`	String	Reason for the transaction
├─ `referenceNumber`	String	Reference number for tracking
├─ `type`	String	Type of transaction (e.g., `SEND`)
├─ `state`	String	Current state of the transaction
├─ `quote`	Object	Quote details associated with the transaction
│ ├─ `id`	String	Quote ID
│ ├─ `source`	Object	Source currency details
│ │ ├─ `currency`	String	Source currency code (e.g., `NGN`)
│ │ ├─ `country`	String	Source country code (e.g., `NG`)
│ │ ├─ `amount`	Number	Source amount
│ ├─ `target`	Object	Target currency details
│ │ ├─ `currency`	String	Target currency code (e.g., `USD`)
│ │ ├─ `country`	String	Target country code (e.g., `US`)
│ │ ├─ `amount`	Number	Target amount
│ ├─ `rate`	Number	Exchange rate
│ ├─ `fee`	Object	Fee details
│ │ ├─ `amount`	Number	Fee amount
├─ `recipient`	Object	Recipient details
│ ├─ `name`	String	Name of the recipient
│ ├─ `type`	String	Type of recipient (e.g., `BANK`)
│ ├─ `account`	Object	Recipient's account information
│ │ ├─ `accountNumber`	String	Bank account number
│ │ ├─ `bankCode`	String	Bank code
│ ├─ `paymentChannel`	String	Payment method used
│ ├─ `currency`	String	Recipient’s currency code
│ ├─ `country`	String	Recipient’s country code
├─ `created`	String	Creation timestamp
├─ `processed`	String	Processing timestamp

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`	Bad Request	Invalid parameters
`401`	Unauthorized	Invalid API key
`422`	Unprocessable Entity	Invalid quote ID
`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 a valid API key in the headers.
✅ Handle error responses correctly in your integration.

NGN to GBP NGN to CNY AliPay (Email)