Quickstart

Get Started with FossaPay

This quickstart guide will have you making your first API call in minutes. We’ll create a customer, open an NGN wallet, use production-only credentials, and verify a real deposit webhook.

Prerequisites

Before you begin, make sure you have:

A FossaPay account (Sign up here)
Your API keys from the dashboard
Node.js installed (or your preferred programming language)

Step 1: Get Your API Keys

Create an account at dashboard.fossapay.com

Get Live Keys

Navigate to Settings → API Keys and copy your production secret key (starts with fk_production_)

Store Securely

Save your API key as an environment variable:

export FOSSAPAY_SECRET_KEY="fk_production_DTKUG..."

FossaPay currently operates in production only. Any API call you make will hit production systems, so use small live amounts when you are validating your integration.

Step 2: Create a Customer

Create the customer before creating any wallet or payment flow.

curl -X POST https://api-production.fossapay.com/api/v1/customers \
  -H "x-api-key: $FOSSAPAY_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "John",
    "lastName": "Doe",
    "middleName": "Michael",
    "emailAddress": "john.doe@example.com",
    "mobileNumber": "+2348012345678",
    "dateOfBirth": "1990-08-15",
    "address": "123 Main Street",
    "city": "Lagos",
    "country": "Nigeria",
    "type": "individual"
  }'

Expected Response:

{
  "status": "success",
  "statusCode": 201,
  "message": "Customer created successfully",
  "data": {
    "id": "cus_123456789",
    "firstName": "John",
    "lastName": "Doe",
    "emailAddress": "john.doe@example.com",
    "mobileNumber": "+2348012345678",
    "customerType": "individual"
  }
}

Step 3: Create Your First NGN Wallet

Create an NGN wallet for the customer you just created:

curl -X POST https://api-production.fossapay.com/api/v1/wallets/fiat/create \
  -H "x-api-key: $FOSSAPAY_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "cus_123456789",
    "walletName": "Main Wallet",
    "walletReference": "wallet_ref_001"
  }'

Expected Response:

{
  "success": true,
  "message": "NGN wallet created successfully",
  "data": {
    "walletId": "wal_abc123xyz",
    "bankName": "Wema Bank",
    "bankCode": "035",
    "accountNumber": "1234567890"
  }
}

Step 4: Configure Your Webhook

Configure your webhook URL and secret in the dashboard before making a live deposit.

Go to Settings → Webhooks
Set your webhook URL
Copy the webhook secret and store it as FOSSAPAY_WEBHOOK_SECRET
Make sure your handler expects deposit.completed for incoming deposits

When a deposit is received in production, FossaPay sends a webhook to your server. Here’s how to handle it:

const express = require('express');
const crypto = require('crypto');
const app = express();

app.use(express.json());

app.post('/webhooks/fossapay', (req, res) => {
  // 1. Verify webhook signature
  const signature = req.headers['x-fossapay-signature'];
  const isValid = verifySignature(req.body, signature);

  if (!isValid) {
    return res.status(401).send('Invalid signature');
  }

  // 2. Respond immediately
  res.status(200).send('Webhook received');

  // 3. Process the webhook
  const { event, data } = req.body;

  if (event === 'deposit.completed') {
    console.log('Deposit completed!');
    console.log('Amount:', data.amount);
    console.log('Transaction ID:', data.transactionId);

    // Credit user wallet, update database, send notification, etc.
    creditUserWallet(data.customerId, data.amount);
  }
});

function verifySignature(payload, signature) {
  const secret = process.env.FOSSAPAY_WEBHOOK_SECRET;
  const hash = crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(payload))
    .digest('hex');

  return hash === signature;
}

app.listen(3000, () => {
  console.log('Webhook server running on port 3000');
});

from flask import Flask, request
import hmac
import hashlib
import json
import os

app = Flask(__name__)

@app.route('/webhooks/fossapay', methods=['POST'])
def handle_webhook():
    # 1. Verify signature
    signature = request.headers.get('X-FossaPay-Signature')
    is_valid = verify_signature(request.data, signature)

    if not is_valid:
        return 'Invalid signature', 401

    # 2. Respond immediately
    payload = request.json

    # 3. Process webhook
    event = payload['event']
    data = payload['data']

    if event == 'deposit.completed':
        print('Deposit completed!')
        print(f'Amount: {data["amount"]}')
        print(f'Transaction ID: {data["transactionId"]}')

        # Credit user wallet, update database, etc.
        credit_user_wallet(data['customerId'], data['amount'])

    return 'Webhook received', 200

