Create Payout

curl --request POST \
  --url https://sandboxapi.me-cash.com/v2/payout \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "remark": "TESTING",
  "reason": "GIFT",
  "quoteId": "91e58c2d-ef14-4777-906b-xxxxxxxxxxxxx",
  "recipient": {
    "name": "Adeolu Adebayo",
    "account": {
      "bankName": "GT Bank",
      "accountNumber": "0010401234",
      "bankCode": "058"
    }
  }
}
'

{
  "status": "success",
  "message": "Transaction created successfully.",
  "data": {
    "id": "c6611ad3-805a-415b-98b7-xxxxxxxxxxxxx",
    "remark": "Testing",
    "reason": "Gift",
    "referenceNumber": "L2TEZEHNXXXXXX",
    "type": "SEND",
    "state": "COMPLETED",
    "quote": {
      "id": "e5eec724-38f9-40e2-9i86-xxxxxxxxxxxxx",
      "source": {
        "currency": "NGN",
        "country": "NG",
        "amount": 150000
      },
      "target": {
        "currency": "USD",
        "country": "US",
        "amount": 81.97
      },
      "rate": 1830,
      "fee": {
        "amount": 0
      },
      "rules": [
        {
          "category": "LIMIT",
          "appliedCurrency": "USD",
          "appliedCountry": "US",
          "transaction": {
            "minimum": 1,
            "maximum": 20000000000000
          },
          "invoice": 200000000000
        }
      ],
      "summary": {
        "total": 150000
      },
      "settlementTime": "1 hr",
      "quoteCurrency": "USD",
      "expiresInSeconds": 600
    },
    "recipient": {
      "paymentChannel": "BANK_TRANSFER",
      "currency": "NGN",
      "country": "NG",
      "account": {
        "accountNumber": "0010401234",
        "bankName": "<string>",
        "sortCode": "058"
      },
      "name": "<string>",
      "type": "INDIVIDUAL",
      "address": "<string>"
    },
    "created": "2023-11-07T05:31:56Z",
    "processed": "2023-11-07T05:31:56Z"
  }
}

POST

payout

curl --request POST \
  --url https://sandboxapi.me-cash.com/v2/payout \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "remark": "TESTING",
  "reason": "GIFT",
  "quoteId": "91e58c2d-ef14-4777-906b-xxxxxxxxxxxxx",
  "recipient": {
    "name": "Adeolu Adebayo",
    "account": {
      "bankName": "GT Bank",
      "accountNumber": "0010401234",
      "bankCode": "058"
    }
  }
}
'

{
  "status": "success",
  "message": "Transaction created successfully.",
  "data": {
    "id": "c6611ad3-805a-415b-98b7-xxxxxxxxxxxxx",
    "remark": "Testing",
    "reason": "Gift",
    "referenceNumber": "L2TEZEHNXXXXXX",
    "type": "SEND",
    "state": "COMPLETED",
    "quote": {
      "id": "e5eec724-38f9-40e2-9i86-xxxxxxxxxxxxx",
      "source": {
        "currency": "NGN",
        "country": "NG",
        "amount": 150000
      },
      "target": {
        "currency": "USD",
        "country": "US",
        "amount": 81.97
      },
      "rate": 1830,
      "fee": {
        "amount": 0
      },
      "rules": [
        {
          "category": "LIMIT",
          "appliedCurrency": "USD",
          "appliedCountry": "US",
          "transaction": {
            "minimum": 1,
            "maximum": 20000000000000
          },
          "invoice": 200000000000
        }
      ],
      "summary": {
        "total": 150000
      },
      "settlementTime": "1 hr",
      "quoteCurrency": "USD",
      "expiresInSeconds": 600
    },
    "recipient": {
      "paymentChannel": "BANK_TRANSFER",
      "currency": "NGN",
      "country": "NG",
      "account": {
        "accountNumber": "0010401234",
        "bankName": "<string>",
        "sortCode": "058"
      },
      "name": "<string>",
      "type": "INDIVIDUAL",
      "address": "<string>"
    },
    "created": "2023-11-07T05:31:56Z",
    "processed": "2023-11-07T05:31:56Z"
  }
}

Error responses

Status	Message	What it means	How to fix
400	`Insufficient wallet balance for transaction`	Wallet cannot cover the payout total.	Deposit more funds or reduce the amount before retrying.
400	`Quotes only last for 10 minutes`	The referenced quote expired.	Fetch a new quote and submit the payout right away.
400	`Invalid country or currency ISO code`	Payload contains an unsupported corridor combination.	Use valid ISO codes for corridors enabled on your workspace.
400	`Account name mismatch, use account enquiry endpoint`	Account name conflicts with bank enquiry data.	Run the account enquiry endpoint and mirror its response.
400	`Invalid Bank Sortcode`	Provided sort code is missing, malformed, or unsupported.	Retrieve the correct sort code from the bank list endpoint.
400	`{field_name} cannot be empty`	Required recipient attribute missing from the payload.	Populate every mandatory field before sending the request.
401	`API key missing or incorrect`	Authentication header missing/invalid.	Include the proper `x-api-key` for the environment.
403	`IP not whitelisted`	Call originated from an unapproved IP address.	Add your server IP to the dashboard whitelist.
404	`The requested endpoint does not exist`	Incorrect path or API version.	Ensure you are calling `POST /v2/payout` on the right base URL.
422	`Invalid quote ID provided`	Quote ID missing, expired, or already consumed.	Create a new quote and reference its `id`.
500	`Service temporarily unavailable`	Backend disruption prevented processing.	Retry later with exponential backoff; contact support if needed.

