SennPayy
SENNPAYY API V1

Integrasi payment link
langsung dari backend Anda.

Gunakan API SennPayy untuk membuat payment link, membaca status pembayaran, dan menerima webhook saat invoice sudah dibayar. Default yang aman: fee QRIS ditanggung merchant (pembayar membayar sesuai nominal).

Kepatuhan QRIS: MDR QRIS ditanggung merchant dan tidak boleh dibebankan ke konsumen (aturan BI/ASPI). fee_bearer=customer nonaktif secara default dan hanya diterima bila admin mengaktifkannya setelah review kepatuhan + perjanjian PJP/acquirer; jika tidak, create mengembalikan 422 CUSTOMER_FEE_DISABLED.

Target production base URLhttps://www.sennpayy.biz.id/api/v1
URL environment inihttps://www.sennpayy.biz.id/api/v1

Authentication

API key dibuat dari Dashboard - Integrasi API.

Kirim API key hanya dari server Anda melalui header Authorization. Jangan menaruh secret key di browser, aplikasi frontend, atau source publik.

Authorization: Bearer sp_live_xxxxxxxxxxxxxxxxxxxxxxxx

Key sp_test_... selalu diproses sebagai sandbox di semua environment: invoice yang dibuat tidak menyentuh saldo, ledger, atau penarikan merchant, dan webhook dikirim dengan is_sandbox=true. Key sp_live_... hanya diterima di produksi; di environment non-produksi key live ditolak sebagai key tidak valid (401) dan tidak boleh dipakai untuk pengujian. Prefix tidak mengubah contract endpoint maupun alur pembayaran.

Akun pemilik key wajib aktif dan selesai onboarding. Key hilang, salah, revoked, atau akun tidak memenuhi syarat tersebut menghasilkan 401. Pemeriksaan ulang akun saat pembuatan invoice juga dapat menghasilkan 403 ACCOUNT_UNAVAILABLE bila kondisi akun berubah setelah autentikasi.

Create invoice

Membuat invoice dan URL checkout baru.

POST/invoices

POST /payment-links adalah alias dengan contract yang sama. external_id adalah idempotency key per akun: replay dengan seluruh field efektif yang sama mengembalikan invoice tersimpan dengan HTTP 200 dan created: false; invoice baru menghasilkan HTTP 201 dan created: true. Perbedaan amount, title, fee bearer hasil resolusi, callback hasil resolusi, project, atau expiry menghasilkan 409 IDEMPOTENCY_CONFLICT.

FieldTypeKeterangan
external_idstringID order unik dari sistem Anda. Wajib.
amountintegerNominal invoice dalam Rupiah, Rp1.000–Rp10.000.000. Wajib.
providerstringopsional: manual = SennPay QRIS (default), QR dinamis bernominal otomatis, diverifikasi dari mutasi (min Rp1.000). paymenku = sudah dihapus total: permintaan eksplisit ditolak 410 PROVIDER_RETIRED tanpa side effect. Buat payment link baru agar pembeli mendapat QRIS SennPayy atau SennPay Express. wijayapay = SennPay Express: QRIS diterbitkan jaringan SennPayy, pembeli menanggung fee kanal, fee SennPayy dipotong dari saldo merchant. Nilai wpay masih diterima untuk kompatibilitas klien lama dan dijalankan sebagai SennPay QRIS. Menghilangkan field ini = mengikuti pengaturan akun (default akun, lalu fallback bila akun mengaktifkannya). Project tidak menentukan jalur. Admin platform dapat menonaktifkan salah satu jalur; permintaan ke jalur yang nonaktif dialihkan ke jalur yang aktif. Baca field provider di response untuk tahu jalur sebenarnya.
titlestringJudul 2–120 karakter. Default Pembayaran.
fee_bearerstringmerchant (disarankan/default) atau customer. Bila kosong, pakai default project lalu merchant. customer hanya bila kebijakan fee customer sedang aktif.
expires_in_minutesintegerMasa berlaku 5 sampai 10.080 menit. Default 1.440 (24 jam).
callback_urlURLHTTPS publik untuk menerima webhook. Bila kosong, pakai callback project. Opsional.
project_idstringID project milik akun. Invoice ikut default fee + callback project. Opsional.

