A local payment gateway simulator for Indonesia. Use it to test QRIS, Virtual Account, and e-Wallet flows without a third-party sandbox that goes down or rate limits you.
Webhooks are signed with HMAC-SHA256, so you can test signature verification on your side too.
A payment sandbox is a shared service on someone else's network, and that shape causes four problems during development.
Rate limits, maintenance windows, and network latency turn a green build into a flaky one. This simulator runs as a container in the same job, answers in milliseconds, and needs no internet. The recipe for GitHub Actions is in docs/CI.md.
Provider sandboxes test the happy path. Here you can return 504 from every call with SIMULATED_FAILURE_STATUS, let a webhook fail three times in a row to exercise the retry queue, or post a body with a wrong HMAC to prove your app rejects it.
Both containers share a Docker network, so callback_url points at a service name. No tunnel, no exposed laptop, and no callback that breaks when your connection drops.
Stripe CLI tests cards. This project models QRIS with an EMVCo payload and CRC-16, Virtual Accounts for BCA, Mandiri, BRI, BNI, and Permata, and e-Wallet deeplinks for GoPay, OVO, ShopeePay, and DANA.
Point your base URL at the simulator and use SECRET_KEY as the Basic auth username with an empty password. Request bodies stay the same.
POST /v2/chargeacceptstransaction_details,payment_type, andcallback_urlGET /v2/{order_id}/statusreturns the same fields you already read- Webhooks carry
signature_key, computed with SHA512 exactly as Midtrans documents
Snap, cards, refunds, and payouts are not supported. The full mapping is in docs/MIDTRANS.md.
| Provider sandbox | Stripe CLI | idnpay-sandbox | |
|---|---|---|---|
| Runs offline | No | Partly | Yes |
| Account required | Yes | Yes | No |
| Force 504 or repeated webhook failures | No | No | Yes |
| Indonesian rails (QRIS, VA, e-Wallet) | Yes | No | Yes |
| Real bank numbers and settlement | Yes | n/a | No |
| Production use | Sandbox only | No | No |
| Midtrans-compatible requests | It is Midtrans | No | Subset |
It does not move real money, does not implement bank settlement rules, and its Virtual Account prefixes are illustrative rather than official bank numbers. Use it to test your integration, not to model a bank.
- Transaction states
PENDING,PAID,FAILED, andEXPIRED, driven by simulation endpoints - Signed webhooks with retries and exponential backoff
- Redis queue (optional). Without Redis, the queue runs in memory
- Configurable latency, failure rate, and failure status for resilience testing
- A browser dashboard for trying flows without writing code
Docker Compose builds the image and starts the simulator with Redis.
docker compose up -d --buildRun the same command after pulling changes, otherwise Docker keeps the old image.
Or run the published package without cloning, on Node.js 22 or newer:
npx idnpay-sandboxThen open http://localhost:9000 and use the dashboard, or follow these three calls.
- Create a charge:
curl -X POST http://localhost:9000/v1/charge \
-H "Content-Type: application/json" \
-H "X-Client-Key: idnpay-dev-client-key" \
-d '{
"order_id": "ORDER-10293",
"gross_amount": 150000,
"payment_type": "qris",
"callback_url": "http://host.docker.internal:8000/api/payments/webhook"
}'- Copy
transaction_idfrom the response and mark it paid:
curl -X POST http://localhost:9000/v1/simulate/pay \
-H "Content-Type: application/json" \
-H "X-Client-Key: idnpay-dev-client-key" \
-d '{ "transaction_id": "trx-..." }'- Watch your
callback_urlreceive a webhook withtransaction_statusset toPAID.
Without Docker, use Node.js 22 or newer:
npm ci
npm run build
npm startFor auto-reload during development, run npm run dev. Settings can live in a .env file; see .env.example.
If the simulator runs in Docker and your app runs on the host, use host.docker.internal in callback_url. Inside a container, localhost points at the container itself, not your machine.
| Your app | Simulator | callback_url |
|---|---|---|
| Host | Docker | http://host.docker.internal:<port>/... |
| Host | Host | http://localhost:<port>/... |
| Container in same stack | Docker | http://<service-name>:<port>/... |
transaction_status |
status_code |
Meaning |
|---|---|---|
PENDING |
201 |
Waiting for payment |
PAID |
200 |
Payment received |
FAILED |
202 |
Payment failed |
EXPIRED |
407 |
Past expiry_time |
Final states never change again, and every state change sends exactly one webhook.
payment_type |
Extra field | Response field |
|---|---|---|
qris |
– | qr_string |
bank_transfer |
bank: bca, mandiri, bri, bni, permata |
va_number |
ewallet |
ewallet: gopay, ovo, shopeepay, dana |
deeplink_url |
Virtual Account numbers use a different prefix per bank so they are easy to recognize in logs. These prefixes are illustrative, not real bank numbers. Deeplinks follow each provider's scheme but do not open a real app.
Is it a drop-in replacement for the Midtrans sandbox? For charge, status, and webhook flows it covers the subset listed in docs/MIDTRANS.md. Snap, cards, refunds, and payouts are not implemented.
Does any real money move? No. Nothing connects to a bank, and the Virtual Account numbers are illustrative.
Can I run it in CI?
Yes. Start it as a service container in the same job and point callback_url at the service name. docs/CI.md has the workflow.
My app runs on the host. Where do webhooks go?
Use host.docker.internal in callback_url. The table under Connecting your app covers the other combinations.
How do I test a webhook that fails?
Point callback_url at an endpoint that returns 503. The simulator retries with a delay of 2^n seconds until WEBHOOK_RETRY_LIMIT (5 by default), and every attempt is signed.
Apa ini bisa menggantikan sandbox Midtrans? Untuk charge, cek status, dan webhook, bisa, sebatas yang tercantum di docs/MIDTRANS.md. Snap, kartu, refund, dan payout belum ada.
Ada uang sungguhan yang berpindah? Tidak. Tidak ada koneksi ke bank, dan nomor Virtual Account di sini hanya contoh.
Bisa dipakai di CI?
Bisa. Jalankan sebagai service container di job yang sama, lalu arahkan callback_url ke nama service. Contoh workflow-nya ada di docs/CI.md.
Aplikasi saya jalan di host, webhook dikirim ke mana?
Pakai host.docker.internal di callback_url. Kombinasi lain ada di tabel Connecting your app.
Gimana cara ngetes webhook yang gagal?
Arahkan callback_url ke endpoint yang membalas 503. Simulator mencoba ulang dengan jeda 2^n detik sampai WEBHOOK_RETRY_LIMIT (default 5), dan setiap percobaan tetap ditandatangani.
- API: endpoints, request and response formats, error codes
- Midtrans: the compatible subset and its limits
- Webhooks: payload, signature verification, retries
- Configuration: every environment variable
- Architecture: how the pieces fit and what happens on failure
- CI: run it in GitHub Actions, edge-case recipes
- Design: the visual direction and the reasons behind it
- Deployment: why it needs a container, not serverless
- Contributing
- Code of conduct
- Security
- Changelog
npm ci
npm run ci # format, lint, typecheck, tests with coverage, build
npm test # tests only
npm run test:coverage # tests with the coverage gate (90% lines, 85% branches and functions)Redis integration tests only run when TEST_REDIS_URL is set:
TEST_REDIS_URL=redis://127.0.0.1:6379 npm testLayout:
src/
config/ configuration and constants
controllers/ request handlers
plugins/ auth, network simulation, error handling
queues/ webhook queue (memory and Redis) and worker
routes/ endpoints and validation schemas
services/ transaction state, payment details, webhooks, QRIS
app.ts application wiring
index.ts process entry point
public/ dashboard
test/ unit and integration tests
This is a development tool, not a production service. Change CLIENT_KEY and SECRET_KEY before exposing it to anyone else. See SECURITY.md.
MIT. See LICENSE.
