Sandbox / Test Mode

SaySwitch payout endpoints support sandbox responses when requests are made with a test secret key:

Authorization: Bearer sk_test_...

In sandbox mode, SaySwitch returns mock bank and account data in the same response structure as live mode. This allows merchants to test payout flows without calling external banking providers.

Supported Endpoints

The following Merchant API payout endpoints support sandbox mode:

• GET /api/v1/bank_list/{currency?}
• POST /api/v1/account_name_verify
• POST /api/v1/bank_transfer
• POST /api/v1/bank_transfer/wallet

Supported Currencies

Sandbox payout testing supports:

• NGN
• KES
• GHS

Sandbox Bank List

When using a test secret key, the bank list endpoint returns sandbox banks in the same structure as live.

Sample request:

curl -X GET https://backendapi.sayswitchgroup.com/api/v1/bank_list/NGN \
  -H "Authorization: Bearer sk_test_YOUR_SECRET_KEY"

Sample response:

{
  "success": true,
  "message": "Bank list retrieved",
  "currency": "NGN",
  "data": [
    {
      "bankName": "Sayswitch Test Bank",
      "bankCode": "999001",
      "logo": "https://cdn-icons-png.freepik.com/256/2830/2830155.png"
    },
    {
      "bankName": "Moniepoint Test Bank",
      "bankCode": "50515",
      "logo": "https://cdn-icons-png.freepik.com/256/2830/2830155.png"
    },
    {
      "bankName": "Wema Test Bank",
      "bankCode": "035",
      "logo": "https://cdn-icons-png.freepik.com/256/2830/2830155.png"
    }
  ]
}

Sandbox Account Details

Use the following account details for account name verification and test payouts.

NGN

KES

GHS

Account Name Verification Example

Request:

curl -X POST https://backendapi.sayswitchgroup.com/api/v1/account_name_verify \
  -H "Authorization: Bearer sk_test_YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "currency": "NGN",
    "bank_code": "999001",
    "account_number": "0000000001"
  }'

Response:

{
  "success": true,
  "message": "Account name retrieved.",
  "data": "SAYSWITCH TEST USER"
}

Initiate Payout Example

Request:

curl -X POST https://backendapi.sayswitchgroup.com/api/v1/bank_transfer \
  -H "Authorization: Bearer sk_test_YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "currency": "NGN",
    "amount": 1000,
    "bank_code": "999001",
    "bank_name": "Sayswitch Test Bank",
    "account_number": "0000000001",
    "narration": "Sandbox payout test",
    "reference": "sandbox-test-reference-001"
  }'

In sandbox mode, the payout is simulated. SaySwitch validates the sandbox account details, creates payout records, debits the test wallet, and returns the same response structure as live mode. No external banking provider is contacted.

Sandbox Webhook Notifications

When a payout is initiated with a test secret key (sk_test_...) or through dashboard test mode (mode=test), SaySwitch simulates the payout using sandbox data.

If the sandbox payout is successful, SaySwitch sends a payout webhook to the merchant’s test webhook URL, not the live webhook URL.

The webhook uses the same event structure as live payout webhooks, so merchants can test their webhook handling before going live.

Webhook URL Used

Webhook Trigger

Sandbox payout webhooks are triggered when the sandbox payout status is success.

If the sandbox payout status is pending, no successful payout webhook is sent immediately.

Sample Successful Sandbox Payout Webhook

{
  "notify": "payout",
  "notifyType": "successful",
  "data": {
    "reference": "sandbox-test-reference-001",
    "currency": "NGN",
    "amount": 1000,
    "fee": 0,
    "stamp_duty": 0,
    "bank_code": "999001",
    "bank_name": "Sayswitch Test Bank",
    "account_number": "0000000001",
    "account_name": "SAYSWITCH TEST USER",
    "narration": "Sandbox payout test",
    "domain": "test",
    "status": "success",
    "sessionid": "000000000000"
  }
}

Webhook Headers

Sandbox payout webhooks include the same signature headers as live payout webhooks:

payloadSignature: HMAC_SHA512(payload, test_secret_key)
merchantSignature: HMAC_SHA512(test_public_key, test_secret_key)
timestamp: CURRENT_TIMESTAMP
Content-Type: application/json

Important Notes

• Sandbox payout webhooks are sent to the merchant’s configured test webhook URL.
• Live payout webhooks are sent to the merchant’s configured live webhook URL.
• Sandbox webhooks are only sent for successful simulated payouts.
• Sandbox payouts do not call external banks or payment providers.
• The webhook payload structure is intentionally similar to live mode so merchants can test integration logic safely.

Initiate Payout From Wallet

The wallet-specific payout endpoint also supports sandbox mode with the same sandbox bank codes and account numbers.

Endpoint:

POST /api/v1/bank_transfer/wallet

The request should include wallet_code where required by the merchant’s wallet setup.

S2S Bank Transfer Initialization

S2S bank transfer initialization also supports test mode for NGN collection/checkout virtual accounts.

Supported endpoints:

• POST /s2s/banktransfer/initialize
• POST /s2s/banktransfer/initialize/wallet
• POST /s2s/v1/banktransfer/initialize
• POST /s2s/v1/banktransfer/initialize/wallet

Sample sandbox response:

{
  "status": true,
  "message": "Account generated successfully",
  "data": {
    "account_name": "SAYSWITCH TEST CHECKOUT",
    "account_number": "0000000000",
    "bank_name": "Sayswitch Test Bank"
  }
}

Important: S2S bank transfer initialization is for NGN collection/checkout virtual accounts only. KES and GHS sandboxing applies to payout flows, not S2S bank transfer collections.

Notes

• Use sk_test_... keys for sandbox mode.
• Use sk_live_... keys for live payout processing.
• Sandbox payouts do not call external banks or payment providers.
• Sandbox responses follow the same response structure as live where possible.
• Test wallets must have sufficient balance for payout simulations.