Integrasi pembayaran,
lebih jelas dari awal.

Dokumentasi ini menjelaskan Public API V1 PembayaranKu untuk membuat invoice QRIS dinamis, membaca status invoice, dan menerima event melalui webhook.

Yang dapat dilakukan

• Membuat invoice Live memakai QRIS merchant dan generator invoice yang tersedia.
• Menguji alur API memakai kredensial Sandbox terpisah.
• Membaca invoice dengan ID milik merchant yang terautentikasi.
• Menerima status invoice melalui webhook bertanda tangan HMAC-SHA256.

1. Buka Dashboard → Developer dan pilih lingkungan Sandbox.
2. Buat API key Sandbox dan simpan secret yang ditampilkan satu kali.
3. Panggil endpoint pembuatan invoice dari backend Anda. Jangan menaruh API key di browser atau aplikasi mobile.
4. Uji perubahan status melalui endpoint simulasi Sandbox.
5. Atur URL webhook Sandbox, lalu validasi signature dan deduplikasi event.

curl -X POST https://www.pembayaranku.com/api/v1/invoices \
  -H "Authorization: Bearer $PEMBAYARANKU_TEST_KEY" \
  -H "Idempotency-Key: order-2026-001" \
  -H "Content-Type: application/json" \
  -d '{"amount":50000,"description":"Pesanan 2026-001","expires_at":"2026-11-08T15:00:00+07:00"}'

Gunakan nilai payment_url untuk membuka halaman invoice. Invoice Sandbox tidak menampilkan QRIS dan tidak menerima pembayaran uang sungguhan.

Setiap endpoint API V1 membutuhkan API key di header Authorization. Buat atau cabut key di Dashboard → Developer. Nilai penuh hanya ditampilkan sekali; server menyimpan hash key.

Authorization: Bearer pk_test_<secret>
Content-Type: application/json
Accept: application/json

• Simpan key di secret manager atau environment variable server.
• Jangan mengirim key ke frontend, aplikasi Android, log, atau repositori.
• Gunakan key terpisah untuk Sandbox dan Live.
• Cabut dan ganti key bila diduga bocor.

Lingkungan ditentukan oleh API key, bukan dari body. Request Live menggunakan QRIS merchant aktif. Request Sandbox membuat invoice tanpa QRIS. Jangan sertakan qris_account_id pada Sandbox.

Body JSON

{
  "amount": 50000,
  "description": "Pesanan 2026-001",
  "expires_at": "2026-11-08T15:00:00+07:00",
  "customer": { "name": "Pelanggan" }
}

Tambahkan header Idempotency-Key yang stabil untuk satu operasi pembuatan invoice. Response Live menyertakan qris_payload jika invoice pending dan QRIS siap; response Sandbox selalu mengembalikan qris_payload: null.

Path memakai UUID invoice yang dikembalikan saat pembuatan. Invoice tidak ditemukan atau berada di lingkungan lain menghasilkan 404.

curl https://www.pembayaranku.com/api/v1/invoices/00000000-0000-4000-8000-000000000001 \
  -H "Authorization: Bearer $PEMBAYARANKU_TEST_KEY"

{
  "data": {
    "id": "00000000-0000-4000-8000-000000000001",
    "invoice_number": "PK-20261108-0123456789ABCDEF",
    "environment": "sandbox",
    "status": "pending",
    "base_amount": 50000,
    "total_amount": 50000,
    "currency": "IDR",
    "expires_at": "2026-11-08T08:00:00Z",
    "paid_at": null,
    "payment_confirmation": null,
    "matching_status": "not_started"
  }
}

Detail response tidak menyertakan data kontak pelanggan. Status pending yang telah melewati expires_at diproses sebagai kedaluwarsa.

Response sukses dibungkus dalam data; error dibungkus dalam error. Semua jumlah adalah integer IDR.

Status invoice

Invoice Live dapat berstatus pending, matched, paid, expired, atau cancelled. matched menunggu verifikasi Finance. Sandbox juga menyediakan failed untuk pengujian simulasi.

Format error: { "error": { "code": "…", "message": "…" } }. Pesan spesifik dapat berbeda sesuai tahap validasi.

Idempotency-Key wajib pada POST /api/v1/invoices, panjang 1–200 karakter. Gunakan ID pesanan yang unik dan tetap sama saat mengulang operasi yang sama.

Idempotency-Key: order-2026-001

Key yang sama dan parameter yang sama mengembalikan invoice yang sudah dibuat. Memakai key yang sama dengan parameter berbeda menghasilkan konflik. Lingkungan Live dan Sandbox memiliki namespace idempotency masing-masing.

Batas default adalah 120 request per menit untuk setiap API key. Respons 429 menyertakan Retry-After; hormati nilai tersebut sebelum mengirim ulang.