def verify_signature(payload, signature):
    secret = os.environ['FOSSAPAY_WEBHOOK_SECRET']
    hash = hmac.new(
        secret.encode(),
        payload,
        hashlib.sha256
    ).hexdigest()

    return hmac.compare_digest(hash, signature)

if __name__ == '__main__':
    app.run(port=3000)

Local Development: Use ngrok to expose your local server while you build:

ngrok http 3000

Then set the ngrok URL in your webhook settings.

Step 5: Make a Small Live Deposit

From a bank account you control, send a small live deposit to the wallet account number from Step 3. You should receive a deposit.completed webhook with the transaction details and customer ID.

Step 6: Verify the Deposit

Use the transaction ID from the webhook to fetch the transaction record:

curl https://api-production.fossapay.com/api/v1/wallets/fiat/transactions/txn_abc123 \
  -H "x-api-key: $FOSSAPAY_SECRET_KEY"

Step 7: Send a Small Production Payout

Now let’s send money from your wallet to a bank account using a small live amount:

curl -X POST https://api-production.fossapay.com/api/v1/transfers/fiat/inter-bank \
  -H "x-api-key: $FOSSAPAY_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "cus_123456789",
    "destinationBankCode": "044",
    "destinationAccountName": "Test Recipient",
    "destinationAccountNumber": "0000000001",
    "destinationBankName": "ACCESS BANK",
    "reference": "payout-'$(date +%s)'",
    "remarks": "Test payout",
    "amount": 25000
  }'

Complete Example

Here’s a complete example that ties everything together:

const express = require('express');
const app = express();

app.use(express.json());

// Handle incoming deposits
app.post('/webhooks/fossapay', async (req, res) => {
  res.status(200).send('OK');

  const { event, data } = req.body;

  if (event === 'deposit.completed') {
    // Credit user's balance
    await creditUserBalance(data.customerId, data.amount);

    // Send notification
    await sendNotification(data.customerId, {
      title: 'Payment Received',
      message: `Your account was credited with ₦${data.amount}`
    });
  }
});

app.listen(3000);

Next Steps

Authentication

Learn about API authentication and security

Collections Guide

Complete guide to accepting payments

Payouts Guide

Send money to bank accounts

Webhooks

Handle real-time notifications

Testing Checklist

Before using production for real volume, make sure you’ve tested:

Going Live

When you’re ready for regular production use:

Complete business verification in the dashboard
Use production API keys (starts with fk_production_)
Update webhook URL to your production server
Test with small amounts before full launch
Monitor the dashboard for any issues

Get Live API Keys

Complete verification to get live access

Need Help?

Join Community

Get help from the FossaPay community

Contact Support

Email our support team

API Reference

Explore the full API documentation

Dashboard

View your transactions and settings

Getting Started

Core Concepts

Guides

AI Tools

Get Started with FossaPay

Prerequisites

Step 1: Get Your API Keys

Step 2: Create a Customer

Step 3: Create Your First NGN Wallet

Step 4: Configure Your Webhook

Step 5: Make a Small Live Deposit

Step 6: Verify the Deposit

Step 7: Send a Small Production Payout

Complete Example

Next Steps

Authentication

Collections Guide

Payouts Guide

Webhooks

Testing Checklist

Going Live

Get Live API Keys

Need Help?

Join Community

Contact Support

API Reference

Dashboard

​Get Started with FossaPay

​Prerequisites

​Step 1: Get Your API Keys

​Step 2: Create a Customer

​Step 3: Create Your First NGN Wallet

​Step 4: Configure Your Webhook

​Step 5: Make a Small Live Deposit

​Step 6: Verify the Deposit

​Step 7: Send a Small Production Payout

​Complete Example

​Next Steps

Authentication

Collections Guide

Payouts Guide

Webhooks

​Testing Checklist

​Going Live

Get Live API Keys

​Need Help?

Join Community

Contact Support

API Reference

Dashboard

Get Started with FossaPay

Prerequisites

Step 1: Get Your API Keys

Step 2: Create a Customer

Step 3: Create Your First NGN Wallet

Step 4: Configure Your Webhook

Step 5: Make a Small Live Deposit

Step 6: Verify the Deposit

Step 7: Send a Small Production Payout

Complete Example

Next Steps

Testing Checklist

Going Live

Need Help?