Payouts Guide

Overview

Send money to another FossaPay customer or to an external Nigerian bank account using FossaPay’s Payouts API. This guide covers single payouts, bulk disbursements, and handling payout failures.

Choose the Correct Transfer Type

Transfer type	Use when	Fee
Wallet-to-Wallet Transfer	The sender and recipient are both FossaPay customers under the same business	Free
Inter-Bank Transfer	The recipient uses an account at another supported Nigerian bank	Calculate the applicable fee before sending

Wallet-to-wallet transfer is an internal movement between two customer wallets under your business. Inter-bank transfer sends money outside that wallet network to another bank.

Prerequisites

Sufficient balance in your FossaPay wallet or bank account
Verified business account
Live API keys for production

Single Payout

Basic Inter-Bank Transfer

curl -X POST https://api-production.fossapay.com/api/v1/transfers/fiat/inter-bank \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "cus_123",
    "destinationBankCode": "058",
    "destinationAccountName": "Jane Smith",
    "destinationAccountNumber": "0123456789",
    "destinationBankName": "GTBank",
    "reference": "transfer-1705315200000",
    "remarks": "Salary payment - January 2024",
    "amount": 25000
  }'

Response:

{
  "status": true,
  "statusCode": 200,
  "message": "Transfer request is being processed",
  "data": {
    "reference": "transfer-1705315200000"
  }
}

Validate Account First

curl -X POST https://api-production.fossapay.com/api/v1/transfers/fiat/bank-name-enquiry \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountNumber": "0123456789",
    "bankCode": "058"
  }'

Response:

{
  "success": true,
  "message": "Account details retrieved successfully",
  "data": {
    "accountNumber": "0123456789",
    "accountName": "JANE SMITH",
    "bankCode": "058",
    "bankName": "GTBank"
  }
}

Proceed with transfer if name matches.

Multiple Transfers

For multiple transfers, make individual API calls or implement batch processing in your application.

Handling Webhooks

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

  const { event, data } = req.body;

  switch (event) {
    case 'withdrawal.completed':
      await handleTransferCompleted(data);
      break;

    case 'withdrawal.failed':
      await handleTransferFailed(data);
      break;
  }
});

async function handleTransferCompleted(transfer) {
  // Update transaction status
  await db.transactions.update({
    reference: transfer.reference
  }, {
    status: 'completed',
    completed_at: transfer.completed_at
  });

  // Notify recipient
  await sendNotification(transfer.customerId, {
    title: 'Transfer Completed',
    message: `₦${transfer.amount.toLocaleString()} has been sent to your account`
  });
}

async function handleTransferFailed(transfer) {
  // Update status
  await db.transactions.update({
    reference: transfer.reference
  }, {
    status: 'failed',
    failure_reason: transfer.failure_reason
  });

  // Alert admin
  await sendAlert({
    type: 'transfer_failed',
    reference: transfer.reference,
    reason: transfer.failure_reason
  });
}

Checking Payout Status

const payout = await client.payouts.getStatus('pay_abc123');

console.log(payout);
// {
//   "payout_id": "pay_abc123",
//   "amount": 25000,
//   "status": "completed",
//   "account_number": "0123456789",
//   "bank_name": "GTBank",
//   "reference": "payout-1705315200000",
//   "completed_at": "2024-01-15T11:05:23Z"
// }

Bank Codes

Common Nigerian bank codes:

Bank Code	Bank Name
044	Access Bank
063	Access Bank (Diamond)
050	Ecobank Nigeria
070	Fidelity Bank
011	First Bank of Nigeria
214	First City Monument Bank
058	Guaranty Trust Bank
030	Heritage Bank
301	Jaiz Bank
082	Keystone Bank
50211	Kuda Bank
090175	Rubies MFB
221	Stanbic IBTC Bank
068	Standard Chartered
232	Sterling Bank
100	Suntrust Bank
032	Union Bank
033	United Bank for Africa
215	Unity Bank
035	Wema Bank
057	Zenith Bank

Get the full list of supported banks via the API: /v1/transfers/fiat/get-supported-banks

Error Handling

try {
  const payout = await client.payouts.create({
    amount: 25000,
    account_number: '0123456789',
    bank_code: '058'
  });
} catch (error) {
  if (error.code === 'INSUFFICIENT_BALANCE') {
    // Handle insufficient balance
    await notifyAdmin('Insufficient balance for payout');
  } else if (error.code === 'INVALID_ACCOUNT') {
    // Handle invalid account
    await notifyUser('Invalid account details');
  } else {
    // Handle other errors
    console.error('Payout failed:', error);
  }
}

Common Error Codes

Code	Description	Solution
`INSUFFICIENT_BALANCE`	Not enough funds	Top up your balance
`INVALID_ACCOUNT`	Account doesn’t exist	Verify account details
`DAILY_LIMIT_EXCEEDED`	Exceeded daily limit	Wait or request increase
`BANK_UNAVAILABLE`	Bank temporarily unavailable	Retry later
`DUPLICATE_REFERENCE`	Reference already used	Use unique reference

Best Practices

Always Validate Accounts

Use account validation before payouts to prevent failures:

const validation = await client.payouts.validateAccount({
  account_number: accountNumber,
  bank_code: bankCode
});

Use Unique References

Generate unique references for each payout:

const reference = `payout-${Date.now()}-${userId}`;

Check Balance First

Verify sufficient balance before initiating payouts:

const balance = await client.wallets.getBalance();
if (balance.available >= totalAmount) {
  // Proceed with payout
}

Handle Webhooks

Always implement webhook handlers for real-time status updates.

Store Payout IDs

Save payout IDs for reconciliation and support.

Next Steps

Wallet-to-Wallet Transfer

Free transfers between two customers under your business

Inter-Bank Transfer

Transfers to accounts at external banks

Bank Name Enquiry API

Validate account details

Webhooks

Handle transfer webhooks

Getting Started

Core Concepts

Guides

AI Tools

Overview

Choose the Correct Transfer Type

Prerequisites

Single Payout

Basic Inter-Bank Transfer

Validate Account First

Multiple Transfers

Handling Webhooks

Checking Payout Status

Bank Codes

Error Handling

Common Error Codes

Best Practices

Next Steps

Wallet-to-Wallet Transfer

Inter-Bank Transfer

Bank Name Enquiry API

Webhooks

​Overview

​Choose the Correct Transfer Type

​Prerequisites

​Single Payout

​Basic Inter-Bank Transfer

​Validate Account First

​Multiple Transfers

​Handling Webhooks

​Checking Payout Status

​Bank Codes

​Error Handling

​Common Error Codes

​Best Practices

​Next Steps

Wallet-to-Wallet Transfer

Inter-Bank Transfer

Bank Name Enquiry API

Webhooks

Overview

Choose the Correct Transfer Type

Prerequisites

Single Payout

Basic Inter-Bank Transfer

Validate Account First

Multiple Transfers

Handling Webhooks

Checking Payout Status

Bank Codes

Error Handling

Common Error Codes

Best Practices

Next Steps