1. Buka Dashboard → Developer dan pilih tab Live atau Sandbox.
2. Simpan URL HTTPS publik untuk lingkungan tersebut.
3. Salin signing secret saat ditampilkan; secret hanya terlihat satu kali.
4. Validasi signature pada body mentah sebelum memproses event.
5. Balas HTTP 2xx setelah event tersimpan aman di sistem Anda.

URL dan secret webhook Sandbox tersimpan terpisah dari Live. Menyimpan ulang URL membuat secret baru. Event uji dari dashboard adalah webhook.test, bukan pembayaran.

{
  "id": "<event-id>",
  "type": "invoice.status_changed",
  "created_at": "2026-11-08T08:00:00Z",
  "data": {
    "environment": "sandbox",
    "invoice_id": "<invoice-id>",
    "invoice_number": "PK-20261108-0123456789ABCDEF",
    "status": "paid",
    "previous_status": "pending",
    "amount": 50000,
    "currency": "IDR",
    "paid_at": "2026-11-08T08:00:00Z"
  }
}

Payload mencerminkan perubahan yang sudah tercatat. Untuk event Sandbox, data.environment bernilai test; nilai status simulasi bukan pembayaran nyata.

Header pengiriman:

Signature dihitung sebagai HMAC-SHA256 dari string <timestamp>.<raw request body> menggunakan webhook secret. Gunakan byte body yang diterima sebelum parsing JSON.

import { createHmac, timingSafeEqual } from "node:crypto";

export function verifyWebhook(rawBody, header, secret) {
  const match = /^t=(\d+),v1=([0-9a-f]{64})$/i.exec(header || "");
  if (!match) return false;
  const [, timestamp, receivedHex] = match;
  const expected = createHmac("sha256", secret)
    .update(timestamp + "." + rawBody, "utf8")
    .digest();
  const received = Buffer.from(receivedHex, "hex");
  if (received.length !== expected.length) return false;
  return timingSafeEqual(received, expected);
}

Tambahkan pemeriksaan umur timestamp dengan replay window yang sesuai kebijakan server Anda, lalu deduplikasi berdasarkan event ID.

Status perubahan masuk ke outbox bersama transaksi. Pengiriman awal dicoba setelah perubahan status selesai. Delivery gagal tetap tercatat; retry menggunakan jeda bertahap dengan maksimum 12 percobaan, dan delivery log memuat status HTTP serta alasan gagal.

Pemroses retry terjadwal memeriksa delivery yang sudah jatuh tempo dan lease yang kedaluwarsa. Untuk mengirim ulang delivery yang selesai/gagal, owner atau admin dapat memakai tindakan kirim ulang pada Dashboard → Developer. Gunakan event ID untuk menghindari pemrosesan ganda karena webhook dapat dikirim kembali.

const response = await fetch(
  "https://www.pembayaranku.com/api/v1/invoices",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer " + process.env.PEMBAYARANKU_API_KEY,
      "Content-Type": "application/json",
      "Idempotency-Key": order.id,
    },
    body: JSON.stringify({
      amount: order.total,
      description: "Pesanan " + order.number,
      expires_at: order.paymentDeadline,
    }),
  }
);

const result = await response.json();
if (!response.ok) throw new Error(result.error?.code || "invoice_error");
await saveInvoiceReference(order.id, result.data.id);
return result.data.payment_url;

Simpan hubungan ID order dan ID invoice di backend Anda. Gunakan webhook untuk menerima perubahan status dan GET invoice untuk memeriksa ulang jika diperlukan. Jangan menandai pesanan lunas hanya karena request create invoice berhasil.

curl -X POST https://www.pembayaranku.com/api/v1/sandbox/invoices/<invoice_id>/simulate \
  -H "Authorization: Bearer $PEMBAYARANKU_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status":"paid"}'

Ganti status dengan paid, failed, expired, atau cancelled. Hanya invoice Sandbox pending yang dapat disimulasikan. Perubahan dicatat dan mengantrekan webhook Sandbox bila URL webhook aktif.

{
  "data": {
    "invoice_id": "<invoice_id>",
    "environment": "sandbox",
    "status": "paid",
    "simulation_only": true
  }
}

Sandbox opsional untuk menguji integrasi. Merchant dapat menggunakan Live setelah registrasi tanpa harus menyelesaikan pengujian Sandbox atau memperoleh persetujuan Admin rutin.

• Jika diperlukan, integrasi dapat diuji lebih dulu dengan key pk_test_; langkah ini opsional.
• API key Live hanya berada pada backend dan dapat dicabut dari dashboard.
• QRIS merchant Live aktif dan sesuai untuk pembuatan invoice.
• Setiap pembuatan invoice memakai Idempotency-Key stabil.
• Endpoint webhook Live memakai HTTPS dan secret Live tersimpan aman.
• Signature diverifikasi terhadap body mentah; event ID dideduplikasi.
• Handler webhook menyimpan event secara durable sebelum merespons 2xx.
• Alur bisnis tidak mengartikan notifikasi matching sebagai settlement bank/PSP resmi.
• Tim dapat melihat delivery log dan melakukan recovery dari Dashboard → Developer.