Authentication

FossaPay authenticates API requests with a secret API key sent in the x-api-key request header. The key identifies your merchant account and determines which customers, wallets, checkouts, payouts, and transactions the request can access.

FossaPay currently provides production access only. There is no staging or sandbox environment. Every authenticated request reaches production and can create or affect live financial resources.

Before you begin

To generate an API key, your merchant account must have:

completed business verification;
two-factor authentication enabled; and
access to Dashboard → Settings → API Keys.

Production API keys use the fk_production_ prefix.

Generate and store a key

Sign in to the FossaPay Dashboard.
Open Settings → API Keys.
Generate a production API key and complete the two-factor authentication challenge.
Copy the key into a secrets manager or protected server environment.

Treat an API key like a password. Never place it in browser code, a mobile application, a public repository, a screenshot, an analytics event, or a support message.

For local server-side development, load the base URL and key from environment variables:

export FOSSAPAY_API_URL="https://api-production.fossapay.com/api/v1"
export FOSSAPAY_API_KEY="fk_production_REPLACE_WITH_YOUR_KEY"

Do not commit .env files, and avoid commands that leave real credentials in shell history.

Authenticate a request

Send the API key in the x-api-key header on every protected endpoint:

curl --request GET \
  --url "$FOSSAPAY_API_URL/customers?page=1&limit=1" \
  --header "x-api-key: $FOSSAPAY_API_KEY"

Header names are case-insensitive, but the documentation uses x-api-key consistently. Do not add Bearer or another authentication scheme to the value.

x-api-key: fk_production_REPLACE_WITH_YOUR_KEY

An authenticated request returns the normal endpoint response. For example:

{
  "status": "success",
  "statusCode": 200,
  "message": "Customers retrieved successfully",
  "data": {
    "result": [],
    "pagination": {
      "page": 1,
      "limit": 1,
      "total": 0,
      "totalPages": 0,
      "hasNextPage": false,
      "hasPrevPage": false
    }
  }
}

The returned customer data depends on the resources already owned by your merchant account.

Request headers

Header	When to send it	Purpose
`x-api-key`	Every protected request	Authenticates the merchant
`Content-Type: application/json`	Requests with a JSON body	Declares the request-body format
`X-Idempotency-Key`	Creating a checkout, master-wallet payout, bulk payout batch, or identity verification	Prevents duplicate logical operations and repeated verification charges
`x-timezone`	Optional	Requests supported timestamps in the supplied timezone; the default is `Africa/Lagos`

Authentication and idempotency solve different problems. An API key establishes who is calling; an idempotency key identifies one logical write operation. Never use an API key as an idempotency key.

Server-side example

const response = await fetch(
  `${process.env.FOSSAPAY_API_URL}/wallets/fiat/create`,
  {
    method: 'POST',
    headers: {
      'x-api-key': process.env.FOSSAPAY_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      customerId: '11111111-1111-4111-8111-111111111111',
      walletName: 'John Doe',
      walletReference: 'wallet-customer-1042'
    })
  }
);

const body = await response.json();

if (!response.ok) {
  throw new Error(`FossaPay request failed (${response.status}): ${body.message}`);
}

The example must run on infrastructure you control. Your frontend should call your backend, and your backend should authenticate with FossaPay.

Merchant isolation

An API key is associated with one merchant. FossaPay uses that merchant association to scope protected resources:

customers created with the key belong to that merchant;
customer and wallet lookups are restricted to that merchant’s records;
checkout and single-payout references are evaluated within that merchant;
bulk payout batch references are globally unique, while batch retrieval remains merchant-scoped; and
a valid key does not grant access to another merchant’s resources.

Persist the FossaPay resource IDs returned to your merchant. A 403 or 404 during retrieval can indicate an incorrect ID or a resource that is not owned by the authenticated merchant.

Idempotency for financial writes

POST /checkouts, POST /payouts, and POST /payouts/batches require an idempotency header. Use X-Idempotency-Key for new integrations. The legacy Idempotency-Key header is also accepted for compatibility.

curl --request POST \
  --url "$FOSSAPAY_API_URL/checkouts" \
  --header "x-api-key: $FOSSAPAY_API_KEY" \
  --header "X-Idempotency-Key: checkout-order-10025-v1" \
  --header "Content-Type: application/json" \
  --data '{
    "amount": 5000,
    "currency": "NGN",
    "reference": "ORDER-10025",
    "feeBearer": "customer"
  }'

Apply these rules:

generate one stable key for each logical checkout, payout, or payout batch;
store it with your internal operation record before sending the request;
retry an uncertain request with the same key and identical body;
never reuse the key for a different request body;
limit the value to 255 characters; and
if both supported idempotency headers are sent, give them exactly the same value.

The same key and request return the original resource without creating another operation. Reusing the key with a different request returns HTTP 409. For multipart bulk payouts, the CSV bytes are part of the idempotency comparison. Missing, oversized, or conflicting idempotency headers return HTTP 400.

Idempotency requirements are endpoint-specific. Do not add X-Idempotency-Key to wallet creation merely because it is a write request.

Authentication failures

Errors use FossaPay’s standard response envelope. A missing key returns HTTP 401:

{
  "status": "error",
  "statusCode": 401,
  "message": "API key is required"
}

An unrecognized key also returns HTTP 401:

{
  "status": "error",
  "statusCode": 401,
  "message": "Invalid API key"
}

Some protected endpoint groups use a more specific equivalent message, such as API key is required in the x-api-key header or API key is invalid or inactive.

Status	Meaning	Recommended action
`400`	A required operation header is missing or invalid	Correct the request; do not retry it unchanged
`401`	The API key is missing, invalid, inactive, or revoked	Verify the header and key; generate or deploy a valid key if necessary
`403`	The merchant is not permitted to perform the operation or does not own the resource	Confirm business verification and resource ownership
`404`	The merchant-scoped resource was not found	Verify the resource ID or merchant reference
`409`	A reference conflicts or an idempotency key was reused with different data	Reconcile the original operation; do not generate a replacement blindly
`429`	The applicable request limit was exceeded	Back off and retry with jitter

Do not automatically retry 401, 403, or validation failures. Correct the credential, account state, ownership mapping, or request first.

Key rotation and revocation

Rotate credentials without interrupting service:

generate a new production key;
store and deploy it through your secret-management process;
verify authenticated reads and controlled writes with the new key;
remove the previous key from every workload; and
delete the previous key in the dashboard.

If a key may have been exposed, stop using it immediately, delete it in the dashboard, deploy a replacement, and review request and transaction activity for unexpected operations.

Operational security checklist

Keep API calls on trusted server-side infrastructure.
Inject keys at runtime from a secrets manager or protected environment variable.
Redact x-api-key from application, proxy, error-tracking, and observability logs.
Restrict production-secret access to workloads and personnel that require it.
Enable secret scanning for source repositories and deployment artifacts.
Rotate keys after personnel, vendor, or infrastructure access changes.
Monitor 401, 403, and 429 rates for configuration errors or abuse.
Keep webhook signing secrets separate from API keys.

Troubleshooting

The API says the key is required

Confirm that x-api-key reaches FossaPay. Review reverse-proxy and HTTP-client configuration for headers that may be removed before forwarding.

The API says the key is invalid or inactive

Remove whitespace and quotation marks from the configured value, confirm that you deployed the complete production key, and check that the key still exists in the dashboard.

The request succeeds for one resource but not another

Confirm that the resource belongs to the merchant associated with the key. Customer, wallet, checkout, payout, and transaction access is merchant-scoped.

A write timed out after submission

Do not assume the operation failed. For checkout and payout creation, retry the identical request with its original idempotency key or retrieve the resource using its ID or merchant reference.

Next steps

Quickstart

Authenticate and create your first customer and NGN wallet.

Customers

Understand customer validation and merchant ownership.

Checkouts

Create idempotent one-time NGN checkout sessions.

Payouts

Send funds safely from the merchant master wallet.

Getting Started

Core Concepts

Guides

AI Tools

Before you begin

Generate and store a key

Authenticate a request

Request headers

Server-side example

Merchant isolation

Idempotency for financial writes

Authentication failures

Key rotation and revocation

Operational security checklist

Troubleshooting

Next steps

Quickstart

Customers

Checkouts

Payouts

​Before you begin

​Generate and store a key

​Authenticate a request

​Request headers

​Server-side example

​Merchant isolation

​Idempotency for financial writes

​Authentication failures

​Key rotation and revocation

​Operational security checklist

​Troubleshooting

​Next steps

Quickstart

Customers

Checkouts

Payouts

Before you begin

Generate and store a key

Authenticate a request

Request headers

Server-side example

Merchant isolation

Idempotency for financial writes

Authentication failures

Key rotation and revocation

Operational security checklist

Troubleshooting

Next steps