Authorizations

x-api-key

string

header

required

Body

application/json

quoteId

string

required

The unique identifier for the quote.

recipient

NGN Payout · object

required

Details of the recipient. The structure depends on the recipient's currency and payment channel.

Show child attributes

recipient.paymentChannel

enum<string>

required

The channel through which the payment will be processed.

Available options:

BANK_TRANSFER,

INTERAC,

SWIFT

Example:

"BANK_TRANSFER"

recipient.currency

enum<string>

required

Currency code (ISO 4217).

Available options:

NGN,

USD,

GBP,

EUR,

MWK,

CAD

Example:

"NGN"

recipient.country

enum<string>

required

Country code (ISO 3166-1 alpha-2).

Available options:

NG,

US,

GB,

DE,

MW,

CA

Example:

"NG"

recipient.account

object

required

Currency-specific account details. Refer to the destination currency schema for the exact structure.

Show child attributes

recipient.account.accountNumber

string

required

Recipient's account number

Example:

"0010401234"

recipient.account.bankName

string

The name of the Bank

recipient.account.sortCode

string

The 3-digit NIP sort code.

Example:

"058"

recipient.name

string

required

Full name of the recipient.

recipient.type

enum<string>

The type of recipient.

Available options:

INDIVIDUAL,

BUSINESS

recipient.address

string

Full address of the recipient.

reason

enum<string>

The reason for the payout.

Available options:

FAMILY_SUPPORT,

GIFT,

SALARY_PAYMENT,

EDUCATIONAL_FEES,

BUSINESS_INVOICE,

OTHER

remark

string

A standardized remark for the transaction.

Response

Payout transaction created successfully.

status

string

required

Example:

"success"

message

string

required

Example:

"Transaction created successfully."

data

object

required

Show child attributes

data.id

string

Example:

"c6611ad3-805a-415b-98b7-xxxxxxxxxxxxx"

data.remark

string

Example:

"Testing"

data.reason

string

Example:

"Gift"

data.referenceNumber

string

Example:

"L2TEZEHNXXXXXX"

data.type

string

Example:

"SEND"

data.state

string

Example:

"COMPLETED"

data.quote

object

Show child attributes

data.quote.id

string<uuid>

Example:

"e5eec724-38f9-40e2-9i86-xxxxxxxxxxxxx"

data.quote.source

object

Show child attributes

data.quote.source.currency

string

Example:

"NGN"

data.quote.source.country

string

Example:

"NG"

data.quote.source.amount

number

Example:

150000

data.quote.target

object

Show child attributes

data.quote.target.currency

string

Example:

"USD"

data.quote.target.country

string

Example:

"US"

data.quote.target.amount

number

Example:

81.97

data.quote.rate

number

Example:

1830

data.quote.fee

object

Show child attributes

data.quote.fee.amount

number

Example:

0

data.quote.rules

object[]

Show child attributes

data.quote.rules.category

string

Example:

"LIMIT"

data.quote.rules.appliedCurrency

string

Example:

"USD"

data.quote.rules.appliedCountry

string

Example:

"US"

data.quote.rules.transaction

object

Show child attributes

data.quote.rules.transaction.minimum

number

Example:

1

data.quote.rules.transaction.maximum

number

Example:

20000000000000

data.quote.rules.invoice

number

Example:

200000000000

data.quote.summary

object

Show child attributes

data.quote.summary.total

number

Example:

150000

data.quote.settlementTime

string

Example:

"1 hr"

data.quote.quoteCurrency

string

Example:

"USD"

data.quote.expiresInSeconds

integer

Example:

600

data.recipient

NGN Payout · object

Details of the recipient. Structure mirrors CreatePayoutRequest.recipient.

Show child attributes

data.recipient.paymentChannel

enum<string>

required

The channel through which the payment will be processed.

Available options:

BANK_TRANSFER,

INTERAC,

SWIFT

Example:

"BANK_TRANSFER"

data.recipient.currency

enum<string>

required

Currency code (ISO 4217).

Available options:

NGN,

USD,

GBP,

EUR,

MWK,

CAD

Example:

"NGN"

data.recipient.country

enum<string>

required

Country code (ISO 3166-1 alpha-2).

Available options:

NG,

US,

GB,

DE,

MW,

CA

Example:

"NG"

data.recipient.account

object

required

Currency-specific account details. Refer to the destination currency schema for the exact structure.

Show child attributes

data.recipient.account.accountNumber

string

required

Recipient's account number

Example:

"0010401234"

data.recipient.account.bankName

string

The name of the Bank

data.recipient.account.sortCode

string

The 3-digit NIP sort code.

Example:

"058"

data.recipient.name

string

required

Full name of the recipient.

data.recipient.type

enum<string>

The type of recipient.

Available options:

INDIVIDUAL,

BUSINESS

data.recipient.address

string

Full address of the recipient.

data.created

string<date-time>

data.processed

string<date-time>

Get Quote Get Transaction

⌘I

Introduction

Wallet

Quote

Payout

Virtual Account

Miscellaneous

Error responses

Authorizations

Body

Response

Introduction

Wallet

Quote

Payout

Virtual Account

Miscellaneous

​Error responses

Authorizations

Body

Response

Error responses