Skip to main content
POST
Create a payout from the merchant master NGN wallet
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.

Authorizations

x-api-key
string
header
required

Headers

X-Idempotency-Key
string
required

Unique key for this logical payout. Idempotency-Key is also accepted; if both headers are sent, they must match.

Maximum string length: 255

Body

application/json
amount
integer
required

Amount the beneficiary receives in NGN.

Required range: x >= 1
currency
enum<string>
required
Available options:
NGN
reference
string
required
Required string length: 1 - 100
Pattern: ^[A-Za-z0-9._:-]+$
destinationBankCode
string
required
Required string length: 1 - 100
destinationBankName
string
required
Required string length: 1 - 199
destinationAccountName
string
required
Required string length: 1 - 199
destinationAccountNumber
string
required
Required string length: 1 - 199
remarks
string
Maximum string length: 255
metadata
object

Optional merchant data limited to 4,096 UTF-8 bytes and returned unchanged.

Response

Payout accepted, completed synchronously, or idempotently replayed

status
string
required
Allowed value: "success"
statusCode
enum<integer>
required
Available options:
200,
202
message
string
required
data
object
required