Sandbox Testing

The sandbox environment allows you to test payout integrations without processing real transactions. Use specific account numbers or phone numbers to simulate different scenarios, including successful transfers, failures, and various error conditions.

Important: All sandbox testing uses the CrissCross Payouts API request shape. See Bank Transfers and Mobile Wallet for the correct request structure.

Bank Transfer Testing

Nigeria (NGN)

When testing payouts to Nigerian bank accounts, you can simulate various scenarios by encoding the test case in the last two digits of the recipient’s account number.

How it works:

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

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

Example: Testing Successful Transfer

1
{
2
  "merchantId": "your-merchant-id",
3
  "merchantReference": "PAYOUT-TEST-001",
4
  "destinationValue": {
5
    "minorAmount": 1000000,
6
    "currency": "NGN"
7
  },
8
  "paymentMethodId": "banktransfer",
9
  "paymentLocation": "NGA",
10
  "recipient": {
11
    "type": "bank_account",
12
    "accountNumber": "0123456700",
13
    "bankCode": "044",
14
    "accountHolderName": "John Doe",
15
    "country": "NGA"
16
  },
17
  "attributes": {}
18
}

Note: minorAmount: 1000000 = 10,000.00 NGN. Account number ending in 00 triggers successful transfer.

Example: Testing Insufficient Balance

1
{
2
  "merchantId": "your-merchant-id",
3
  "merchantReference": "PAYOUT-TEST-002",
4
  "destinationValue": {
5
    "minorAmount": 1000000,
6
    "currency": "NGN"
7
  },
8
  "paymentMethodId": "banktransfer",
9
  "paymentLocation": "NGA",
10
  "recipient": {
11
    "type": "bank_account",
12
    "accountNumber": "0123456712",
13
    "bankCode": "044",
14
    "accountHolderName": "Jane Smith",
15
    "country": "NGA"
16
  },
17
  "attributes": {}
18
}

Note: Account number ending in 12 triggers insufficient balance error.

Egypt (EGP)

When testing payouts to Egyptian bank accounts, you can simulate different transaction flows by using specific suffixes in the account number.

Account number formats:

• Standard account number format (e.g., 100045022697)
• IBAN format (e.g., EG550019000510000000000000010)

IBAN format is recommended for international compatibility.

Transaction Flow Mapping

Note: The default flow applies to any account number that doesn’t end with 101, 104, 105, or 106. This means successful transactions can use any valid account number without a special suffix.

Example: Testing Successful Transfer (Default Flow)

1
{
2
  "merchantId": "your-merchant-id",
3
  "merchantReference": "PAYOUT-TEST-EGP-001",
4
  "destinationValue": {
5
    "minorAmount": 10000,
6
    "currency": "EGP"
7
  },
8
  "paymentMethodId": "banktransfer",
9
  "paymentLocation": "EGY",
10
  "recipient": {
11
    "type": "bank_account",
12
    "accountNumber": "EG550019000510000000000000010",
13
    "bankCode": "CIB",
14
    "accountHolderName": "John Doe",
15
    "country": "EGY"
16
  },
17
  "attributes": {}
18
}

Note: minorAmount: 10000 = 100.00 EGP. Account number without special suffix triggers default successful flow.

Example: Testing Failed Transaction (Suffix 101)

1
{
2
  "merchantId": "your-merchant-id",
3
  "merchantReference": "PAYOUT-TEST-EGP-002",
4
  "destinationValue": {
5
    "minorAmount": 10000,
6
    "currency": "EGP"
7
  },
8
  "paymentMethodId": "banktransfer",
9
  "paymentLocation": "EGY",
10
  "recipient": {
11
    "type": "bank_account",
12
    "accountNumber": "EG550019000510000000000000101",
13
    "bankCode": "CIB",
14
    "accountHolderName": "John Doe",
15
    "country": "EGY"
16
  },
17
  "attributes": {}
18
}

Note: Account number ending in 101 triggers failed transaction flow.

Mobile Wallet Testing

Kenya (KES) - M-Pesa

For M-Pesa payouts in Kenya, use the operator "mpesa" (M-Pesa). Phone numbers are automatically normalized to international format.

Amount limits:

• Minimum: 10.00 KES (specify as minorAmount: 1000 in the request)
• Maximum: 150,000.00 KES per transaction (specify as minorAmount: 15000000 in the request)

Note: Amounts are in minor units (integer, same as production). For example, minorAmount: 500000 = 5,000.00 KES.

Phone number formats:

• Local: 0723993187 → normalized to 254723993187
• International: +254723993187 or 254723993187 → normalized to 254723993187

Example: Testing M-Pesa Payout

1
{
2
  "merchantId": "your-merchant-id",
3
  "merchantReference": "PAYOUT-TEST-KES-001",
4
  "destinationValue": {
5
    "minorAmount": 500000,
6
    "currency": "KES"
7
  },
8
  "paymentMethodId": "mobilemoney",
9
  "paymentLocation": "KEN",
10
  "recipient": {
11
    "type": "mobile_money",
12
    "phoneNumber": "254723993187",
13
    "country": "KEN",
14
    "operator": "mpesa",
15
    "name": "Test User"
16
  },
17
  "attributes": {}
18
}

