Skip to main content
FossaPay provides payment and wallet infrastructure for businesses that need to collect, hold, and transfer NGN and supported crypto assets through one server-side API. You can create individual customers, provision customer wallets, accept bank-transfer payments, send customer- or business-funded transfers, and receive signed webhook notifications as transactions change state.

​
Platform capabilities

​
Resource model

FossaPay integrations are organized around merchants, customers, wallets, and financial operations.
1

Merchant

Your business is the top-level owner of API keys, master wallets, customers, webhook endpoints, and all associated activity.
2

Customer

A customer represents an individual end user served by your business. Customer records are merchant-scoped.
3

Wallet

Customer wallets hold funds attributed to an individual. Master wallets hold funds owned by the business. NGN and stablecoin wallets use separate API resources.
4

Financial operation

Deposits, transfers, checkouts, and payouts create records with identifiers and statuses that you use for reconciliation.
5

Webhook event

When an asynchronous operation changes state, FossaPay delivers a signed event to each active webhook configured for the merchant.

​
Understand fund ownership

Choose an API based on who owns the source funds and what the payment is intended to do.
Do not use a customer wallet to represent business-owned funds or a master wallet to represent customer-owned funds. The source determines the correct API, fee treatment, and reconciliation flow.

​
Integration lifecycle

Most integrations follow this sequence:
  1. Create and verify your merchant account in the FossaPay dashboard.
  2. Obtain an API key.
  3. Make authenticated requests from your backend using the x-api-key header.
  4. Store your own references together with returned FossaPay resource IDs.
  5. Configure a public HTTPS webhook endpoint and securely store its secret.
  6. Verify webhook signatures, acknowledge deliveries quickly, and process events idempotently.
  7. Reconcile important operations with authenticated retrieval endpoints.

​
Authentication and production access

Public API requests use an API key in the x-api-key header:
Keep API keys on trusted servers. Never embed them in browser code, mobile applications, public repositories, or client-visible logs.

​
Asynchronous processing

Some requests return before the underlying financial operation reaches a terminal state. An accepted or processing response does not necessarily mean funds reached the beneficiary. For asynchronous operations:
  • persist the returned identifiers and your request reference;
  • treat processing states as non-terminal;
  • verify and deduplicate webhook deliveries using eventId;
  • finalize your own records only from the appropriate terminal state;
  • use GET endpoints to reconcile delayed or ambiguous notifications.
Webhook delivery state and transaction state are independent. For example, fetch failed means FossaPay could not deliver a webhook to your server; it does not mean the corresponding financial transaction failed.

​
Choose an integration path

Create customers and wallets

Model individual customers, then provision NGN or stablecoin wallets.

Accept NGN collections

Receive recurring deposits through customer-specific bank accounts.

Accept checkout payments

Create one-time payment instructions for an exact NGN amount.

Send NGN

Choose between customer-funded transfers and business-funded payouts.

​
Documentation structure

  • Documentation explains product concepts, lifecycle, implementation decisions, security, and operational guidance.
  • API Reference defines exact HTTP methods, paths, headers, parameters, request bodies, and response shapes.
Start with the Quickstart, then use the relevant product guide alongside its API Reference pages while implementing.

​
Support

For integration support, contact product@fossapay.com. Include the FossaPay resource ID, your merchant reference, and the timestamp. Never send API keys or webhook secrets.