external_id di-trim dan panjangnya 1–100 karakter; title juga di-trim. project_id di-trim dan panjangnya 1–64 karakter. Prioritas project: body → project bawaan API key → tanpa project. Field fee/callback eksplisit mengalahkan default project. Project harus milik akun dan aktif (tidak ditemukan: 404; nonaktif: 409). Replay tetap melalui validasi request dan project; perubahan default project bisa menimbulkan conflict. Replay tidak memperpanjang expiry atau mengubah nominal/fee tersimpan; status respons mengikuti kondisi invoice saat dibaca, bukan selalu waiting_payment.

cURL

curl -X POST https://www.sennpayy.biz.id/api/v1/invoices \
  -H "Authorization: Bearer sp_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "ORDER-1024",
    "amount": 125000,
    "title": "Pesanan #1024",
    "fee_bearer": "merchant",
    "callback_url": "https://example.com/webhooks/sennpayy"
  }'

JavaScript

const response = await fetch("https://www.sennpayy.biz.id/api/v1/invoices", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.SENNPAYY_API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    external_id: "ORDER-1024",
    amount: 125000,
    title: "Pesanan #1024",
    fee_bearer: "merchant",
    callback_url: "https://example.com/webhooks/sennpayy"
  })
});

const payment = await response.json();
console.log(payment.payment_url);

PHP

$payload = json_encode([
  "external_id" => "ORDER-1024",
  "amount" => 125000,
  "title" => "Pesanan #1024",
  "fee_bearer" => "merchant"
]);

$ch = curl_init("https://www.sennpayy.biz.id/api/v1/invoices");
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer " . getenv("SENNPAYY_API_KEY"),
    "Content-Type: application/json"
  ],
  CURLOPT_POSTFIELDS => $payload
]);

$result = json_decode(curl_exec($ch), true);

Python

import os
import requests

response = requests.post(
    "https://www.sennpayy.biz.id/api/v1/invoices",
    headers={
        "Authorization": f"Bearer {os.environ['SENNPAYY_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "external_id": "ORDER-1024",
        "amount": 125000,
        "title": "Pesanan #1024",
        "fee_bearer": "merchant",
        "callback_url": "https://example.com/webhooks/sennpayy",
    },
    timeout=15,
)

payment = response.json()
print(payment["payment_url"])

Response

{
  "id": "inv_xxxxx",
  "external_id": "ORDER-1024",
  "status": "waiting_payment",
  "amount": 125000,
  "fee_amount": 1250,
  "fee_bearer": "merchant",
  "payable_amount": 125000,
  "net_amount": 123750,
  "unique_code": 0,
  "project_id": null,
  "provider": "manual",
  "provider_expires_at": null,
  "payment_url": "https://www.sennpayy.biz.id/pay/pay-xxxxx",
  "created": true,
  "expires_at": "2026-09-24T13:00:00.000Z",
  "created_at": "2026-09-23T13:00:00.000Z",
  "paid_at": null
}

Status, payment mode & escrow

Dari menunggu bayar sampai dana tersedia.

Status yang dapat dibaca: waiting_payment, under_review, paid, rejected, expired, dan cancelled. Upload bukti mengubah invoice terbuka menjadi under_review; admin kemudian menetapkan paid atau rejected. Invoice waiting_payment/rejected yang melewati expires_at dibaca sebagai expired; bukti yang sudah masuk sebelum expiry tetap dapat direview. cancelled berarti dibatalkan via API sebelum dibayar, jadi nominalnya bebas dipakai invoice lain dan tidak akan pernah match otomatis.

Mode checkout publik memakai QRIS dinamis per invoice bila payload QRIS SennPayy sudah diisi admin: QR mengisi total payable_amount (termasuk kode unik) secara otomatis. Tanpa payload, checkout memakai gambar statis dan pembayar mengetik total secara manual di aplikasi e-wallet; selisih Rp1 saja membuat auto-match gagal. Verifikasi otomatis hanya berlaku bila koneksi platform (satu akun pemilik QRIS SennPayy, dihubungkan sekali oleh admin) berstatus connected dan proses polling dijalankan. Mutasi dicocokkan ke seluruh invoice terbuka lintas merchant: harus cocok persis dengan payable_amount, berada dalam rentang waktu invoice, dan hanya memiliki satu kandidat; kondisi ambigu tetap manual. Koneksi provider tidak mengubah contract endpoint invoice dan tidak menjamin kapan polling dijalankan.

Durasi escrow dibaca dari konfigurasi aktif saat invoice diverifikasi, bukan nilai tetap di contract API: 0 jam berarti saldo langsung tersedia; 1–168 jam berarti escrow_release_at = paid_at + durasi. Timestamp API adalah ISO 8601 UTC (Z) dan perhitungan jatuh tempo menggunakan clock database/server. Rilis hanya terjadi saat proses escrow dijalankan, dapat ditahan admin, dan tidak dijanjikan tepat pada detik escrow_release_at. Endpoint status publik tidak mengembalikan field escrow; lihat saldo/dashboard untuk ketersediaan dana.

