Overview
Accept customer payments through mobile wallets in Bangladesh, Nepal, Egypt, and Iraq using the same two REST APIs. Regional differences are limited to headers (region, operator) and operator-specific configuration—not separate endpoints or integration patterns.
Not covered here: Pakistan pay-in uses a different API surface (
/v2/wallets/...). See Pakistan — Wallet APIs.
Payment Flow
All unified regions follow a redirect-based flow.
| Step | Action | API |
|---|---|---|
| 1 | Create payment session | Initiate |
| 2 | Redirect customer to payment_url from the Initiate response | — |
| 3 | Customer pays on the wallet operator's page | — |
| 4 | Customer lands on your successUrl or failureUrl | — |
| 5 | Confirm final status server-side | Inquire |
| 6 | Receive async notification (if configured) | Webhooks |
Always call Inquire on your success/failure landing page. Do not treat the redirect alone as proof of payment. Status 0037 (Transaction-Pending) means the customer has not finished paying yet.
APIs At A Glance
| API | Method | Path |
|---|---|---|
| Initiate Payment | POST | /payins/payments/initiate |
| Inquire Payment | POST | /payins/payments/inquire |
Environments
| Environment | Base URL |
|---|---|
| Sandbox | https://sandbox.simpaisa.com |
| Production | https://payin.simpaisa.com |
Regional Configuration
Set these values per region and operator. Use the same merchantId in sandbox and production.
| Region | region header | Currency | Operators | Operator code | Body / response field |
|---|---|---|---|---|---|
| Bangladesh | BD | BDT | bKash | 10001 | operator |
| Bangladesh | BD | BDT | Nagad | 10002 | operator |
| Nepal | NP | NPR | Khalti | 100025 | operatorId |
| Egypt | EG | EGP | Paymob | 100026 | operatorId |
| Iraq | IQ | IQD | ZainCash | 100027 | operatorId |
Common Request Headers
| Header | Value | Required |
|---|---|---|
Accept | text/plain, application/json, application/*+json | Yes |
Content-Type | application/json | Yes |
api-token | API token issued by Simpaisa | Yes |
mode | payin | Yes |
region | BD · NP · EG · IQ | Yes |
operatorId | Operator code from table above | Yes |
version | 3.0 | Yes |
Pass the operator in both the operatorId header and the request/response payload field. Field name is region-specific: operator for Bangladesh only; operatorId for Nepal, Egypt, and Iraq. See Initiate samples.
Authentication
Unified pay-in regions authenticate with an api-token header or Signature. Simpaisa provides this token with your merchant credentials during onboarding.
For webhook setup and postback handling, see Webhooks and Platform webhooks reference.
Operator Use Cases
Each operator uses the same Initiate and Inquire APIs. Examples with region-specific payloads:
| Operator | Region | Guide |
|---|---|---|
| bKash | Bangladesh | Use case: bKash |
| Nagad | Bangladesh | Use case: Nagad |
| Khalti | Nepal | Use case: Khalti |
| Paymob | Egypt | Use case: Paymob |
| ZainCash | Iraq | Use case: ZainCash |
Status Codes
See Unified Pay-In status codes.
Key codes:
| Code | Message | Meaning |
|---|---|---|
0000 | Success | Payment completed |
0037 | Transaction-Pending | Customer has not finished paying |
0021 | Channel-Failed-Transaction | Operator rejected the payment |
0101 | Invalid-Credential | Check api-token and merchantId |
Getting Started
- Request sandbox credentials and
api-tokenfrom the Simpaisa integration team. - Configure your postback URL.
- Implement Initiate → redirect → Inquire.
- Test each operator you plan to go live with using the use-case guides above.
- Move to production (
payin.simpaisa.com) after sign-off.