Quickstart

This Quickstart establishes the minimum working FossaPay integration: authenticate a server-side request, create an individual customer, provision the customer’s NGN wallet, and retrieve the wallet for reconciliation.

FossaPay currently supports production access only. All requests use the production API and can create or affect live financial resources.

What you will build

By the end of this guide, your backend will be able to:

authenticate with FossaPay;
create a merchant-scoped individual customer;
create that customer’s dedicated NGN wallet;
retrieve the wallet using its FossaPay ID; and
receive and verify signed webhook events.

Prerequisites

Before making requests, you need:

a FossaPay merchant account;
completed business verification;
two-factor authentication enabled for API-key management;
an active production API key from Dashboard → Settings → API Keys; and
curl or an equivalent HTTP client.

Production API keys use the fk_production_ prefix. Complete your integration and operational readiness checks before creating financial resources.

API keys authorize access to merchant financial resources. Keep them in a secret manager or protected server environment. Never expose them in browser code, mobile applications, public repositories, screenshots, or support messages.

1. Configure your environment

For local development, assign the production API URL and API key to shell variables:

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

The variable names are local conventions; they are not request headers. Every public request must send the key as x-api-key.

2. Verify authentication

List customers to confirm that the key is active and the request is authenticated for the correct merchant:

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

A successful request returns HTTP 200 with the standard response envelope:

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

The contents of result and the remaining pagination fields depend on existing data. HTTP 401 means the key is missing, invalid, inactive, or unavailable to the request.

3. Create an individual customer

Customer records represent individuals served by your business. Send exactly one name in each name field, and set type to individual.

curl --request POST \
  --url "$FOSSAPAY_API_URL/customers" \
  --header "x-api-key: $FOSSAPAY_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "firstName": "John",
    "middleName": "Michael",
    "lastName": "Doe",
    "emailAddress": "john.doe@example.com",
    "mobileNumber": "+2348012345678",
    "dateOfBirth": "1990-08-15",
    "address": "123 Example Street",
    "city": "Lagos",
    "country": "Nigeria",
    "type": "individual"
  }'

Use unique customer information. An email address already used by your merchant is rejected. An HTTP 201 response has this structure:

{
  "status": "success",
  "statusCode": 201,
  "message": "Customer created successfully",
  "data": {
    "id": "11111111-1111-4111-8111-111111111111",
    "firstName": "John",
    "middleName": "Michael",
    "lastName": "Doe",
    "emailAddress": "john.doe@example.com",
    "mobileNumber": "+2348012345678",
    "dob": "1990-08-15",
    "address": "123 Example Street",
    "customerType": "individual",
    "businessId": "22222222-2222-4222-8222-222222222222",
    "createdAt": "2026-09-15T09:00:00+01:00"
  }
}

Store data.id as the FossaPay customer ID. It is a UUID and is required by customer-scoped wallet and transfer operations.

Response values above are illustrative. Use identifiers and account details from your actual response.

See Customers for name validation, required information, and ownership rules.

4. Create the customer’s NGN wallet

Create one NGN wallet for the customer using the returned customer UUID:

curl --request POST \
  --url "$FOSSAPAY_API_URL/wallets/fiat/create" \
  --header "x-api-key: $FOSSAPAY_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "customerId": "11111111-1111-4111-8111-111111111111",
    "walletName": "John Doe",
    "walletReference": "wallet-customer-1042"
  }'

walletReference is your correlation value. Generate it in your system and retain it with the customer mapping. An HTTP 201 response has this structure:

{
  "status": "success",
  "statusCode": 201,
  "message": "Fiat wallet created successfully",
  "data": {
    "walletId": "33333333-3333-4333-8333-333333333333",
    "bankName": "Provider Bank",
    "bankCode": "000000",
    "accountName": "John Doe",
    "accountNumber": "9710000000"
  }
}

Store the wallet ID, bank details, and wallet reference. Do not hard-code the bank name or bank code; provider account details are determined at provisioning time. Only one NGN wallet can be created for the same customer. If your create request has an ambiguous outcome, retrieve the customer or reconcile your stored response before attempting another creation.

5. Retrieve the wallet

Retrieve the wallet with data.walletId from the creation response:

curl --request GET \
  --url "$FOSSAPAY_API_URL/wallets/fiat/33333333-3333-4333-8333-333333333333" \
  --header "x-api-key: $FOSSAPAY_API_KEY"

