Skip to main content
This guide covers essential payment operations including setting up collection accounts for receiving funds and processing payouts to beneficiaries.

​
Creating Collection Accounts

There are two types of accounts you can create via the API, each serving different purposes:
Dashboard accounts are not accessible via the API. You must create accounts programmatically for API operations.

​
Option 1: Collection Sub-Accounts (No Customer Required)

Collection sub-accounts are designed for receiving payments and do not require customer creation.
1

Create Collection Sub-Account

Use the Create Account endpoint directly for collection purposes:
{
  "account_type": "static",
  "third_party": false,
  "account_name": "Collections Account"
}
The API will return an account number that can receive payments from any bank in Nigeria. No customer creation is needed for this type of account.

​
Option 2: Customer-Linked Business Accounts

Business accounts are linked to specific customers and require customer creation first.
1

Create Customer

Use the Create Customer endpoint to register customer details:
{
  "email": "[email protected]",
  "phone": "08012345678",
  "first_name": "John",
  "last_name": "Doe",
  "bvn": "12345678901"
}
2

Create Customer-Linked Account

Use the Create Account endpoint with the customer ID:
{
  "account_type": "static",
  "third_party": true,
  "customer_id": "1732ca47-42b2-4990-a65d-c369e934eed3"
}
This creates a business account linked to the specific customer for more personalized banking operations.

​
Monitoring Collections

Track incoming payments using webhooks and transaction endpoints for both account types.
1

Set Up Webhooks

Configure webhooks to receive real-time notifications for incoming transactions:
  • account.incoming-transaction - Triggered when funds are received
See Webhooks Documentation for setup details.
2

Fetch Transactions

Use Fetch Transactions to retrieve payment history and verify collections.

​
Processing Payouts

Payouts allow you to send money from your API-created accounts to any Nigerian bank account.
Minimum payout amount is ₦200. Source account must be created via the API.

​
Step 1: Validate Beneficiary Account

Before initiating any payout, validate the beneficiary’s account details.
1

Resolve Account Details

Use the Resolve Account endpoint to verify beneficiary information:
{
  "account_number": "1234567890",
  "bank_code": "058"
}
This endpoint returns the actual account name, which you’ll need for the payout request.

​
Step 2: Check Account Balance

Ensure your source account has sufficient funds for the payout.
1

Fetch Balance

Use Fetch Balance to check available funds in your source account.
Verify you have enough balance to cover both the payout amount and any applicable fees.

​
Step 3: Create Payout

Execute the payout using validated beneficiary details and your API-created source account.
1

Initiate Payout

Use the Create Payout endpoint:
{
  "amount": 50000,
  "source": {
    "account_number": "your_api_account_number"
  },
  "beneficiary": {
    "bank_code": "058",
    "bank_name": "GTBank",
    "account_number": "1234567890",
    "account_name": "Jane Smith"
  },
  "reference": "PAYOUT_USER123_20260119",
  "remark": "Service payment"
}
Use unique references for each payout to avoid duplicate transactions.
2

Track Payout Status

Monitor payout progress using Get Payout Status with your payout reference.

​
Best Practices

  • Always use API-created accounts for programmatic operations
  • Keep track of customer-to-account relationships
  • Regularly monitor account balances before payouts
  • Always validate beneficiary accounts before payouts
  • Use unique references for each transaction
  • Implement webhook signature verification
  • Handle insufficient balance scenarios gracefully
  • Retry failed account validation requests
  • Log all transaction attempts for audit purposes

​
Common Use Cases

​
E-commerce Platform

  1. Create collection accounts for merchants
  2. Monitor incoming payments via webhooks
  3. Process payouts to merchant bank accounts

​
Payroll System

  1. Create accounts for employee salary management
  2. Fund accounts from company’s main account
  3. Distribute salaries using batch payouts

​
Marketplace

  1. Create collection accounts for sellers
  2. Collect payments from buyers
  3. Pay sellers after transaction completion
For detailed API specifications and additional parameters, refer to the individual endpoint documentation in the API Reference section.