> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fossapay.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Payouts Guide
> Complete guide to sending money with FossaPay
## Overview
Send money to any Nigerian bank account in seconds using FossaPay's Payouts API. This guide covers single payouts, bulk disbursements, and handling payout failures.
## Prerequisites
* Sufficient balance in your FossaPay wallet or bank account
* Verified business account
* Live API keys (test keys for sandbox)
## Single Payout
### Basic Transfer
```bash theme={null}
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:**
```json theme={null}
{
"status": true,
"statusCode": 200,
"message": "Transfer request is being processed",
"data": {
"reference": "transfer-1705315200000"
}
}
```
### Validate Account First
```bash theme={null}
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:**
```json theme={null}
{
"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
```javascript theme={null}
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
```javascript theme={null}
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
```javascript theme={null}
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
Use account validation before payouts to prevent failures:
```javascript theme={null}
const validation = await client.payouts.validateAccount({
account_number: accountNumber,
bank_code: bankCode
});
```
Generate unique references for each payout:
```javascript theme={null}
const reference = `payout-${Date.now()}-${userId}`;
```
Verify sufficient balance before initiating payouts:
```javascript theme={null}
const balance = await client.wallets.getBalance();
if (balance.available >= totalAmount) {
// Proceed with payout
}
```
Always implement webhook handlers for real-time status updates.
Save payout IDs for reconciliation and support.
## Next Steps
API reference for transfers
Validate account details
Handle transfer webhooks
Fund transfers from wallets