Sandbox & Test Environment Standard¶
Version: 1.0 Last Updated: 2026-04-03 Owner: Platform Team Status: Active
Purpose¶
Define the sandbox environment specification for Simpaisa's payment APIs. The sandbox enables merchants to integrate and test without processing real money or connecting to live payment channels.
Environment¶
| Property | Value |
|---|---|
| Base URL | https://sandbox.simpaisa.com |
| Gateway | KrakenD (identical configuration to production) |
| API versions | /v3/ (primary), /v1/, /v2/ (legacy, for migration testing) |
| Authentication | Same RSA signing mechanism as production |
| TLS | Cloudflare-terminated, TLS 1.3 |
Sandbox Parity¶
The sandbox MUST maintain parity with production:
- Same API contract: Identical request/response schemas, same required fields
- Same error format: Same error codes, same HTTP status codes (per HTTP-STATUS-CODE-STANDARD.md)
- Same authentication: RSA-SHA256 signing, same header format
- Same webhook format: Same payload structure, same signature verification
- Same rate limiting logic: Same headers (
X-RateLimit-Limit,Retry-After), relaxed thresholds
Differences from production: - No real money movement - No real channel connections — mock responses based on test values - Relaxed rate limits (10x production) - Self-service data reset
Test Credentials¶
- Merchants register sandbox credentials via the DevEx portal (self-service).
- Sandbox credentials are separate from production — no shared keys.
- Each sandbox merchant receives:
merchantId, RSA key pair, webhook signing secret. - Sandbox credentials never expire (unlike production key rotation policy).
Magic Test Values¶
Deterministic test values allow merchants to trigger specific outcomes without randomness.
Amount-Based Triggers¶
| Amount | Behaviour | Use Case |
|---|---|---|
100.00 |
Always succeeds | Happy path testing |
999.99 |
Always fails — INSUFFICIENT_FUNDS |
Error handling |
888.88 |
Always times out (simulates 30s channel timeout) | Timeout handling |
777.77 |
Always returns PENDING (async flow) |
Webhook-driven flow testing |
666.66 |
Always returns ON_HOLD (compliance review) |
Hold/review state testing |
555.55 |
Succeeds on second attempt (first returns 502) |
Retry logic testing |
| Any other | Succeeds | Default behaviour |
MSISDN-Based Triggers (Pay-In)¶
| MSISDN | Behaviour |
|---|---|
03001234567 |
OTP always succeeds (use OTP 123456) |
03009999999 |
OTP always fails |
03008888888 |
OTP expires (never verifiable) |
Any other 03xx |
OTP succeeds with 123456 |
Account-Based Triggers (Pay-Out / Remittance)¶
| Account Number | Behaviour |
|---|---|
1234567890 |
Title fetch succeeds, disbursement succeeds |
0000000000 |
Title fetch fails — account not found |
9999999999 |
Title fetch succeeds, disbursement fails |
| Any other | Title fetch and disbursement succeed |
Card-Based Triggers (Cards)¶
| Card Number | Behaviour |
|---|---|
4242424242424242 |
Authorisation and capture succeed |
4000000000000002 |
Authorisation declined |
4000000000009995 |
Authorisation succeeds, capture fails |
4000000000003220 |
Triggers 3DS authentication |
Webhook Testing¶
- Sandbox delivers webhooks to the merchant's configured callback URL.
- Webhooks use the same payload format and signature as production.
- Webhook delivery retries: 3 attempts with exponential backoff (1s, 5s, 30s).
- Merchants can view webhook delivery history via the DevEx portal (last 100 events).
- Webhook replay: Merchants can trigger re-delivery of any webhook via API:
POST /v3/sandbox/webhooks/{webhookId}/replay
Rate Limiting¶
| Limit | Production | Sandbox |
|---|---|---|
| Requests per minute | 100/merchant | 1000/merchant |
| Transactions per day | Per contract | 10,000/merchant |
| Webhook replay | N/A | 100/hour |
Rate limit responses use the same headers and 429 status code as production, so merchants can test their backoff logic by exceeding sandbox limits.
Data Isolation¶
- Sandbox and production run on separate infrastructure — no shared databases, no shared queues.
- Sandbox transaction IDs are prefixed with
SBX-to prevent confusion. - Sandbox data is not backed up and may be purged with 30 days notice.
Data Reset¶
Merchants can reset their sandbox data via API:
POST /v3/sandbox/reset
This clears: - All transactions - All webhook delivery history - All idempotency keys
It does NOT reset: - Merchant credentials - Webhook endpoint configuration - Rate limit counters (reset hourly)
Sandbox-Specific Endpoints¶
These endpoints exist only in sandbox, not in production:
| Endpoint | Purpose |
|---|---|
POST /v3/sandbox/reset |
Reset all merchant test data |
POST /v3/sandbox/webhooks/{id}/replay |
Replay a webhook delivery |
GET /v3/sandbox/webhooks |
List webhook delivery history |
POST /v3/sandbox/time/advance |
Simulate time passing (test expiry flows) |
Infrastructure¶
Merchant → Cloudflare → KrakenD (sandbox config) → Mock Services → SurrealDB (sandbox instance)
- Mock services implement the same API interface as real services but return deterministic responses based on magic test values.
- SurrealDB sandbox instance stores transaction state for stateful testing (e.g. initiate then query status).
- OpenTelemetry is active in sandbox — merchants can request trace data for debugging.
Availability¶
- Sandbox target uptime: 99% (not 99.9% like production).
- Maintenance windows: Tuesdays 02:00–04:00 UTC (communicated via DevEx portal status page).
- Sandbox may run newer API versions than production for pre-release testing (flagged in response headers:
X-Simpaisa-Preview: true).
Onboarding Checklist¶
Merchants integrating with Simpaisa should follow this sequence:
- Register on DevEx portal → receive sandbox credentials
- Implement RSA signing → test with
POST /v3/payin/transactions(amount100.00) - Implement webhook receiver → verify signature on incoming webhooks
- Test error scenarios → amounts
999.99,888.88,777.77 - Test retry logic → amount
555.55 - Run full integration suite → request production credentials