Skip to main content
Use this endpoint to disburse funds to a beneficiary. The payout consumes an existing quote, validates the beneficiary, and queues the transfer for settlement. The code examples below mirror the corridors covered in our payout guides. Select the appropriate recipient payload to match your payout use case, or browse the dedicated payout examples for a full walkthrough.

​
Endpoint

POST {{baseURL}}/v2/payout
You must supply the quoteId generated by the Create Quote API. Quotes that have expired or already been consumed will be rejected.

​
Request headers

HeaderDescriptionRequiredExample
x-api-keyWorkspace API key for authentication.✅ YesYOUR_API_KEY
Content-TypeMedia type of the request body.✅ Yesapplication/json

​
Request body

copy
{
  "recipient": {
    "name": "Chris Tiana",
    "paymentChannel": "BANK_TRANSFER",
    "country": "NG",
    "stored": false,
    "account": {
      "bankName": "Guaranty Trust Bank",
      "sortCode": "058",
      "accountNumber": "0712617XXX"
    }
  },
  "quoteId": "453eeu-567j-6tr3d-xxxxxxxxxxxxx",
  "reason": "Bills",
  "remark": ""
}

​
Body fields

FieldTypeDescriptionRequiredExample
recipient.nameStringFull name of the beneficiary.✅ YesChris Tiana
recipient.paymentChannelStringChannel to deliver funds (BANK_TRANSFER, MOBILE_MONEY, etc.).✅ YesBANK_TRANSFER
recipient.countryStringRecipient country (ISO 3166-1 alpha-2).✅ YesNG
recipient.storedBooleanWhether the recipient is saved in your address book.✅ Yesfalse
recipient.account.bankNameStringFinancial institution name.✅ YesGuaranty Trust Bank
recipient.account.sortCodeStringRouting or sort code where applicable.✅ Yes058
recipient.account.accountNumberStringDestination account number.✅ Yes0712617XXX
quoteIdStringQuote identifier returned from the Quote API.✅ Yes453eeu-567j-6tr3d-xxxxxxxxxxxxx
reasonStringHigh-level purpose of the transfer.✅ YesBills
remarkStringAdditional comments or reference.OptionalSeptember utilities
Depending on the corridor and channel, additional fields (such as mobile wallet metadata or address information) may be required. Refer to the route-specific examples in payout docs examples.

​
Request examples

curl --request POST '{{baseURL}}/v2/payout' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "recipient": {
      "name": "Chris Tiana",
      "paymentChannel": "BANK_TRANSFER",
      "country": "NG",
      "stored": false,
      "account": {
        "bankName": "Guaranty Trust Bank",
        "sortCode": "058",
        "accountNumber": "0712617XXX"
      }
    },
    "quoteId": "453eeu-567j-6tr3d-xxxxxxxxxxxxx",
    "reason": "Bills",
    "remark": ""
  }'

​
Successful response

copy
{
  "message": "payout queued",
  "status": "success",
  "data": {
    "id": "f4e597cc-18fa-4c23-b9c1-xxxxxxxxxxxxx",
    "reference": "BILLS-20240915",
    "quoteId": "453eeu-567j-6tr3d-xxxxxxxxxxxxx",
    "state": "PROCESSING",
    "recipient": {
      "name": "Chris Tiana",
      "country": "NG",
      "paymentChannel": "BANK_TRANSFER"
    },
    "metadata": {},
    "created": "2024-09-15T10:32:11.238Z"
  }
}

​
Field reference

FieldTypeDescription
data.idStringUnique payout identifier returned by meCash.
data.referenceStringYour client-generated reference if supplied.
data.stateStringInitial processing state (PROCESSING, QUEUED, etc.).
data.recipientObjectEchoes key beneficiary attributes.
data.createdStringISO timestamp for when the payout was accepted.

​
Error responses

StatusMessageCauseHow to resolve
400Insufficient wallet balance for transactionWallet balance cannot cover the payout amount.Top up the wallet or lower the payout total before retrying.
400Quotes only last for 10 minutesQuote expired before you attempted to consume it.Generate a fresh quote and submit the payout immediately.
400Invalid country or currency ISO codeUnsupported country/currency combination supplied in the request.Use corridor-supported ISO codes for both quote and recipient data.
400Account name mismatch, use account enquiry endpointAccount name in payload differs from bank enquiry results.Re-run account enquiry and match the returned account name.
400Invalid Bank SortcodeSort code missing, malformed, or unsupported.Fetch the correct sort code from the bank list and verify formatting.
400{field_name} cannot be emptyRequired recipient field omitted from the payload.Fill in every mandatory field (name, account number, etc.) before submitting.
401API key missing or incorrectx-api-key header absent, invalid, or expired.Supply the correct API key for the environment you are targeting.
403IP not whitelistedRequest originated from an unapproved IP.Add your server IP to the dashboard allowlist.
404The requested endpoint does not existIncorrect API path or version specified.Confirm you are calling POST /v2/payout on the right base URL.
422Invalid quote ID providedQuote ID missing, invalid, expired, or already consumed.Create a new quote and reference it in the payout call.
500Service temporarily unavailableTemporary backend/service disruption.Retry with exponential backoff; contact support if it persists.

​
Best practices

  • Generate idempotency references to safely retry without duplicating transfers.
  • Validate recipients locally before calling the API to reduce error handling.
  • Listen to payout webhooks and reconcile with the Get Transaction API for final settlement details.
Testing Failed Payouts: In the sandbox environment, you can simulate a failed payout by setting "remark": "fail" in your request. This will trigger a payout.failed webhook, allowing you to test your error handling logic.