idnpay-sandbox

Indonesian payment rails, running on your machine.

idnpay-sandbox simulates QRIS, Virtual Account, and e-Wallet payments on localhost, so your integration tests stop depending on a provider sandbox you cannot control.

Webhooks carry an HMAC-SHA256 signature and retry with exponential backoff. Failures you need to test, from a 503 to a body with the wrong signature, you trigger on purpose.

Quickstart

npx idnpay-sandbox

Runs the published package on Node.js 22 or newer. The API listens on http://localhost:9000, and the dashboard opens at the same address.

Or run the source in Docker, which also starts Redis:

git clone https://github.com/Reyhandhani/idnpay-sandbox.git
cd idnpay-sandbox
docker compose up -d --build

Default keys are idnpay-dev-client-key and idnpay-dev-secret-key. Change both before anyone else can reach the port.

What it covers

payment_type Options Returned to you
qris Dynamic QRIS string with EMVCo payload and CRC-16 qr_string
bank_transfer BCA, Mandiri, BRI, BNI, Permata va_number
ewallet GoPay, OVO, ShopeePay, DANA deeplink_url

Virtual Account prefixes are illustrative, not official bank numbers. Deeplinks follow each provider scheme and do not open a real app.

Why run it locally

Your CI stops being flaky
The simulator runs as a container in the same job and answers in milliseconds. No rate limit, no maintenance window, no network hop to someone else's sandbox.
You can reproduce the failure
Set a failure status, or point the callback at an endpoint that returns 503 and watch the retry queue work through it.
Webhooks do not need a public URL
Both containers share a Docker network, so callback_url uses a service name. No tunnel, no exposed laptop.
It speaks a Midtrans subset
POST /v2/charge, the status endpoint, and signature_key work as Midtrans documents them. Snap, cards, refunds, and payouts are not implemented.

Documentation

README
Setup, request examples, transaction states.
API
Endpoints, payloads, error codes.
Webhooks
Signature verification and retry schedule.
CI
Running it inside GitHub Actions.

FAQ

Is it a drop-in replacement for the Midtrans sandbox?
For charge, status, and webhook flows it covers the subset in the Midtrans guide. 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. The workflow is in the CI guide.
My app runs on the host. Where do webhooks go?
Use host.docker.internal in callback_url. Inside a container, use the service name instead.
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.