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:  18402d0aab33bfb67d4ba32f6e2c1770cd5e1b608dd9d13f35c74e507ae4272a
import { 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).

API reference (OpenAPI)