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 virtual account, 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: Install SDK (Optional)

npm install fossapay-node
Or use cURL for direct API calls.

​
Step 3: Create Your First Virtual Account

Let’s create a virtual account for collecting payments: 
const Fossapay = require('fossapay-node');
const fossapay = new Fossapay(process.env.FOSSAPAY_SECRET_KEY);

async function createVirtualAccount() {
  const account = await fossapay.virtualAccounts.create({
    type: 'dedicated',
    customer_name: 'John Doe',
    customer_email: '[email protected]',
    customer_phone: '+2348012345678',
    metadata: {
      user_id: '12345'
    }
  });

  console.log('Virtual Account Created!');
  console.log('Account Number:', account.data.account_number);
  console.log('Bank Name:', account.data.bank_name);

  return account;
}

createVirtualAccount();
Expected Response: 
{
  "status": "success",
  "data": {
    "virtual_account_id": "va_abc123",
    "account_number": "1234567890",
    "account_name": "FOSSAPAY - JOHN DOE",
    "bank_name": "Wema Bank",
    "type": "dedicated",
    "status": "active"
  }
}

​
Step 4: Simulate a Payment (Sandbox Only)

In sandbox mode, simulate a payment to test your integration: 
async function simulatePayment(accountNumber) {
  const payment = await fossapay.sandbox.simulatePayment({
    virtual_account_number: accountNumber,
    amount: 50000, // ₦500 in kobo
    sender_name: 'Test Customer',
    sender_account: '0987654321',
    sender_bank: '058'
  });

  console.log('Payment Simulated!');
  console.log('Transaction ID:', payment.data.transaction_id);

  return payment;
}

// Use the account number from Step 3
simulatePayment('1234567890');

​
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.user_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: 
async function sendPayout() {
  const payout = await fossapay.payouts.create({
    amount: 25000, // ₦250
    account_number: '0000000001', // Test account
    account_name: 'Test Recipient',
    bank_code: '058',
    narration: 'Test payout',
    reference: `payout-${Date.now()}`
  });

  console.log('Payout initiated!');
  console.log('Payout ID:', payout.data.payout_id);
  console.log('Status:', payout.data.status);

  return payout;
}

sendPayout();

​
Complete Example

Here’s a complete example that ties everything together: 
const Fossapay = require('fossapay-node');
const express = require('express');

const fossapay = new Fossapay(process.env.FOSSAPAY_SECRET_KEY);
const app = express();

app.use(express.json());

// Create virtual account for new user
async function onboardUser(user) {
  const account = await fossapay.virtualAccounts.create({
    type: 'dedicated',
    customer_name: user.name,
    customer_email: user.email,
    metadata: {
      user_id: user.id
    }
  });

  console.log(`Virtual account created for ${user.name}`);
  console.log(`Account Number: ${account.data.account_number}`);

  return account;
}

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

  const { event, data } = req.body;

  if (event === 'payment.received') {
    // Credit user's balance
    await creditUserBalance(data.metadata.user_id, data.amount);

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

// Process withdrawal
async function processWithdrawal(userId, amount, bankDetails) {
  const payout = await fossapay.payouts.create({
    amount: amount,
    account_number: bankDetails.accountNumber,
    account_name: bankDetails.accountName,
    bank_code: bankDetails.bankCode,
    reference: `withdrawal-${userId}-${Date.now()}`
  });

  return payout;
}

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