Get invoice status

Ambil invoice milik akun menggunakan ID SennPayy.

GET/invoices/:id

GET /payment-links/:id adalah alias dengan contract yang sama.

curl https://www.sennpayy.biz.id/api/v1/invoices/inv_xxxxx \
  -H "Authorization: Bearer sp_live_..."

Response berisi id, external_id, status, amount, fee_amount, fee_bearer, payable_amount, net_amount, unique_code, title, project_id, provider, provider_expires_at, payment_url, created_at, paid_at, dan expires_at. provider menunjukkan jalur yang benar-benar dipakai (manual atau wijayapay), dan provider_expires_at adalah masa berlaku kode bayar provider: pada SennPay Express kode bisa kedaluwarsa lebih dulu daripada invoice, jadi pakai payment_url agar pembeli mendapat kode pengganti. unique_code 0 berarti nonaktif untuk invoice tersebut. Invoice akun lain diperlakukan sebagai tidak ditemukan (404).

Panduan polling status

Andalkan webhook sebagai sinyal utama dan gunakan polling sebagai cadangan: poll GET /invoices/:id tiap 10–30 detik sampai status final (paid, rejected, atau expired), lalu hentikan. Jangan poll lebih cepat dari 5 detik agar tidak kena rate limit API key (120/menit). Status paid berarti pembayaran terverifikasi, tetapi dana bisa masih ditahan escrow, jadi cek saldo/dashboard untuk ketersediaan dana.

import os
import time
import requests

BASE = "https://www.sennpayy.biz.id/api/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['SENNPAYY_API_KEY']}"}

for _ in range(60):
    invoice = requests.get(f"{BASE}/invoices/inv_xxxxx", headers=HEADERS, timeout=15).json()
    if invoice["status"] in ("paid", "rejected", "expired", "cancelled"):
        break
    time.sleep(15)

print(invoice["status"])

Cancel invoice

Batalkan invoice yang belum dibayar.

POST/invoices/:id/cancel

POST /payment-links/:id/cancel adalah alias dengan contract yang sama. Aman dipanggil karena belum ada dana bergerak: hanya waiting_payment yang beralih ke cancelled. Response mengembalikan invoice + flag cancelled.

KondisiHasilCatatan
waiting_payment200, cancelled: trueStatus menjadi cancelled; nominal bebas dipakai invoice lain.
paid409 ALREADY_PAIDDana sudah bergerak; ajukan refund via support.
under_review409 IN_REVIEWBukti sedang diperiksa admin; tunggu keputusan.
expired / rejected / cancelled200, cancelled: falseSudah terminal; tidak ada yang diubah.
curl -X POST https://www.sennpayy.biz.id/api/v1/invoices/inv_xxxxx/cancel \
  -H "Authorization: Bearer sp_live_..."

Bot Telegram memakai endpoint ini saat buyer menekan Batalkan, lalu berhenti polling status invoice tersebut.

Node SDK (server-side)

Paket lokal untuk backend Node.js; browser SDK di /sdk/sennpay.js tidak berubah.

Untuk integrasi server tersedia paket npm sennpayy-node (MIT, ESM, Node 22.16.0+, tanpa dependency runtime): npm install sennpayy-node. Lisensi MIT hanya mencakup paket SDK ini, bukan aplikasi SennPayy, platform, atau layanan hostingnya. Jangan pakai paket ini di browser; integrasi client tetap memakai /sdk/sennpay.js yang contract-nya tidak berubah.

import { SennPayy, SennPayyError, verifyWebhook } from "sennpayy-node";

const sennpayy = new SennPayy({ apiKey: process.env.SENNPAYY_API_KEY });

// Buat invoice. Provider paymenku sudah dihapus, ditolak 410 PROVIDER_RETIRED.
const inv = await sennpayy.invoices.create({
  external_id: "ORDER-1024",
  amount: 125000,
  title: "Pesanan #1024",
  fee_bearer: "merchant",
});
console.log(inv.payment_url);

const status = await sennpayy.invoices.get(inv.id);
await sennpayy.invoices.cancel(inv.id); // hanya waiting_payment yang batal

