Dokumentasi

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.

Base URL 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

  1. 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.
  2. Buat API key sandbox (sk_test_…). Key hanya ditampilkan sekali; simpan di server Anda.
  3. Atur URL webhook proyek dan simpan rahasia penandatanganannya (whsec_…).
  4. Buat tagihan dengan POST /v1/invoices, arahkan pembeli ke paymentUrl, dan coba alurnya dengan tombol simulasi di halaman bayar sandbox atau POST /v1/invoices/:id/simulate.
  5. 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.

Terminal
npm install poketo-node
Node.js
const 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.create otomatis mengirim Idempotency-Key, jadi request yang timeout dicoba ulang tanpa membuat tagihan ganda. Kirim kunci sendiri dengan create(params, { idempotencyKey }).
  • Request baca dan create dicoba ulang sampai 2 kali untuk 429 (mengikuti Retry-After), 5xx, dan error jaringan. cancel dan simulate tidak pernah dicoba ulang. Atur dengan opsi maxRetries dan timeout.
  • Error API dilempar sebagai PoketoError dengan status, code, dan retryAfter.
Menangani error
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.

Webhook (Express)
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.

Prompt integrasi
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.

URL server MCP: 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 Code
claude mcp add --transport http poketo https://poketo.id/api/mcp \
  --header "Authorization: Bearer sk_test_..."
Klien lain (Cursor, Claude Desktop, VS Code)
{
  "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.

Header
Authorization: Bearer sk_test_7Hq2…   # sandbox
Authorization: Bearer sk_live_Lm9x…   # live
Sandbox (`sk_test_`)Live (`sk_live_`)
Uang berpindahTidakYa
PembayaranDisimulasikan (tombol di halaman bayar atau endpoint simulate)QRIS, Virtual Account, PayLater, dan kartu debit lewat DOKU
Saldo dan laporanTidak terpengaruhMasuk saldo setelah settlement
WebhookDikirim seperti biasa, environment: "sandbox"Dikirim, environment: "live"
SyaratAkun PoketoIdentitas 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.

EndpointBatas per key
GET /v1/payment-methods, GET /v1/invoices, GET /v1/invoices/:id120 / menit
POST /v1/invoices60 / menit
POST /v1/invoices/:id/simulate30 / menit
POST /v1/invoices/:id/cancel20 / menit
POST /v1/invoices/:id/check-status30 / menit
GET /v1/payment-links, GET /v1/payment-links/:id120 / menit
POST, PATCH, DELETE /v1/payment-links30 / menit
GET /v1/memberships…, GET /v1/members/:id120 / menit
POST /v1/memberships/:id/checkout60 / menit
POST, PATCH, DELETE membership dan member lainnya30 / 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
curl "https://poketo.id/api/v1/payment-methods?amount=250000" \
  -H "Authorization: Bearer $POKETO_KEY"
Respons
{
  "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

FieldTipeKeterangan
amountinteger, wajibNominal yang Anda terima, minimal 10.000.
referenceIdstringID 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.
titlestringJudul di halaman bayar. Default "Pembayaran".
descriptionstringKeterangan tambahan.
customerobject{ name, email, phone }. email dipakai untuk bukti pembayaran.
itemsarrayMaks 50 item { name, quantity, price }. Jumlah quantity × price wajib sama dengan amount.
expiresInMinutesinteger5–43.200 (30 hari). Default 1.440 (24 jam). Kode QRIS ikut berhenti berlaku saat tagihan kedaluwarsa.
redirectUrlstringURL https:// tujuan pembeli setelah membayar (lihat bagian Redirect).
metadataobjectMaks 20 key; nilai string (≤ 500 karakter), angka, boolean, atau null; total ≤ 4 KB. Disimpan dan dikembalikan apa adanya, termasuk di webhook.
merchantNamestringNama penjual di halaman bayar. Default: nama proyek.
applicationFeeAmountintegerHanya bersama header Poketo-Account (Connect). Bagian dari amount untuk platform Anda, dari 0 sampai kurang dari amount. Lihat bagian Connect.
curl
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" }
  }'
Node.js
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.paymentUrl
Respons
HTTP/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

EndpointKeterangan
GET /v1/invoices/:id:id boleh id Poketo (INV-PKT-…) atau referenceId Anda.
GET /v1/invoicesTerbaru 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/cancelHanya untuk tagihan pending. Selain itu 409 invoice_not_pending. Mengirim webhook invoice.cancelled.
POST /v1/invoices/:id/check-statusMenanyakan 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.
curl
# 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
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.

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.

EndpointKeterangan
POST /v1/membershipstitle 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/membershipsMembership di proyek ini, terbaru dulu, dengan stats (aktif, segera berakhir, berakhir, pendapatan) untuk environment key.
GET, PATCH, DELETE /v1/memberships/:idAmbil, ubah (active: false menutup pendaftaran; tiers dikirim lengkap, sertakan id untuk paket yang dipertahankan), atau arsipkan (tagihan terbuka dibatalkan).
POST /v1/memberships/:id/checkoutcustomer: { 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/membersFilter status (pending, active, expiring, expired, cancelled), cari q (email, nama, HP), limit (maks 100), offset.
POST /v1/memberships/:id/membersTambah member yang membayar di luar Poketo: name, email, tierId, opsional expiresAt, phone, note. Langsung aktif.
GET /v1/members/:idSatu member.
PATCH /v1/members/:idmonths (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/renewalTagihan perpanjangan untuk paket member (tagihan terbuka dipakai ulang), atau tierId lain. Opsional sendEmail: true (live), expiresInMinutes, redirectUrl, metadata.
curl
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"
  }'
Respons
{
  "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/…" }
  }
}
Webhook membership.activated
{
  "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.

EndpointKeterangan
POST /v1/connect/accountsreferenceId 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/accountsDaftar akun proyek, terbaru dulu. Filter status (pending, active, revoked), limit, offset.
GET /v1/connect/accounts/:idSatu akun: status, kycVerified, linkedAt, revokedAt, revokedBy.
DELETE /v1/connect/accounts/:idPutuskan tautan. Tagihan yang sudah dibuat tidak terpengaruh.
  1. Buat akun untuk pengguna Anda, lalu arahkan pengguna ke onboardingUrl. Pengguna masuk atau mendaftar di Poketo dan menyetujui tautan; status menjadi active dan Anda menerima webhook account.updated.
  2. Buat tagihan untuk pengguna itu dengan POST /v1/invoices ditambah header Poketo-Account: acct_…. Tagihan dan pembayarannya milik pengguna tersebut; webhook invoice.* tetap dikirim ke proyek Anda.
  3. Isi purpose: "donation" untuk dukungan atau donasi, sehingga halaman bayar menulis "Dukungan untuk" dan "Dari" alih-alih bahasa tagihan.
  4. Ambil komisi platform dengan applicationFeeAmount. Saat lunas, pengguna menerima amount − applicationFeeAmount dan komisinya masuk ke saldo pemilik proyek, dengan masa settlement yang sama. Refund membalik keduanya. Respons tagihan memuat applicationFeeAmount.
  5. Tagihan live baru bisa dibuat setelah pengguna lolos verifikasi identitas (kycVerified: true, diberitahukan lewat account.updated). Tagihan sandbox tidak memerlukannya.
curl
# 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
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
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:

GET /api/public/status
curl https://poketo.id/api/public/status

Respons 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

StatusArtiWebhook
pendingMenunggu pembayaran.–
paidLunas. Dana masuk saldo setelah settlement (QRIS hari kerja berikutnya, kartu debit 7 hari).invoice.paid
expiredLewat masa berlaku tanpa dibayar. Ditandai paling lambat satu menit setelah waktunya.invoice.expired
cancelledDibatalkan lewat API atau dashboard.invoice.cancelled
refundedPembayaran 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://.

Contoh request
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", "…": "…" }
}
HeaderIsi
Poketo-Signaturet=<detik unix>,v1=<hex HMAC-SHA256(rahasia, "<t>.<raw body>")>
Poketo-EventJenis event, misalnya invoice.paid.
Poketo-Event-IdID event (evt_…), sama untuk setiap percobaan ulang. Pakai untuk deduplikasi.
Poketo-DeliveryID 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.

