Nigeria Bank Transfer Payout Testing

This guide explains how to test different payout scenarios in the sandbox environment using account number suffixes for Nigeria bank transfers.

Overview

When testing payouts to Nigerian bank accounts in the sandbox environment, you can simulate various scenarios by encoding the test case in the last two digits of the recipient’s account number. This allows you to comprehensively test your integration’s error handling, retry logic, and different payout states without needing real bank accounts or transactions.

How It Works

When you execute a payout in the sandbox environment:

1. Use a valid 10-digit Nigerian bank account number
2. Set the last two digits to match the scenario you want to test
3. The payout will behave according to the mapped scenario

Test Scenario Mapping

Usage Examples

Testing Successful Transfer

Use an account number ending in 00 to simulate a successful payout:

1
{
2
  "amount": {
3
    "value": 10000,
4
    "currency": "NGN"
5
  },
6
  "recipient": {
7
    "type": "BANK_ACCOUNT",
8
    "accountNumber": "0123456700",
9
    "bankCode": "044",
10
    "accountName": "John Doe"
11
  },
12
  "paymentMethod": "NIGERIA_BANK_TRANSFER",
13
  "reference": "PAYOUT-12345"
14
}

Expected Result: Payout completes successfully

Testing Insufficient Balance Error

Use an account number ending in 12 to simulate an insufficient balance scenario:

1
{
2
  "amount": {
3
    "value": 10000,
4
    "currency": "NGN"
5
  },
6
  "recipient": {
7
    "type": "BANK_ACCOUNT",
8
    "accountNumber": "0123456712",
9
    "bankCode": "044",
10
    "accountName": "Jane Smith"
11
  },
12
  "paymentMethod": "NIGERIA_BANK_TRANSFER",
13
  "reference": "PAYOUT-12346"
14
}

Expected Result: Payout fails with an insufficient balance error

Testing Invalid Amount Error

Use an account number ending in 13 to simulate an invalid amount scenario:

1
{
2
  "amount": {
3
    "value": 10000,
4
    "currency": "NGN"
5
  },
6
  "recipient": {
7
    "type": "BANK_ACCOUNT",
8
    "accountNumber": "0123456713",
9
    "bankCode": "044",
10
    "accountName": "Bob Johnson"
11
  },
12
  "paymentMethod": "NIGERIA_BANK_TRANSFER",
13
  "reference": "PAYOUT-12347"
14
}

Expected Result: Payout fails with an invalid amount error

Testing Account Not Found

Use an account number ending in 23 to simulate an account not found scenario:

1
{
2
  "amount": {
3
    "value": 10000,
4
    "currency": "NGN"
5
  },
6
  "recipient": {
7
    "type": "BANK_ACCOUNT",
8
    "accountNumber": "0123456723",
9
    "bankCode": "044",
10
    "accountName": "Alice Williams"
11
  },
12
  "paymentMethod": "NIGERIA_BANK_TRANSFER",
13
  "reference": "PAYOUT-12348"
14
}

Expected Result: Payout fails with an account not found error

Using Unmapped Suffixes

Account numbers ending in digits 26 through 99 (not in the mapping table) will behave according to default sandbox behavior, which typically results in successful payouts:

1
{
2
  "amount": {
3
    "value": 10000,
4
    "currency": "NGN"
5
  },
6
  "recipient": {
7
    "type": "BANK_ACCOUNT",
8
    "accountNumber": "0123456799",
9
    "bankCode": "044",
10
    "accountName": "Test User"
11
  },
12
  "paymentMethod": "NIGERIA_BANK_TRANSFER",
13
  "reference": "PAYOUT-12349"
14
}

Expected Result: Default sandbox behavior (typically successful)

Important Notes

1. Sandbox Environment Only: These test scenarios only apply to the sandbox environment. Production payouts will use real bank account numbers and process actual transactions.

2. Account Number Format: Use valid 10-digit Nigerian bank account numbers with the last two digits set to your desired test scenario suffix.

3. Consistent Testing: When checking the status of a test payout, the same test scenario will be maintained throughout the lifecycle of that transaction.

4. Default Behavior: Account numbers ending in digits 26 through 99 (not included in the mapping table) will follow default sandbox behavior, which typically results in successful payouts.

5. Error Messages: Failed payout scenarios will return appropriate error messages and status codes that match real-world error conditions.

Testing Best Practices

• Test Happy Path First: Start by testing successful transfers (suffix 00) to ensure your integration works correctly.
• Test Error Handling: Work through various error scenarios to ensure your application handles failures gracefully.
• Check Idempotency: Test duplicate reference scenarios (suffix 10) to verify your idempotency handling.
• Test Limits: Verify your application correctly handles amount limits (suffixes 02, 03, 05, 06) and frequency limits (suffixes 07, 08, 21, 22).
• Monitor Webhook Events: Ensure your webhook handlers correctly process status updates for both successful and failed payouts.

Next Steps

Once you’ve completed testing in the sandbox environment, contact your account manager to enable production payouts. Production transactions will use real bank account numbers and process actual funds transfers.