// Di endpoint webhook Anda: verifikasi byte mentah, jangan parse JSON dulu.
const rawBody = Buffer.from(await request.arrayBuffer());
try {
  const event = verifyWebhook({
    rawBody,
    signature: request.headers.get("x-sennpayy-signature") ?? "",
    timestamp: request.headers.get("x-sennpayy-timestamp") ?? "",
    secret: process.env.SENNPAYY_WEBHOOK_SECRET,
  });
  // Signature valid bukan bukti lunas: cocokkan event.invoice_id, status, dan
  // nominal dengan order Anda, lalu ubah status order secara atomik.
} catch (error) {
  if (error instanceof SennPayyError) return new Response(null, { status: 400 });
  throw error;
}

SDK memakai contract endpoint yang sama dengan contoh curl di atas. Error berupa SennPayyError dengan status dan code dari API (mis. PROVIDER_RETIRED, IDEMPOTENCY_CONFLICT); verifyWebhook menolak signature salah atau timestamp di luar window (default 5 menit) dan hanya mengembalikan payload JSON yang sudah terverifikasi.

Node SDK (server-side)

Paket npm untuk backend Node.js; browser SDK di /sdk/sennpay.js tidak berubah.

Untuk integrasi server tersedia paket npm sennpayy-node (MIT, ESM, Node 22.16.0+, tanpa dependency runtime): npm install sennpayy-node. Lisensi MIT hanya mencakup paket SDK ini, bukan aplikasi SennPayy, platform, atau layanan hostingnya. Jangan pakai paket ini di browser; integrasi client tetap memakai /sdk/sennpay.js yang contract-nya tidak berubah.

import { SennPayy, SennPayyError, verifyWebhook } from "sennpayy-node";

const sennpayy = new SennPayy({ apiKey: process.env.SENNPAYY_API_KEY });

// Buat invoice. Nilai provider:"paymenku" ditolak SDK (410 PROVIDER_RETIRED)
// tanpa request ke API; jalur lain mengikuti pengaturan akun.
const inv = await sennpayy.invoices.create({
  external_id: "ORDER-1024",
  amount: 125000,
  title: "Pesanan #1024",
  fee_bearer: "merchant",
});
console.log(inv.payment_url);

const status = await sennpayy.invoices.get(inv.id);
await sennpayy.invoices.cancel(inv.id); // hanya waiting_payment yang batal

// Di endpoint webhook Anda: verifikasi byte mentah, jangan parse JSON dulu.
const rawBody = Buffer.from(await request.arrayBuffer());
try {
  const event = verifyWebhook({
    rawBody,
    signature: request.headers.get("x-sennpayy-signature") ?? "",
    timestamp: request.headers.get("x-sennpayy-timestamp") ?? "",
    secret: process.env.SENNPAYY_WEBHOOK_SECRET,
  });
  // Signature valid bukan bukti lunas: cocokkan event.invoice_id, status, dan
  // nominal dengan order Anda, lalu ubah status order secara atomik.
} catch (error) {
  if (error instanceof SennPayyError) return new Response(null, { status: 400 });
  throw error;
}

SDK memakai contract endpoint yang sama dengan contoh curl di atas. Error berupa SennPayyError dengan status dan code dari API (mis. IDEMPOTENCY_CONFLICT); verifyWebhook menolak signature salah atau timestamp di luar window (default 5 menit) dan hanya mengembalikan payload JSON yang sudah terverifikasi.

Dynamic QRIS pricing

Estimator ini memakai konfigurasi biaya yang sama dengan halaman publik dan dihitung dari snapshot konfigurasi saat halaman dimuat. Invoice sebenarnya menghitung ulang konfigurasi aktif ketika dibuat; jangan menyimpan hasil estimator sebagai sumber tagihan.

Penanggung biaya layanan
KomponenNilai
Nominal transaksiRp 100.000
Biaya layananRp 850
Total dibayar pelangganRp 100.000
Saldo bersih diterima akunRp 99.150
Jika dicairkan ke rekening bankRp 93.150setelah biaya Rp 6.000

Rumus aktif: nominal ≥ Rp 10.000.001 → fee 0,7% (pecahan dibulatkan ke atas); di bawah itu → 0,7% + Rp 150. Biaya layanan di atas bisa ditanggung akun Anda atau pembayar (lihat opsi di atas).

Simulasi memakai tarif yang berlaku saat halaman dimuat. Biaya pencairan ke rekening bank Rp 6.000 per pencairan, terpisah dari biaya layanan. Kode unik Rp10–99 ditambahkan ke total yang dibayar pembayar, lalu masuk ke saldo akun Anda (penerima), bukan kembali ke rekening pembayar.

