NGN Collections

Use a customer NGN wallet when you want a persistent bank account tied to an individual customer. For a one-time order with a fixed amount and expiry, use Checkout Wallet instead.

Collection flow

Create the individual customer

Call POST /api/v1/customers and store the customer UUID.

Create the NGN wallet

Call POST /api/v1/wallets/fiat/create with the customer UUID, your wallet name, and your wallet reference.

Display the account details

Show the returned bank, account name, and account number to that customer.

Receive a signed event

FossaPay sends deposit.completed after a deposit is successfully processed.

Reconcile and credit once

Deduplicate the event, persist its transaction identifiers, and update your own ledger exactly once.

Create the customer and wallet

curl --request POST \
  --url https://api-production.fossapay.com/api/v1/wallets/fiat/create \
  --header "x-api-key: $FOSSAPAY_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "customerId": "11111111-1111-4111-8111-111111111111",
    "walletName": "Primary NGN Wallet",
    "walletReference": "wallet-customer-1042"
  }'

Store the returned wallet ID and account number with your customer mapping. The wallet is persistent; do not describe it to the customer as a one-time or expiring account.

Handle the deposit event

import crypto from 'node:crypto';
import express from 'express';

const app = express();
app.use(express.json());

function validSignature(body, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(body.data))
    .digest('hex');

  const received = String(signature || '');
  if (received.length !== expected.length) return false;
  return crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected));
}

app.post('/webhooks/fossapay', async (req, res) => {
  if (!validSignature(
    req.body,
    req.get('x-fossapay-signature'),
    process.env.FOSSAPAY_WEBHOOK_SECRET
  )) {
    return res.sendStatus(401);
  }

  res.sendStatus(200);

  if (req.body.eventType !== 'deposit.completed') return;

  // Queue this work. Enforce a unique constraint on eventId.
  await enqueueDeposit({
    eventId: req.body.eventId,
    transaction: req.body.data
  });
});

A webhook can be delivered more than once. Make eventId unique in your database and make the ledger update part of the same database transaction as recording the processed event.

Reconcile a deposit

Use the wallet’s transaction list when a webhook is delayed or an operator needs an account statement. Retrieve a single transaction by ID when you already have the identifier from a webhook or support case.

curl --request GET \
  --url 'https://api-production.fossapay.com/api/v1/wallets/fiat/WALLET_ID/transactions?page=1&limit=50&transactionType=deposit' \
  --header "x-api-key: $FOSSAPAY_API_KEY"

Do not synthesize transaction status from webhook delivery status. A failed webhook delivery means your endpoint was not reached or did not return 2xx; it does not mean the financial transaction failed.

Persistent wallet versus checkout

Requirement	Customer NGN wallet	Checkout Wallet
Persistent account for a known customer	Yes	No
Exact expected amount	Managed by your application	Enforced by checkout flow
Built-in expiry	No	30-minute checkout
Best for	Wallet top-ups and recurring collections	Orders, invoices, and one-time payments

Production checklist

Create an individual customer and persist its UUID.
Store the FossaPay wallet ID, account number, and your wallet reference.
Keep API keys and webhook secrets server-side.
Verify the signature over JSON.stringify(body.data).
Return 2xx quickly and process asynchronously.
Deduplicate by eventId and also retain the transaction reference.
Reconcile delayed notifications through wallet transaction endpoints.
Keep personal and bank information out of application logs where possible.

Create customer

Create NGN wallet

Provision the customer’s dedicated bank account.

Wallet transactions

Reconcile deposits and withdrawals.

Webhook handling

Verify, acknowledge, deduplicate, and monitor events.

Getting Started

Core Concepts

Guides

AI Tools

Collection flow

Create the customer and wallet

Handle the deposit event

Reconcile a deposit

Persistent wallet versus checkout

Production checklist

Create customer

Create NGN wallet

Wallet transactions

Webhook handling

​Collection flow

​Create the customer and wallet

​Handle the deposit event

​Reconcile a deposit

​Persistent wallet versus checkout

​Production checklist

​Related endpoints

Create customer

Create NGN wallet

Wallet transactions

Webhook handling

Collection flow

Create the customer and wallet

Handle the deposit event

Reconcile a deposit

Persistent wallet versus checkout

Production checklist

Related endpoints