API Pembayaran Poketo
Buat tagihan dari server Anda, arahkan pembeli ke halaman bayar Poketo (QRIS, Virtual Account, PayLater, dan kartu debit), lalu terima webhook saat tagihan lunas. Uangnya masuk ke saldo Rupiah akun Poketo Anda dan ditarik dari dashboard.
https://poketo.id/api/v1. JSON lewat HTTPS. Nominal dalam Rupiah bulat (tanpa desimal), waktu dalam ISO 8601 UTC. Pesan error berbahasa Indonesia; kode error berbahasa Inggris dan stabil.Memulai
- Masuk ke dashboard Poketo, buka Merchant, lalu buat merchant (di API disebut proyek, id
proj_…). API key dan webhook ada di Dashboard → Merchant → Pengaturan API. - Buat API key sandbox (
sk_test_…). Key hanya ditampilkan sekali; simpan di server Anda. - Atur URL webhook proyek dan simpan rahasia penandatanganannya (
whsec_…). - Buat tagihan dengan
POST /v1/invoices, arahkan pembeli kepaymentUrl, dan coba alurnya dengan tombol simulasi di halaman bayar sandbox atauPOST /v1/invoices/:id/simulate. - Lengkapi info merchant (website, kategori, deskripsi) dan selesaikan verifikasi identitas, lalu buat API key live (
sk_live_…) dan ganti key di server Anda. Sebelum verifikasi, total penerimaan live dibatasi Rp 1.000.000.
SDK Node.js
Paket resmi poketo-node membungkus semua endpoint di bawah dan verifikasi webhook. Tanpa dependensi, butuh Node.js 18+, dan dilengkapi tipe TypeScript.
npm install poketo-nodeconst Poketo = require('poketo-node');
const poketo = new Poketo(process.env.POKETO_SECRET_KEY); // sk_test_… or sk_live_…
const invoice = await poketo.invoices.create({
referenceId: order.id,
amount: 50000,
title: `Pesanan #${order.number}`,
customer: { name: order.customerName, email: order.customerEmail },
metadata: { orderId: order.id },
redirectUrl: `https://toko.example/pesanan/${order.id}/selesai`,
});
// send the buyer to invoice.paymentUrl
await poketo.paymentMethods.list({ amount: 250000 });
await poketo.invoices.retrieve(order.id); // Poketo id or your referenceId
await poketo.invoices.list({ status: 'paid', limit: 20 });
await poketo.invoices.cancel(order.id);
await poketo.invoices.simulate(order.id, { result: 'paid' }); // sandbox keys only
await poketo.invoices.checkStatus(order.id); // ask DOKU again if an update was missed
const link = await poketo.paymentLinks.create({ title: 'Traktir kopi', minAmount: 10000 });
// share link.url; payments: poketo.invoices.list({ paymentLinkId: link.id })invoices.createotomatis mengirimIdempotency-Key, jadi request yang timeout dicoba ulang tanpa membuat tagihan ganda. Kirim kunci sendiri dengancreate(params, { idempotencyKey }).- Request baca dan create dicoba ulang sampai 2 kali untuk
429(mengikutiRetry-After),5xx, dan error jaringan.canceldansimulatetidak pernah dicoba ulang. Atur dengan opsimaxRetriesdantimeout. - Error API dilempar sebagai
PoketoErrordenganstatus,code, danretryAfter.
const { PoketoError } = require('poketo-node');
try {
await poketo.invoices.cancel('ORDER-2026-000123');
} catch (err) {
if (err instanceof PoketoError && err.code === 'invoice_not_pending') {
// already paid or expired
}
}Verifikasi webhook cukup satu baris. Lihat bagian Webhook untuk isi event dan aturan percobaan ulang.
app.post('/webhooks/poketo', express.raw({ type: 'application/json' }), (req, res) => {
let event;
try {
// raw body + header + whsec_… secret; throws on a bad or older-than-5-minutes signature
event = poketo.webhooks.verify(req.body, req.get('Poketo-Signature'), process.env.POKETO_WEBHOOK_SECRET);
} catch (err) {
return res.status(400).send('invalid signature');
}
if (event.type === 'invoice.paid') {
// mark event.data.referenceId as paid; deduplicate on event.id
}
res.sendStatus(200);
});Agen AI (MCP dan llms.txt)
Cara tercepat: salin prompt ini ke Claude Code, Cursor, atau Codex di folder proyek Anda. Agen akan membaca llms.txt lalu memasang tagihan, redirect, dan webhook.
Integrate Poketo payments into this project.
1. Read https://poketo.id/llms.txt first; it describes the whole API.
2. Use a sandbox secret key (sk_test_…) from the POKETO_SECRET_KEY environment variable. Never hard-code keys.
3. Create invoices with POST https://poketo.id/api/v1/invoices (Authorization: Bearer <key>). Send my order id as referenceId and an Idempotency-Key header, then redirect the buyer to the returned paymentUrl.
4. Mark orders paid only from the invoice.paid webhook: verify Poketo-Signature (HMAC-SHA256 over "<t>.<raw body>" with the whsec_ secret), reject timestamps older than 5 minutes, and dedupe by Poketo-Event-Id.
5. Test the whole flow with POST /api/v1/invoices/:id/simulate in sandbox.
6. If you support MCP, the Poketo MCP server is https://poketo.id/api/mcp with the same key.Agen AI seperti Claude, Cursor, atau ChatGPT bisa membuat tagihan dan link pembayaran untuk Anda lewat server MCP Poketo. Agen memakai API key proyek yang sama, jadi aturan, batas, dan pemisahan sandbox/live persis sama dengan API.
https://poketo.id/api/mcp (Streamable HTTP). Autentikasi: header Authorization: Bearer sk_test_…. Mulai dengan key sandbox; dengan key live, agen membuat tagihan sungguhan.claude mcp add --transport http poketo https://poketo.id/api/mcp \
--header "Authorization: Bearer sk_test_..."{
"mcpServers": {
"poketo": {
"type": "http",
"url": "https://poketo.id/api/mcp",
"headers": { "Authorization": "Bearer sk_test_..." }
}
}
}- Tool:
get_payment_methods,create_invoice,list_invoices,get_invoice,check_invoice_status,cancel_invoice,simulate_payment(sandbox),create_payment_link,list_payment_links,get_payment_link,update_payment_link,archive_payment_link. - Tool yang menghapus atau membatalkan ditandai agar klien meminta konfirmasi dulu. Agen tidak bisa menarik dana atau mengubah rekening.
- Untuk asisten coding, seluruh API ringkas dalam satu file: poketo.id/llms.txt.
Autentikasi dan environment
Kirim API key proyek di header Authorization. Key menentukan proyek dan environment-nya.
Authorization: Bearer sk_test_7Hq2… # sandbox
Authorization: Bearer sk_live_Lm9x… # live| Sandbox (`sk_test_`) | Live (`sk_live_`) | |
|---|---|---|
| Uang berpindah | Tidak | Ya |
| Pembayaran | Disimulasikan (tombol di halaman bayar atau endpoint simulate) | QRIS, Virtual Account, PayLater, dan kartu debit lewat DOKU |
| Saldo dan laporan | Tidak terpengaruh | Masuk saldo setelah settlement |
| Webhook | Dikirim seperti biasa, environment: "sandbox" | Dikirim, environment: "live" |
| Syarat | Akun Poketo | Identitas terverifikasi |
Tagihan sandbox dan live terpisah: key sandbox tidak bisa membaca tagihan live, dan sebaliknya. Simpan key hanya di server, jangan di aplikasi frontend atau repositori kode. Key yang bocor bisa dicabut dari dashboard dan langsung berhenti bekerja.
| Endpoint | Batas per key |
|---|---|
GET /v1/payment-methods, GET /v1/invoices, GET /v1/invoices/:id | 120 / menit |
POST /v1/invoices | 60 / menit |
POST /v1/invoices/:id/simulate | 30 / menit |
POST /v1/invoices/:id/cancel | 20 / menit |
POST /v1/invoices/:id/check-status | 30 / menit |
GET /v1/payment-links, GET /v1/payment-links/:id | 120 / menit |
POST, PATCH, DELETE /v1/payment-links | 30 / menit |
GET /v1/memberships…, GET /v1/members/:id | 120 / menit |
POST /v1/memberships/:id/checkout | 60 / menit |
POST, PATCH, DELETE membership dan member lainnya | 30 / menit |
Batas dihitung per API key, per endpoint, dalam jendela tetap 1 menit; key sandbox dan live punya kuota sendiri-sendiri. Lewat batas dibalas 429 too_many_requests dengan header Retry-After (detik sampai jendela berikutnya). Tunggu sesuai header itu sebelum mencoba lagi; SDK melakukannya otomatis.
Metode pembayaran dan biaya
GET /v1/payment-methods?amount= mengembalikan metode yang tersedia, aturan biaya, batas nominal, lama settlement, dan, bila amount dikirim, total yang akan dibayar pembeli per metode. Metode yang dimatikan penjual di dashboard (Merchant → Metode Pembayaran) memiliki enabled: false dan available: false; dengan header Poketo-Account, pengaturan akun tersebut yang dipakai.
curl "https://poketo.id/api/v1/payment-methods?amount=250000" \
-H "Authorization: Bearer $POKETO_KEY"{
"data": [
{
"code": "QRIS", "name": "QRIS", "type": "qris", "feePaidBy": "buyer",
"fee": { "platform": { "percent": 0.3, "min": 200, "max": 1000 }, "gatewayPercent": 0.7, "gatewayFlat": 0, "gatewaySmallTier": { "upTo": 100000, "flat": 1000, "flatFrom": 1000, "from": "2026-10-23T00:00:00+07:00" }, "vatPercentOnGatewayFee": 11 },
"limits": { "min": 10000, "max": 10000000 },
"settlementDays": 1, "settlementDayType": "working", "available": true,
"quote": { "amount": 250000, "platformFee": 750, "gatewayFee": 1964, "totalAmount": 252714 }
},
{
"code": "VA", "name": "Virtual Account", "type": "virtual_account", "feePaidBy": "buyer",
"fee": { "platform": { "percent": 0.3, "min": 200, "max": 1000 }, "gatewayPercent": 0, "gatewayFlat": 4000, "vatPercentOnGatewayFee": 11 },
"limits": { "min": 10000, "max": 50000000 },
"banks": [{ "code": "BRI", "name": "BRI" }, { "code": "BNI", "name": "BNI" }, { "code": "PERMATA", "name": "Permata" }, "…"],
"settlementDays": 1, "settlementDayType": "working", "available": true,
"quote": { "amount": 250000, "platformFee": 750, "gatewayFee": 4440, "totalAmount": 255190 }
},
{
"code": "AKULAKU", "name": "Akulaku PayLater", "type": "paylater", "feePaidBy": "buyer",
"fee": { "platform": { "percent": 0.3, "min": 200, "max": 1000 }, "gatewayPercent": 1.5, "gatewayFlat": 2000, "vatPercentOnGatewayFee": 11 },
"limits": { "min": 10000, "max": null },
"settlementDays": 2, "settlementDayType": "working", "available": true,
"quote": { "amount": 250000, "platformFee": 750, "gatewayFee": 6504, "totalAmount": 257254 }
},
{
"code": "CARD", "name": "Kartu debit Visa/Mastercard", "type": "card", "feePaidBy": "buyer",
"fee": { "platform": { "percent": 0.3, "min": 200, "max": 1000 }, "gatewayPercent": 2.8, "gatewayFlat": 2000, "vatPercentOnGatewayFee": 11 },
"limits": { "min": 10000, "max": null },
"settlementDays": 7, "settlementDayType": "calendar", "available": true,
"quote": { "amount": 250000, "platformFee": 750, "gatewayFee": 10336, "totalAmount": 261086 }
}
]
}Biaya layanan selalu dibayar pembeli. Total = nominal + biaya layanan, sehingga Anda menerima amount secara utuh. Biaya layanan terdiri dari dua bagian: bagian dasar 0,3% dari nominal, minimal Rp 200, maksimal Rp 1.000 (fee.platform; platformFee di quote, fees.platform di tagihan), dan bagian metode yang dihitung dari total, yaitu (gatewayPercent dari total + gatewayFlat) × (1 + vatPercentOnGatewayFee/100) (gatewayFee di quote, fees.gateway di tagihan). Hasilnya: QRIS 0,777% dari total, atau Rp 1.110 bila total sampai Rp 100.000 (gatewaySmallTier), dengan batas Rp 10.000.000 per transaksi (aturan Bank Indonesia); Virtual Account Rp 4.440 untuk 10 bank (banks) dengan batas Rp 50.000.000; PayLater 1,665% + Rp 2.220; kartu debit 3,108% + Rp 2.220. settlementDayType working berarti hari kerja (siap tarik pukul 09.00 WIB), calendar berarti hari kalender.
Buat tagihan
POST /v1/invoices
| Field | Tipe | Keterangan |
|---|---|---|
amount | integer, wajib | Nominal yang Anda terima, minimal 10.000. |
referenceId | string | ID pesanan Anda, 1–64 karakter (huruf, angka, . _ : -). Unik per proyek dan environment. Membuat tagihan dengan referenceId yang sudah ada mengembalikan tagihan pertama (200), bukan tagihan baru. |
title | string | Judul di halaman bayar. Default "Pembayaran". |
description | string | Keterangan tambahan. |
customer | object | { name, email, phone }. email dipakai untuk bukti pembayaran. |
items | array | Maks 50 item { name, quantity, price }. Jumlah quantity × price wajib sama dengan amount. |
expiresInMinutes | integer | 5–43.200 (30 hari). Default 1.440 (24 jam). Kode QRIS ikut berhenti berlaku saat tagihan kedaluwarsa. |
redirectUrl | string | URL https:// tujuan pembeli setelah membayar (lihat bagian Redirect). |
metadata | object | Maks 20 key; nilai string (≤ 500 karakter), angka, boolean, atau null; total ≤ 4 KB. Disimpan dan dikembalikan apa adanya, termasuk di webhook. |
merchantName | string | Nama penjual di halaman bayar. Default: nama proyek. |
applicationFeeAmount | integer | Hanya bersama header Poketo-Account (Connect). Bagian dari amount untuk platform Anda, dari 0 sampai kurang dari amount. Lihat bagian Connect. |
curl -X POST https://poketo.id/api/v1/invoices \
-H "Authorization: Bearer $POKETO_KEY" \
-H "Content-Type: application/json" \
-d '{
"referenceId": "ORDER-2026-000123",
"amount": 250000,
"title": "Desain ulang landing page",
"customer": { "name": "Rizky Pratama", "email": "rizky@example.com" },
"items": [
{ "name": "Desain halaman utama", "quantity": 1, "price": 150000 },
{ "name": "Revisi", "quantity": 2, "price": 50000 }
],
"expiresInMinutes": 2880,
"redirectUrl": "https://toko.example/pesanan/123/selesai",
"metadata": { "orderId": "123", "channel": "web" }
}'const res = await fetch('https://poketo.id/api/v1/invoices', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.POKETO_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
referenceId: order.id, // your own order ID: retries never create a duplicate
amount: order.total,
title: `Pesanan #${order.number}`,
customer: { name: order.customerName, email: order.email },
redirectUrl: `https://toko.example/pesanan/${order.id}/selesai`,
metadata: { orderId: order.id },
}),
});
const { data, error } = await res.json();
if (error) throw new Error(`${error.code}: ${error.message}`);
// Send the buyer to data.paymentUrlHTTP/1.1 201 Created
{
"data": {
"object": "invoice",
"id": "INV-PKT-20261018-48213",
"referenceId": "ORDER-2026-000123",
"environment": "sandbox",
"status": "pending",
"amount": 250000,
"fees": { "platform": 750, "gateway": 1964 },
"totalAmount": 252714,
"currency": "IDR",
"paymentMethod": null,
"title": "Desain ulang landing page",
"merchantName": "Toko Contoh",
"customer": { "name": "Rizky Pratama", "email": "rizky@example.com", "phone": null },
"items": [
{ "name": "Desain halaman utama", "quantity": 1, "price": 150000, "total": 150000 },
{ "name": "Revisi", "quantity": 2, "price": 50000, "total": 100000 }
],
"metadata": { "orderId": "123", "channel": "web" },
"redirectUrl": "https://toko.example/pesanan/123/selesai",
"paymentUrl": "https://pay.poketo.id/inv/q8ZtV2mKcR4xL7nB1sYwD3fH",
"expiresAt": "2026-10-20T09:15:00.000Z",
"paidAt": null,
"refundedAt": null,
"createdAt": "2026-10-18T09:15:00.000Z"
}
}Kirim ulang dengan aman. Pakai referenceId untuk ID pesanan Anda, atau header Idempotency-Key (1–255 karakter tanpa spasi, berlaku 24 jam) untuk request tanpa referenceId. Request ulang dengan kunci yang sama mengembalikan respons pertama beserta header Idempotent-Replayed: true.
totalAmount di respons adalah perkiraan untuk QRIS. Begitu pembeli memilih metode di halaman bayar, biayanya dihitung ulang untuk metode itu.
Ambil, daftar, dan batalkan tagihan
| Endpoint | Keterangan |
|---|---|
GET /v1/invoices/:id | :id boleh id Poketo (INV-PKT-…) atau referenceId Anda. |
GET /v1/invoices | Terbaru dulu. Query status (pending, paid, expired, cancelled, refunded), createdFrom dan createdTo (tanggal ISO 8601; tanggal tanpa jam dihitung dari 00.00 sampai 23.59 WIB), paymentLinkId, limit (1–100, default 20), offset. Respons punya hasMore. |
POST /v1/invoices/:id/cancel | Hanya untuk tagihan pending. Selain itu 409 invoice_not_pending. Mengirim webhook invoice.cancelled. |
POST /v1/invoices/:id/check-status | Menanyakan status terbaru ke DOKU dan melunasi tagihan bila ternyata sudah dibayar. Respons { data, check: { checked, providerStatus } }. Maksimal sekali per 10 detik per tagihan; tagihan sandbox dikembalikan apa adanya. |
# By Poketo id or by your referenceId
curl https://poketo.id/api/v1/invoices/ORDER-2026-000123 \
-H "Authorization: Bearer $POKETO_KEY"
# List (newest first)
curl "https://poketo.id/api/v1/invoices?status=paid&limit=20&offset=0" \
-H "Authorization: Bearer $POKETO_KEY"curl -X POST https://poketo.id/api/v1/invoices/ORDER-2026-000123/cancel \
-H "Authorization: Bearer $POKETO_KEY"Status tetap akurat walau notifikasi terlewat. Poketo otomatis menanyakan ulang ke DOKU tagihan yang sudah mulai dibayar tapi belum lunas (tiap 2 menit di jam pertama, lalu tiap 15 menit sampai 26 jam), dan juga saat pembeli menunggu di halaman bayar. Jadi check-status jarang perlu dipanggil manual.
Link pembayaran
Satu URL yang bisa dibayar banyak orang, dengan nominal tetap atau diisi pembeli. Cocok untuk platform yang membuat link per pengguna (misalnya halaman traktir kreator). Setiap pembayaran menjadi tagihan biasa dengan paymentLinkId, jadi webhook invoice.paid tetap terkirim. Link milik proyek dan environment key-nya: link sandbox menghasilkan tagihan sandbox yang bisa disimulasikan.
| Endpoint | Keterangan |
|---|---|
POST /v1/payment-links | title wajib. Nominal tetap: amount (min 10.000). Diisi pembeli: minAmount (default 10.000) dan maxAmount (default 10.000.000). Opsional description, askEmail (default true), redirectUrl, merchantName, dan opsi jualan di bawah. Balas 201. |
GET /v1/payment-links | Semua link aktif dan nonaktif di proyek dan environment ini, terbaru dulu, dengan paidCount dan paidAmount. |
GET /v1/payment-links/:id | Satu link. |
PATCH /v1/payment-links/:id | Ubah field di atas. active: false menonaktifkan link; amount: null mengubahnya menjadi nominal diisi pembeli. |
DELETE /v1/payment-links/:id | Arsipkan. URL berhenti bekerja; tagihan yang sudah dibayar tetap ada. |
curl -X POST https://poketo.id/api/v1/payment-links \
-H "Authorization: Bearer $POKETO_KEY" \
-H "Content-Type: application/json" \
-d '{ "title": "Traktir kopi", "minAmount": 10000, "maxAmount": 200000 }'HTTP/1.1 201 Created
{
"data": {
"object": "payment_link",
"id": "plink_Zk3q9TxP2mLa",
"url": "https://poketo.id/l/k7mq2xw9rh4p",
"environment": "live",
"active": true,
"title": "Traktir kopi",
"amount": null,
"minAmount": 10000,
"maxAmount": 200000,
"askEmail": true,
"paidCount": 0,
"paidAmount": 0,
"createdAt": "2026-10-19T02:10:00.000Z"
}
}Pembeli membuka url, mengisi nama (dan nominal bila diisi pembeli), lalu diarahkan ke halaman bayar tagihannya, yang berlaku 2 jam. Daftar pembayaran per link: GET /v1/invoices?paymentLinkId=plink_….
Opsi jualan. Semuanya opsional, di POST maupun PATCH:
| Field | Keterangan |
|---|---|
allowQuantity, maxQuantity | Pembeli memilih jumlah, 1 sampai maxQuantity (1–100, default 10). Hanya untuk nominal tetap. |
stockLimit | Jumlah unit yang bisa terjual (0–1.000.000), null untuk tanpa batas. Checkout yang belum dibayar menahan stok selama 15 menit. Respons satu link memuat stockLeft. |
customFields | Maks 5 isian { label, type, required, options }; type berupa text, phone, atau select (2–10 options). Jawaban pembeli tersimpan di tagihan sebagai customFields. |
afterPaymentMessage | Pesan untuk pembeli di halaman bayar setelah lunas, maks 500 karakter. |
curl https://poketo.id/api/v1/payment-links \
-H "Authorization: Bearer $POKETO_KEY" -H "Content-Type: application/json" \
-d '{
"title": "Kaos Poketo", "amount": 120000,
"allowQuantity": true, "maxQuantity": 5, "stockLimit": 100,
"customFields": [
{ "label": "Ukuran", "type": "select", "options": ["S", "M", "L"], "required": true },
{ "label": "Nomor WhatsApp", "type": "phone" }
],
"afterPaymentMessage": "Terima kasih! Kaos dikirim dalam 2 hari kerja."
}'Tagihan dari link memuat quantity, discountAmount (bila pembeli memakai kode promo yang Anda buat di dashboard), dan customFields berisi jawaban pembeli.
Membership
Langganan berbayar per 1, 3, 6, atau 12 bulan (kelas, komunitas, konten eksklusif). Produk membership milik proyek key-nya; membership yang dibuat di dashboard bisa dihubungkan ke proyek dari halaman membership. Produk dipakai bersama kedua environment, tetapi member tidak: key sandbox hanya melihat dan membuat member sandbox (dibayar lewat POST /v1/invoices/:id/simulate), dan email yang sama bisa menjadi member sandbox dan live sekaligus tanpa saling memengaruhi. Tidak ada debit otomatis: member live mendapat email pengingat beserta tagihan perpanjangan.
Alur integrasi. (1) Buat membership lewat POST /v1/memberships, atau buat di dashboard lalu buka halaman membership itu dan pilih merchant (proyek) di panel Pakai lewat API (di sana juga ada ID membership, ID paket, dan contoh kode). (2) Saat pengguna mendaftar di aplikasi Anda, panggil POST /v1/memberships/:id/checkout dengan nama dan email mereka, lalu arahkan ke invoice.paymentUrl: halaman bayar sudah atas nama member, tanpa isian lagi. Simpan member.id di data pengguna Anda. (3) Setelah dibayar, webhook membership.activated masuk: buka aksesnya. (4) Sebelum masa aktif habis Poketo mengirim pengingat; pembayaran perpanjangan mengirim membership.renewed dengan expiresAt baru, dan bila tidak diperpanjang Anda menerima membership.expired: tutup aksesnya. Untuk mengecek kapan saja, GET /v1/members/:id.
| Endpoint | Keterangan |
|---|---|
POST /v1/memberships | title dan tiers (1–5 paket { name, price, periodMonths }, harga min 10.000) wajib. Opsional description, benefits (maks 10), customFields, maxMembers. Balas 201 dengan url halaman daftar. |
GET /v1/memberships | Membership di proyek ini, terbaru dulu, dengan stats (aktif, segera berakhir, berakhir, pendapatan) untuk environment key. |
GET, PATCH, DELETE /v1/memberships/:id | Ambil, ubah (active: false menutup pendaftaran; tiers dikirim lengkap, sertakan id untuk paket yang dipertahankan), atau arsipkan (tagihan terbuka dibatalkan). |
POST /v1/memberships/:id/checkout | customer: { name, email, phone? }, tierId (boleh dikosongkan bila hanya ada satu paket aktif), answers untuk isian tambahan, opsional expiresInMinutes (default 1440), redirectUrl, metadata. Email yang sudah menjadi member mendapat tagihan perpanjangan. Balas { member, invoice }. |
GET /v1/memberships/:id/members | Filter status (pending, active, expiring, expired, cancelled), cari q (email, nama, HP), limit (maks 100), offset. |
POST /v1/memberships/:id/members | Tambah member yang membayar di luar Poketo: name, email, tierId, opsional expiresAt, phone, note. Langsung aktif. |
GET /v1/members/:id | Satu member. |
PATCH /v1/members/:id | months (1, 3, 6, 12) memperpanjang dari tanggal berakhir, atau expiresAt mengatur tanggalnya; tierId pindah paket; note; status: "cancelled" menghentikan (tagihan terbuka dibatalkan), "active" mengaktifkan lagi. |
POST /v1/members/:id/renewal | Tagihan perpanjangan untuk paket member (tagihan terbuka dipakai ulang), atau tierId lain. Opsional sendEmail: true (live), expiresInMinutes, redirectUrl, metadata. |
curl -X POST https://poketo.id/api/v1/memberships/mbp_…/checkout \
-H "Authorization: Bearer sk_test_…" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: join-user-42" \
-d '{
"tierId": "mbt_…",
"customer": { "name": "Budi", "email": "budi@example.com" },
"metadata": { "userId": "42" },
"redirectUrl": "https://example.com/kelas"
}'{
"data": {
"member": {
"object": "member", "id": "mem_…", "productId": "mbp_…", "environment": "sandbox",
"status": "pending", "email": "budi@example.com", "name": "Budi",
"tier": { "id": "mbt_…", "name": "Bulanan", "price": 50000, "periodMonths": 1 },
"startedAt": null, "expiresAt": null, "totalPaid": 0, "payments": 0
},
"invoice": { "object": "invoice", "id": "INV-PKT-…", "status": "pending", "amount": 50000,
"memberId": "mem_…", "paymentUrl": "https://pay.poketo.id/inv/…" }
}
}{
"id": "evt_…",
"object": "event",
"type": "membership.activated",
"environment": "live",
"createdAt": "2026-11-08T03:15:00.000Z",
"data": {
"object": "membership",
"id": "mem_…",
"environment": "live",
"product": { "id": "mbp_…", "title": "Kelas Musik" },
"tier": { "id": "mbt_…", "name": "Bulanan", "price": 50000, "periodMonths": 1 },
"email": "budi@example.com",
"name": "Budi",
"status": "active",
"startedAt": "2026-11-08T03:15:00.000Z",
"expiresAt": "2026-12-08T03:15:00.000Z",
"payments": 1
}
}Pembayaran menambah masa aktif dari tanggal berakhir (bayar lebih awal tidak menghilangkan hari), dan refund menariknya kembali. Tagihan membership memuat memberId. Webhook membership.activated, membership.renewed, membership.updated, membership.cancelled, dan membership.expired dikirim ke proyek dengan environment member-nya; buka atau tutup akses dari situ. Status member: pending (belum pernah bayar), active, expiring (≤ 7 hari lagi), expired, cancelled. Header Poketo-Account (Connect) belum didukung untuk membership (400 connect_not_supported).
Connect untuk platform
Untuk platform yang menerima pembayaran atas nama penggunanya, misalnya kreator di platform dukungan. Setiap pengguna platform memakai akun Poketo sendiri: mereka menyetujui tautan, menyelesaikan verifikasi identitas, dan menarik saldonya sendiri. Platform hanya membuat tagihan, dan tidak pernah memegang dana pengguna. Connect perlu diaktifkan oleh tim Poketo untuk proyek Anda (hubungi kami); di sandbox lokal semua proyek bisa memakainya.
| Endpoint | Keterangan |
|---|---|
POST /v1/connect/accounts | referenceId wajib (ID pengguna di platform Anda), opsional email dan name. Membuat akun berstatus pending dengan onboardingUrl (berlaku 7 hari, sekali pakai). referenceId yang sama mengembalikan akun yang sama; selama masih pending, setiap panggilan memberi onboardingUrl baru dan tautan lama tidak berlaku lagi. |
GET /v1/connect/accounts | Daftar akun proyek, terbaru dulu. Filter status (pending, active, revoked), limit, offset. |
GET /v1/connect/accounts/:id | Satu akun: status, kycVerified, linkedAt, revokedAt, revokedBy. |
DELETE /v1/connect/accounts/:id | Putuskan tautan. Tagihan yang sudah dibuat tidak terpengaruh. |
- Buat akun untuk pengguna Anda, lalu arahkan pengguna ke
onboardingUrl. Pengguna masuk atau mendaftar di Poketo dan menyetujui tautan; status menjadiactivedan Anda menerima webhookaccount.updated. - Buat tagihan untuk pengguna itu dengan
POST /v1/invoicesditambah headerPoketo-Account: acct_…. Tagihan dan pembayarannya milik pengguna tersebut; webhookinvoice.*tetap dikirim ke proyek Anda. - Isi
purpose: "donation"untuk dukungan atau donasi, sehingga halaman bayar menulis "Dukungan untuk" dan "Dari" alih-alih bahasa tagihan. - Ambil komisi platform dengan
applicationFeeAmount. Saat lunas, pengguna menerimaamount − applicationFeeAmountdan komisinya masuk ke saldo pemilik proyek, dengan masa settlement yang sama. Refund membalik keduanya. Respons tagihan memuatapplicationFeeAmount. - Tagihan live baru bisa dibuat setelah pengguna lolos verifikasi identitas (
kycVerified: true, diberitahukan lewataccount.updated). Tagihan sandbox tidak memerlukannya.
# 1. Akun untuk pengguna platform (kirim pengguna ke onboardingUrl)
curl https://poketo.id/api/v1/connect/accounts \
-H "Authorization: Bearer sk_test_..." -H "Content-Type: application/json" \
-d '{ "referenceId": "creator-42", "email": "rina@example.com", "name": "Rina" }'
# 2. Setelah status active: tagihan dukungan untuk pengguna itu
curl https://poketo.id/api/v1/invoices \
-H "Authorization: Bearer sk_test_..." -H "Content-Type: application/json" \
-H "Poketo-Account: acct_..." \
-d '{ "amount": 25000, "title": "Dukungan untuk Rina", "purpose": "donation", "referenceId": "don-981" }'curl https://poketo.id/api/v1/invoices \
-H "Authorization: Bearer $POKETO_KEY" \
-H "Poketo-Account: acct_…" -H "Content-Type: application/json" \
-d '{ "amount": 100000, "applicationFeeAmount": 5000, "purpose": "donation", "title": "Dukungan untuk Rina" }'Pengguna dapat memutus tautan kapan saja dari Pengaturan akun di dashboard Poketo; Anda menerima account.revoked. Membership milik merchant (proyek) Anda (Dashboard → Membership → Merchant) mengirim membership.activated, membership.renewed, membership.expired, membership.cancelled, dan membership.updated dengan objek membership (id, product, tier, email, name, status, startedAt, expiresAt), sehingga akses bisa dibuka dan ditutup otomatis. Kode error khusus: connect_not_enabled (403), account_not_found (404), account_pending dan account_revoked (409), account_kyc_required (403).
Simulasi di sandbox
POST /v1/invoices/:id/simulate dengan key sandbox. result: paid (dengan paymentMethod QRIS, VA, AKULAKU, atau CARD) atau expired. Webhook dikirim seperti pembayaran sungguhan, tetapi tidak ada uang dan saldo yang berubah. Key live dibalas 403 sandbox_only.
curl -X POST https://poketo.id/api/v1/invoices/ORDER-2026-000123/simulate \
-H "Authorization: Bearer $POKETO_TEST_KEY" \
-H "Content-Type: application/json" \
-d '{ "result": "paid", "paymentMethod": "QRIS" }'Halaman bayar tagihan sandbox juga menampilkan tombol simulasi, sehingga alur pembeli bisa dicoba dari browser.
Status layanan dan demo
Kondisi API, halaman bayar, pemrosesan DOKU, dan webhook diperiksa setiap 5 menit dan ditampilkan di poketo.id/status bersama riwayat uptime 90 hari. Data yang sama tersedia tanpa API key:
curl https://poketo.id/api/public/statusRespons berisi overall (operational, degraded, down) dan components (api, checkout, doku, webhooks), masing-masing dengan status, latencyMs, uptime90d, dan history harian.
Untuk melihat halaman bayar tanpa membuat akun, pakai tombol coba halaman bayar demo di beranda. Tombol itu membuat tagihan sandbox milik toko demo yang bisa disimulasikan lunas.
Status tagihan
| Status | Arti | Webhook |
|---|---|---|
pending | Menunggu pembayaran. | – |
paid | Lunas. Dana masuk saldo setelah settlement (QRIS hari kerja berikutnya, kartu debit 7 hari). | invoice.paid |
expired | Lewat masa berlaku tanpa dibayar. Ditandai paling lambat satu menit setelah waktunya. | invoice.expired |
cancelled | Dibatalkan lewat API atau dashboard. | invoice.cancelled |
refunded | Pembayaran dibatalkan bank atau DOKU (refund atau chargeback). | invoice.refunded |
Bila pembeli tetap membayar tagihan yang sudah kedaluwarsa atau dibatalkan (misalnya QR sudah terlanjur dipindai), uangnya sudah berpindah, jadi tagihan tetap menjadi paid dan invoice.paid dikirim.
Webhook
Poketo mengirim POST JSON ke URL webhook proyek setiap kali status tagihan dari API berubah. URL wajib https://.
POST /webhooks/poketo HTTP/1.1
Content-Type: application/json
User-Agent: Poketo-Webhooks/1.0
Poketo-Event: invoice.paid
Poketo-Event-Id: evt_Jr3T0aZ1kQm8nB2c
Poketo-Delivery: whd_9VbX2LkP0aQe7sYt
Poketo-Signature: t=1792330921,v1=5f2b0c…e81a
{
"id": "evt_Jr3T0aZ1kQm8nB2c",
"object": "event",
"type": "invoice.paid",
"environment": "live",
"createdAt": "2026-10-18T09:21:44.000Z",
"data": { "object": "invoice", "id": "INV-PKT-20261018-48213", "referenceId": "ORDER-2026-000123", "status": "paid", "…": "…" }
}| Header | Isi |
|---|---|
Poketo-Signature | t=<detik unix>,v1=<hex HMAC-SHA256(rahasia, "<t>.<raw body>")> |
Poketo-Event | Jenis event, misalnya invoice.paid. |
Poketo-Event-Id | ID event (evt_…), sama untuk setiap percobaan ulang. Pakai untuk deduplikasi. |
Poketo-Delivery | ID pengiriman (whd_…), berbeda di setiap percobaan. |
Verifikasi tanda tangan dengan rahasia whsec_… proyek, atas body mentah persis seperti yang diterima, dan tolak t yang lebih tua dari 5 menit.
import crypto from 'crypto';
import express from 'express';
const app = express();
// Use the raw body: the signature is computed over the exact bytes Poketo sent
app.post('/webhooks/poketo', express.raw({ type: 'application/json' }), (req, res) => {
const header = req.get('Poketo-Signature') || '';
const { t, v1 } = Object.fromEntries(header.split(',').map((p) => p.split('=')));
const expected = crypto
.createHmac('sha256', process.env.POKETO_WEBHOOK_SECRET) // whsec_…
.update(`${t}.${req.body}`)
.digest('hex');
const valid = v1 && v1.length === expected.length &&
crypto.timingSafeEqual(Buffer.from(v1), Buffer.from(expected));
const fresh = Math.abs(Date.now() / 1000 - Number(t)) < 300; // reject replays older than 5 minutes
if (!valid || !fresh) return res.status(400).send('invalid signature');
const event = JSON.parse(req.body);
// Deduplicate on event.id: retries and redeliveries reuse it
if (event.type === 'invoice.paid') {
// mark event.data.referenceId as paid in your database
}
res.sendStatus(200); // answer within 10 seconds; do slow work in a queue
});- Balas
2xxdalam 10 detik. Pekerjaan berat sebaiknya dimasukkan ke antrean. - Percobaan ulang: sampai 6 kali (langsung, lalu +30 detik, +2 menit, +10 menit, +1 jam, +6 jam) untuk respons
5xx,408,429, timeout, atau error jaringan. Respons4xxlain dianggap gagal permanen. - Redirect tidak diikuti, dan alamat jaringan privat ditolak.
- Riwayat pengiriman, kode respons, latensi, dan tombol Kirim ulang ada di Dashboard → Merchant → Pengaturan API. Tombol Kirim tes mengirim event
ping. - Bila ragu, cocokkan dengan
GET /v1/invoices/:id.
Redirect setelah bayar
Bila redirectUrl diisi, halaman bayar menampilkan tombol kembali ke situs Anda setelah lunas dan mengarahkan pembeli otomatis dalam 5 detik. Jangan menganggap pesanan lunas hanya karena pembeli sampai di redirectUrl; pastikan lewat webhook atau GET /v1/invoices/:id.
Setelah lunas, halaman bayar menyediakan bukti bayar PDF untuk diunduh. Pembeli juga bisa melihat semua pembayarannya di poketo.id/receipts dengan kode yang dikirim ke emailnya.
Checkout tersemat (pop-up)
Buka halaman bayar Poketo sebagai pop-up di situs Anda, tanpa memindahkan pembeli ke tab lain. Berlaku untuk paymentUrl tagihan maupun url link pembayaran.
<script src="https://poketo.id/js/checkout.js"></script>
<!-- Cara 1: tandai link pembayaran -->
<a href="https://pay.poketo.id/l/traktir-kopi" data-poketo-checkout>Bayar</a>
<!-- Cara 2: buka dari JavaScript, misalnya dengan paymentUrl dari POST /v1/invoices -->
<script>
Poketo.checkout.open(invoice.paymentUrl, {
onPaid(e) { location.href = '/pesanan/' + e.invoice; }, // tetap cek di server
onStatus(e) { console.log(e.status); }, // pending, paid, expired, cancelled
onClose() {},
});
</script>onPaid dipanggil saat tagihan lunas, onStatus pada setiap perubahan status, onClose saat pembeli menutup pop-up. Link dengan data-poketo-checkout mengirim event poketo:paid dan poketo:close. Pembayaran kartu dibuka di tab baru karena formulir bank tidak bisa berjalan di dalam bingkai. Pop-up hanya untuk kenyamanan: tandai pesanan lunas dari webhook atau GET /v1/invoices/:id.
Log request
Setiap panggilan API dengan key proyek tercatat di Dashboard → Merchant → merchant Anda → Pengaturan API → Log request API: waktu, method, endpoint, status, durasi, Idempotency-Key, Poketo-Account, serta isi request dan respons (maks 8 KB). Bisa difilter hanya yang gagal. Log disimpan 30 hari.
Error
Respons gagal selalu berbentuk { "error": { "code", "message" } }.
HTTP/1.1 400 Bad Request
{
"error": {
"code": "invalid_request",
"message": "amount wajib bilangan bulat minimal 10000."
}
}| HTTP | Kode | Kapan |
|---|---|---|
400 | invalid_request | Validasi gagal: nominal, item, referenceId, metadata, redirectUrl, atau expiresInMinutes. |
401 | unauthorized | API key tidak ada, salah, dicabut, atau proyeknya diarsipkan. |
403 | sandbox_only | Simulasi dengan key live. |
404 | not_found | Tagihan tidak ada di proyek dan environment key ini. |
409 | invoice_not_pending, idempotency_in_progress | Status tagihan tidak lagi pending, atau request dengan Idempotency-Key yang sama masih diproses. |
422 | idempotency_key_reused | Idempotency-Key dipakai ulang dengan isi berbeda. |
423 | account_suspended | Akun ditangguhkan. |
423 | kyc_required | Tagihan live ini akan membuat total penerimaan melewati Rp 1.000.000 sebelum identitas pemilik akun terverifikasi. |
423 | business_profile_required, business_review_pending, business_rejected | Info merchant belum lengkap, sedang ditinjau, atau ditolak. Hanya untuk key live; key sandbox tidak terpengaruh. |
429 | too_many_requests | Lewat batas permintaan. |
500 | internal_error | Kesalahan di sisi Poketo. Aman dicoba ulang dengan jeda (pakai referenceId agar tidak dobel). |