Konfigurasi aktif saat halaman dimuat: boundary Rp10.000.001; tarif bawah 70 bps + Rp150; tarif mulai boundary 70 bps; withdrawal fee Rp6.000; escrow 25 jam.

Untuk nominal A, boundary mengikuti konfigurasi qrisHighMinAmount: bila A ≥ boundary, fee = ceil(A × qrisHighBps / 10.000); bila lebih kecil, fee = ceil(A × qrisLowBps / 10.000) + qrisLowFixed. Semua pecahan dibulatkan ke atas. Bila kode unik aktif, invoice baru mendapat kode U (1–999): customer: payable_amount = A + fee + U dan net_amount = A + U. merchant: payable_amount = A + U dan net_amount = max(0, A − fee) + U. Kode unik dikembalikan sebagai saldo, bukan fee. Bila nonaktif atau total melebihi batas, U = 0.

customer (tidak disarankan)

Nilai legacy yang tidak disarankan untuk integrasi baru. Nonaktif secara default; hanya diterima bila admin mengaktifkannya, jika tidak create invoice mengembalikan 422 CUSTOMER_FEE_DISABLED. Aturan QRIS melarang surcharge ke konsumen.

merchant

Customer membayar nominal invoice, dan fee dipotong dari saldo akun. Ini adalah default akhir jika tidak ada fee bearer eksplisit maupun default project.

Nama value merchant dipertahankan pada API contract sebagai istilah teknis. Penarikan memakai biaya konfigurasi terpisah: max(0, saldo − withdrawalFee). Pembuatan invoice ditolak 422 INVALID_FEE_TOTAL bila net ≤ 0 atau total customer melampaui batas nominal API.

Contoh perhitungan (tarif aktif saat halaman dimuat)

NominalFeeMerchant: bayar / terima
Rp50.000Rp 500Rp50.000 / Rp 49.500
Rp100.000Rp 850Rp100.000 / Rp 99.150
Rp100.001Rp 851Rp100.001 / Rp 99.150
Rp500.000Rp 3.650Rp500.000 / Rp 496.350
Rp1.000.000Rp 7.150Rp1.000.000 / Rp 992.850

Nilai di atas dihitung dari konfigurasi aktif dan belum termasuk kode unik (Rp1–999 acak per invoice bila aktif, masuk ke saldo akun). Batas tarif mengikuti qrisHighMinAmount yang berlaku, bukan angka tetap.

Webhook & Notifikasi

Dikirim ke callback_url saat pembayaran berhasil atau tagihan kedaluwarsa.

SennPayy mengirim request POST ke callback_url dengan header berikut. Webhook signing secret per akun dapat dilihat di Dashboard → Integrasi API.

x-sennpayy-signature: <hmac-sha256>
x-sennpayy-timestamp: <detik-unix>
x-sennpayy-delivery-id: whd_xxxxx
x-sennpayy-event: invoice.paid | invoice.expired
content-type: application/json

Event 1: invoice.paid

Dikirim saat pembayaran berhasil diverifikasi dan saldo siap dikreditkan / masuk escrow.

{
  "event": "invoice.paid",
  "invoice_id": "inv_xxxxx",
  "external_id": "ORDER-1024",
  "status": "paid",
  "amount": 125000,
  "fee_amount": 1250,
  "fee_bearer": "merchant",
  "payable_amount": 125000,
  "net_amount": 123750,
  "unique_code": 0,
  "provider": "manual",
  "paid_at": "2026-09-23T13:00:00.000Z"
}

Event 2: invoice.expired

Dikirim saat batas waktu pembayaran habis tanpa pembayaran terverifikasi. Gunakan untuk membatalkan pesanan atau mengembalikan stok otomatis.

{
  "event": "invoice.expired",
  "invoice_id": "inv_xxxxx",
  "external_id": "ORDER-1024",
  "status": "expired",
  "amount": 125000,
  "title": "Langganan Paket Premium",
  "expired_at": "2026-09-23T14:00:00.000Z"
}

Verifikasi signature (Node.js)

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

function verifySennPayyWebhook(rawBody, signature, timestamp, secret, toleranceSec = 300) {
  if (!Buffer.isBuffer(rawBody) || !secret) return false;
  if (!/^[0-9a-f]{64}$/i.test(signature)) return false;
  const ts = Number(timestamp);
  if (!Number.isInteger(ts) || ts <= 0) return false;
  if (Math.abs(Math.floor(Date.now() / 1000) - ts) > toleranceSec) return false;

  const expected = createHmac("sha256", secret)
    .update(ts + "." + rawBody.toString("utf8"))
    .digest();
  const received = Buffer.from(signature, "hex");
  return received.length === expected.length && timingSafeEqual(received, expected);
}

