Merchant Onboarding & Integration Guide Standard¶
Standard ID: MERCHANT-ONBOARDING Version: 1.0 Effective: 2026-04-03 Owner: CDO
1. Onboarding Flow¶
Register → Sandbox → Integration → Certification → Go-Live
| Stage | Duration Target | Description |
|---|---|---|
| Register | < 5 minutes | Self-service sign-up on DevEx portal |
| Sandbox | Instant | Sandbox credentials issued automatically |
| Integration | < 2 days (SDK) / < 1 week (custom) | Merchant implements against sandbox |
| Certification | < 1 day | Automated test suite validates implementation |
| Go-Live | < 1 day | Production credentials issued after certification |
2. Self-Service Sandbox Access¶
- Merchants register on the DevEx portal (developer.simpaisa.com).
- Sandbox API credentials generated instantly upon registration.
- No manual approval required for sandbox access.
- Sandbox environment mirrors production behaviour with test data.
- Rate limits applied to prevent abuse (100 requests/minute default).
3. Integration Checklist¶
Every merchant integration must satisfy these requirements before certification:
Security¶
- Implement RSA-SHA256 request signing on all API calls.
- Implement webhook signature verification (verify Simpaisa's signature on callbacks).
- Store API keys securely (never in client-side code or version control).
Reliability¶
- Implement idempotency keys on all payment endpoints.
- Handle asynchronous flows — process webhooks AND implement polling as fallback.
- Implement retry with exponential backoff for transient failures (429, 502, 503).
- Handle all documented error codes gracefully (do not treat unknown codes as fatal).
Testing¶
- Test with magic values covering all scenarios:
- Successful payment.
- Declined payment (insufficient funds, card expired, limit exceeded).
- Timeout / pending (async resolution via webhook).
- Duplicate request (idempotency check).
- Invalid signature (rejected).
Per Product¶
| Product | Additional Requirements |
|---|---|
| Pay-In | Handle redirect flow, verify final status via API (not redirect params) |
| Pay-Out | Implement balance check before submission, handle partial failures |
| Remittance | Validate beneficiary details format per corridor (PK/BD/NP/IQ) |
| Cards | Implement 3DS challenge flow, handle soft-decline retry |
4. Certification¶
Certification is automated — merchants run the Simpaisa certification test suite against their sandbox integration.
Process¶
- Merchant triggers certification from the DevEx portal.
- Automated suite sends test transactions through the merchant's integration.
- Suite validates: correct signing, idempotency, error handling, webhook processing.
- Pass: all tests green — merchant proceeds to go-live.
- Fail: detailed report showing which tests failed and remediation guidance.
Certification Criteria¶
- 100% of mandatory tests must pass.
- No test may be skipped.
- Certification expires after 90 days if go-live is not completed (must re-certify).
5. Go-Live Criteria¶
Before production credentials are issued:
- Certification suite passed.
- Production webhook URL configured and verified (Simpaisa sends a verification ping).
- Rate limits configured per merchant tier.
- Merchant agreement signed (commercial/legal).
- KYB (Know Your Business) verification completed.
6. Code Samples & SDKs¶
Generated SDKs¶
Available in 5 languages, auto-generated from OpenAPI specifications:
| Language | Package Manager |
|---|---|
| Java | Maven Central |
| Python | PyPI |
| Node.js | npm |
| PHP | Packagist |
| C# | NuGet |
SDKs handle signing, idempotency, retries, and webhook verification out of the box.
Code Samples¶
Each SDK includes working examples for: - Pay-In initiation and status check. - Pay-Out submission and tracking. - Webhook receiver with signature verification. - Error handling patterns.
7. DevEx Portal Content¶
The developer experience portal (developer.simpaisa.com) must provide:
| Content | Format |
|---|---|
| Getting Started Guide | Step-by-step walkthrough from registration to first test payment |
| API Reference | Interactive documentation via Scalar (generated from OpenAPI spec) |
| Code Samples | Per-language examples for each product |
| Webhook Reference | Event types, payload schemas, delivery guarantees |
| FAQ | Common integration questions and troubleshooting |
| Changelog | Versioned list of API changes with migration guidance |
| Status Page | Real-time service status for all environments |
| Magic Values | Test card numbers, account numbers, and expected outcomes |
8. Support¶
| Phase | Support Channel | SLA |
|---|---|---|
| Integration (pre-go-live) | Dedicated integration support (Slack or email) | 4-hour response |
| Post-go-live | Standard support channels | Per merchant tier SLA |
9. Merchant Tiers¶
| Tier | Rate Limit | Support | Custom Config |
|---|---|---|---|
| Standard | 100 req/min | Standard channels, 8-hour SLA | No |
| Premium | 500 req/min | Priority queue, 2-hour SLA | Limited |
| Enterprise | Custom | Dedicated support contact, 1-hour SLA | Full |
Tier assignment based on: - Projected transaction volume. - Commercial agreement. - Strategic importance.
10. Integration Time Targets¶
| Integration Method | Target Time to Go-Live |
|---|---|
| SDK (any language) | < 2 working days |
| Custom integration | < 1 working week |
| Enterprise (custom requirements) | < 2 working weeks |
Track actual integration time per merchant. Escalate to CDO if a merchant exceeds 2x the target.
11. Post-Go-Live Monitoring¶
For the first 7 days after go-live:
- Monitor merchant's transaction success rate.
- Alert if success rate drops below 90%.
- Proactive outreach if error patterns detected.
- Ensure webhook delivery success rate is > 99%.