Skip to main content
POST
Create a 30-minute NGN checkout wallet
Creates a merchant-scoped checkout and returns the exact amount and bank account the customer should pay. If a temporary account cannot be generated after retries, the response falls back to the merchant’s permanent NGN account.

Headers

string
required
Your existing active FossaPay API key with full permission.
string
required
A unique key of up to 255 characters. Idempotency-Key is also accepted for backward compatibility. If both headers are present, they must match.

Body

integer
required
Underlying merchant order amount in NGN. Minimum 1.
string
required
Currency code. Currently only NGN is supported.
string
required
Your unique checkout reference, 1–100 characters. Allowed: letters, numbers, ., _, :, and -.
string
required
customer adds the fee to amountPayable; merchant deducts it from settlementAmount.
object
Optional customer details containing name, email, and/or phoneNumber. A payment-confirmation email is queued after success when email is present.
object
Optional merchant-defined JSON, up to 4,096 UTF-8 bytes. Returned unchanged in responses and webhooks.
string
Optional description, up to 255 characters.

Request

Response

Instruct the customer to transfer exactly data.amountPayable once before data.expiresAt. Fulfill only after a verified checkout.completed webhook.

Errors

For integration behavior and webhook verification, see the Checkout Wallet Guide.

Authorizations

x-api-key
string
header
required

Headers

X-Idempotency-Key
string
required

Unique key for this logical checkout request. Idempotency-Key is also accepted for backward compatibility.

Maximum string length: 255

Body

application/json
amount
integer
required

Underlying merchant order amount 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._:-]+$
feeBearer
enum<string>
required
Available options:
customer,
merchant
customer
object
metadata
object

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

description
string
Maximum string length: 255

Response

Checkout session created or idempotently replayed

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