Developer Docs
Onboard a new product to accept payments in under 30 minutes: register, sign your request, call the Charge API, receive the webhook.
Quickstart (< 30 min)
1. Register your product
There is no self-serve merchant dashboard yet: products are still registered by our team through the Admin API. Start on the [Get started page](/en/daftar): sign in with your Efolusi account, then send us your product name and callback URL (must be HTTPS). You receive a product_id, an api_key, and a webhook_secret (test + live) over a secure channel.
2. Sign your request
Every API call is HMAC-signed (see the Signature guide below). Send the `X-Product-Id`, `X-Timestamp`, and `X-Signature` headers.
3. Create a charge
Call `POST /v1/charges` with an `Idempotency-Key` header. Hosted checkout is in `routing.redirectUrl` when supplied by the provider. If the response is lost, repeat the same key or call `GET /v1/charges/:id` using the same product and test/live mode. A persisted routing outcome is returned without creating another charge. It may be absent during routing or for legacy transactions; do not create a new key to force a retry. `routing.status=charged` means checkout creation, NOT payment or entitlement proof; use verified transaction status/payment events.
4. Receive the webhook
Pay sends one uniform signed webhook to your callback URL for each status change. Verify `X-Pay-Signature-V2` (the v2 recipe with info `efolusi-pay/v2/outbound` and prefix `v2.outbound.`, or `verifyPayWebhook` from `@efolusi/pay-sdk`), then reply `200` quickly.
Signature guide
Every request is signed (HMAC v2) so it cannot be replayed. Derive the request key from `webhook_secret`:
```
key = HKDF-SHA256(webhook_secret, empty salt, info "efolusi-pay/v2/inbound", 32 bytes)
```
Build the signing string:
```
v2.inbound.<X-Timestamp>.<METHOD>.<path>.<rawBody>
```
then send `X-Signature-Version: 2` and `X-Signature = hex( HMAC-SHA256(key, signing string) )`. Easiest: use `@efolusi/pay-sdk`. The server rejects a wrong signature (`401`) or one outside the time-skew window. `METHOD` upper-case; `path` without query; `rawBody` the exact bytes sent.
Signing example
X-Product-Id: prod_demo
X-Timestamp: 1700000000
X-Signature-Version: 2
Signing string: v2.inbound.1700000000.POST./v1/charges.{"amount":10000,"currency":"IDR"}
X-Signature: 18402d0aab33bfb67d4ba32f6e2c1770cd5e1b608dd9d13f35c74e507ae4272aimport { createHmac, hkdfSync } from 'node:crypto';
const ts = String(Math.floor(Date.now() / 1000));
const key = Buffer.from(hkdfSync('sha256', webhookSecret, Buffer.alloc(0), 'efolusi-pay/v2/inbound', 32));
const signingString = `v2.inbound.${ts}.${'POST'}.${'/v1/charges'}.${body}`;
const sig = createHmac('sha256', key).update(signingString).digest('hex');
// headers: X-Product-Id, X-Timestamp: ts, X-Signature-Version: 2, X-Signature: sig
// Or use @efolusi/pay-sdk (PayClient), which signs v2 for you.Sandbox (test mode)
Use your test credentials to hit the sandbox at `https://dev-pay-api.efolusi.com`. Test-mode transactions are isolated from live data and move no real funds. Headers and the signature recipe are identical to production. Full reference in the OpenAPI spec: [/openapi.json](/openapi.json).