Note: minorAmount: 500000 = 5,000.00 KES. Use operator: "mpesa" for M-Pesa in Kenya.

Francophone Africa (XOF / XAF)

When testing payouts to mobile money wallets in Francophone Africa (Ivory Coast, Senegal, Benin, etc.), you can simulate various scenarios by using specific test phone numbers (MSISDNs).

Important: In the sandbox environment, phone number normalization is disabled to support specific test numbers. You must use the exact test MSISDNs listed below without any modifications or country codes.

Supported Providers by Country

Test Scenario Mapping

Provider Availability Matrix

Not all test numbers work with every operator. For the widest range of error simulations, we recommend testing with Senegal / orange or wave (if supported).

Example: Testing Successful Transfer (Ivory Coast - MTN)

1
{
2
  "merchantId": "your-merchant-id",
3
  "merchantReference": "PAYOUT-TEST-XOF-001",
4
  "destinationValue": {
5
    "minorAmount": 500000,
6
    "currency": "XOF"
7
  },
8
  "paymentMethodId": "mobilemoney",
9
  "paymentLocation": "CIV",
10
  "recipient": {
11
    "type": "mobile_money",
12
    "phoneNumber": "00000001",
13
    "country": "CI",
14
    "operator": "mtn"
15
  },
16
  "attributes": {}
17
}

Note: minorAmount: 500000 = 5,000.00 XOF. MSISDN 00000001 triggers successful transfer. Use exact test MSISDNs in sandbox (no country code prefix).

Example: Testing Failed Transaction (Senegal - Orange)

1
{
2
  "merchantId": "your-merchant-id",
3
  "merchantReference": "PAYOUT-TEST-XOF-002",
4
  "destinationValue": {
5
    "minorAmount": 500000,
6
    "currency": "XOF"
7
  },
8
  "paymentMethodId": "mobilemoney",
9
  "paymentLocation": "SEN",
10
  "recipient": {
11
    "type": "mobile_money",
12
    "phoneNumber": "00000206",
13
    "country": "SN",
14
    "operator": "orange"
15
  },
16
  "attributes": {}
17
}

Note: MSISDN 00000206 triggers invalid amount error. Ensure you use a provider that supports this error (e.g., Senegal / Orange).

Testing Best Practices

1. Test Happy Path First: Start by testing successful transfers to ensure your integration works correctly.

   • Nigeria: Use account number ending in 00 with paymentMethodId: "banktransfer", paymentLocation: "NGA"
   • Egypt: Use any valid account number without special suffix with paymentMethodId: "banktransfer", paymentLocation: "EGY"
   • Mobile wallet: Use MSISDN 00000001 (for Francophone) or valid phone numbers (for Kenya) with paymentMethodId: "mobilemoney"

2. Test Error Handling: Work through various error scenarios to ensure your application handles failures gracefully.

   • Test insufficient balance (Nigeria: suffix 12)
   • Test invalid amounts (Nigeria: suffix 13, Francophone: MSISDN 00000206)
   • Test account not found (Nigeria: suffix 23)

3. Test Limits: Verify your application correctly handles amount limits and frequency limits.

   • Nigeria: Suffixes 02, 03, 05, 06 for amount limits
   • Nigeria: Suffixes 07, 08, 21, 22 for frequency limits

4. Test Idempotency: Test duplicate merchantReference scenarios to verify your idempotency handling.

   • Nigeria: Suffix 10 for duplicate transaction reference

5. Monitor Webhook Events: Ensure your webhook handlers correctly process status updates for both successful and failed payouts.

6. Test Transaction Lifecycles: For Egypt, test different transaction flows (suffixes 101, 104-106) to understand the complete lifecycle.

Important Notes

• Sandbox Environment Only: These test scenarios only apply to the sandbox environment. Production payouts will use real account numbers/phone numbers and process actual transactions.
• Consistent Testing: When checking the status of a test payout, the same test scenario will be maintained throughout the lifecycle of that transaction.
• Error Messages: Failed payout scenarios will return appropriate error messages and status codes that match real-world error conditions.
• Amount Format: All amounts in sandbox testing use minor units (integer, same as production). For example, minorAmount: 1000000 = 10,000.00 NGN, minorAmount: 500000 = 5,000.00 KES. Multiply major units by 100 to get minor units.
• Phone Number Normalization:
  • Sandbox (Francophone): Phone number normalization is disabled. Use exact test MSISDNs (e.g., 00000001).
  • Sandbox (Kenya): Phone numbers are normalized. You can use local or international format.
  • Production: Phone numbers are automatically normalized to international format.

Next Steps

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

For more information on the payout API structure, see:

• Bank Transfers — Request structure and required fields
• Mobile Wallet — Request structure and providers
• Single Payouts — Creating individual payouts
• Bulk Payouts — Creating multiple payouts