Panduan · Terbit
Integrasi payment gateway di PocketBase: route kustom di pb_hooks yang memegang kunci API, webhook yang diverifikasi dengan $security.hs256, dan satu transaksi yang mencatat event sekaligus menandai pesanan lunas
Aplikasi yang backend-nya PocketBase tidak butuh server kedua untuk menerima pembayaran. Dua route kustom di pb_hooks sudah cukup: satu membuat permintaan pembayaran untuk pengguna yang login, satu menerima webhook. Kunci API tinggal di environment proses PocketBase, dan status lunas hanya ditulis oleh route webhook setelah tanda tangannya terbukti. Tiga hal khas PocketBase menentukan hasilnya: SDK JavaScript resmi tidak berjalan di JSVM-nya sehingga panggilan dan verifikasi ditulis dengan $http.send dan $security.hs256, setiap handler berjalan di konteks terisolasi sehingga kode bersama harus lewat require, dan API rules collection harus menutup semua penulisan dari klien. Tanpa yang terakhir, pengguna yang login bisa menandai pesanannya sendiri lunas dengan satu PATCH dari konsol peramban.
Semua kode di halaman ini dijalankan dengan PocketBase v0.40.6 melawan tiruan API Kasera Pay: pembuatan pembayaran, penolakan pengguna lain, tanda tangan salah dan kedaluwarsa, pengiriman ulang, urutan antar percobaan, dan realtime. Kalau backend proyeknya Supabase, pola yang setara ada di panduan integrasi Supabase, dan untuk Firebase di panduan integrasi Firebase.
Alurnya, sebelum menulis kode
Aplikasi memanggil /api/bayar/{id}. Route itu membaca total dari collection orders, memanggil POST /v1/transactions, lalu mengembalikan checkout_url. Pembeli membayar dengan QRIS atau Virtual Account tujuh bank. Kasera Pay mengirim payment.paid bertanda tangan ke /api/kasera/webhook, route itu mencatat event dan menandai pesanan lunas dalam satu transaksi, dan halaman pesanan yang berlangganan realtime langsung berubah. Kepulangan pembeli ke return_url tidak dianggap bukti apa pun. Status permintaan pembayaran adalah pending, succeeded, dan expired; payment.paid adalah nama event-nya, bukan status.
pocketbase # binary
pb_migrations/
1763460000_kasera.js # collection orders dan kasera_events
pb_hooks/
kasera.pb.js # dua route: bayar dan webhook
kasera.js # modul bersama (bukan .pb.js, jadi tidak dimuat sebagai hook)
# Kunci dibaca dari environment proses, tidak pernah ditulis di file hook.
KASERA_PAY_KEY=kp_test_... KASERA_PAY_WEBHOOK_SECRET=whsec_... ./pocketbase serve1. Collection dan API rules lewat migrasi
// pb_migrations/1763460000_kasera.js
migrate((app) => {
const users = app.findCollectionByNameOrId("users");
const orders = new Collection({
type: "base",
name: "orders",
// Pembeli hanya melihat pesanannya sendiri.
listRule: "user = @request.auth.id",
viewRule: "user = @request.auth.id",
// null = hanya superuser dan kode server. Klien tidak bisa menulis apa pun.
createRule: null,
updateRule: null,
deleteRule: null,
fields: [
{ name: "user", type: "relation", required: true, collectionId: users.id, maxSelect: 1 },
{ name: "total", type: "number", required: true, onlyInt: true, min: 1 }, // rupiah utuh
{ name: "status", type: "select", required: true, maxSelect: 1,
values: ["BARU", "MENUNGGU", "LUNAS", "KEDALUWARSA"] },
{ name: "attempt", type: "number", onlyInt: true, min: 0 },
{ name: "payment_request_id", type: "text" },
{ name: "paid_at", type: "date" },
],
});
app.save(orders);
const events = new Collection({
type: "base",
name: "kasera_events",
listRule: null, viewRule: null, createRule: null, updateRule: null, deleteRule: null,
fields: [
{ name: "event_id", type: "text", required: true },
{ name: "type", type: "text", required: true },
],
indexes: ["CREATE UNIQUE INDEX idx_kasera_events_event_id ON kasera_events (event_id)"],
});
app.save(events);
}, (app) => {
app.delete(app.findCollectionByNameOrId("kasera_events"));
app.delete(app.findCollectionByNameOrId("orders"));
});Rule null berarti hanya superuser dan kode server yang boleh, bukan “tanpa batasan”; string kosong justru berarti semua orang. Dengan migrasi ini, PATCH dari pengguna biasa ke orders dijawab 403, dan pengguna lain yang membuka pesanan itu mendapat 404. Baris pesanan, termasuk total-nya, dibuat oleh kode server yang membaca harga dari collection produk. Kalau klien boleh membuat pesanan dengan total sendiri, pembeli yang sedikit paham bisa membuat pesanan Rp 1.000 untuk barang Rp 500.000 dan membayarnya dengan sah.
Menulis collection sebagai migrasi, bukan klik di dashboard /_/, membuat rule yang sama ikut ke server produksi. Indeks unik pada event_id adalah pengaman terakhir untuk dedupe, bukan mekanisme utamanya; alasannya ada di langkah 4.
2. Modul bersama dan jebakan isolasi handler
// pb_hooks/kasera.js
// Modul bersama. Handler PocketBase berjalan di konteks terisolasi,
// jadi konstanta di luar handler tidak terlihat; semuanya lewat require.
const BASE = "https://pay.kasera.id";
const TOLERANCE = 300; // detik, sama dengan dokumentasi webhook
function verify(raw, header, secret) {
if (!header || !secret) return false;
const parts = header.split(",");
if (parts[0].indexOf("t=") !== 0) return false;
const t = Number(parts[0].slice(2));
if (!isFinite(t) || Math.abs(Date.now() / 1000 - t) > TOLERANCE) return false;
const expected = $security.hs256(t + "." + raw, secret); // hex
for (let i = 1; i < parts.length; i++) {
if (parts[i].indexOf("v1=") === 0 && $security.equal(parts[i].slice(3), expected)) {
return true; // selama rotasi secret ada dua entri v1
}
}
return false;
}
module.exports = { BASE, verify };PocketBase menyerialisasi setiap handler dan menjalankannya di konteks sendiri. Fungsi verify yang ditulis di bagian atas kasera.pb.js tidak terlihat dari dalam routerAdd, dan galatnya baru muncul saat webhook pertama tiba. Karena itu kode bersama ditaruh di file tanpa akhiran .pb.js dan dimuat dengan require(`${__hooks}/kasera.js`) di dalam handler.
$security.hs256 mengembalikan HMAC-SHA256 dalam heksadesimal huruf kecil, bentuk yang sama dengan entri v1 di header. Perbandingannya memakai $security.equal, yang waktunya konstan. Toleransi 300 detik mengikuti referensi webhook, dan perulangan atas semua entri menjaga pengiriman tetap lolos selama 24 jam masa rotasi signing secret, saat header membawa dua entri v1.
3. Route yang membuat permintaan pembayaran
// pb_hooks/kasera.pb.js (bagian pertama)
routerAdd("POST", "/api/bayar/{id}", (e) => {
const k = require(`${__hooks}/kasera.js`);
let order;
try {
order = $app.findRecordById("orders", e.request.pathValue("id"));
} catch (_) {
return e.json(404, { error: "not_found" });
}
// Route kustom tidak menjalankan viewRule, jadi kepemilikan diperiksa di sini.
if (order.get("user") !== e.auth.id) return e.json(404, { error: "not_found" });
if (order.get("status") === "LUNAS") return e.json(409, { error: "sudah_lunas" });
let res;
try {
res = $http.send({
url: k.BASE + "/v1/transactions",
method: "POST",
timeout: 20,
headers: {
"Authorization": "Bearer " + $os.getenv("KASERA_PAY_KEY"),
"Content-Type": "application/json",
// Nomor percobaan naik saat permintaan sebelumnya kedaluwarsa.
"Idempotency-Key": "order-" + order.id + "-" + order.getInt("attempt"),
},
body: JSON.stringify({
amount: order.getInt("total"), // dibaca dari database, bukan dari klien
description: "Pesanan " + order.id,
external_id: order.id,
return_url: "https://toko.example/pesanan/" + order.id,
checkout: {},
}),
});
} catch (err) {
return e.json(502, { error: "kasera_tidak_terjangkau" });
}
if (res.statusCode !== 200 && res.statusCode !== 201) {
const code = res.json && res.json.error ? res.json.error.code : "kasera_error";
return e.json(502, { error: code });
}
// Tulis ulang dari database supaya status LUNAS yang baru masuk tidak tertimpa.
$app.runInTransaction((txApp) => {
const fresh = txApp.findRecordById("orders", order.id);
if (fresh.get("status") === "LUNAS") return;
fresh.set("payment_request_id", res.json.id);
fresh.set("status", "MENUNGGU");
txApp.save(fresh);
});
return e.json(200, { checkoutUrl: res.json.checkout_url });
}, $apis.requireAuth("users"));Pesanan di atas Rp 1.000.000. Sejak 26 Oktober 2026, create lewat API di atas Rp 1.000.000 wajib membawa description minimal 10 karakter, customer.name, customer.phone atau customer.email, delivery_date (format YYYY-MM-DD, WIB), dan delivery_terms_shown: true. Tanpa itu create ditolak 422. Kunci tes tidak memeriksa aturan ini, jadi contoh di atas lolos di mode tes dan baru ditolak di live. Kirim field itu setiap kali total pesanan melewati Rp 1.000.000. Contoh body lengkap dan arti delivery_terms_shown ada di panduan menerima pembayaran di atas Rp 1 juta.
$app.findRecordById melewati API rules, jadi kepemilikan pesanan wajib diperiksa sendiri terhadap e.auth.id. Tanpa baris itu, siapa pun yang login dan menebak id pesanan orang lain bisa memancing tautan pembayarannya. Jawabannya 404, bukan 403, supaya keberadaan pesanan tidak bocor.
Kunci idempotensinya dibentuk dari id pesanan dan nomor percobaan. Ketukan ganda pada tombol bayar mengirim key yang sama dan mendapat permintaan pembayaran yang sama. Id saja tidak cukup: key yang sama selalu mengembalikan permintaan asli, termasuk yang sudah kedaluwarsa setelah 60 menit, sehingga pembeli yang kembali besok tidak akan pernah bisa membayar. Nomor percobaan dinaikkan oleh route webhook saat payment.expired tiba. Hanya header Idempotency-Key yang mencegah duplikat; external_id sekadar label. Latar belakangnya ada di idempotency untuk pembayaran.
$http.send melempar galat saat jaringan putus atau waktu habis, jadi panggilannya dibungkus try. Penulisan MENUNGGU membaca ulang pesanan di dalam transaksi, karena webhook pembayaran dari percobaan sebelumnya bisa tiba di antara panggilan API dan penulisan itu.
4. Route webhook
// pb_hooks/kasera.pb.js (lanjutan file yang sama)
routerAdd("POST", "/api/kasera/webhook", (e) => {
const k = require(`${__hooks}/kasera.js`);
const raw = toString(e.request.body); // byte mentah, dibaca sekali
const header = e.request.header.get("Kasera-Signature-V1");
if (!k.verify(raw, header, $os.getenv("KASERA_PAY_WEBHOOK_SECRET"))) {
return e.string(400, "bad signature");
}
const event = JSON.parse(raw);
const data = event.data || {};
if (!data.external_id) return e.string(200, "ignored");
try {
$app.runInTransaction((txApp) => {
// Transaksi tulis PocketBase berjalan satu per satu, jadi cek lalu
// sisip di sini aman. Indeks unik tetap jadi pengaman terakhir.
const seen = txApp.countRecords("kasera_events", $dbx.hashExp({ event_id: event.id }));
if (seen > 0) return; // pengiriman ulang event yang sama
const ev = new Record(txApp.findCollectionByNameOrId("kasera_events"));
ev.set("event_id", event.id);
ev.set("type", event.type);
txApp.save(ev);
let order;
try {
order = txApp.findRecordById("orders", data.external_id);
} catch (_) {
return; // bukan pesanan dari aplikasi ini
}
if (event.type === "payment.paid") {
// Uang yang masuk selalu menang, termasuk dari percobaan lama.
order.set("status", "LUNAS");
order.set("paid_at", data.paid_at || new Date().toISOString());
txApp.save(order);
} else if (event.type === "payment.expired" || event.type === "payment.failed") {
if (order.get("status") !== "LUNAS" &&
order.get("payment_request_id") === data.payment_request_id) {
order.set("status", "KEDALUWARSA");
order.set("attempt", order.getInt("attempt") + 1);
txApp.save(order);
}
}
});
} catch (err) {
console.error("kasera webhook", err);
return e.string(500, "retry"); // Kasera Pay mengulang
}
return e.string(200, "ok");
});Body dibaca sekali dengan toString(e.request.body), dan string itulah yang diverifikasi. Memakai e.requestInfo().body lalu menyusunnya ulang dengan JSON.stringify menghasilkan isi yang sama dengan byte berbeda, dan setiap pengiriman sah ditolak 400. Route ini sengaja tanpa $apis.requireAuth: Kasera Pay tidak membawa token PocketBase, dan pengamannya adalah tanda tangan.
Dedupe dikerjakan oleh countRecords di dalam runInTransaction. PocketBase menjalankan penulisan lewat satu koneksi, jadi transaksi kedua menunggu yang pertama selesai dan melihat event yang sudah tercatat. Mengandalkan indeks unik saja tampak cukup, tetapi gagal dengan cara yang lebih buruk: event yang dikirim ulang memicu pelanggaran indeks, transaksi gagal, route menjawab 500, dan Kasera Pay mengulang pengiriman yang akan selalu gagal. Setelah 10 kegagalan berturut-turut selama minimal satu jam, endpoint itu dijeda dan event lain ikut tertahan.
Pemeriksaan payment_request_id pada cabang kedaluwarsa menjaga urutan antar percobaan: tanpa itu, payment.expired dari percobaan pertama yang terlambat tiba bisa menandai kedaluwarsa pesanan yang sedang menunggu pembayaran percobaan kedua. payment.paid tidak diperiksa begitu, karena uang yang sudah masuk selalu menang, termasuk setelah expired atau failed. Event selain payment.paid hanya dikirim ke endpoint yang mencentangnya di dashboard, menu Developer. paid_at dikirim dengan zona +07:00 dan disimpan PocketBase dalam UTC, jadi 17:04:58+07:00 tampil sebagai 10:04:58.000Z.
5. Sisi aplikasi
import PocketBase from "pocketbase";
const pb = new PocketBase("https://api.toko.example");
// Tombol bayar. Token login pengguna ikut otomatis.
const { checkoutUrl } = await pb.send("/api/bayar/" + orderId, { method: "POST" });
window.location.assign(checkoutUrl);
// Halaman pesanan: berubah saat webhook menulis status.
pb.collection("orders").subscribe(orderId, (e) => {
if (e.record.status === "LUNAS") tampilkanLunas();
});pb.send membawa token login pengguna secara otomatis. Langganan realtime tunduk pada viewRule yang sama: saat diuji, pemilik pesanan menerima update dengan status LUNAS dan pengguna lain yang berlangganan id yang sama tidak menerima apa pun. Di Flutter, paket pocketbase untuk Dart punya send dan subscribe yang setara.
6. Menguji sebelum kunci live dipasang
Dengan kunci kp_test_, halaman checkout menampilkan tombol simulasi, dan hasil berhasil maupun kedaluwarsa bisa dipicu lewat endpoint simulasi di dokumentasi mode tes. PocketBase yang berjalan di laptop butuh terowongan supaya webhook bisa masuk; caranya ada di webhook di localhost dan mode tes. Lima hal yang layak dicoba: ketukan ganda menghasilkan satu permintaan pembayaran, event yang dikirim ulang tidak mengubah apa pun, simulasi kedaluwarsa lalu bayar ulang menghasilkan permintaan baru, PATCH status dari klien dijawab 403, dan transaksi yang sengaja dibuat gagal menghasilkan 500, bukan 200. Saat beralih ke live, ganti KASERA_PAY_KEY dan KASERA_PAY_WEBHOOK_SECRET bersamaan: webhook mode tes dan live adalah endpoint terpisah dengan secret masing-masing.
Pertanyaan yang sering muncul
Kenapa tidak memakai SDK JavaScript resmi kasera-pay di pb_hooks?
Karena pb_hooks tidak menjalankan Node. Hook PocketBase berjalan di JSVM berbasis goja: tanpa fetch, tanpa Web Crypto, tanpa async, dan hanya modul CommonJS. SDK JavaScript resmi ditujukan untuk Node 20.19+, Deno, Bun, dan edge runtime. Yang dibutuhkan pun hanya dua hal, panggilan HTTP dan HMAC-SHA256, dan PocketBase sudah menyediakan keduanya sebagai $http.send dan $security.hs256. Kalau PocketBase dipakai sebagai framework Go, panggilan yang sama bisa ditulis dengan net/http dan crypto/hmac.
Bisakah status pesanan diubah dari hook onRecordUpdateRequest saja, tanpa route webhook sendiri?
Tidak. Kasera Pay tidak login ke PocketBase, jadi pengirimannya tidak bisa melewati API collection yang updateRule-nya null, dan membuka updateRule untuk umum justru membuat siapa pun bisa menandai pesanan lunas. Route kustom tanpa requireAuth yang memverifikasi Kasera-Signature-V1 adalah satu-satunya pintu yang tepat: aksesnya publik, tetapi hanya pengiriman bertanda tangan sah yang bisa menulis.
Apakah SQLite PocketBase aman untuk 30 pengiriman event yang sama sekaligus?
Ya, dengan kode di atas. PocketBase menjalankan semua penulisan lewat satu koneksi, jadi runInTransaction berjalan satu per satu, dan pemeriksaan countRecords di dalamnya melihat hasil transaksi sebelumnya. Saat diuji dengan 30 pengiriman paralel untuk satu event, hasilnya 30 jawaban 200, satu baris kasera_events, dan nomor percobaan naik tepat satu kali. Kalau pemeriksaan itu dihapus, 29 dari 30 pengiriman berakhir 500 karena ditolak indeks unik, dan setiap pengiriman ulangnya akan ditolak lagi.
Di mana PocketBase sebaiknya dijalankan supaya webhook bisa masuk?
Di server dengan alamat publik dan HTTPS, karena URL webhook Kasera Pay wajib https dan mengarah ke alamat publik. PocketBase bisa mengurus sertifikatnya sendiri saat dijalankan dengan domain sebagai argumen serve, atau diletakkan di belakang reverse proxy. URL yang didaftarkan di dashboard berbentuk https://api.toko.example/api/kasera/webhook.