Skip to main content
POST
https://api.fossapay.com
/
v1
/
payouts
Create Single Payout
curl --request POST \
  --url https://api.fossapay.com/v1/payouts \
  --header 'Content-Type: application/json' \
  --data '
{
  "amount": 123,
  "account_number": "<string>",
  "account_name": "<string>",
  "bank_code": "<string>",
  "narration": "<string>",
  "reference": "<string>",
  "currency": "<string>",
  "metadata": {}
}
'
{
  "status": "success",
  "message": "Payout initiated successfully",
  "data": {
    "payout_id": "pay_abc123",
    "amount": 50000,
    "fee": 50,
    "total_debit": 50050,
    "status": "pending",
    "reference": "payout-jan-2024-001",
    "account_number": "0123456789",
    "account_name": "JANE SMITH",
    "bank_code": "058",
    "bank_name": "GTBank",
    "currency": "NGN",
    "narration": "Salary payment",
    "metadata": {
      "employee_id": "emp_456"
    },
    "created_at": "2024-01-15T11:00:00Z"
  }
}

​
Request

​
amount
number
required
Amount to send in kobo (e.g., 50000 = ₦500)
​
account_number
string
required
Recipient’s bank account number (10 digits)
​
account_name
string
required
Recipient’s account name (for validation)
​
bank_code
string
required
Recipient’s bank code (e.g., “058” for GTBank)
​
narration
string
Payment description (max 50 characters)
​
reference
string
required
Unique reference for this payout (max 100 characters)
​
currency
string
default:"NGN"
Currency code (NGN, USD, etc.)
​
metadata
object
Custom data to store with the payout

​
Request Example

curl -X POST https://api.fossapay.com/v1/payouts \
  -H "Authorization: Bearer fp_live_sk_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 50000,
    "account_number": "0123456789",
    "account_name": "Jane Smith",
    "bank_code": "058",
    "narration": "Salary payment",
    "reference": "payout-jan-2024-001",
    "currency": "NGN",
    "metadata": {
      "employee_id": "emp_456"
    }
  }'

const payout = await client.payouts.create({
  amount: 50000,
  account_number: '0123456789',
  account_name: 'Jane Smith',
  bank_code: '058',
  narration: 'Salary payment',
  reference: `payout-${Date.now()}`
});

​
Response

​
status
string
Response status: success or error
​
data
object

​
Response Example

{
  "status": "success",
  "message": "Payout initiated successfully",
  "data": {
    "payout_id": "pay_abc123",
    "amount": 50000,
    "fee": 50,
    "total_debit": 50050,
    "status": "pending",
    "reference": "payout-jan-2024-001",
    "account_number": "0123456789",
    "account_name": "JANE SMITH",
    "bank_code": "058",
    "bank_name": "GTBank",
    "currency": "NGN",
    "narration": "Salary payment",
    "metadata": {
      "employee_id": "emp_456"
    },
    "created_at": "2024-01-15T11:00:00Z"
  }
}

​
Webhooks

Listen for payout status changes: 
app.post('/webhooks/fossapay', (req, res) => {
  const { event, data } = req.body;

  if (event === 'payout.completed') {
    console.log('Payout completed:', data.payout_id);
  }

  if (event === 'payout.failed') {
    console.log('Payout failed:', data.failure_reason);
  }

  res.status(200).send('OK');
});

​
Error Codes

CodeDescription
INSUFFICIENT_BALANCENot enough funds in wallet
INVALID_ACCOUNTInvalid account number
DUPLICATE_REFERENCEReference already used
BANK_UNAVAILABLEBank temporarily unavailable
DAILY_LIMIT_EXCEEDEDDaily payout limit exceeded