Wallet retrieval is merchant-scoped. A wallet belonging to another merchant is not accessible with your API key. You can also retrieve a wallet using its account number:

curl --request GET \
  --url "$FOSSAPAY_API_URL/wallets/fiat/account/9710000000" \
  --header "x-api-key: $FOSSAPAY_API_KEY"

At this point, the core integration is working: the merchant can authenticate, create a customer, provision an NGN wallet, and retrieve it.

6. Prepare webhook handling

Before accepting live deposits, configure a public HTTPS URL from Dashboard → Settings → Webhooks and store its secret securely. FossaPay signs exactly JSON.stringify(body.data) with HMAC-SHA256. The lowercase hexadecimal result is sent in x-fossapay-Signature.

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

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

function verifyWebhook(body, signature, secret) {
  if (!body || typeof body.data !== 'object' || !secret) return false;

  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, 'utf8'),
    Buffer.from(expected, 'utf8')
  );
}

app.post('/webhooks/fossapay', async (req, res) => {
  const valid = verifyWebhook(
    req.body,
    req.get('x-fossapay-signature'),
    process.env.FOSSAPAY_WEBHOOK_SECRET
  );

  if (!valid) return res.sendStatus(401);

  const inserted = await insertWebhookIfNew(req.body.eventId, req.body);
  res.sendStatus(200);

  if (inserted) await queueWebhookProcessing(req.body.eventId);
});

app.listen(3000);

insertWebhookIfNew and queueWebhookProcessing represent your persistence and job-queue implementation. Enforce a unique database constraint on eventId; do not implement deduplication only in application memory. See Webhooks for the event catalogue, retry schedule, signature rules, and reconciliation guidance.

Error handling

FossaPay returns errors using an HTTP status and structured JSON body:

{
  "status": "error",
  "statusCode": 422,
  "message": "customerId must be a UUID"
}

Status	Meaning	Recommended action
`400`	The request conflicts with resource or provider requirements	Inspect the message; do not retry unchanged
`401`	API-key authentication failed	Verify the key, header, and activation state
`403`	The authenticated merchant does not own the resource	Verify the customer or wallet mapping
`404`	The requested resource was not found	Check the identifier and merchant ownership
`409`	A unique reference or idempotency constraint was violated	Reconcile the original operation instead of creating another
`422`	Request validation failed	Correct the named field before retrying
`429`	Request rate limit exceeded	Back off and retry with jitter
`5xx`	FossaPay or an upstream provider was temporarily unavailable	Retry safe reads; reconcile writes before retrying

For write requests, distinguish a confirmed rejection from an ambiguous network failure. Never create a second financial operation solely because the original response was lost.

Production readiness

Before processing customer funds:

confirm business verification and production API-key access;
use a production HTTPS webhook endpoint;
store API keys and webhook secrets in production secret management;
verify signature rejection, duplicate delivery, and queue recovery behavior;
persist FossaPay IDs and your references for every operation;
monitor API errors, webhook delivery failures, and pending transactions; and
begin with controlled amounts and reconcile each result.

FossaPay does not currently provide a staging or sandbox environment. Requests made with your production API key operate on live resources and may initiate real financial activity.

Next steps

Authentication

Understand API-key security and idempotency.

NGN collections

Receive and reconcile customer deposits.

Checkout Wallet

Accept exact-amount, one-time NGN payments.

NGN transfers

Move customer or business funds using the correct flow.

Getting Started

Core Concepts

Guides

AI Tools

What you will build

Prerequisites

1. Configure your environment

2. Verify authentication

3. Create an individual customer

4. Create the customer’s NGN wallet

5. Retrieve the wallet

6. Prepare webhook handling

Error handling

Production readiness

Next steps

Authentication

NGN collections

Checkout Wallet

NGN transfers

​What you will build

​Prerequisites

​1. Configure your environment

​2. Verify authentication

​3. Create an individual customer

​4. Create the customer’s NGN wallet

​5. Retrieve the wallet

​6. Prepare webhook handling

​Error handling

​Production readiness

​Next steps

Authentication

NGN collections

Checkout Wallet

NGN transfers

What you will build

Prerequisites

1. Configure your environment

2. Verify authentication

3. Create an individual customer

4. Create the customer’s NGN wallet

5. Retrieve the wallet

6. Prepare webhook handling

Error handling

Production readiness

Next steps