Node.js (Express), tanpa SDK
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 2xx dalam 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. Respons 4xx lain 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.

HTML
<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" } }.

Contoh
HTTP/1.1 400 Bad Request
{
  "error": {
    "code": "invalid_request",
    "message": "amount wajib bilangan bulat minimal 10000."
  }
}
HTTPKodeKapan
400invalid_requestValidasi gagal: nominal, item, referenceId, metadata, redirectUrl, atau expiresInMinutes.
401unauthorizedAPI key tidak ada, salah, dicabut, atau proyeknya diarsipkan.
403sandbox_onlySimulasi dengan key live.
404not_foundTagihan tidak ada di proyek dan environment key ini.
409invoice_not_pending, idempotency_in_progressStatus tagihan tidak lagi pending, atau request dengan Idempotency-Key yang sama masih diproses.
422idempotency_key_reusedIdempotency-Key dipakai ulang dengan isi berbeda.
423account_suspendedAkun ditangguhkan.
423kyc_requiredTagihan live ini akan membuat total penerimaan melewati Rp 1.000.000 sebelum identitas pemilik akun terverifikasi.
423business_profile_required, business_review_pending, business_rejectedInfo merchant belum lengkap, sedang ditinjau, atau ditolak. Hanya untuk key live; key sandbox tidak terpengaruh.
429too_many_requestsLewat batas permintaan.
500internal_errorKesalahan di sisi Poketo. Aman dicoba ulang dengan jeda (pakai referenceId agar tidak dobel).
Ada pertanyaan? Hubungi kami di contact@dahono.com.