Skip to main content

​
Get Started with FossaPay

This quickstart guide will have you making your first API call in minutes. We’ll create a fiat wallet, simulate a payment, and handle the webhook notification.

​
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

1

Sign up

Create an account at dashboard.fossapay.com
2

Get Test Keys

Navigate to Settings → API Keys and copy your test secret key (starts with fp_test_sk_)
3

Store Securely

Save your API key as an environment variable:
export FOSSAPAY_SECRET_KEY="fp_test_sk_xxxxxxxx"

​
Step 2: Make Your First API Call

Use cURL for direct API calls.

​
Step 3: Create Your First Fiat Wallet

Let’s create a fiat wallet for collecting payments: 
curl -X POST https://api-staging.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": "Fiat wallet created successfully",
  "data": {
    "walletId": "wal_abc123xyz",
    "bankName": "Wema Bank",
    "bankCode": "035",
    "accountNumber": "1234567890"
  }
}

​
Step 4: Simulate a Payment (Sandbox Only)

In sandbox mode, simulate a payment to test your integration: 
curl -X POST https://api-staging.fossapay.com/api/v1/sandbox/simulate-payment \
  -H "x-api-key: $FOSSAPAY_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "virtual_account_number": "1234567890",
    "amount": 50000,
    "sender_name": "Test Customer",
    "sender_account": "0987654321",
    "sender_bank": "058"
  }'

​
Step 5: Handle Webhook Notification

When a payment is received, 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 === 'payment.received') {
    console.log('Payment received!');
    console.log('Amount:', data.amount);
    console.log('From:', data.sender_name);
    console.log('Transaction ID:', data.transaction_id);

    // Credit user wallet, update database, send notification, etc.
    creditUserWallet(data.metadata.customer_id, 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');
});
Local Testing: Use ngrok to expose your local server for webhook testing:
ngrok http 3000
Then set the ngrok URL in your webhook settings.

​
Step 6: Send a Payout

Now let’s send money from your wallet to a bank account: 
curl -X POST https://api-staging.fossapay.com/api/v1/transfers/fiat/inter-bank \
  -H "x-api-key: $FOSSAPAY_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "550e8400-e29b-41d4-a716-446655440000",
    "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 payments
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 / 100}`
    });
  }
});

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 going to production, make sure you’ve tested:
  • Creating virtual accounts
  • Simulating payments in sandbox
  • Receiving and processing webhooks
  • Handling webhook failures
  • Sending payouts
  • Error handling
  • Webhook signature verification

​
Going Live

When you’re ready for production:
  1. Complete business verification in the dashboard
  2. Switch to live API keys (starts with fp_live_sk_)
  3. Update webhook URL to your production server
  4. Test with small amounts before full launch
  5. 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