Dokumentasi API

1. Daftar jadi mitra dan salin API key (ditampilkan sekali).
2. Atur Callback URL website Anda di dashboard.
3. Panggil endpoint POST /api/v1/transactions dari server Anda.
4. Tampilkan QRIS ke pelanggan, lalu tunggu callback / cek status.

Kirim API key sebagai Bearer token di header setiap permintaan API:

Authorization: Bearer pg_xxxx_yyyy

API key hanya ditampilkan sekali. Jika hilang, lakukan rotate di dashboard (key lama langsung non-aktif).

POST /api/v1/transactions

curl -X POST {BASE_URL}/api/v1/transactions \
  -H "Authorization: Bearer pg_xxxx_yyyy" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 15000,
    "order_id": "INV-1001",
    "customer_name": "Budi",
    "customer_email": "budi@mail.com",
    "callback_url": "https://tokosaya.com/pg-callback",
    "payment_method": "SP"
  }'

Respons:

{
  "success": true,
  "data": {
    "transaction_id": "clx...",
    "order_id": "INV-1001",
    "amount": 15000,
    "status": "PENDING",
    "method": "QRIS",
    "qr_string": "00020101...",
    "payment_url": "https://...",
    "checkout_url": "{BASE_URL}/pay/clx...",
    "expired_at": "2026-..."
  }
}

Tampilkan qr_string sebagai QR code, atau arahkan pelanggan ke checkout_url (halaman pembayaran siap pakai dari kami).

Idempotency: kirim header Idempotency-Key: <unik> agar permintaan yang terulang mengembalikan transaksi yang sama (bukan membuat baru).
Pilih metode di checkout: set "select_on_checkout": true agar pelanggan memilih metode (QRIS/VA/e-wallet) langsung di checkout_url.

GET /api/v1/transactions/:id — fallback bila callback terlambat. Jika masih PENDING, kami cek langsung ke Duitku.

curl {BASE_URL}/api/v1/transactions/clx... \
  -H "Authorization: Bearer pg_xxxx_yyyy"

Saat status berubah jadi PAID, kami mengirim POST ke callback URL Anda dengan body JSON dan header tanda tangan X-PG-Signature = HMAC-SHA256(callbackSecret, rawBody). Verifikasi dari raw body sebelum dipercaya.

// Node.js — verifikasi callback
import crypto from "node:crypto";
const expected = crypto.createHmac("sha256", CALLBACK_SECRET)
  .update(rawBody, "utf8").digest("hex");
if (req.headers["x-pg-signature"] !== expected) reject();

Contoh body callback:

{
  "transaction_id": "clx...",
  "order_id": "INV-1001",
  "amount": 15000,
  "status": "PAID",
  "reference": "D1234",
  "paid_at": "2026-..."
}

Default QRIS. Daftar metode yang tersedia untuk nominal tertentu bisa diambil via:

GET {BASE_URL}/api/v1/payment-methods?amount=15000
Authorization: Bearer pg_xxxx_yyyy

Gunakan kode pada field payment_method saat membuat transaksi. Kode QRIS dapat berbeda per akun — konfirmasikan lewat endpoint ini.

Semua error mengikuti bentuk:

{ "success": false, "error": { "code": "VALIDATION_ERROR", "message": "..." } }

Kode umum: UNAUTHORIZED (401), MERCHANT_INACTIVE (403), VALIDATION_ERROR (422), CONFLICT (409), RATE_LIMITED (429), UPSTREAM_ERROR (502).