Dokumentasi Developer
Onboarding produk baru menerima pembayaran dalam kurang dari 30 menit: daftar, tanda tangani request, panggil Charge API, terima webhook.
Quickstart (< 30 menit)
1. Daftarkan produk
Belum ada dashboard merchant self-serve: produk masih didaftarkan tim kami lewat Admin API. Mulai dari [halaman Mulai](/daftar): masuk dengan akun Efolusi, lalu hubungi tim dengan nama produk dan callback URL (harus HTTPS). Kamu menerima product_id, api_key, dan webhook_secret (test + live) lewat jalur aman.
2. Tanda tangani request
Setiap panggilan API ditandatangani HMAC (lihat panduan Signature di bawah). Kirim header `X-Product-Id`, `X-Timestamp`, dan `X-Signature`.
3. Buat charge
Panggil `POST /v1/charges` dengan header `Idempotency-Key`. Hosted checkout tersedia di `routing.redirectUrl` bila provider mengembalikannya. Jika respons hilang, ulangi dengan key yang sama atau panggil `GET /v1/charges/:id` memakai produk dan mode test/live yang sama. Hasil routing yang sudah tersimpan dikembalikan tanpa membuat charge baru. Hasil bisa belum tersedia saat routing berlangsung atau untuk transaksi lama; jangan membuat key baru untuk memaksa retry. `routing.status=charged` berarti checkout dibuat, BUKAN bukti pembayaran atau entitlement; gunakan status transaksi/event pembayaran yang terverifikasi.
4. Terima webhook
Pay mengirim satu webhook seragam ber-signature ke callback URL-mu untuk tiap perubahan status. Verifikasi `X-Pay-Signature-V2` (resep v2 dengan info `efolusi-pay/v2/outbound` dan awalan `v2.outbound.`, atau `verifyPayWebhook` dari `@efolusi/pay-sdk`), lalu balas `200` cepat.
Panduan Signature
Semua request ditandatangani (HMAC v2) agar tak bisa di-replay. Turunkan kunci request dari `webhook_secret`:
```
key = HKDF-SHA256(webhook_secret, salt kosong, info "efolusi-pay/v2/inbound", 32 byte)
```
Bangun signing string:
```
v2.inbound.<X-Timestamp>.<METHOD>.<path>.<rawBody>
```
lalu kirim `X-Signature-Version: 2` dan `X-Signature = hex( HMAC-SHA256(key, signing string) )`. Paling mudah: pakai `@efolusi/pay-sdk`. Server menolak signature yang salah (`401`) atau di luar jendela waktu (skew). `METHOD` huruf besar; `path` tanpa query; `rawBody` byte mentah persis seperti dikirim.
Contoh signing
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)
Gunakan kredensial test untuk memakai sandbox di `https://dev-pay-api.efolusi.com`. Transaksi mode test terisolasi dari data live dan tidak memindahkan dana nyata. Header dan resep signature identik dengan production. Lihat referensi lengkap di OpenAPI: [/openapi.json](/openapi.json).