Sandbox / Test Mode

Overview

Sandbox mode allows you to test your integration without processing real transactions or affecting real balances. All sandbox transactions are completely isolated from live transactions.

Sandbox transactions do not require real balance and will not affect your live account.

Using Sandbox Mode

1. Get Your Test API Key

In your dashboard, you will find two API keys:

Live API Key - For production transactions
Test API Key - For sandbox transactions

2. Use Test API Key in Requests

Simply use your test API key instead of your live key:


curl -X POST "https://dashboard.mbiyo.africa/api/v1/merchant/payin" \
  -H "Authorization: Bearer YOUR_TEST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 1000,
    "currency": "USD",
    "payment_method": "mobile_money",
    "order_id": "TEST-ORDER-123",
    "callback_url": "https://yoursite.com/webhook",
    "metadata": {
      "phone_number": "243970000000",
      "network": "vodacom",
      "country_code": "CD"
    }
  }'

Test Phone Numbers

Use these test phone numbers to simulate different transaction outcomes:

Phone Number Pattern	Result	Description
`*0000`	Successful	Any number ending in 0000 will succeed immediately
`*1111`	Successful	Any number ending in 1111 will succeed immediately
`*2222`	Successful	Any number ending in 2222 will succeed immediately
`*3333`	Pending	Transaction will remain pending
`*4444`	Pending	Transaction will remain pending
`*5555`	Failed	Transaction will fail immediately
`*9999`	Failed	Transaction will fail immediately

Example Test Numbers by Country

Democratic Republic of Congo (CD)

Vodacom Success: 243970000000
Vodacom Failed: 243979999999
Airtel Success: 243971111111
Orange Success: 243892222222

Burkina Faso (BF)

MTN Success: 22670000000
Orange Success: 22671111111

Cameroon (CM)

MTN Success: 237670000000
Orange Success: 237690000000

Sandbox Behavior

What happens in sandbox mode:

Transactions are stored in a separate database table
No real payment gateways are called
No real money is processed
Balance checks are skipped for payouts
Webhooks are still sent to your callback URL
Transaction status is determined by test phone number

Testing Webhooks

Sandbox transactions will trigger webhooks just like live transactions. This allows you to test your webhook handling logic.

Example Webhook Payload (Sandbox)


{
  "transaction_id": "CI-69884B3D6868F1770539837",
  "amount": 1000,
  "fee": 15,
  "currency": "USD",
  "order_id": "TEST-ORDER-123",
  "status": "successful",
  "charged_amount": 1015,
  "type": "cashin",
  "created_at": "2026-02-08T10:30:00Z",
  "updated_at": "2026-02-08T10:30:05Z",
  "metadata": {
    "phone_number": "243970000000",
    "network": "vodacom",
    "country_code": "CD"
  }
}

Viewing Sandbox Transactions

All API endpoints work the same way in sandbox mode:

GET /api/v1/merchant/transactions - List all sandbox transactions
GET /api/v1/merchant/transactions/{id} - Get sandbox transaction status
POST /api/v1/merchant/transactions/{id}/resend-webhook - Resend sandbox webhook

When using your test API key, you will only see sandbox transactions. Live transactions are completely separate.

Best Practices

Always test your integration in sandbox mode before going live
Test all possible transaction outcomes (success, pending, failed)
Verify your webhook handling works correctly
Test error scenarios and edge cases
Never use test API keys in production
Keep your live and test API keys secure