const rawBody = Buffer.from(await request.arrayBuffer());
const valid = verifySennPayyWebhook(
  rawBody,
  request.headers.get("x-sennpayy-signature"),
  request.headers.get("x-sennpayy-timestamp"),
  process.env.SENNPAYY_WEBHOOK_SECRET
);
if (!valid) return new Response("Invalid signature", { status: 401 });
const event = JSON.parse(rawBody.toString("utf8"));

Verifikasi terhadap body mentah sebelum parsing JSON. Signature dihitung atas ${timestamp}.{rawBody}: header x-sennpayy-timestamp (detik Unix) digabung titik dengan raw JSON body, lalu HMAC-SHA256 hex memakai secret signing. Toleransi waktu maksimal sekitar 5 menit; timestamp di luar window ditolak sebagai signature tidak valid. Secret signing berbeda dari API key dan tidak boleh dikirim ke client.

Event tersedia: invoice.paid dan invoice.expired. Balas HTTP 2xx agar delivery dianggap sukses; status non-2xx, timeout 5 detik, error jaringan/DNS, atau target callback yang gagal validasi dianggap gagal. Sistem mencoba maksimal 8 kali dengan backoff 60 detik, 5 menit, 15 menit, 1 jam, 6 jam, 12 jam, lalu 24 jam. Cuplikan balasan server (maks 500 karakter) disimpan untuk memudahkan debugging di dashboard.

Gunakan x-sennpayy-delivery-id sebagai idempotency key consumer. Setiap event dibuat paling banyak sekali per invoice (dijamin unik di database), tetapi request yang sama dapat diterima berulang karena retry. Kegagalan webhook tidak mengubah status invoice maupun kredit saldo.

Spesifikasi OpenAPI 3.1.0 lengkap, termasuk skema request, response, rate limit headers, dan katalog webhooks, tersedia di /api/openapi.json dan bisa langsung dimuat ke Swagger UI atau Redoc.

Rate limits

Respons 429 menyertakan header x-ratelimit-* dan retry-after. Batas saat ini:

ScopeBatasCatatan
per IP300/menitSeluruh API v1 dari satu IP.
per API key120/menitPer key, terpisah dari limit IP.
upload bukti5/15 menitPer kombinasi IP + invoice.

Error responses

HTTPArtiContoh
400Payload invalidField hilang atau format salah.
401UnauthorizedAPI key tidak valid/revoked.
403ForbiddenAkun belum onboarding/aktif, atau kebijakan menolak.
404Not foundInvoice bukan milik API key tersebut.
409ConflictIdempotency (external_id beda payload), ALREADY_PAID, atau IN_REVIEW saat cancel.
422Policy conflictContoh: fee customer sedang dinonaktifkan admin.
429Rate limitedTerlalu banyak request.

QR untuk bot (Telegram/dll)

Jangan kirim gambar QR statis pusat ke pembayar: nominalnya kosong sehingga pembayar harus ketik manual. Setiap response create/get invoice menyertakan qr_image_url (GET /api/pay/:slug/qr, publik tanpa API key, PNG, rate limit 120/menit per IP+slug). Kirim URL itu sebagai foto dengan caption total payable_amount:

import requests

inv = requests.post(
    "https://www.sennpayy.biz.id/api/v1/invoices",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={"external_id": "TG-77123", "amount": 50000},
    timeout=15,
).json()

photo_url = inv["qr_image_url"]
total = format(inv["payable_amount"], ",d").replace(",", ".")
caption = "Bayar Rp" + total + " dengan scan QR ini. Nominal sudah terisi otomatis."
# requests.post("https://api.telegram.org/bot" + TOKEN + "/sendPhoto",
#               data={"chat_id": chat_id, "caption": caption, "photo": photo_url})

QR per invoice tidak berubah selama umurnya (boleh di-cache). Invoice lama yang dibuat sebelum payload QRIS SennPayy disimpan mendapat QR statis fallback, sehingga pembayar ketik nominal manual. URL QR invoice paid/expired mengembalikan 404.

Bantuan developer

Kendala integrasi: support@sennpayy.biz.id (laporan dapat dikirim 24 jam). Sertakan external_id atau invoice ID, timestamp WIB, dan response error yang diterima agar dicek lebih cepat.