Skip to main content
POST
Create Master Wallet Payout
Creates a payout from the authenticated merchant’s permanent NGN master wallet. You do not send a customerId, wallet ID, or source account—the API derives the source wallet from your live API key. The destination account number determines how the payout is routed:
Perform a Bank Name Enquiry first and submit the returned bank code, bank name, account name, and account number.

Headers

string
required
An active production FossaPay API key with full permission. The associated business must be verified.
string
required
A unique key of up to 255 characters for this logical payout. Idempotency-Key is also accepted. If both headers are sent, their values must match.

Body

integer
required
Amount the beneficiary should receive in NGN. Minimum 1.
string
required
Currency code. Currently only NGN is supported.
string
required
Your unique payout reference, 1–100 characters. Allowed characters are letters, numbers, ., _, :, and -.
string
required
Bank code returned by the supported-banks or bank-name-enquiry endpoint.
string
required
Beneficiary bank name, up to 199 characters.
string
required
Verified beneficiary account name, up to 199 characters.
string
required
Beneficiary account number, up to 199 characters. FossaPay uses this value to detect same-business and cross-business wallet destinations automatically.
string
Optional payout narration, up to 255 characters.
object
Optional merchant-defined JSON, up to 4,096 UTF-8 bytes. It is returned unchanged in API responses and payout webhooks.

Request

Response

The endpoint returns HTTP 202. A same-business transfer may already be completed; other routes normally begin as processing and reach a terminal state asynchronously.

Idempotency

  • Retrying the identical request with the same idempotency key returns the original payout without another debit.
  • Reusing an idempotency key with a different body returns HTTP 409.
  • Each reference must also be unique for the authenticated merchant.
  • If a request times out, retrieve the payout by reference before deciding whether to retry. Never retry a payout with a new key merely because the first response was delayed.

Statuses

Errors

Treat processing as non-terminal. Confirm the outcome using a signed payout webhook or either retrieval endpoint before marking a payout final.