TemanQRIS

API QRIS TemanQRIS: Dokumentasi

REST API QRIS untuk mengubah QRIS statis menjadi QRIS dinamis dengan nominal custom, fee, dan payment link yang bisa dibagikan. Autentikasi memakai header X-API-Key.

Ada dua cara menerima pembayaran:

Manual

QRIS milik Anda sendiri. Dana langsung masuk ke rekening atau e-wallet Anda, lalu Anda (atau sistem Anda) memverifikasi pembayaran.

Otomatis (Payment Gateway)

TemanQRIS menerbitkan QRIS dengan kode unik, mencocokkan pembayaran sendiri, lalu mengirim webhook payment.confirmed. Dana masuk ke wallet TemanQRIS Anda.

Base URLhttps://temanqris.com
PrefixIsiAutentikasi
/api/qrisQRIS, payment link, order, penggunaan APIX-API-Key live atau JWT dashboard
/api/payment-gatewayPayment Gateway otomatis dan SandboxX-API-Key live, X-API-Key sandbox (tq_test_), atau JWT
/api/payHalaman bayar publik (status link, tombol Sudah Bayar)Tanpa autentikasi
/api/widgetWidget pembayaran yang dipasang di websiteTanpa autentikasi, memakai Merchant ID

Baru di v1.3.4: pembayaran gateway live tidak lagi memakai kuota harian

POST /api/payment-gateway/payments dengan key live sekarang dibatasi per menit (bawaan 60), bukan 50 atau 1.000 per hari. Kuota harian tetap berlaku untuk fitur QRIS manual. Lihat batasnya atau changelog.

Mulai dari sini

Quick StartDua jalur: QRIS milik Anda atau gateway otomatis. AutentikasiAPI key, sandbox key, dan arti setiap 401 dan 403. Buat pembayaran gatewaySatu request, QRIS dengan kode unik, konfirmasi otomatis. Verifikasi webhookHMAC-SHA256 dari raw body, contoh Node.js, PHP, Python.

Autentikasi

Hampir semua endpoint butuh autentikasi. Pengecualiannya endpoint publik untuk pelanggan: /api/pay/* (halaman bayar) dan /api/widget/* (widget). Ambil API key di Dashboard Settings.

CaraHeaderKapan dipakai
API key liveX-API-Key: YOUR_API_KEYIntegrasi server Anda. Key berupa 64 karakter heksadesimal.
API key sandboxX-API-Key: tq_test_...Hanya untuk Payment Gateway mode Sandbox. Lihat Mode Sandbox.
JWT dashboardAuthorization: Bearer YOUR_JWTSesi dashboard, atau server yang sudah memegang token login. Cookie tq_token dari dashboard juga diterima.

Aturan penting

  • API key hanya dibaca dari header X-API-Key, tidak pernah dari query string.
  • Panggil API dari backend. Endpoint /api/qris dan /api/payment-gateway memakai daftar origin CORS yang ketat, jadi panggilan dari browser di domain lain ditolak dengan 403 CORS: origin not allowed. Frontend cukup menerima URL pembayaran dari server Anda.
  • Sandbox key (tq_test_) hanya diterima di endpoint Payment Gateway (buat pembayaran, status, cek invoice sandbox, simulasi). Di endpoint lain key ini dianggap tidak dikenal (401).
  • Key disimpan dalam bentuk hash. Untuk melihat key lengkap, buka Dashboard Settings dan masukkan password. Membuat ulang (rotate) key juga meminta password dan key lama langsung berhenti bekerja.

Response saat gagal

StatusBodyArtinya
401{"error":"API key required (send it in the x-api-key header)"}Header X-API-Key tidak dikirim.
401{"error":"Invalid API key"}Key salah, sudah di-rotate, atau sandbox key dipakai di endpoint non-gateway.
401{"error":"Access token required"}JWT tidak dikirim.
403{"error":"Account is deactivated"}Akun dinonaktifkan.
403{"error":"Invalid or expired token"}JWT tidak valid atau kedaluwarsa (berlaku 7 hari).
403{"error":"CORS: origin not allowed"}Dipanggil dari browser di domain yang tidak diizinkan.

Keamanan API key

Jangan taruh key di frontend, aplikasi mobile, atau repository. Simpan di environment variable server. Kalau key bocor, rotate dari Dashboard Settings.

Contoh panggilan pertama (cek apakah key Anda bekerja):

curl https://temanqris.com/api/qris/my-qris \
  -H "X-API-Key: YOUR_API_KEY"

Quick Start

Pilih jalur yang paling cocok. Keduanya bisa dipakai bersamaan di satu akun.

Jalur Manual (QRIS milik Anda)

  1. Upload QRIS statis

    Upload gambar atau string QRIS statis Anda lewat POST /api/qris/upload. Cukup sekali.

  2. Buat QRIS dinamis

    Panggil POST /api/qris/generate atau POST /api/qris/payment-link dengan nominal dan order_id.

  3. Bagikan atau pasang

    Kirim link https://temanqris.com/p/{link_code} ke pelanggan, atau pasang widget di website.

  4. Verifikasi

    Setelah dana masuk ke rekening atau e-wallet Anda, panggil POST /api/qris/orders/:orderId/verify.

Jalur Otomatis (Payment Gateway)

  1. Coba di Sandbox

    Buka Payment Gateway, pindah ke Sandbox, lalu ambil key tq_test_. Tidak perlu KYC.

  2. Buat pembayaran

    POST /api/payment-gateway/payments dengan order_id, amount, dan header Idempotency-Key.

  3. Terima webhook

    Verifikasi signature, lalu tandai order lunas saat menerima payment.confirmed.

  4. Pindah ke Live

    Setelah KYC disetujui, ganti key dan webhook secret ke versi live. Endpoint dan kode Anda tetap sama.

Rate Limit dan Kuota

Kuota harian per tier

TierRequest per hari (bawaan)QRIS statis tersimpanFitur
Free501 (upload ulang akan mengganti QRIS lama)Fitur dasar
Premium1.000Sesuai paket (bawaan 100)Semua fitur dan dukungan prioritas

Kuota ini untuk fitur QRIS manual. Angka kuota bisa diubah admin. Angka yang berlaku untuk akun Anda selalu ada di GET /api/qris/usage dan di header response.

Endpoint yang memakai kuota harian

Endpoint baca seperti my-qris, render, payment-links, orders, usage, dan GET /api/payment-gateway/status tidak memakai kuota.

POST /api/payment-gateway/payments dengan key live (atau JWT dashboard) juga tidak memakai kuota harian. Setiap pembayaran gateway sudah dikenai biaya layanan, jadi batasnya per menit, bukan per hari. Lihat Batas Payment Gateway live. Panggilan itu tetap tercatat di statistik GET /api/qris/usage. Dengan key tq_test_, panggilan yang sama memakai kuota Sandbox.

Cara hitungnya

  • Kuota direset setiap hari pukul 00.00 UTC (07.00 WIB).
  • Request yang ditolak karena input salah (4xx) tetap dihitung. Hanya error server (5xx) yang dikembalikan ke kuota.
  • Setiap response yang memakai kuota membawa header:
HeaderIsi
X-RateLimit-LimitBatas harian Anda
X-RateLimit-RemainingSisa kuota hari ini
X-RateLimit-ResetWaktu reset dalam Unix timestamp (detik), akhir hari UTC

Saat kuota habis:

JSON
{
  "error": "Rate limit exceeded",
  "message": "You have exceeded your daily limit of 50 requests",
  "tier": "free",
  "limit": 50,
  "used": 50,
  "resetTime": "Midnight (server time)"
}

Status 429. Tunggu sampai reset, atau upgrade ke Premium.

Batas Payment Gateway live

Berlaku untuk POST /api/payment-gateway/payments dengan key live atau JWT dashboard, dan untuk Widget API dengan payment_mode: "gateway". Semua angka di bawah adalah nilai bawaan dan bisa diubah admin.

BatasNilai bawaanKalau terlewat
Invoice baru per menit60 per merchant per menit (khusus API, bukan widget)429 dengan code: "gateway_rate_limited" dan header Retry-After
Invoice yang masih terbuka50 per merchant429 dengan code: "gateway_open_limit"
Total nominal harian untuk akun yang baru lolos KYCTidak aktif. Kalau diaktifkan admin, berlaku selama 14 hari pertama setelah KYC disetujui403 dengan code: "new_account_daily_amount_cap"

Batas per menit

  • Dihitung per merchant dalam jendela satu menit UTC. Jendela baru dimulai setiap pergantian menit.
  • Semua request create dihitung, termasuk yang ditolak karena input salah (4xx) dan replay dengan Idempotency-Key yang sama. Hanya error server (5xx) yang dikembalikan.
  • Response yang lolos membawa header berikut. Angkanya untuk jendela per menit, bukan kuota harian:
HeaderIsi
X-RateLimit-LimitBatas invoice per menit Anda
X-RateLimit-RemainingSisa di menit ini
X-RateLimit-ResetAwal menit berikutnya dalam Unix timestamp (detik)

Saat batas terlewat, status 429 datang dengan header Retry-After (detik sampai menit berikutnya) dan tanpa header X-RateLimit-*:

JSON
{
  "error": "Too many gateway payments created in a short time. Try again shortly.",
  "code": "gateway_rate_limited",
  "limit": 60,
  "window_seconds": 60,
  "retry_after_seconds": 18
}

Tunggu sesuai Retry-After (sama dengan retry_after_seconds), lalu kirim ulang request yang sama dengan Idempotency-Key yang sama. Invoice tidak dibuat saat 429, jadi tidak ada yang dobel.

Batas nominal harian akun baru

  • Tidak aktif secara bawaan. Admin bisa mengaktifkannya dengan batas rupiah per hari.
  • Hanya berlaku untuk merchant yang KYC-nya disetujui kurang dari 14 hari (bawaan, bisa diatur 1 sampai 365 hari). Setelah itu batas ini tidak berlaku lagi.
  • Yang dijumlahkan adalah amount (nominal dasar) dari setiap invoice gateway live baru per tanggal UTC. Reset 00.00 UTC (07.00 WIB).
  • Replay dengan Idempotency-Key yang sama untuk invoice yang sudah ada tidak dihitung lagi dan tidak pernah ditolak oleh batas ini. Request yang gagal membuat invoice juga tidak dihitung.
  • used berisi total nominal yang sudah terpakai hari ini, belum termasuk request yang ditolak.
JSON
{
  "error": "Daily payment gateway amount limit reached for a newly verified account",
  "code": "new_account_daily_amount_cap",
  "limit": 5000000,
  "used": 4900000,
  "resetTime": "Midnight (UTC)"
}

Status 403. Jangan diulang di hari yang sama. Tunggu reset, buat invoice dengan nominal yang masih muat, atau pakai jalur manual. Di Widget API, body 403 ini hanya berisi error dan code.

Batas lain

BatasNilaiKalau terlewat
Ukuran body JSON10 KB413
Kuota Sandbox500 panggilan per hari, terpisah dari kuota live429 dengan "mode": "sandbox"
Cek invoice Sandbox120 per menit per merchant, tidak memakai kuota harian429 dengan code: "rate_limited"
Halaman bayar /p/:code60 per menit per IP429
GET /api/pay/:code120 per menit per IP429
POST /api/pay/:code/confirm30 per menit per IP429
POST /api/widget/generate60 per menit per IP. Mode manual juga memakai kuota harian tier merchant. Mode gateway tidak memakai kuota harian.429
POST /api/widget/confirm/:orderId30 per menit per IP429

Tips

Pantau pemakaian dengan GET /api/qris/usage, dan baca X-RateLimit-Remaining di setiap response untuk angka yang paling akurat.

Kode Error

Bentuk response error

Semua error dikirim sebagai JSON dengan field error (pesan). Ada tiga bentuk yang perlu Anda kenali:

Error Payment Gateway dan Sandbox selalu membawa code berupa string. Pakai code untuk logika program, jangan mencocokkan teks error.

JSON
{ "error": "fee amount must not exceed base amount", "code": "fee_exceeds_base" }

Error endpoint QRIS dan Payment Link (/api/qris/*) membawa error dan kadang message, tanpa code. Contoh:

JSON
{ "success": false, "error": "Order not found", "message": "No order found with order_id \"INV-999\" for your account." }

Error umum (JSON rusak, body terlalu besar, error server) membawa code berupa angka status HTTP:

JSON
{ "error": "Internal Server Error", "code": 500 }

Pesan error server (5xx) tidak pernah berisi detail internal. Kalau dapat 5xx, ulangi request yang sama. Untuk Payment Gateway, ulangi dengan Idempotency-Key yang sama supaya tidak membuat invoice ganda.

Tabel kode error

HTTPcodeEndpointArtinyaYang perlu dilakukan
400invalid_order_idGateway, Sandboxorder_id kosong atau lebih dari 30 karakter.Kirim order_id 1 sampai 30 karakter.
400missing_idempotency_keyGateway, SandboxHeader Idempotency-Key tidak dikirim.Tambahkan header.
400invalid_idempotency_keyGateway, SandboxKey kosong, lebih dari 256 karakter, atau ada karakter di luar ASCII yang bisa dicetak.Pakai key ASCII 1 sampai 256 karakter, misalnya INV-2026-0001-a1.
400invalid_amountGateway, Sandboxamount bukan bilangan bulat positif.Kirim angka bulat, misalnya 150000 atau "150000". Jangan pakai titik, koma, atau desimal.
400amount_too_largeGateway, Sandboxamount di atas Rp1.000.000.Pecah tagihan, atau pakai jalur manual.
400invalid_fee_amountGateway, Sandboxfee_amount bukan bilangan bulat 0 atau lebih.Kirim angka bulat.
400fee_exceeds_baseGateway, Sandboxfee_amount lebih besar dari amount.Turunkan fee, maksimal sama dengan amount.
400amount_below_provider_feeGateway, SandboxBiaya layanan gateway menghabiskan seluruh amount + fee_amount, merchant tidak menerima apa pun.Naikkan nominal. Biaya layanan 0,8% dari amount dibulatkan ke atas (minimal Rp1), jadi amount + fee_amount minimal Rp2.
400total_amount_too_large, gateway_total_exceeds_capGateway, Sandboxamount + fee_amount + kode unik melewati batas total (bawaan Rp1.000.999).Kurangi amount atau fee_amount.
400invalid_webhook_urlGateway, SandboxURL tidak valid, bukan HTTPS di production, host tidak ada, atau mengarah ke alamat non-publik.Pakai URL HTTPS publik.
400invalid_callback_urlGateway, Sandboxcallback_url bukan URL http(s) yang valid.Perbaiki URL.
400sandbox_invalid_resultSandbox simulasiresult bukan paid, expired, atau late_paid.Kirim salah satu nilai itu.
400amount_too_smallWidget API (gateway)Nominal terlalu kecil untuk pembayaran otomatis.Naikkan nominal.
400400 (angka)SemuaBody JSON rusak.Periksa JSON dan header Content-Type: application/json.
403KYC_REQUIREDGateway live, Widget API (gateway)KYC belum disetujui. Body juga berisi kyc_status.Selesaikan verifikasi di Dashboard Verifikasi. Sambil menunggu, pakai Sandbox.
403account_inactiveGateway, SandboxAkun merchant tidak aktif.Hubungi support.
403wrong_gateway_modeSandbox (cek, simulasi)Endpoint sandbox dipanggil dengan key live.Pakai key tq_test_.
403new_account_daily_amount_capGateway live, Widget API (gateway)Total nominal invoice hari ini sudah mencapai batas untuk akun yang baru lolos KYC. Body API berisi limit, used, dan resetTime.Jangan diulang hari ini. Tunggu reset 07.00 WIB, kecilkan nominal, atau pakai jalur manual.
404sandbox_payment_not_foundSandboxTidak ada invoice sandbox dengan order_id itu di akun Anda.Periksa order_id dan key yang dipakai.
409gateway_order_id_usedGateway, Sandboxorder_id sudah punya pembayaran (aktif, gagal, atau kedaluwarsa), atau dipakai pembayaran lain. Juga muncul saat key yang sama mengulang pembayaran yang sudah gagal atau kedaluwarsa.Buat pembayaran baru dengan order_id baru, misalnya INV-2026-0001-R2.
409idempotency_key_in_useGateway, SandboxKey yang sama sedang dipakai request lain untuk order ini.Kirim ulang request yang sama persis.
409gateway_creation_in_progressGatewayRequest pertama dengan key ini masih diproses.Tunggu 2 sampai 5 detik, lalu kirim ulang request yang sama.
409gateway_attempt_terminalWidget API (gateway)Pembayaran untuk idempotency_key ini sudah gagal atau kedaluwarsa.Pakai idempotency_key baru.
409sandbox_invalid_transitionSandbox simulasiInvoice sudah dibayar atau sudah kedaluwarsa, jadi hasil itu tidak berlaku.Pakai late_paid untuk invoice kedaluwarsa, atau buat invoice baru.
409sandbox_webhook_pending, sandbox_no_webhook_event, sandbox_no_webhook_url, sandbox_no_webhook_secretConsole Sandbox (kirim ulang webhook)Kirim ulang ditolak: webhook sebelumnya masih antre, belum ada simulasi, invoice tanpa webhook_url, atau secret sandbox belum bisa disiapkan.Tunggu, simulasikan dulu, atau buat invoice dengan webhook_url.
422idempotency_key_reusedGateway, SandboxKey yang sama sudah dipakai untuk request dengan isi berbeda.Kirim ulang isi request yang asli, atau pakai key baru.
429gateway_rate_limitedGateway liveTerlalu banyak invoice dibuat dalam satu menit (bawaan 60). Body berisi limit, window_seconds, dan retry_after_seconds.Tunggu sesuai header Retry-After, lalu kirim ulang request yang sama dengan Idempotency-Key yang sama.
429gateway_open_limitGatewayTerlalu banyak invoice gateway yang masih terbuka.Tunggu sebagian dibayar atau kedaluwarsa (1 jam).
429rate_limitedSandbox (cek invoice)Lebih dari 120 cek per menit.Perlambat polling, misalnya setiap 3 sampai 5 detik.
429(tanpa code)Endpoint QRIS yang memakai kuota, SandboxKuota harian habis (Rate limit exceeded). Kuota Sandbox membawa "mode": "sandbox".Tunggu reset 07.00 WIB atau upgrade.
503gateway_amount_busyGatewaySemua kode unik untuk nominal ini sedang dipakai invoice lain.Coba lagi beberapa menit lagi, atau ubah nominal sedikit.
503gateway_amount_reservation_lostGatewayPembayaran terlalu lama disiapkan dan reservasi nominal lepas.Buat pembayaran baru dengan order_id baru.
503provider_timeoutGatewayPenyedia pembayaran tidak menjawab dalam 20 detik. Tidak ada QR yang dibuat. Response berisi retryable: true.Buat pembayaran baru dengan order_id baru, misalnya INV-2026-0001-R2.
503webhook_dns_unavailableGateway, SandboxDNS sedang bermasalah saat memeriksa webhook_url.Kirim ulang request yang sama.
503server_busySemuaServer sedang sibuk sehingga API key belum bisa diperiksa. Ada header Retry-After.Kirim ulang request yang sama setelah jeda di Retry-After.
503upload_busyuploadBanyak gambar sedang diproses. Ada retry_after dan header Retry-After.Kirim ulang file yang sama setelah jeda itu.
503(tanpa code)GatewayPayment gateway mode is disabled by admin, atau gateway belum dikonfigurasi.Coba lagi nanti, pakai Sandbox, atau jalur manual.
503(tanpa code)Semua yang memakai kuota, GatewayRate limiter unavailable: kuota atau batas per menit sementara tidak bisa diperiksa.Ulangi beberapa detik lagi dengan request yang sama.
500500 (angka) atau tanpa codeSemuaError server.Ulangi request yang sama. Untuk gateway pakai Idempotency-Key yang sama lalu cek status order.
HTTPerrorEndpointYang perlu dilakukan
400QRIS string or image is required, Invalid QRIS format (+ details), Could not decode QR code..., File too large. Max size is 1.5MB, Image dimensions are unsupported or too largeuploadKirim QRIS statis yang jelas, JPG atau PNG, maksimal 1,5 MB dan 6000 px.
400Please upload a static QRIS code...uploadQRIS dinamis tidak bisa dijadikan template. Pakai QRIS statis dari bank atau e-wallet.
400Merchant limit reachedupload (Premium)Hapus salah satu QRIS di dashboard.
400Valid amount is required..., Amount is required and must be a whole number...generate, payment-linkamount bilangan bulat 1 sampai 100.000.000.
400Invalid fee_type..., Invalid fee_value, fee_type is required when fee_value is provided, Percent fee cannot exceed 100, Rupiah fee must be a whole numbergenerate, payment-linkPeriksa aturan fee di Generate QRIS.
400Order ID too long (max 30 chars), Order ID must be a stringgenerate, payment-linkPakai string 1 sampai 30 karakter.
400Only JPG and PNG images are alloweduploadKirim JPG atau PNG. Format lain (GIF, BMP, TIFF, WebP) ditolak.
400status must be one of: pending, awaiting_confirmation, paid, expired, cancelledordersPakai salah satu status itu, atau kosongkan status.
400Order ID already exists (+ existing_link_code)payment-linkOrder ini sudah punya link. Ambil statusnya dengan GET /orders/:orderId.
400Invalid webhook URL..., Webhook URL must use HTTPS, Invalid callback URL formatgenerate, payment-linkPakai URL HTTPS publik.
400Order already verified, Order expired, Order cancelledverifyOrder tidak bisa diverifikasi di status ini.
400Cannot cancel paid order, Order already cancelledcancelTidak perlu tindakan.
404No QRIS found... / No active QRIS found... (400 di payment-link)generate, payment-linkUpload QRIS statis dulu.
404Order not foundorders, verify, cancelPeriksa order_id.
404Payment link not found or unauthorizedDELETE payment-linkPakai id numerik dari response, bukan link_code.
409Order ID sudah dipakai untuk pembayaran gatewaygeneratePakai order_id lain untuk QRIS manual.
409Order ID sudah dibayar atau menunggu konfirmasigenerateNominal order yang sudah dibayar tidak bisa diubah. Pakai order_id baru.
409Gateway order requires automatic settlement reconciliationverifyOrder gateway dikonfirmasi otomatis. Jangan verifikasi manual.
409Order state changedcancelStatus berubah saat dibatalkan (misalnya baru saja dibayar). Cek ulang order.
409Paid or confirmed payment links cannot be removedDELETE payment-linkLink yang sudah dibayar atau menunggu konfirmasi tidak bisa diarsipkan.
503code: "webhook_dns_unavailable"generateDNS sedang bermasalah saat memeriksa webhook_url. Kirim ulang request yang sama.

MCP untuk agent AI

Hubungkan Claude, ChatGPT, Codex, Cursor, Gemini CLI, VS Code, Devin Desktop, atau agent AI lain ke akun TemanQRIS. Agent memanggil API yang sama lewat satu endpoint MCP, dengan aturan, KYC, kuota, dan rate limit yang sama dengan REST API.

Endpoint MCPhttps://temanqris.com/mcp

Endpoint memakai Streamable HTTP dan hanya menerima POST. Tidak ada sesi dan tidak ada stream SSE: agent mengirim pesan JSON-RPC dan membaca balasan JSON.

Ada dua cara menghubungkan:

API key

Tempel key di konfigurasi agent. Key sandbox (tq_test_) hanya melihat tool gateway sandbox, key live melihat tool QRIS, payment link, dan order.

Login (OAuth)

Tanpa menyalin key. Agent membuka halaman izin TemanQRIS, Anda memilih sandbox atau live, dan aksesnya bisa diputus kapan saja.

Yang dilihat agent mengikuti key atau login yang dipakai, jadi daftar tool selalu pas dengan haknya:

  • Key sandbox (tq_test_) dan login mode sandbox hanya melihat empat tool gateway sandbox. Tidak perlu KYC dan tidak ada uang sungguhan.
  • Key live dan login mode live melihat tool QRIS, payment link, order, dan penggunaan API. create_gateway_payment di live baru muncul setelah KYC Anda disetujui.
  • Hanya login mode live yang juga melihat tiga tool baca: get_wallet, list_withdrawals, dan get_kyc_status. Key API tidak pernah bisa.
  • Menarik saldo, mengunggah KYC, mengubah pengaturan, dan melihat key atau webhook secret tidak tersedia lewat MCP. Semuanya tetap di dashboard.

Mulai dari sandbox

Sandbox tidak menyentuh uang, saldo, atau order asli. Coba alurnya dulu bersama agent, baru ganti ke key atau login live.

Hubungkan dengan API key

  1. Ambil key sandbox

    Buka Payment Gateway di dashboard, pindah ke Sandbox, lalu salin key tq_test_. Tidak perlu KYC.

  2. Tambahkan server ke agent

    Pilih agent Anda di bawah dan salin konfigurasinya. Key dikirim di header X-API-Key atau Authorization: Bearer. JWT dashboard ditolak.

  3. Coba satu permintaan

    Misalnya: "Buat pembayaran sandbox Rp10.000, lalu simulasikan lunas." Agent memanggil create_gateway_payment, lalu sandbox_simulate_payment.

  4. Pindah ke live

    Ganti dengan key live (64 karakter heksadesimal) dari Settings di dashboard. Tool QRIS, payment link, dan order langsung muncul.

Claude Code (terminal). Ganti tq_test_... dengan key Anda:

claude mcp add --transport http temanqris https://temanqris.com/mcp \
  --header "X-API-Key: tq_test_..."

Supaya key tidak tersimpan di file konfigurasi, pakai .mcp.json di proyek. Claude Code mengisi ${TEMANQRIS_API_KEY} dari environment:

{
  "mcpServers": {
    "temanqris": {
      "type": "http",
      "url": "https://temanqris.com/mcp",
      "headers": {
        "X-API-Key": "${TEMANQRIS_API_KEY}"
      }
    }
  }
}

claude.ai di browser: buka Customize, Connectors, klik Add lalu Add custom connector. Isi URL https://temanqris.com/mcp, lalu tambahkan header X-API-Key dengan key Anda di bagian Request headers. Opsi Request headers masih beta dan belum tampil di semua akun. Kalau tidak ada, pakai login (OAuth) atau Claude Code.

Jangan commit key Anda

File konfigurasi agent bisa berisi key. Simpan key di environment variable (contoh di atas memakai TEMANQRIS_API_KEY) dan jangan masukkan ke repository. Kalau key bocor, buat key baru dari Settings di dashboard.

Hubungkan dengan login (OAuth)

Cukup berikan URL https://temanqris.com/mcp. Saat pertama dipakai, browser membuka halaman izin TemanQRIS: Anda masuk, memilih mode sandbox atau live (sandbox sudah terpilih), lalu klik Izinkan. Mode yang dipilih berlaku sampai akses diputus.

Claude Code: tambahkan tanpa header, lalu ketik /mcp di Claude Code dan pilih temanqris untuk login. Dari terminal, claude mcp login temanqris juga bisa.

claude mcp add --transport http temanqris https://temanqris.com/mcp

claude.ai di browser: Customize, Connectors, Add, Add custom connector. Isi URL https://temanqris.com/mcp, lanjutkan, lalu masuk ke TemanQRIS saat diminta.

Login mode live juga bisa membaca saldo wallet, riwayat penarikan, dan status KYC. Menarik saldo, mengubah pengaturan, dan melihat API key tidak pernah bisa.

Untuk memutus akses, buka Settings di dashboard, tab API & Webhook, kartu Aplikasi AI terhubung, lalu cabut aplikasinya. Aplikasi itu langsung kehilangan akses.

Detail untuk pembuat klien

  • Penemuan: /.well-known/oauth-protected-resource/mcp (RFC 9728), lalu /.well-known/oauth-authorization-server (RFC 8414). Endpoint: /oauth/authorize, /oauth/token, /oauth/register, /oauth/revoke.
  • PKCE S256 wajib, parameter resource harus https://temanqris.com/mcp, dan redirect_uri harus cocok persis dengan yang didaftarkan. Klien bersifat publik, tanpa client secret.
  • Klien mendaftar lewat client metadata document (client_id berupa URL HTTPS, dipakai Claude dan ChatGPT) atau dynamic client registration lewat POST /oauth/register (dipakai Cursor, Codex, Gemini CLI, dan VS Code).
  • Access token berawalan tqo_ dan berlaku 1 jam. Refresh token berlaku 30 hari dan berganti setiap dipakai. Memakai refresh token lama mencabut seluruh koneksi.

Tool yang tersedia

Daftar tool mengikuti key atau login Anda, jadi agent hanya melihat tool yang bisa dipakai. Setiap tool menjalankan kode route REST yang sama, jadi validasi, KYC, kuota, dan kode error identik. Daftar ini dibuat dari tool yang benar-benar terdaftar di server.

Tool dan endpointLiveSandboxSifat
get_gateway_statusGET /api/payment-gateway/statusYaYaBaca
get_my_qrisGET /api/qris/my-qrisYaTidakBaca
upload_static_qrisPOST /api/qris/uploadYaTidakTulis
render_qrisPOST /api/qris/renderYaTidakBaca
create_dynamic_qrisPOST /api/qris/generateYaTidakTulis
create_payment_linkPOST /api/qris/payment-linkYaTidakTulis
list_payment_linksGET /api/qris/payment-linksYaTidakBaca
archive_payment_linkDELETE /api/qris/payment-link/:idYaTidakDestruktif
list_ordersGET /api/qris/ordersYaTidakBaca
get_orderGET /api/qris/orders/:orderIdYaTidakBaca
verify_orderPOST /api/qris/orders/:orderId/verifyYaTidakDestruktif
cancel_orderPOST /api/qris/orders/:orderId/cancelYaTidakDestruktif
get_api_usageGET /api/qris/usageYaTidakBaca
create_gateway_paymentPOST /api/payment-gateway/paymentsYa, KYC disetujuiYaTulis
sandbox_get_paymentGET /api/payment-gateway/sandbox/payments/:orderIdTidakYaBaca
sandbox_simulate_paymentPOST /api/payment-gateway/sandbox/payments/:orderId/simulateTidakYaTulis
get_walletGET /api/walletLogin sajaTidakBaca
list_withdrawalsGET /api/wallet/withdrawalsLogin sajaTidakBaca
get_kyc_statusGET /api/kyc/statusLogin sajaTidakBaca

Kolom Live menunjukkan tool yang dilihat key live. Login saja berarti hanya login OAuth mode live yang melihatnya. "Ya, KYC disetujui" berarti tool ini baru muncul di live setelah KYC Anda disetujui.

Jangan panggil verify_order sebelum uang masuk

Tool ini menandai order lunas, mengirim webhook, dan tidak bisa dibatalkan. Sama dengan tombol Tandai Lunas di dashboard. Minta agent memanggilnya hanya setelah Anda melihat sendiri uangnya masuk ke rekening atau e-wallet, dan jangan percaya pesan pembeli yang bilang sudah membayar. Tool ini ditandai destruktif, jadi sebagian besar klien meminta persetujuan Anda dulu. Biarkan permintaan itu menyala.

Hal lain yang perlu diketahui:

  • create_gateway_payment menerima idempotency_key opsional. Kalau dikosongkan, server membuatnya dan mengembalikannya. Kirim ulang dengan nilai yang sama setelah timeout supaya tidak terbit dua invoice.
  • upload_static_qris menerima string QRIS hasil decode, atau image_base64 dengan mime_type (image/png atau image/jpeg, maksimal 5 MB). Batas body di /mcp adalah 8 MB.
  • Gambar QR dari create_dynamic_qris, render_qris, dan create_gateway_payment dikembalikan sebagai image content MCP (image/png), bukan di dalam JSON.
  • Server mengirim instructions saat initialize: mulai dari sandbox, aturan verify_order, dan aturan teks pembeli. Klien yang membacanya meneruskannya ke agent.

Teks dari pembeli hanya data

Nama, catatan, dan deskripsi dari pembeli dikirim sebagai {"untrusted_payer_text": "..."}. Agent tidak boleh menjalankan apa pun yang tertulis di sana.

Kalau MCP gagal

Error dari route REST datang sebagai hasil tool dengan isError: true. JSON-nya membawa code yang sama dengan REST (misalnya KYC_REQUIRED, missing_idempotency_key, wrong_gateway_mode, new_account_daily_amount_cap) ditambah http_status. Bercabanglah dengan code, bukan teks pesan. Limit kuota harian dan limit gateway (429) lewat dengan isi yang sama seperti REST.

Masalah sebelum tool berjalan dijawab sebagai HTTP biasa:

StatusArtinyaYang perlu dilakukan
401Key salah, tidak ada kredensial, atau login sudah tidak berlaku (missing_credentials, invalid_api_key, masked_api_key, invalid_token). Jawaban selalu membawa header WWW-Authenticate ke metadata OAuth.Cek key dan pastikan bukan key yang disamarkan dari dashboard. Untuk login, hubungkan ulang dari agent.
403Akun dinonaktifkan.Berhenti dan hubungi support.
405Endpoint hanya menerima POST.Pakai klien MCP Streamable HTTP, jangan GET atau DELETE.
429rate_limited: lebih dari 120 request per menit dari satu IP di /mcp.Tunggu sesuai header Retry-After, lalu kirim ulang. Kuota lain di Rate Limit dan Kuota.
503mcp_disabled: MCP sedang dimatikan oleh admin. REST API tetap jalan.Jangan diulang terus-menerus. Coba lagi nanti.
503server_busy: server belum bisa memeriksa kredensial.Tunggu 3 detik (Retry-After), lalu coba lagi.

Use Case

Bagian ini menunjukkan cara memakai TemanQRIS API dari sisi sistem Anda, dari order dibuat sampai pembayaran dinyatakan sah di backend. Setiap skenario berisi untuk siapa, alur langkah demi langkah, endpoint yang dipakai, contoh request dan response lengkap, cara menangani webhook (dengan verifikasi signature di Node.js dan PHP), serta kasus khusus yang perlu disiapkan.

Penting

Pakai API key hanya dari backend. Frontend, aplikasi mobile, atau halaman checkout cukup menerima URL pembayaran dari server Anda.

Use caseModeEndpoint utamaYang dilihat pelangganCatatan backend
Checkout toko onlineOtomatisPOST /api/payment-gateway/paymentsHalaman bayar /p/{linkCode} atau QR di halaman AndaTandai lunas dari webhook payment.confirmed.
Invoice via WhatsAppManualPOST /api/qris/payment-linkLink pembayaran di chatPakai nomor invoice sebagai order_id. Verifikasi setelah dana masuk.
Kasir dan UMKMManualPOST /api/qris/generateQR di layar kasirKasir menekan Lunas setelah notifikasi dana masuk.
Sandbox ke LiveOtomatisEndpoint gateway dengan key tq_test_Halaman bayar berlabel SANDBOXUji semua jalur sebelum memegang uang sungguhan.
Kedaluwarsa dan retryKeduanyaIdempotency-Key, GET /api/qris/orders/:orderIdTidak adaRetry tanpa invoice ganda, tangani bayar telat.
Widget di websiteManualwidget.jsTombol Bayar dengan QRISJangan percaya redirect, cek webhook atau API.
Top up dan tagihan SaaSOtomatisGateway + GET /api/qris/orders/:orderIdHalaman bayarTambah saldo pengguna sekali saja per pembayaran.
Banyak outletManual (Premium)qris_id, qris_data_idQR outlet masing-masingSatu akun, banyak QRIS statis.
Rekonsiliasi harianKeduanyaGET /api/qris/orders, GET /api/qris/payment-linksTidak adaCocokkan order lunas dengan catatan Anda.
Alur cURL lengkapManualSemua endpoint jalur manualLink pembayaranCoba seluruh alur dari terminal sebelum menulis kode.
Order dari WhatsApp, Telegram, atau CRMManual atau OtomatisPOST /api/qris/payment-link atau gatewayLink di chatSimpan link_code dan status order di sistem internal.

Siapkan sekali di awal (semua skenario)

  1. Simpan API key di environment variable server.

  2. Buat webhook secret di Dashboard Settings. Tanpa secret, TemanQRIS tidak mengirim webhook sama sekali.

  3. Buat tabel kecil webhook_events dengan kolom idempotency_key yang unik. Dipakai untuk membuang webhook duplikat.

  4. Untuk jalur manual: panggil GET /api/qris/my-qris. Kalau has_qris bernilai false, upload sekali via POST /api/qris/upload.

  5. Untuk jalur otomatis: cek GET /api/payment-gateway/status. Lanjut ke live hanya kalau gateway_access bernilai available.

Checkout toko online dengan gateway otomatis

Untuk siapa: toko online, marketplace kecil, atau aplikasi yang ingin pembayaran terkonfirmasi otomatis tanpa admin mengecek mutasi. Butuh KYC yang sudah disetujui.

Alur

  1. Pelanggan menekan Bayar. Backend Anda membuat order di database dengan status pending dan menyimpan Idempotency-Key untuk percobaan ini, misalnya INV-2026-0001-1. Simpan key sebelum request dikirim.

  2. Simpan dari response: payment_attempt_id, payment_link.linkCode, payment_link.totalAmount, payment_link.expiresAt, payment_link.net_amount.

  3. Arahkan pelanggan ke https://temanqris.com + payment_link.url, atau tampilkan payment_link.qr_image di halaman Anda bersama nominal totalAmount dan hitung mundur sampai expiresAt.

  4. Pelanggan membayar tepat sebesar totalAmount (sudah termasuk kode unik). QR berlaku 1 jam.

  5. TemanQRIS mencocokkan pembayaran, mengkreditkan wallet Anda (net_amount, tertahan sampai 00.00 WIB hari berikutnya), lalu mengirim webhook payment.confirmed.

  6. Endpoint webhook Anda memverifikasi signature, memastikan mode live, membuang duplikat, mencocokkan order_id dan total_amount, lalu menandai order lunas dalam satu transaksi database.

  7. Pelanggan bisa diarahkan ke callback_url. Halaman itu hanya menampilkan status dari database Anda sendiri, bukan dari parameter URL.

  8. Cadangan: kalau webhook belum masuk 5 menit setelah expiresAt, cek GET /api/qris/orders/INV-2026-0001.

Request

cURL
curl -X POST https://temanqris.com/api/payment-gateway/payments \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Idempotency-Key: INV-2026-0001-1" \
  -H "Content-Type: application/json" \
  -d '{
    "order_id": "INV-2026-0001",
    "amount": 150000,
    "fee_amount": 0,
    "title": "Pesanan INV-2026-0001",
    "description": "2 item, Toko Kopi Senja",
    "webhook_url": "https://tokokamu.id/webhooks/temanqris",
    "callback_url": "https://tokokamu.id/orders/INV-2026-0001/selesai"
  }'
Respons
201 CreatedContent-Type: application/json
{
  "success": true,
  "existing": false,
  "payment_mode": "gateway",
  "payment_attempt_id": "2de4a4d5-3b0e-4b7a-9a3e-4c9f7a2b1e55",
  "payment_link": {
    "id": 456,
    "linkCode": "aZ3kQ9mP2xLw",
    "orderId": "INV-2026-0001",
    "amount": 150000,
    "feeAmount": 0,
    "provider_fee_amount": 1200,
    "net_amount": 148800,
    "uniqueCode": 321,
    "totalAmount": 150321,
    "description": "2 item, Toko Kopi Senja",
    "expiresAt": "2026-10-17T03:15:00.000Z",
    "payable_until": "2026-10-17T04:15:00.000Z",
    "url": "/p/aZ3kQ9mP2xLw",
    "qr_image": "data:image/png;base64,iVBOR..."
  },
  "mode": "live"
}

Kode backend (Node.js, Express)

Node.js
const express = require('express');
const crypto = require('crypto');

const app = express();
const BASE = 'https://temanqris.com';

app.post('/checkout/:orderId/pay', express.json(), async (req, res) => {
  const order = await db.orders.find(req.params.orderId);          // order milik Anda
  const key = order.idempotency_key || `${order.id}-1`;
  await db.orders.update(order.id, { idempotency_key: key });       // simpan dulu

  const response = await fetch(`${BASE}/api/payment-gateway/payments`, {
    method: 'POST',
    headers: {
      'X-API-Key': process.env.TEMANQRIS_API_KEY,
      'Idempotency-Key': key,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      order_id: order.id,
      amount: order.subtotal,
      title: `Pesanan ${order.id}`,
      webhook_url: 'https://tokokamu.id/webhooks/temanqris',
      callback_url: `https://tokokamu.id/orders/${order.id}/selesai`
    })
  });
  const data = await response.json().catch(() => ({}));
  if (!response.ok) {
    return res.status(502).json({ error: data.code || `http_${response.status}` });
  }

  await db.orders.update(order.id, {
    attempt_id: data.payment_attempt_id,
    expected_total: data.payment_link.totalAmount,
    expires_at: data.payment_link.expiresAt
  });
  res.json({ pay_url: BASE + data.payment_link.url });
});

Webhook

function verifySignature(rawBody, header, secret) {
  const expected = 'sha256=' + crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
  if (typeof header !== 'string' || header.length !== expected.length) return false;
  return crypto.timingSafeEqual(Buffer.from(header), Buffer.from(expected));
}

app.post('/webhooks/temanqris', express.raw({ type: 'application/json' }), async (req, res) => {
  if (!verifySignature(req.body, req.get('X-TemanQRIS-Signature'), process.env.TEMANQRIS_WEBHOOK_SECRET)) {
    return res.status(401).json({ error: 'invalid signature' });
  }
  const event = JSON.parse(req.body.toString('utf8'));
  if (req.get('X-TemanQRIS-Mode') !== 'live' || event.data.mode !== 'live') {
    return res.status(400).json({ error: 'not a live webhook' });
  }
  if (event.event !== 'payment.confirmed' || event.data.payment_mode !== 'gateway') {
    return res.sendStatus(204);
  }
  try {
    await db.transaction(async (tx) => {
      const isNew = await tx.webhookEvents.insertIgnore(event.idempotency_key); // kolom unik
      if (!isNew) return;                                                      // duplikat
      const order = await tx.orders.findForUpdate(event.data.order_id);
      if (!order || order.expected_total !== event.data.total_amount) {
        await tx.anomalies.insert({ event });                                  // selidiki manual
        return;
      }
      if (order.status !== 'paid') {
        await tx.orders.update(order.id, {
          status: 'paid',
          paid_at: event.data.paid_at,
          net_amount: event.data.net_amount
        });
      }
    });
    res.sendStatus(204);
  } catch (err) {
    console.error(err);
    res.sendStatus(500); // TemanQRIS akan mengirim ulang
  }
});

Kasus khusus

KejadianYang terjadiYang perlu Anda lakukan
Request create timeoutAnda tidak tahu invoice sudah dibuat atau belum.Kirim ulang request yang sama dengan key yang sama. Anda akan mendapat 200 dengan existing: true dan invoice yang sama.
503 provider_timeoutPenyedia pembayaran sedang lambat. TemanQRIS berhenti menunggu di detik ke-20 dan tidak membuat QR.Tampilkan "Coba lagi" ke pelanggan, lalu buat percobaan baru dengan order_id baru.
409 gateway_creation_in_progressRequest pertama masih diproses.Tunggu 2 sampai 5 detik, kirim ulang yang sama.
403 KYC_REQUIREDKYC belum disetujui.Tampilkan metode bayar lain, atau pakai jalur manual sementara.
503 gateway_amount_busySemua kode unik untuk nominal itu sedang dipakai.Coba lagi beberapa menit kemudian. Jangan ganti order_id hanya karena ini.
Pelanggan membayar nominal berbedaPembayaran tidak cocok dengan invoice mana pun dan masuk antrean tinjauan admin.Minta pelanggan menghubungi support dengan bukti transfer. Jangan membuat invoice baru dengan nominal yang ditebak.
Pelanggan membayar setelah QR kedaluwarsaMasih dicocokkan selama masa tenggang (1 jam setelah kedaluwarsa). Webhook tetap payment.confirmed.Jangan anggap order gagal sebelum payable_until (expiresAt + 1 jam). Lihat Kedaluwarsa dan retry.
Webhook Anda sedang matiDikirim ulang 3 kali (30 detik, 2 menit, 10 menit). Setelah itu admin diberi tahu.Jalankan polling cadangan GET /api/qris/orders/:orderId untuk order yang masih menunggu.
Webhook datang dua kaliKunci idempotency_key sama.Tabel webhook_events membuang duplikat.
Pelanggan minta refundRefund tidak tersedia lewat API.Hubungi support. Kalau refund dilakukan di sisi penyedia, admin meninjau dan menarik kembali dana dari saldo Anda (saldo tertahan dulu, lalu saldo tersedia).
callback_url dibuka tanpa bayarSiapa pun bisa membuka URL itu.Halaman callback hanya membaca status dari database Anda.

Invoice lewat payment link yang dibagikan di WhatsApp

Untuk siapa: freelancer, agency, jasa, toko yang menerima order lewat chat. Memakai QRIS Anda sendiri (jalur manual), jadi dana langsung masuk ke rekening atau e-wallet Anda tanpa potongan TemanQRIS.

Alur

  1. Admin atau bot membuat invoice di sistem Anda, misalnya INV-0815.

  2. Backend memanggil POST /api/qris/payment-link dengan order_id = nomor invoice, description, webhook_url, dan callback_url (opsional).

  3. Simpan payment_link.id dan payment_link.link_code. Kalau existing bernilai true, invoice ini sudah punya link aktif dengan nominal dan fee yang sama, dan link itulah yang dikembalikan.

  4. Kirim https://temanqris.com + payment_link.url ke pelanggan lewat WhatsApp.

  5. Pelanggan membuka link, scan QR, membayar, lalu menekan Sudah Bayar.

  6. Status menjadi awaiting_confirmation. TemanQRIS mengirim webhook payment.awaiting_confirmation dan email ke Anda.

  7. Admin mengecek mutasi rekening atau e-wallet. Kalau dana masuk dengan nominal yang benar, backend memanggil POST /api/qris/orders/INV-0815/verify.

  8. Status menjadi paid dan webhook payment.confirmed terkirim. Kirim konfirmasi ke pelanggan.

Request

cURL
curl -X POST https://temanqris.com/api/qris/payment-link \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 750000,
    "description": "Desain logo, invoice INV-0815",
    "order_id": "INV-0815",
    "webhook_url": "https://studiokamu.id/webhooks/temanqris",
    "callback_url": "https://studiokamu.id/terima-kasih"
  }'
Respons
200 OKContent-Type: application/json
{
  "success": true,
  "payment_link": {
    "id": 812,
    "link_code": "K7QPMX4TRB2N",
    "order_id": "INV-0815",
    "url": "/p/K7QPMX4TRB2N",
    "amount": 750000,
    "fee_type": "none",
    "fee_value": 0,
    "fee_amount": 0,
    "total_amount": 750000,
    "description": "Desain logo, invoice INV-0815",
    "merchant_name": "STUDIO KAMU",
    "webhook_url": "https://studiokamu.id/webhooks/temanqris",
    "callback_url": "https://studiokamu.id/terima-kasih",
    "expires_at": "2026-10-18T03:00:00.000Z",
    "qr_image": "data:image/png;base64,iVBOR..."
  }
}

Contoh pesan WhatsApp: Halo Kak, tagihan INV-0815 sebesar Rp750.000 bisa dibayar lewat QRIS di sini: https://temanqris.com/p/K7QPMX4TRB2N. Link berlaku sampai 18 Okt 10.00 WIB.

Verifikasi setelah dana masuk

cURL
curl -X POST https://temanqris.com/api/qris/orders/INV-0815/verify \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "payer_name": "Budi Santoso", "payer_note": "Masuk BCA 10.12 WIB" }'

Webhook

const express = require('express');
const crypto = require('crypto');
const app = express();

function verifySignature(rawBody, header, secret) {
  const expected = 'sha256=' + crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
  if (typeof header !== 'string' || header.length !== expected.length) return false;
  return crypto.timingSafeEqual(Buffer.from(header), Buffer.from(expected));
}

app.post('/webhooks/temanqris', express.raw({ type: 'application/json' }), async (req, res) => {
  if (!verifySignature(req.body, req.get('X-TemanQRIS-Signature'), process.env.TEMANQRIS_WEBHOOK_SECRET)) {
    return res.sendStatus(401);
  }
  const event = JSON.parse(req.body.toString('utf8'));
  if (req.get('X-TemanQRIS-Mode') !== 'live' || event.data.mode !== 'live') return res.sendStatus(400);
  if (!(await db.webhookEvents.insertIgnore(event.idempotency_key))) return res.sendStatus(204);

  const { order_id: orderId, amount } = event.data; // amount = nominal dasar, tanpa fee
  if (event.event === 'payment.awaiting_confirmation') {
    await db.invoices.update(orderId, { status: 'cek_mutasi' });
    await notifyFinance(`Pelanggan bilang sudah bayar ${orderId} sebesar Rp${amount}. Cek mutasi.`);
  }
  if (event.event === 'payment.confirmed') {
    await db.invoices.update(orderId, { status: 'lunas', paid_at: event.data.paid_at });
    await sendWhatsApp(orderId, 'Pembayaran diterima. Terima kasih!');
  }
  res.sendStatus(204);
});

Kasus khusus

KejadianYang perlu Anda lakukan
Response existing: trueInvoice ini sudah punya link aktif dengan nominal dan fee yang sama. Kirim ulang link itu. Link milik invoice lain tidak pernah dipakai ulang.
400 Order ID already existsInvoice ini sudah punya link. Ambil link dan statusnya dengan GET /api/qris/orders/INV-0815, kirim ulang link lama.
Link kedaluwarsa sebelum dibayarLink berlaku 24 jam (Free) atau 7 hari (Premium). Untuk memperpanjang, panggil POST /api/qris/generate dengan order_id dan nominal yang sama. Link yang sama aktif lagi dengan masa berlaku baru. Kirim ulang webhook_url dan callback_url, karena nilai yang tidak dikirim akan dikosongkan.
Pelanggan menekan Sudah Bayar padahal belumStatus tetap awaiting_confirmation. Jangan verifikasi sebelum dana terlihat di mutasi. Kalau tidak pernah masuk, batalkan dengan POST /api/qris/orders/INV-0815/cancel.
Pelanggan transfer kurang atau lebihQR dinamis mengunci nominal, tapi transfer manual bisa berbeda. Selesaikan dengan pelanggan, lalu verifikasi atau batalkan.
Invoice dibatalkanPOST /api/qris/orders/INV-0815/cancel. Link tidak bisa dibayar lagi lewat halaman bayar.
Order sudah paidMemanggil POST /api/qris/generate lagi dengan isi yang sama aman: order dikembalikan dengan existing: true dan status tetap paid. Nominal atau fee berbeda ditolak 409.
Mau konfirmasi otomatisPakai gateway, tapi buat invoice gateway hanya saat pelanggan siap membayar (QR gateway berlaku 1 jam), misalnya saat pelanggan membalas "BAYAR" di chat.

Kasir toko dan UMKM dengan QRIS dinamis

Untuk siapa: kasir toko, warung, kafe, atau aplikasi POS yang ingin QR dengan nominal pas untuk setiap transaksi, tanpa pelanggan mengetik nominal sendiri. Jalur manual, dana masuk langsung ke QRIS Anda.

Alur

  1. Kasir menyelesaikan keranjang di POS. POS punya nomor transaksi, misalnya POS-0817-0042.

  2. POS memanggil POST /api/qris/generate dengan amount dan order_id.

  3. Tampilkan qr_image di layar pelanggan, tablet, atau cetak di struk. Tampilkan juga total_amount.

  4. Pelanggan scan dan membayar. Nominal sudah terkunci di QR.

  5. Kasir melihat notifikasi dana masuk di aplikasi bank atau e-wallet merchant dengan nominal yang sama.

  6. Kasir menekan Lunas di POS. POS memanggil POST /api/qris/orders/POS-0817-0042/verify.

  7. Kalau pelanggan batal, POS memanggil POST /api/qris/orders/POS-0817-0042/cancel.

  8. Tutup kasir: tarik GET /api/qris/orders?status=paid untuk laporan harian.

Request

cURL
curl -X POST https://temanqris.com/api/qris/generate \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 48500,
    "order_id": "POS-0817-0042",
    "webhook_url": "https://pos.kopisenja.id/webhooks/temanqris"
  }'
Respons
200 OKContent-Type: application/json
{
  "success": true,
  "qris": "00020101021226...6304A1B2",
  "qr_image": "data:image/png;base64,iVBOR...",
  "amount": 48500,
  "fee": null,
  "fee_amount": 0,
  "total_amount": 48500,
  "expires_at": "2026-10-18T03:20:00.000Z",
  "payment_link": {
    "id": 9031,
    "link_code": "R2TNQ8MKXH5P",
    "order_id": "POS-0817-0042",
    "url": "/p/R2TNQ8MKXH5P",
    "amount": 48500,
    "fee_type": "none",
    "fee_value": 0,
    "fee_amount": 0,
    "total_amount": 48500,
    "merchant_name": "KOPI SENJA",
    "webhook_url": "https://pos.kopisenja.id/webhooks/temanqris",
    "callback_url": null,
    "expires_at": "2026-10-18T03:20:00.000Z"
  }
}

Tombol Lunas di POS

cURL
curl -X POST https://temanqris.com/api/qris/orders/POS-0817-0042/verify \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "payer_note": "Dicek kasir Rina, notifikasi GoPay Merchant 10.21" }'
Respons
200 OKContent-Type: application/json
{
  "success": true,
  "message": "Payment verified successfully",
  "order": {
    "order_id": "POS-0817-0042",
    "amount": 48500,
    "status": "paid",
    "paid_at": "2026-10-17T03:21:04.000Z",
    "confirmed_by": "api"
  }
}

Webhook untuk server pusat (Node.js)

Berguna kalau beberapa kasir melapor ke satu server laporan. Event yang masuk adalah payment.confirmed setelah verify, atau payment.awaiting_confirmation kalau pelanggan membuka link dan menekan Sudah Bayar.

Node.js
const express = require('express');
const crypto = require('crypto');
const app = express();

function verifySignature(rawBody, header, secret) {
  const expected = 'sha256=' + crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
  if (typeof header !== 'string' || header.length !== expected.length) return false;
  return crypto.timingSafeEqual(Buffer.from(header), Buffer.from(expected));
}

app.post('/webhooks/temanqris', express.raw({ type: 'application/json' }), async (req, res) => {
  if (!verifySignature(req.body, req.get('X-TemanQRIS-Signature'), process.env.TEMANQRIS_WEBHOOK_SECRET)) {
    return res.sendStatus(401);
  }
  const event = JSON.parse(req.body.toString('utf8'));
  if (req.get('X-TemanQRIS-Mode') !== 'live' || event.data.mode !== 'live') return res.sendStatus(400);
  if (event.event === 'payment.confirmed' && (await db.webhookEvents.insertIgnore(event.idempotency_key))) {
    await db.sales.markPaid(event.data.order_id, event.data.paid_at);
  }
  res.sendStatus(204);
});

Webhook untuk server pusat (PHP)

PHP
<?php
$raw = file_get_contents('php://input');
$expected = 'sha256=' . hash_hmac('sha256', $raw, getenv('TEMANQRIS_WEBHOOK_SECRET'));
if (!hash_equals($expected, $_SERVER['HTTP_X_TEMANQRIS_SIGNATURE'] ?? '')) {
    http_response_code(401);
    exit;
}
$event = json_decode($raw, true);
if (($_SERVER['HTTP_X_TEMANQRIS_MODE'] ?? '') !== 'live' || ($event['data']['mode'] ?? '') !== 'live') {
    http_response_code(400);
    exit;
}
if ($event['event'] === 'payment.confirmed') {
    $pdo = new PDO(getenv('DB_DSN'), getenv('DB_USER'), getenv('DB_PASS'), [PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION]);
    $ins = $pdo->prepare('INSERT IGNORE INTO webhook_events (idempotency_key) VALUES (?)');
    $ins->execute([$event['idempotency_key']]);
    if ($ins->rowCount() === 1) {
        $pdo->prepare("UPDATE sales SET status = 'paid', paid_at = NOW() WHERE pos_no = ?")
            ->execute([$event['data']['order_id']]);
    }
}
http_response_code(204);

Kasus khusus

KejadianYang perlu Anda lakukan
Dua pelanggan membayar nominal sama di waktu berdekatanJalur manual tidak membedakan pembayaran dengan nominal sama. Cocokkan dengan jam notifikasi atau nama pembayar. Kalau sering terjadi, pakai gateway yang menambahkan kode unik.
Kasir salah menekan LunasTidak ada endpoint untuk membatalkan verifikasi. Tekan Lunas hanya setelah notifikasi dana terlihat.
Pelanggan pergi sebelum bayarPOST /api/qris/orders/:orderId/cancel.
Kuota harian habis di jam ramaiFree hanya 50 request per hari dan setiap QR memakai satu. Toko aktif sebaiknya Premium (1.000 per hari). Pantau X-RateLimit-Remaining.
Mau membebankan biaya tambahanKirim fee_type (rupiah atau percent) dan fee_value. Pelanggan membayar total_amount.
Internet kasir matiSediakan QRIS statis cetak sebagai cadangan. Pelanggan mengetik nominal sendiri, kasir mencatat manual.
Retry generate karena timeoutAman. order_id dan nominal yang sama mengembalikan link yang sama. Kalau order sudah paid, response berisi existing: true dan status tetap paid.

Uji di Sandbox, lalu checklist go live

Untuk siapa: developer yang membangun integrasi gateway. Sandbox tidak butuh KYC, tidak memakai uang sungguhan, dan tidak menyentuh saldo.

Alur

  1. Buka Payment Gateway, pindah ke Sandbox. Tampilkan sandbox key (tq_test_...) dan webhook secret sandbox (whsec_test_...) dengan password.

  2. Simpan keduanya di environment server uji: TEMANQRIS_API_KEY=tq_test_..., TEMANQRIS_WEBHOOK_SECRET=whsec_test_..., TEMANQRIS_EXPECTED_MODE=sandbox.

  3. Buat invoice dengan POST /api/payment-gateway/payments memakai sandbox key. Response berisi "mode": "sandbox" dan url berbentuk /p/sb_....

  4. Buka halaman bayar. Ada label SANDBOX, jangan dibayar. QR sengaja tidak bisa dibayar.

  5. Simulasikan hasil: POST /api/payment-gateway/sandbox/payments/:order_id/simulate dengan {"result":"paid"}, atau tombol di halaman bayar.

  6. Webhook payment.confirmed masuk sekitar satu menit kemudian dengan X-TemanQRIS-Mode: sandbox, ditandatangani dengan secret sandbox.

  7. Ulangi untuk expired dan late_paid, lalu uji kasus error dan duplikat (lihat checklist).

Request

cURL
curl -X POST https://temanqris.com/api/payment-gateway/payments \
  -H "X-API-Key: tq_test_KEY_SANDBOX_ANDA" \
  -H "Idempotency-Key: TEST-0001-1" \
  -H "Content-Type: application/json" \
  -d '{
    "order_id": "TEST-0001",
    "amount": 150000,
    "webhook_url": "https://staging.tokokamu.id/webhooks/temanqris"
  }'
Respons
201 CreatedContent-Type: application/json
{
  "success": true,
  "existing": false,
  "payment_mode": "gateway",
  "payment_attempt_id": "7b0f3c2e-9a41-4d5e-8c3b-1f2e3d4c5b6a",
  "payment_link": {
    "id": 31,
    "linkCode": "sb_Xk2mQ9aZ3pLw7RtY",
    "orderId": "TEST-0001",
    "amount": 150000,
    "feeAmount": 0,
    "provider_fee_amount": 1200,
    "net_amount": 148800,
    "uniqueCode": 87,
    "totalAmount": 150087,
    "description": null,
    "expiresAt": "2026-10-17T03:15:00.000Z",
    "payable_until": "2026-10-17T04:15:00.000Z",
    "url": "/p/sb_Xk2mQ9aZ3pLw7RtY",
    "qr_image": "data:image/png;base64,iVBOR..."
  },
  "mode": "sandbox",
  "paid_late": false
}

Simulasi bayar

cURL
curl -X POST https://temanqris.com/api/payment-gateway/sandbox/payments/TEST-0001/simulate \
  -H "X-API-Key: tq_test_KEY_SANDBOX_ANDA" \
  -H "Content-Type: application/json" \
  -d '{"result":"paid"}'
Respons
200 OKContent-Type: application/json
{
  "success": true,
  "existing": true,
  "payment_mode": "gateway",
  "payment_attempt_id": "7b0f3c2e-9a41-4d5e-8c3b-1f2e3d4c5b6a",
  "payment_link": { "linkCode": "sb_Xk2mQ9aZ3pLw7RtY", "orderId": "TEST-0001", "totalAmount": 150087, "...": "..." },
  "mode": "sandbox",
  "paid_late": false,
  "changed": true,
  "webhook_queued": true,
  "webhook_reason": null,
  "status": "paid",
  "paid_at": "2026-10-17T03:05:41.000Z"
}

Webhook sandbox yang diterima

JSON
{
  "event": "payment.confirmed",
  "idempotency_key": "3b1c9d2e-4f5a-4b6c-8d7e-9f0a1b2c3d4e",
  "timestamp": "2026-10-17T03:06:12.000Z",
  "data": {
    "order_id": "TEST-0001",
    "link_code": "sb_Xk2mQ9aZ3pLw7RtY",
    "amount": 150000,
    "description": null,
    "status": "paid",
    "paid_at": "2026-10-17T03:05:41.000Z",
    "created_at": "2026-10-17T03:00:02.000Z",
    "mode": "sandbox",
    "payment_mode": "gateway",
    "payment_attempt_id": "7b0f3c2e-9a41-4d5e-8c3b-1f2e3d4c5b6a",
    "base_amount": 150000,
    "fee_amount": 0,
    "unique_code": 87,
    "total_amount": 150087,
    "provider_fee_amount": 1200,
    "net_amount": 148800,
    "confirmed_by": "gateway",
    "paid_late": false
  }
}

Satu handler untuk dua lingkungan (Node.js)

Mode yang diharapkan diatur lewat environment, jadi kode yang sama aman dipakai di staging (sandbox) dan production (live).

Node.js
const express = require('express');
const crypto = require('crypto');
const app = express();
const EXPECTED_MODE = process.env.TEMANQRIS_EXPECTED_MODE || 'live'; // 'sandbox' hanya di staging

function verifySignature(rawBody, header, secret) {
  const expected = 'sha256=' + crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
  if (typeof header !== 'string' || header.length !== expected.length) return false;
  return crypto.timingSafeEqual(Buffer.from(header), Buffer.from(expected));
}

app.post('/webhooks/temanqris', express.raw({ type: 'application/json' }), async (req, res) => {
  if (!verifySignature(req.body, req.get('X-TemanQRIS-Signature'), process.env.TEMANQRIS_WEBHOOK_SECRET)) {
    return res.sendStatus(401);
  }
  const event = JSON.parse(req.body.toString('utf8'));
  if (req.get('X-TemanQRIS-Mode') !== EXPECTED_MODE || event.data.mode !== EXPECTED_MODE) {
    return res.sendStatus(400); // production menolak sandbox, staging menolak live
  }
  if (!(await db.webhookEvents.insertIgnore(event.idempotency_key))) return res.sendStatus(204);
  if (event.event === 'payment.confirmed') {
    await db.orders.markPaid(event.data.order_id, {
      total: event.data.total_amount,
      late: event.data.paid_late === true
    });
  }
  res.sendStatus(204);
});

Satu handler untuk dua lingkungan (PHP)

PHP
<?php
$expectedMode = getenv('TEMANQRIS_EXPECTED_MODE') ?: 'live';
$raw = file_get_contents('php://input');
$expected = 'sha256=' . hash_hmac('sha256', $raw, getenv('TEMANQRIS_WEBHOOK_SECRET'));
if (!hash_equals($expected, $_SERVER['HTTP_X_TEMANQRIS_SIGNATURE'] ?? '')) {
    http_response_code(401);
    exit;
}
$event = json_decode($raw, true);
if (($_SERVER['HTTP_X_TEMANQRIS_MODE'] ?? '') !== $expectedMode || ($event['data']['mode'] ?? '') !== $expectedMode) {
    http_response_code(400);
    exit;
}
$pdo = new PDO(getenv('DB_DSN'), getenv('DB_USER'), getenv('DB_PASS'), [PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION]);
$ins = $pdo->prepare('INSERT IGNORE INTO webhook_events (idempotency_key) VALUES (?)');
$ins->execute([$event['idempotency_key']]);
if ($ins->rowCount() === 1 && $event['event'] === 'payment.confirmed') {
    $pdo->prepare("UPDATE orders SET status = 'paid', paid_at = NOW() WHERE id = ?")
        ->execute([$event['data']['order_id']]);
}
http_response_code(204);

Checklist sebelum go live

Uji di sandbox:

  • Invoice baru mengembalikan 201, dan request ulang dengan key dan isi yang sama mengembalikan 200 dengan existing: true.
  • Key yang sama dengan isi berbeda (misalnya amount lain) ditangani sebagai bug: 422 idempotency_key_reused.
  • order_id yang sudah kedaluwarsa memakai order_id baru (409 gateway_order_id_used).
  • result: "paid" membuat order lunas tepat sekali.
  • Tombol Kirim ulang webhook di console tidak membuat order diproses dua kali (idempotency key sama).
  • result: "expired" membuat order Anda kedaluwarsa, tapi tetap bisa menerima bayar telat.
  • result: "late_paid" membuat order lunas walau sudah ditandai kedaluwarsa.
  • Signature salah ditolak dengan 401. Body diverifikasi dalam bentuk mentah (raw), bukan JSON yang diserialisasi ulang.
  • Error dibaca dari field code, bukan dari teks error.
  • Endpoint webhook membalas 2xx dalam kurang dari 10 detik.

Pindah ke live:

  • KYC disetujui: GET /api/payment-gateway/status dengan key live menunjukkan gateway_access: "available" dan enabled: true.
  • Webhook secret live sudah dibuat di Dashboard Settings.
  • Production memakai key live dan webhook secret live. Key tq_test_ dan whsec_test_ tidak ada di server production.
  • Handler production hanya menerima X-TemanQRIS-Mode: live dan data.mode: "live".
  • webhook_url live memakai HTTPS dan bisa dijangkau dari internet.
  • Ada polling cadangan GET /api/qris/orders/:orderId untuk order yang tertunda.
  • Tim tahu bahwa dana masuk sebagai saldo tertahan dan bisa ditarik mulai 00.00 WIB hari berikutnya.

Kasus khusus

KejadianYang perlu Anda lakukan
403 wrong_gateway_modeEndpoint simulasi dan cek invoice sandbox butuh key tq_test_.
401 Invalid API key dengan key tq_test_Sandbox key hanya diterima di endpoint Payment Gateway. Endpoint /api/qris/* butuh key live.
Webhook sandbox tidak datangLihat webhook_reason di response simulasi: no_webhook_url (invoice tanpa webhook_url) atau no_webhook_secret.
Dua invoice sandbox punya total samaNormal. Kode unik sandbox diacak tanpa reservasi. Di live, total selalu unik.
429 dengan "mode": "sandbox"Kuota 500 per hari habis. Reset 00.00 UTC. Polling cek invoice tidak memakai kuota ini.
order_id sama di sandbox dan liveBoleh. Keduanya terpisah.

Kedaluwarsa, bayar telat, dan retry aman dengan Idempotency-Key

Untuk siapa: semua integrasi gateway, dan integrasi manual yang perlu tahan terhadap timeout jaringan.

Konsep

  • Idempotency-Key menjawab pertanyaan "request ini sudah pernah diproses atau belum". Key dihitung bersama akun dan order_id, disimpan sebagai hash, dan mengingat isi request pertama (amount, fee_amount, order_id, title, description, webhook_url, callback_url).
  • order_id hanya bisa punya satu pembayaran gateway, apa pun hasilnya. Untuk mencoba lagi setelah gagal atau kedaluwarsa, pakai order_id baru.
  • QR gateway berlaku 1 jam. Setelah itu halaman bayar menampilkan kedaluwarsa, tapi pembayaran yang dilakukan dalam masa tenggang (1 jam setelah kedaluwarsa) tetap dicocokkan dan dikreditkan. Jadi order baru final setelah expiresAt + 1 jam.

Alur retry yang aman

  1. Sebelum memanggil API, simpan di database: order_id, nomor percobaan (misalnya 1), dan Idempotency-Key (misalnya INV-2026-0001-1).

  2. Kirim request. Kalau ada timeout, error jaringan, 5xx, atau 409 gateway_creation_in_progress, ulangi request yang sama dengan key yang sama memakai backoff (1 detik, 2 detik, 4 detik, maksimal 5 kali).

  3. 200 dengan existing: true berarti invoice sudah ada. Pakai datanya seperti response 201.

  4. Kalau invoice kedaluwarsa dan pelanggan ingin mencoba lagi, tunggu sampai payable_until lewat kalau memungkinkan, lalu buat percobaan baru: order_id INV-2026-0001-R2, key INV-2026-0001-R2-1.

  5. Tandai order Anda "kedaluwarsa final" hanya setelah payable_until lewat tanpa webhook (expiresAt + 1 jam). Sebelum itu, statusnya "menunggu, mungkin bayar telat".

Cara membaca status setiap respons

ResponsArtiTindakan
201Invoice baru dibuat.Simpan dan tampilkan.
200 + existing: trueInvoice yang sama dari request sebelumnya.Pakai, jangan buat lagi.
Timeout, error jaringan, 500, 503 webhook_dns_unavailableHasil tidak pasti.Ulangi dengan key dan isi yang sama.
409 gateway_creation_in_progressMasih diproses.Tunggu, ulangi yang sama.
409 idempotency_key_in_useRequest paralel dengan key yang sama.Ulangi yang sama setelah jeda singkat.
422 idempotency_key_reusedIsi berbeda untuk key yang sama. Ini bug di kode Anda.Jangan retry otomatis. Perbaiki pembuatan key atau isi request.
409 gateway_order_id_usedorder_id sudah terpakai.Kalau invoice lama masih berlaku, pakai itu (cek GET /api/qris/orders/:orderId). Kalau sudah gagal atau kedaluwarsa, pakai order_id baru.
503 gateway_amount_busyKode unik untuk nominal ini habis sementara.Ulangi beberapa menit kemudian.
503 gateway_amount_reservation_lostPercobaan ini gagal disiapkan.Buat percobaan baru dengan order_id baru.
503 provider_timeoutPenyedia lambat, tidak ada QR yang dibuat.Buat percobaan baru dengan order_id baru.
400 / 403 lainInput atau akun bermasalah.Jangan retry. Perbaiki penyebabnya.

Retry wrapper

const RETRYABLE = new Set(['gateway_creation_in_progress', 'idempotency_key_in_use', 'webhook_dns_unavailable']);
// Percobaan ini sudah gagal di server. Key yang sama hanya akan dijawab 409, jadi buat order_id baru.
const NEW_ATTEMPT = new Set(['provider_timeout', 'gateway_amount_reservation_lost']);

async function createGatewayPayment(order, attempt) {
  const key = `${order.id}-${attempt}`; // simpan ke DB sebelum fungsi ini dipanggil
  const body = JSON.stringify({
    order_id: attempt === 1 ? order.id : `${order.id}-R${attempt}`,
    amount: order.subtotal,
    webhook_url: 'https://tokokamu.id/webhooks/temanqris'
  });

  for (let i = 0; i < 5; i += 1) {
    let res;
    try {
      res = await fetch('https://temanqris.com/api/payment-gateway/payments', {
        method: 'POST',
        headers: {
          'X-API-Key': process.env.TEMANQRIS_API_KEY,
          'Idempotency-Key': key,
          'Content-Type': 'application/json'
        },
        body,                                   // isi yang sama di setiap percobaan
        signal: AbortSignal.timeout(25000)     // TemanQRIS menjawab dalam 20 detik
      });
    } catch (networkError) {
      await new Promise((r) => setTimeout(r, 1000 * 2 ** i));
      continue;
    }
    const data = await res.json().catch(() => ({}));
    if (res.ok) return data;                    // 201 baru atau 200 existing
    if ((res.status >= 500 && !NEW_ATTEMPT.has(data.code)) || RETRYABLE.has(data.code)) {
      await new Promise((r) => setTimeout(r, 1000 * 2 ** i));
      continue;
    }
    const error = new Error(data.error || `HTTP ${res.status}`);
    error.code = data.code;
    throw error;                                // 4xx lain: jangan retry
  }
  throw new Error('TemanQRIS belum bisa dihubungi, coba lagi nanti');
}

Menangani bayar telat di webhook

const crypto = require('crypto');

function verifySignature(rawBody, header, secret) {
  const expected = 'sha256=' + crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
  if (typeof header !== 'string' || header.length !== expected.length) return false;
  return crypto.timingSafeEqual(Buffer.from(header), Buffer.from(expected));
}

app.post('/webhooks/temanqris', express.raw({ type: 'application/json' }), async (req, res) => {
  if (!verifySignature(req.body, req.get('X-TemanQRIS-Signature'), process.env.TEMANQRIS_WEBHOOK_SECRET)) {
    return res.sendStatus(401);
  }
  const event = JSON.parse(req.body.toString('utf8'));
  if (req.get('X-TemanQRIS-Mode') !== 'live' || event.data.mode !== 'live') return res.sendStatus(400);
  if (event.event !== 'payment.confirmed' || !(await db.webhookEvents.insertIgnore(event.idempotency_key))) {
    return res.sendStatus(204);
  }
  const attempt = await db.attempts.findByGatewayOrderId(event.data.order_id); // INV-2026-0001 atau INV-2026-0001-R2
  const late = new Date(event.data.paid_at) > new Date(attempt.expires_at);
  const order = await db.orders.find(attempt.order_id);

  if (order.status === 'paid') {
    // Pelanggan membayar dua percobaan. Dana kedua sudah masuk wallet Anda.
    await db.refundQueue.insert({ order: order.id, attempt: event.data.order_id, amount: event.data.total_amount });
  } else {
    await db.orders.update(order.id, { status: 'paid', paid_late: late });
  }
  res.sendStatus(204);
});

Kasus khusus

KejadianYang perlu Anda lakukan
Webhook datang setelah order Anda dibatalkan otomatisDana sudah masuk ke wallet Anda. Kirim barang atau kembalikan dana lewat support. Jangan abaikan.
Mau mencegah bayar telat sama sekaliBatalkan order gateway dengan POST /api/qris/orders/:orderId/cancel. Pembayaran yang tetap masuk setelah itu tidak dikreditkan otomatis dan ditinjau admin.
Pembeli membatalkan pesanan di sistem Anda sebelum membayarPanggil POST /api/qris/orders/:orderId/cancel saat itu juga, termasuk kalau QR sudah kedaluwarsa tapi masa tenggang belum lewat. Beri tahu pembeli supaya tidak membayar. Halaman bayar langsung menampilkan dibatalkan. Kalau pembeli tetap membayar, dana tidak masuk wallet Anda dan ditinjau admin. Pembeli menghubungi support dengan bukti bayar untuk refund.
payment.confirmed datang untuk order yang sudah Anda batalkanBisa terjadi kalau pembayaran masuk sebelum pembatalan Anda tercatat, atau admin mengkreditkan pembayaran yang ditinjau. Dana sudah ada di wallet Anda. Proses pesanannya, atau minta refund lewat support. Selalu proses payment.confirmed, apa pun status order di sistem Anda.
Pembeli batal tapi order tidak Anda batalkan di TemanQRISOrder tetap bisa dibayar sampai payable_until, dan pembayaran itu dikreditkan otomatis. Batalkan lewat API kalau pesanan memang tidak akan diproses.
Pelanggan membayar percobaan lama dan baruKeduanya dikreditkan. Kembalikan salah satunya lewat support. Untuk mengurangi risiko ini, buat percobaan baru setelah payable_until percobaan lama lewat, atau batalkan percobaan lama dulu.
Mengulang dengan key baru tapi order_id lamaDitolak 409 gateway_order_id_used. Key baru tidak membuka order_id lama.
Key sama untuk order_id berbedaMembuat pembayaran terpisah, karena key dihitung bersama order_id. Buat key yang selalu memuat order_id.
Jalur manual: request payment-link timeoutTidak ada Idempotency-Key. Ulangi request yang sama. Kalau dapat 400 Order ID already exists, link sudah dibuat: ambil dengan GET /api/qris/orders/:orderId.
Jalur manual: link kedaluwarsaPanggil POST /api/qris/generate dengan order_id dan nominal yang sama untuk mengaktifkan link yang sama lagi.

Memasang widget pembayaran di website

Untuk siapa: landing page, halaman donasi, katalog sederhana, atau website tanpa backend checkout. Satu baris script, tidak perlu API key. Widget memakai jalur manual (QRIS Anda sendiri).

Alur

  1. Ambil Merchant ID di Dashboard > Widget.

  2. Pasang script di halaman. Atur data-amount untuk harga tetap, atau biarkan kosong supaya pelanggan mengisi nominal.

  3. Pelanggan menekan tombol. Widget memanggil POST /api/widget/generate, membuat link dengan order_id berawalan ORD-W, lalu menampilkan QR (berlaku 60 menit).

  4. Pelanggan membayar, lalu menekan tombol konfirmasi di widget. Widget memanggil POST /api/widget/confirm/:orderId.

  5. Status menjadi awaiting_confirmation. Kalau data-webhook diisi dan webhook secret sudah dibuat, server Anda menerima payment.awaiting_confirmation.

  6. Kalau data-callback diisi, browser pelanggan diarahkan ke URL itu dengan ?order_id=...&amount=...&status=confirmed. Parameter ini dibuat browser, jadi bukan bukti bayar.

  7. Anda mengecek mutasi, lalu verifikasi lewat dashboard atau POST /api/qris/orders/:orderId/verify. Webhook payment.confirmed terkirim.

Kode yang dipasang

HTML
<script
  src="https://temanqris.com/widget.js"
  data-merchant="abc123xyz"
  data-amount="50000"
  data-button-text="Bayar Sekarang"
  data-button-color="#22c55e"
  data-description="Kelas Online Batch 7"
  data-callback="https://kelaskamu.id/terima-kasih"
  data-webhook="https://kelaskamu.id/webhooks/temanqris"
></script>

Yang dikirim widget ke TemanQRIS

HTTP
POST /api/widget/generate
Content-Type: application/json

{
  "merchant_id": "abc123xyz",
  "amount": 50000,
  "description": "Kelas Online Batch 7",
  "callback_url": "https://kelaskamu.id/terima-kasih",
  "webhook_url": "https://kelaskamu.id/webhooks/temanqris"
}
Respons
200 OKContent-Type: application/json
{
  "success": true,
  "order_id": "ORD-W5E1A9C03B7D2F4E6",
  "link_code": "W8F3A1C7E92B4D605",
  "amount": 50000,
  "merchant_name": "KELAS KAMU",
  "qr_image": "data:image/png;base64,iVBOR...",
  "qris_string": "00020101021226...",
  "expires_at": "2026-10-17T04:00:00.000Z",
  "description": "Kelas Online Batch 7"
}

Halaman terima kasih (Node.js)

Node.js
app.get('/terima-kasih', async (req, res) => {
  const orderId = String(req.query.order_id || '').slice(0, 30);
  const r = await fetch(`https://temanqris.com/api/qris/orders/${encodeURIComponent(orderId)}`, {
    headers: { 'X-API-Key': process.env.TEMANQRIS_API_KEY }
  });
  const data = await r.json().catch(() => ({}));
  const status = data.order ? data.order.status : 'unknown';
  res.render('terima-kasih', {
    message: status === 'paid' ? 'Pembayaran diterima.' : 'Pembayaran sedang kami periksa.'
  });
});

Webhook

const express = require('express');
const crypto = require('crypto');
const app = express();
const PRICE = 50000; // harga yang Anda harapkan

function verifySignature(rawBody, header, secret) {
  const expected = 'sha256=' + crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
  if (typeof header !== 'string' || header.length !== expected.length) return false;
  return crypto.timingSafeEqual(Buffer.from(header), Buffer.from(expected));
}

app.post('/webhooks/temanqris', express.raw({ type: 'application/json' }), async (req, res) => {
  if (!verifySignature(req.body, req.get('X-TemanQRIS-Signature'), process.env.TEMANQRIS_WEBHOOK_SECRET)) {
    return res.sendStatus(401);
  }
  const event = JSON.parse(req.body.toString('utf8'));
  if (req.get('X-TemanQRIS-Mode') !== 'live' || event.data.mode !== 'live') return res.sendStatus(400);
  if (!(await db.webhookEvents.insertIgnore(event.idempotency_key))) return res.sendStatus(204);

  if (event.data.amount !== PRICE) {
    await db.anomalies.insert({ event }); // nominal tidak sesuai harga
    return res.sendStatus(204);
  }
  if (event.event === 'payment.awaiting_confirmation') {
    await notifyAdmin(`Cek mutasi Rp${event.data.amount} untuk ${event.data.order_id}`);
  }
  if (event.event === 'payment.confirmed') {
    await grantAccess(event.data.order_id);
  }
  res.sendStatus(204);
});

Kasus khusus

KejadianYang perlu Anda lakukan
Pelanggan membuka data-callback tanpa bayarParameter status=confirmed dibuat browser. Jangan beri akses dari halaman ini. Tunggu payment.confirmed.
Merchant ID terlihat di HTMLMemang publik dan bukan rahasia. Orang lain bisa membuat QR atas nama toko Anda, tapi dana tetap masuk ke QRIS Anda. Selalu cek nominal di webhook.
Nominal tidak sesuai hargaSiapa pun bisa memanggil widget API dengan nominal lain. Bandingkan data.amount dengan harga Anda.
Pembayaran widget di daftar linkpayment_mode bernilai unknown dan order_id berawalan ORD-W.
QR kedaluwarsa60 menit setelah dibuat. Pelanggan cukup menekan tombol lagi untuk QR baru.
KuotaSetiap QR widget manual dihitung terhadap kuota harian tier Anda. QR widget mode gateway tidak memakai kuota harian. Keduanya dibatasi 60 per menit per IP.
Butuh konfirmasi otomatiswidget.js selalu manual. Untuk otomatis, panggil Widget API dengan payment_mode: "gateway" dari halaman Anda sendiri, atau pakai gateway dari backend.

Top up saldo dan tagihan SaaS

Untuk siapa: aplikasi dengan saldo atau langganan (game, SaaS, layanan digital) yang menambah saldo pengguna otomatis.

Alur

  1. Pengguna memilih nominal top up, misalnya Rp50.000.

  2. Backend membuat baris topups (status pending) dengan order_id TOPUP-<id> dan key TOPUP-<id>-1.

  3. Kalau ingin pengguna menanggung biaya layanan, isi fee_amount sama dengan biaya layanan gateway: 0,8% dari amount, dibulatkan ke atas. Dengan begitu net_amount sama dengan nominal top up.

  4. POST /api/payment-gateway/payments, tampilkan QR di aplikasi.

  5. Saat payment.confirmed, tambah saldo pengguna dalam satu transaksi dengan pencatatan idempotency_key.

  6. Aplikasi memeriksa status top up dari database Anda (bukan dari TemanQRIS) setiap beberapa detik.

Request

cURL
curl -X POST https://temanqris.com/api/payment-gateway/payments \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Idempotency-Key: TOPUP-88120-1" \
  -H "Content-Type: application/json" \
  -d '{
    "order_id": "TOPUP-88120",
    "amount": 50000,
    "fee_amount": 400,
    "title": "Top up saldo",
    "webhook_url": "https://api.appkamu.id/webhooks/temanqris"
  }'
Respons
201 CreatedContent-Type: application/json
{
  "success": true,
  "existing": false,
  "payment_mode": "gateway",
  "payment_attempt_id": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f",
  "payment_link": {
    "linkCode": "Qm7tR2xP9aKd",
    "orderId": "TOPUP-88120",
    "amount": 50000,
    "feeAmount": 400,
    "provider_fee_amount": 400,
    "net_amount": 50000,
    "uniqueCode": 642,
    "totalAmount": 51042,
    "expiresAt": "2026-10-17T03:15:00.000Z",
    "payable_until": "2026-10-17T04:15:00.000Z",
    "url": "/p/Qm7tR2xP9aKd",
    "qr_image": "data:image/png;base64,iVBOR..."
  },
  "mode": "live"
}

Pengguna membayar Rp51.042 (Rp50.000 + fee Rp400 + kode unik 642). Wallet Anda bertambah Rp50.000, karena biaya layanan 0,8% dari Rp50.000 adalah Rp400.

Webhook

const crypto = require('crypto');

function verifySignature(rawBody, header, secret) {
  const expected = 'sha256=' + crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
  if (typeof header !== 'string' || header.length !== expected.length) return false;
  return crypto.timingSafeEqual(Buffer.from(header), Buffer.from(expected));
}

app.post('/webhooks/temanqris', express.raw({ type: 'application/json' }), async (req, res) => {
  if (!verifySignature(req.body, req.get('X-TemanQRIS-Signature'), process.env.TEMANQRIS_WEBHOOK_SECRET)) {
    return res.sendStatus(401);
  }
  const event = JSON.parse(req.body.toString('utf8'));
  if (req.get('X-TemanQRIS-Mode') !== 'live' || event.data.mode !== 'live') return res.sendStatus(400);
  if (event.event !== 'payment.confirmed') return res.sendStatus(204);

  await db.transaction(async (tx) => {
    if (!(await tx.webhookEvents.insertIgnore(event.idempotency_key))) return;
    const topup = await tx.topups.findForUpdate(event.data.order_id);
    if (!topup || topup.status === 'paid') return;
    await tx.topups.update(topup.id, { status: 'paid' });
    await tx.balances.increment(topup.user_id, topup.amount); // nominal dari DB Anda, bukan dari payload
  });
  res.sendStatus(204);
});

Kasus khusus

KejadianYang perlu Anda lakukan
Top up kecil ditolak amount_below_provider_feeamount + fee_amount harus lebih dari biaya layanan. Tetapkan minimal top up, misalnya Rp10.000.
Top up di atas Rp1.000.000Ditolak amount_too_large. Batasi nominal di aplikasi.
Banyak top up bersamaanMaksimal 50 invoice terbuka per merchant (bawaan). Sebelum membuat invoice baru, pakai ulang invoice yang masih berlaku untuk pengguna yang sama.
Saldo pengguna ditambah dua kaliTidak akan terjadi kalau pencatatan idempotency_key dan penambahan saldo ada di satu transaksi.
Polling dari aplikasiBaca database Anda. Kalau perlu cek ke TemanQRIS, lakukan dari backend dengan GET /api/qris/orders/:orderId.

Banyak outlet dalam satu akun

Untuk siapa: pemilik beberapa cabang atau beberapa rekening penerima. Butuh Premium (sampai 100 QRIS statis secara bawaan, batasnya tampil di halaman harga).

Alur

  1. Upload QRIS statis tiap outlet dengan POST /api/qris/upload.

  2. Panggil GET /api/qris/my-qris. Simpan id dari qris_list untuk setiap outlet di sistem Anda.

  3. Saat membuat QR, kirim qris_id (untuk generate) atau qris_data_id (untuk payment-link). Tanpa itu, QRIS yang paling baru diperbarui yang dipakai.

  4. Pakai awalan order_id per outlet, misalnya BDG-0001, JKT-0001, supaya laporan mudah dipisah.

Request

cURL
curl -X POST https://temanqris.com/api/qris/generate \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 72000, "qris_id": 124, "order_id": "BDG-0001" }'

Response sama dengan Generate QRIS. Webhook dan verifikasi sama dengan Kasir dan UMKM.

Kasus khusus

KejadianYang perlu Anda lakukan
404 No QRIS foundqris_id salah atau QRIS itu sudah dihapus. Cek ulang my-qris.
400 Merchant limit reached saat uploadBatas QRIS paket tercapai. Hapus QRIS yang tidak dipakai di dashboard.
Akun FreeHanya satu QRIS. Upload ulang akan mengganti QRIS lama.

Rekonsiliasi harian

Untuk siapa: tim keuangan yang ingin memastikan semua order lunas tercatat, termasuk yang webhooknya gagal.

Alur

  1. Setiap pagi (setelah 07.00 WIB), jalankan job yang membaca GET /api/qris/orders?status=paid&limit=100&offset=0, lalu naikkan offset sampai semua halaman terbaca.

  2. Untuk setiap order, cocokkan order_id, total_amount, dan paid_at dengan database Anda.

  3. Order yang paid di TemanQRIS tapi belum paid di sistem Anda: proses seperti webhook yang terlambat.

  4. Untuk gateway, jumlahkan net_amount per hari dan bandingkan dengan saldo wallet. Dana pembayaran hari ini baru bisa ditarik mulai 00.00 WIB besok.

  5. Order yang masih pending dengan is_expired: true sudah kedaluwarsa.

Request

cURL
curl "https://temanqris.com/api/qris/orders?status=paid&limit=100&offset=0" \
  -H "X-API-Key: YOUR_API_KEY"

Job (Node.js)

Node.js
async function reconcile() {
  for (let offset = 0; ; offset += 100) {
    const r = await fetch(`https://temanqris.com/api/qris/orders?status=paid&limit=100&offset=${offset}`, {
      headers: { 'X-API-Key': process.env.TEMANQRIS_API_KEY }
    });
    if (!r.ok) throw new Error(`HTTP ${r.status}`);
    const { orders, pagination } = await r.json();
    for (const o of orders) {
      const mine = await db.orders.find(o.order_id);
      if (mine && mine.status !== 'paid') await db.orders.markPaidFromReconcile(o);
    }
    if (offset + orders.length >= pagination.total) break;
  }
}

Kasus khusus

KejadianYang perlu Anda lakukan
Order yang menunggu verifikasiAmbil dengan GET /api/qris/orders?status=awaiting_confirmation, lalu cek mutasi untuk setiap order. Nilai status yang tidak dikenal ditolak 400.
Data banyaklimit maksimal 100 per halaman. Jalankan di luar jam ramai.
Butuh net_amount per linkGET /api/qris/payment-links juga memuat provider_fee_amount dan net_amount untuk link gateway.

Alur cURL lengkap

Untuk siapa: developer yang ingin mencoba seluruh jalur manual dari terminal sebelum menulis kode backend.

Alur

  1. Cek apakah QRIS statis sudah ada dengan GET /api/qris/my-qris.

  2. Kalau has_qris bernilai false, upload sekali lewat POST /api/qris/upload.

  3. Buat link untuk satu order dengan POST /api/qris/payment-link.

  4. Bagikan https://temanqris.com + payment_link.url ke pelanggan, atau arahkan dari halaman checkout.

  5. Pelanggan membayar dan menekan Sudah Bayar. Anda menerima webhook payment.awaiting_confirmation.

  6. Cek status order dari backend dengan GET /api/qris/orders/:orderId.

  7. Setelah dana terlihat di rekening atau e-wallet, verifikasi dengan POST /api/qris/orders/:orderId/verify. Webhook payment.confirmed terkirim.

  8. Pantau sisa kuota dengan GET /api/qris/usage.

Semua perintah

cURL
# 1. Cek apakah QRIS statis sudah ada
curl https://temanqris.com/api/qris/my-qris \
  -H "X-API-Key: YOUR_API_KEY"

# 2. Upload QRIS statis sekali, hanya kalau has_qris bernilai false
curl -X POST https://temanqris.com/api/qris/upload \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "qris_image=@/path/to/qris.png"

# 3. Buat payment link untuk satu order
curl -X POST https://temanqris.com/api/qris/payment-link \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 125000,
    "description": "Checkout order INV-2026-0001",
    "order_id": "INV-2026-0001",
    "webhook_url": "https://company.com/webhooks/temanqris",
    "callback_url": "https://company.com/orders/INV-2026-0001/thank-you"
  }'

# 4. Bagikan URL dari response, misalnya https://temanqris.com/p/ABC12345XYZW

# 5. Cek status order dari backend
curl https://temanqris.com/api/qris/orders/INV-2026-0001 \
  -H "X-API-Key: YOUR_API_KEY"

# 6. Verifikasi setelah tim keuangan memastikan dana masuk
curl -X POST https://temanqris.com/api/qris/orders/INV-2026-0001/verify \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "payer_name": "Budi Santoso",
    "payer_note": "Dana sudah masuk ke rekening merchant"
  }'

# 7. Pantau kuota harian
curl https://temanqris.com/api/qris/usage \
  -H "X-API-Key: YOUR_API_KEY"

Catatan production

Panggil verify hanya dari backend internal setelah dana benar-benar masuk. Jangan buat tombol publik yang langsung memanggil /orders/:orderId/verify.

Upload QRIS Statis

POST/api/qris/upload
  • Auth: X-API-Key
  • Memakai kuota harian

Upload QRIS statis Anda sebagai template. Cukup sekali saat setup. Setelah itu langsung pakai /generate atau /payment-link tanpa upload ulang. Pakai /my-qris untuk mengecek apakah QRIS sudah ada.

Aturan

  • Hanya QRIS statis. QRIS dinamis ditolak.
  • Gambar: JPG/JPEG atau PNG. Format lain ditolak. Ukuran maksimal 1,5 MB (bawaan), sisi terpanjang maksimal 6000 px, total maksimal 16 megapiksel. Field form: qris_image.
  • String: kirim JSON {"qris_string": "000201..."} kalau Anda sudah punya isi QR hasil decode.
  • Akun Free menyimpan 1 QRIS. Upload ulang akan mengganti QRIS lama. Akun Premium menambah QRIS baru sampai batas paket (bawaan 100, tampil di halaman harga).

Opsi 1: upload gambar

curl -X POST https://temanqris.com/api/qris/upload \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "qris_image=@/path/to/qris.png"

Opsi 2: upload string

curl -X POST https://temanqris.com/api/qris/upload \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "qris_string": "00020101021126670016COM.NOBUBANK.WWW..." }'
Respons
200 OKContent-Type: application/json
{
  "message": "QRIS uploaded successfully",
  "qris_string": "00020101021126...",
  "merchant": {
    "name": "TOKO EXAMPLE",
    "city": "JAKARTA"
  }
}

Cek QRIS

GET/api/qris/my-qris
  • Auth: X-API-Key
  • Tanpa kuota

Cek apakah Anda sudah pernah upload QRIS statis. Panggil sebelum /upload supaya tidak upload ulang tanpa perlu. qris adalah QRIS yang paling baru diperbarui, dan QRIS itulah yang dipakai /generate dan /payment-link kalau Anda tidak memilih qris_id.

curl https://temanqris.com/api/qris/my-qris \
  -H "X-API-Key: YOUR_API_KEY"
Respons
200 OKContent-Type: application/json
{
  "success": true,
  "has_qris": true,
  "qris": {
    "id": 123,
    "qris_string": "00020101021126...",
    "merchant_name": "TOKO EXAMPLE",
    "merchant_city": "JAKARTA",
    "created_at": "2026-10-01T03:30:00.000Z",
    "updated_at": "2026-10-01T03:30:00.000Z"
  },
  "qris_list": [
    {
      "id": 123,
      "qris_string": "00020101021126...",
      "merchant_name": "TOKO EXAMPLE",
      "merchant_city": "JAKARTA",
      "created_at": "2026-10-01T03:30:00.000Z",
      "updated_at": "2026-10-01T03:30:00.000Z"
    }
  ],
  "total": 1,
  "default_qris_id": 123
}

Generate QRIS Dinamis

POST/api/qris/generate
  • Auth: X-API-Key
  • Memakai kuota harian

Endpoint utama untuk membuat QRIS dinamis dengan nominal transaksi. Setiap panggilan juga membuat (atau memperbarui) payment link untuk order_id itu.

Request body

NamaTipeStatusKeterangan
amountintegerWajibNominal dalam rupiah, bilangan bulat 1 sampai 100.000.000. Angka dalam string seperti "50000" juga diterima.
fee_typestringOpsional"rupiah" atau "percent". Wajib kalau fee_value bukan 0.
fee_valuenumberOpsionalBiaya tambahan yang dibayar pelanggan. percent: 0 sampai 100, maksimal 4 desimal, dibulatkan ke rupiah terdekat. rupiah: bilangan bulat, maksimal 10 kali amount.
qris_idintegerOpsionalID QRIS tertentu dari my-qris. Bawaan: QRIS yang paling baru diperbarui.
order_idstringOpsionalID order Anda, maksimal 30 karakter. Kalau kosong dibuat otomatis (ORD-A + 12 karakter).
webhook_urlstringOpsionalURL penerima webhook. Harus mengarah ke alamat publik.
callback_urlstringOpsionalURL http(s) tujuan pelanggan setelah menekan Sudah Bayar.

Memakai order_id yang sama lagi

  • Order masih belum dibayar (pending, expired, atau cancelled): link yang sama diperbarui dengan nominal dan QR baru, masa berlakunya diperpanjang, status kembali pending, dan response berisi "updated": true. URL yang sudah Anda bagikan tetap berlaku. webhook_url dan callback_url diganti dengan nilai yang Anda kirim (kosong kalau tidak dikirim).
  • Order sudah paid atau awaiting_confirmation dan request sama persis (nominal dan fee sama): order dikembalikan apa adanya dengan "existing": true. Status, paid_at, dan link tidak berubah, jadi retry aman.
  • Order sudah paid atau awaiting_confirmation tapi nominal atau fee berbeda: ditolak 409. Pakai order_id baru.
  • order_id sudah dipakai pembayaran gateway: ditolak 409.

Request

curl -X POST https://temanqris.com/api/qris/generate \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 50000,
    "fee_type": "rupiah",
    "fee_value": 1000,
    "order_id": "INV-2026-001",
    "webhook_url": "https://yoursite.com/webhook",
    "callback_url": "https://yoursite.com/thank-you"
  }'
Respons
200 OKContent-Type: application/json
{
  "success": true,
  "qris": "00020101021226...",
  "qr_image": "data:image/png;base64,...",
  "amount": 50000,
  "fee": { "type": "rupiah", "value": 1000 },
  "fee_amount": 1000,
  "total_amount": 51000,
  "expires_at": "2026-10-18T03:00:00.000Z",
  "payment_link": {
    "id": 456,
    "link_code": "BTN3EV2XK7QP",
    "order_id": "INV-2026-001",
    "url": "/p/BTN3EV2XK7QP",
    "amount": 50000,
    "fee_type": "rupiah",
    "fee_value": 1000,
    "fee_amount": 1000,
    "total_amount": 51000,
    "merchant_name": "TOKO EXAMPLE",
    "webhook_url": "https://yoursite.com/webhook",
    "callback_url": "https://yoursite.com/thank-you",
    "expires_at": "2026-10-18T03:00:00.000Z"
  }
}
FieldArti
qr_imageGambar QR dalam Base64, bisa langsung dipakai di <img src="...">.
total_amountYang dibayar pelanggan: amount + fee_amount.
expires_at (luar)Batas simpan riwayat QR di dashboard (diatur admin per tier).
payment_link.expires_atBatas link pembayaran: bawaan 24 jam (Free) atau 7 hari (Premium).
payment_link.updatedMuncul true kalau link lama untuk order_id ini diperbarui.
existingMuncul true kalau order sudah paid atau awaiting_confirmation dan dikembalikan tanpa perubahan. Untuk order paid, qris dan qr_image bernilai null karena tidak ada lagi yang perlu dipindai. Order awaiting_confirmation tetap membawa keduanya.
payment_linkBisa null kalau pembuatan link gagal. QR tetap bisa dipakai.

Error: lihat tabel error QRIS. Yang paling sering: 400 nominal atau fee tidak valid, 404 No QRIS found. Please upload your static QRIS first., 409 untuk order_id yang terkunci, dan 503 dengan code: "webhook_dns_unavailable" kalau DNS sedang bermasalah saat memeriksa webhook_url (kirim ulang request yang sama).

Render QR

POST/api/qris/render
  • Auth: X-API-Key
  • Tanpa kuota

Buat gambar QR dari string QRIS. Kirim salah satu: qris_string atau qris_data_id (ID QRIS tersimpan dari /my-qris).

Opsi 1: dari string

cURL
curl -X POST https://temanqris.com/api/qris/render \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "qris_string": "00020101021126..." }'

Opsi 2: dari ID tersimpan

curl -X POST https://temanqris.com/api/qris/render \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "qris_data_id": 123 }'
Respons
200 OKContent-Type: application/json
{
  "success": true,
  "qr_image": "data:image/png;base64,iVBOR..."
}

Payment Link dan Status Order

Payment link adalah halaman bayar https://temanqris.com/p/{link_code} yang bisa dibagikan ke pelanggan. Link dari jalur manual dan gateway sama-sama tercatat sebagai order, jadi bisa dicek dengan endpoint order di bawah.

  1. Buat QRIS
  2. Pelanggan bayar
  3. Webhook atau verifikasi
  4. Selesai

Status order

StatusArti
pendingMenunggu pembayaran.
awaiting_confirmationPelanggan menekan Sudah Bayar (manual dan widget). Menunggu Anda memverifikasi.
paidPembayaran sah. Manual: sudah Anda verifikasi. Gateway: sudah dicocokkan otomatis.
expiredLewat batas waktu tanpa pembayaran. Status bisa masih terbaca pending sebentar sampai sistem menyapu link kedaluwarsa, jadi andalkan is_expired. Order gateway yang dibayar dalam masa tenggang bisa berubah dari expired menjadi paid sampai payable_until lewat.
cancelledDibatalkan atau diarsipkan oleh merchant.

Cek Status Order

GET/api/qris/orders/:orderId
  • Auth: X-API-Key
  • Tanpa kuota

Cek status satu order, manual maupun gateway. Ini juga cara membaca status pembayaran gateway live (tidak ada endpoint baca terpisah untuk gateway live).

curl https://temanqris.com/api/qris/orders/ORD-ABC123 \
  -H "X-API-Key: YOUR_API_KEY"
Respons
200 OKContent-Type: application/json
{
  "success": true,
  "order": {
    "order_id": "ORD-ABC123",
    "title": "Pembayaran Invoice #001",
    "description": "Pembayaran QRIS",
    "amount": 50000,
    "fee_type": "rupiah",
    "fee_value": 1000,
    "total_amount": 51000,
    "status": "paid",
    "payment_method": "qris",
    "created_at": "2026-10-17T03:30:00.000Z",
    "paid_at": "2026-10-17T03:35:00.000Z",
    "expires_at": "2026-10-18T03:30:00.000Z",
    "is_paid": true,
    "is_expired": false
  }
}
  • payment_method: qris (manual API dan dashboard), widget, atau gateway.
  • is_expired adalah tanda kedaluwarsa yang bisa diandalkan. status bisa masih pending sebentar setelah lewat expires_at.
  • paid_at setelah expires_at pada order gateway berarti pelanggan membayar dalam masa tenggang.
  • payable_until (gateway saja): batas terakhir pembayaran yang masih dicocokkan dan dikreditkan otomatis, yaitu expires_at ditambah masa tenggang. Bernilai null kalau order sudah lunas, dibatalkan, atau tidak bisa lagi dikreditkan otomatis, dan selalu null untuk order manual. Biarkan order Anda terbuka sampai waktu ini.

Daftar Order

GET/api/qris/orders
  • Auth: X-API-Key
  • Tanpa kuota
NamaTipeStatusKeterangan
statusstringOpsionalpending, awaiting_confirmation, paid, expired, atau cancelled. Nilai lain ditolak 400. Bawaan: semua.
limitintegerOpsionalMaksimal 100. Bawaan: 20.
offsetintegerOpsionalUntuk halaman berikutnya. Bawaan: 0.
curl "https://temanqris.com/api/qris/orders?status=paid&limit=10" \
  -H "X-API-Key: YOUR_API_KEY"
Respons
200 OKContent-Type: application/json
{
  "success": true,
  "orders": [
    {
      "order_id": "ORD-ABC123",
      "title": "Invoice #001",
      "amount": 50000,
      "total_amount": 51000,
      "status": "paid",
      "is_paid": true,
      "created_at": "2026-10-17T03:30:00.000Z",
      "paid_at": "2026-10-17T03:35:00.000Z"
    }
  ],
  "pagination": { "total": 25, "limit": 10, "offset": 0 }
}

Order gateway di daftar ini juga membawa provider_fee_amount dan net_amount.

Verifikasi Order

POST/api/qris/orders/:orderId/verify
  • Auth: X-API-Key
  • Memakai kuota harian

Tandai order manual sebagai paid lewat API, tanpa membuka dashboard. Panggil hanya setelah dana benar-benar terlihat di rekening atau e-wallet Anda.

Kapan dipakai. Setelah pelanggan menekan Sudah Bayar (status awaiting_confirmation), atau langsung dari status pending kalau Anda sudah melihat dana masuk (misalnya di kasir).

Bukan untuk gateway

Order gateway dikonfirmasi otomatis. Verifikasi manual ditolak dengan 409.

NamaTipeStatusKeterangan
orderId pathstringWajiborder_id Anda, misalnya INV-2026-001.
payer_name bodystringOpsionalNama pembayar, maksimal 100 karakter.
payer_note bodystringOpsionalCatatan, maksimal 500 karakter.
curl -X POST https://temanqris.com/api/qris/orders/INV-2026-001/verify \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "payer_name": "John Doe", "payer_note": "Pembayaran via OVO" }'
Respons
200 OKContent-Type: application/json
{
  "success": true,
  "message": "Payment verified successfully",
  "order": {
    "order_id": "INV-2026-001",
    "amount": 75000,
    "status": "paid",
    "paid_at": "2026-10-17T09:30:00.000Z",
    "confirmed_by": "api"
  }
}

Setelah berhasil, webhook payment.confirmed dikirim kalau order punya webhook_url dan Anda sudah membuat webhook secret.

Alur integrasi manual

  1. Bagikan link ke pelanggan.

  2. Pelanggan scan QRIS dan membayar.

  3. Pelanggan menekan Sudah Bayar, status menjadi awaiting_confirmation.

  4. Anda menerima webhook payment.awaiting_confirmation dan email.

  5. Cek dana masuk di e-wallet atau rekening.

  6. Panggil POST /api/qris/orders/:orderId/verify. Status menjadi paid.

Catatan production

Panggil verify hanya dari backend internal setelah dana benar-benar masuk. Jangan buat tombol publik yang langsung memanggil endpoint ini.

Batalkan Order

POST/api/qris/orders/:orderId/cancel
  • Auth: X-API-Key
  • Memakai kuota harian

Batalkan order yang belum dibayar. Order pending, awaiting_confirmation, dan expired bisa dibatalkan. Link langsung tidak bisa dibayar lagi lewat halaman bayar.

Untuk order gateway, pembatalan juga menghentikan pencocokan otomatis. Kalau pelanggan tetap membayar setelah dibatalkan, dana tidak dikreditkan otomatis dan masuk antrean tinjauan admin.

curl -X POST https://temanqris.com/api/qris/orders/INV-2026-001/cancel \
  -H "X-API-Key: YOUR_API_KEY"
Respons
200 OKContent-Type: application/json
{
  "success": true,
  "message": "Order cancelled successfully",
  "order": { "order_id": "INV-2026-001", "status": "cancelled" }
}

Pelanggan Sudah Bayar (publik)

POST/api/pay/:link_code/confirm
  • Publik, tanpa API key
  • 30 request per menit per IP

Mencatat bahwa pelanggan mengaku sudah membayar. Status berubah menjadi awaiting_confirmation dan Anda perlu memverifikasi.

Ini bukan konfirmasi pembayaran

Endpoint ini hanya mengubah status ke awaiting_confirmation. Anda tetap harus mengecek bahwa dana sudah masuk di e-wallet atau rekening Anda.

API publik. Dipanggil dari halaman bayar saat pelanggan menekan tombol Sudah Bayar. Untuk link gateway endpoint ini tidak mengubah apa pun, karena pembayaran gateway diverifikasi otomatis.

NamaTipeStatusKeterangan
link_code pathstringWajibKode payment link, misalnya ABC12345XYZW.
curl -X POST https://temanqris.com/api/pay/ABC12345XYZW/confirm \
  -H "Content-Type: application/json"
Respons
200 OKContent-Type: application/json
{
  "success": true,
  "message": "Konfirmasi pembayaran berhasil dikirim",
  "order_id": "ORD-ABC12345XYZ",
  "status": "awaiting_confirmation"
}

Yang terjadi setelah konfirmasi

  1. Pelanggan membuka halaman bayar (/p/ABC12345XYZW).

  2. Pelanggan scan QRIS dan membayar di e-wallet.

  3. Pelanggan menekan Sudah Bayar.

  4. Halaman bayar memanggil POST /api/pay/ABC12345XYZW/confirm.

  5. Status menjadi awaiting_confirmation (belum lunas).

  6. Webhook payment.awaiting_confirmation dikirim ke webhook_url (kalau ada dan webhook secret sudah dibuat).

  7. Anda menerima email notifikasi.

  8. Pelanggan diarahkan ke callback_url (kalau ada).

  9. Anda mengecek dana di dashboard bank atau e-wallet.

  10. Setelah dana terlihat, verifikasi lewat API atau dashboard. Status menjadi paid.

Status Link (publik)

GET/api/pay/:link_code
  • Publik, tanpa API key
  • 120 request per menit per IP

Data yang dipakai halaman bayar. Berguna kalau Anda membuat halaman bayar sendiri dan ingin menampilkan QR serta status ke pelanggan. Response tidak pernah memuat biaya layanan gateway atau data internal.

curl https://temanqris.com/api/pay/ABC12345XYZW
Respons
200 OKContent-Type: application/json
{
  "merchant_name": "TOKO EXAMPLE",
  "amount": 75000,
  "base_amount": 75000,
  "fee_amount": 0,
  "fee_type": "none",
  "description": "Pembayaran Order #12345",
  "qr_image": "data:image/png;base64,iVBOR...",
  "expires_at": "2026-10-18T07:00:00.000Z",
  "order_id": "INV-2026-001",
  "branding": "Powered by TemanQRIS",
  "callback_url": "https://yoursite.com/thank-you",
  "payment_mode": "manual",
  "unique_code": null,
  "manual_confirmation_allowed": true,
  "status": "pending",
  "is_paid": false,
  "is_awaiting": false,
  "is_expired": false
}
  • amount adalah total yang dibayar pelanggan. Untuk gateway, sudah termasuk kode unik (unique_code).
  • Link kedaluwarsa menjawab {"is_expired": true}. Link yang dibatalkan atau diarsipkan menjawab {"is_cancelled": true}, jadi pelanggan melihat status dibatalkan. Link tidak ditemukan, atau link kedaluwarsa yang lalu diarsipkan: 404.
  • Jangan pakai endpoint ini sebagai dasar menandai order lunas di backend. Pakai webhook atau GET /api/qris/orders/:orderId.

Gateway Otomatis

Mode gateway menerbitkan QRIS dinamis dan payment link dalam satu request, lalu mengonfirmasi pembayaran sendiri. Anda tidak perlu mengecek mutasi atau mengatur routing pembayaran di frontend.

Hanya di server

Nominal, kode unik, idempotency, penguncian QR, dan konfirmasi pembayaran diproses dan diverifikasi di server TemanQRIS. Jangan mengambil keputusan pembayaran dari data callback browser.

AturanKontrak v1.3.4
Syarat akunKYC harus disetujui untuk mode live. Tanpa KYC, request ditolak 403 KYC_REQUIRED. Sandbox tidak butuh KYC.
Nominal dasar maksimalRp1.000.000 (amount).
Total maksimalRp1.000.999 per transaksi, termasuk fee dan kode unik. Admin bisa menurunkan batas ini.
Kode unikBilangan bulat 0..999 yang dipilih server dari total yang masih bebas di seluruh platform, jadi dua invoice yang masih aktif tidak pernah punya total yang sama. Ikut masuk ke total QRIS, tidak bisa dikembalikan, dan menjadi pendapatan TemanQRIS.
Biaya tambahan (opsional)fee_amount: ditetapkan merchant sendiri, dibayar pelanggan, masuk penuh ke saldo Anda. Tidak boleh lebih besar dari amount (fee_exceeds_base). Pelanggan membayar amount + fee_amount + unique_code.
Biaya layanan gatewayDipotong dari dana yang Anda terima, bukan dari pelanggan. 0,8% dari amount untuk semua nominal, dibulatkan ke atas ke rupiah penuh (Rp150.000 menjadi Rp1.200). Dihitung saat invoice dibuat dan disimpan di invoice itu, jadi perubahan tarif tidak mengubah invoice yang sudah terbit. Wallet bertambah net_amount = amount + fee_amount - provider_fee_amount. Invoice yang tidak menyisakan minimal Rp1 untuk Anda ditolak amount_below_provider_fee.
Masa berlaku QR1 jam sejak diterbitkan (expiresAt).
Masa tenggang bayar telatPembayaran yang dilakukan sampai 1 jam setelah QR kedaluwarsa (bisa diatur admin 0 sampai 300 menit) tetap dicocokkan dan dikreditkan. Halaman bayar sudah menampilkan kedaluwarsa, tapi pencocokan tetap berjalan. Batas untuk setiap invoice ada di payable_until. Kalau admin mengubah masa tenggang, payable_until invoice yang masih terbuka ikut berubah, tapi tidak pernah melewati batas yang dikunci saat QR terbit. Jadi baca ulang lewat GET /api/qris/orders/:orderId sebelum menutup order, jangan hanya menyimpan nilai dari response create.
Saldo tertahan (H+1)Dana gateway masuk ke wallet sebagai saldo tertahan dan bisa ditarik mulai 00.00 WIB hari berikutnya. Lihat Biaya, Saldo, Refund.
Order IDSatu order_id hanya punya satu pembayaran gateway, apa pun hasilnya. Untuk mengulang pembayaran yang gagal atau kedaluwarsa, kirim order_id baru.
Waktu jawabTemanQRIS selalu menjawab dalam 20 detik, termasuk saat pindah ke penyedia cadangan. Kalau penyedia terlalu lambat, jawabannya 503 provider_timeout: tidak ada QR, order ditandai cancelled, dan nominalnya dilepas. Set timeout klien minimal 25 detik, atau kirim header opsional X-Request-Timeout-Ms (milidetik) berisi batas tunggu Anda. TemanQRIS lalu berhenti 1 detik sebelum batas itu (paling cepat 1 detik, paling lama tetap 20 detik).
IdempotencyHeader Idempotency-Key wajib. 1 sampai 256 karakter ASCII yang bisa dicetak. Dihitung bersama akun dan order_id, disimpan sebagai hash SHA-256, dan mengingat isi request pertama.
Invoice terbukaMaksimal 50 invoice yang masih terbuka per merchant (bawaan).
Batas pembuatanKey live tidak memakai kuota harian tier. Batasnya 60 invoice baru per menit per merchant (bawaan, 429 gateway_rate_limited). Akun yang baru lolos KYC bisa diberi batas total nominal harian (403 new_account_daily_amount_cap). Lihat Batas Payment Gateway live.
Status pembayaranWebhook payment.confirmed, atau baca GET /api/qris/orders/:orderId.
BatalPOST /api/qris/orders/:orderId/cancel atau arsip link menghentikan pencocokan. Pembayaran yang masuk setelahnya ditinjau admin.
RoutingRouting, penguncian, dan rekonsiliasi dikelola server. Anda cukup memakai payment link.
Checkout publikPakai payment_link.url dan payment_link.qr_image dari response.

Buat Pembayaran Gateway

POST/api/payment-gateway/payments
  • Key live atau tq_test_
  • Wajib Idempotency-Key
  • Tanpa kuota harian untuk key live
  • 60 invoice per menit (bawaan)
  • Kuota sandbox untuk key tq_test_

Buat satu invoice gateway berisi QRIS dinamis, kode unik, dan link pembayaran.

Header

NamaTipeStatusKeterangan
X-API-KeyheaderWajibUntuk integrasi. Key live dari Dashboard Settings, atau key tq_test_ untuk Sandbox. Key menentukan mode.
Authorization: Bearer ...headerOpsionalAlternatif. Sesi dashboard. Untuk sandbox kirim "mode": "sandbox" di body.
Idempotency-KeyheaderWajibKey unik per percobaan create. Pakai key yang sama saat retry timeout. Body idempotency_key diterima sebagai cadangan kalau header tidak bisa dikirim.
Content-Type: application/jsonheaderWajibBody JSON, maksimal 10 KB.

Request body

NamaTipeStatusKeterangan
order_idstringWajibMaksimal 30 karakter. Identitas order Anda. Satu order_id hanya punya satu pembayaran gateway.
amountintegerWajibNominal dasar positif, maksimal 1.000.000. Angka bulat seperti 150000 atau "150000". Desimal, titik ribuan, atau notasi seperti "1e5" ditolak.
fee_amountintegerOpsionalBiaya tambahan (opsional): ditetapkan merchant sendiri, dibayar pelanggan, masuk penuh ke saldo Anda. Rupiah bulat 0 atau lebih, maksimal sama dengan amount. Bawaan 0.
titlestringOpsionalNama invoice, dipotong maksimal 100 karakter.
descriptionstringOpsionalDeskripsi, dipotong maksimal 255 karakter.
webhook_urlURLOpsionalHTTP(S), wajib HTTPS di production. Host harus mengarah ke alamat publik. Alamat private, loopback, link-local, dan range khusus lain ditolak.
callback_urlURLOpsionalRedirect http(s) untuk pelanggan. Bukan bukti pembayaran.

Request

curl -X POST https://temanqris.com/api/payment-gateway/payments \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Idempotency-Key: INV-2026-0001-attempt-01" \
  -H "Content-Type: application/json" \
  -d '{
    "order_id": "INV-2026-0001",
    "amount": 150000,
    "fee_amount": 0,
    "title": "Pembayaran Paket Premium",
    "description": "Pesanan pelanggan INV-2026-0001",
    "webhook_url": "https://merchant.example/webhooks/temanqris",
    "callback_url": "https://merchant.example/orders/INV-2026-0001/success"
  }'
Respons
201 CreatedContent-Type: application/json
{
  "success": true,
  "existing": false,
  "payment_mode": "gateway",
  "payment_attempt_id": "2de4a4d5-3b0e-4b7a-9a3e-4c9f7a2b1e55",
  "payment_link": {
    "id": 456,
    "linkCode": "aZ3kQ9mP2xLw",
    "orderId": "INV-2026-0001",
    "amount": 150000,
    "feeAmount": 0,
    "provider_fee_amount": 1200,
    "net_amount": 148800,
    "uniqueCode": 321,
    "totalAmount": 150321,
    "description": "Pesanan pelanggan INV-2026-0001",
    "expiresAt": "2026-10-17T03:15:00.000Z",
    "payable_until": "2026-10-17T04:15:00.000Z",
    "url": "/p/aZ3kQ9mP2xLw",
    "qr_image": "data:image/png;base64,iVBOR..."
  },
  "mode": "live"
}
FieldArti
payment_attempt_idID percobaan pembayaran. Simpan untuk tracing dan saat menghubungi support.
payment_link.totalAmountYang harus dibayar pelanggan: amount + feeAmount + uniqueCode.
payment_link.provider_fee_amountBiaya layanan gateway untuk invoice ini.
payment_link.net_amountYang masuk ke wallet Anda saat lunas.
payment_link.expiresAtQR kedaluwarsa (1 jam).
payment_link.payable_untilBatas terakhir pembayaran yang masih dicocokkan dan dikreditkan otomatis: expiresAt ditambah masa tenggang (1 jam). Pakai ini, bukan angka tetap, untuk menentukan kapan order Anda boleh dianggap gagal. null kalau invoice sudah lunas atau dibatalkan.
payment_link.url, payment_link.qr_imageUntuk checkout. Field stabil yang sebaiknya Anda pakai.
modelive atau sandbox.

Catatan

Beberapa field di payment_link memakai camelCase (linkCode, orderId, feeAmount, uniqueCode, totalAmount, expiresAt). Nama ini tetap, jadi aman dipakai.

Request ulang (idempotent replay)

Kalau request diulang dengan akun, order_id, Idempotency-Key, dan isi yang sama, server mengembalikan 200 OK dengan existing: true dan invoice yang sama dalam bentuk lengkap. Jangan membuat invoice kedua dan jangan mengganti key saat retry timeout. Server mengingat isi request pertama (amount, fee_amount, order_id, title, description, webhook_url, callback_url). Key yang sama dengan isi berbeda ditolak 422 idempotency_key_reused.

Respons
200 OKContent-Type: application/json
{
  "success": true,
  "existing": true,
  "payment_mode": "gateway",
  "payment_attempt_id": "2de4a4d5-3b0e-4b7a-9a3e-4c9f7a2b1e55",
  "payment_link": {
    "id": 456,
    "linkCode": "aZ3kQ9mP2xLw",
    "orderId": "INV-2026-0001",
    "amount": 150000,
    "feeAmount": 0,
    "provider_fee_amount": 1200,
    "net_amount": 148800,
    "uniqueCode": 321,
    "totalAmount": 150321,
    "description": "Pesanan pelanggan INV-2026-0001",
    "expiresAt": "2026-10-17T03:15:00.000Z",
    "payable_until": "2026-10-17T04:15:00.000Z",
    "url": "/p/aZ3kQ9mP2xLw",
    "qr_image": "data:image/png;base64,iVBOR..."
  },
  "mode": "live"
}

Mengulang setelah gagal atau kedaluwarsa

Satu order_id hanya boleh dipakai untuk satu pembayaran gateway, apa pun statusnya. Mengganti Idempotency-Key saja tidak membuka order yang sama lagi, dan mengulang key lama untuk pembayaran yang sudah gagal atau kedaluwarsa menghasilkan 409 gateway_order_id_used. Kirim order_id baru, misalnya INV-2026-0001-R2. Key dihitung bersama order_id, jadi key yang sama dengan order_id berbeda membuat pembayaran terpisah.

Error

StatusArtiContoh body
400Input atau idempotency tidak valid. Selalu ada code.invalid_order_id, missing_idempotency_key, invalid_idempotency_key, invalid_amount, amount_too_large, invalid_fee_amount, fee_exceeds_base, amount_below_provider_fee, total_amount_too_large, gateway_total_exceeds_cap, invalid_webhook_url, invalid_callback_url
400Body JSON rusak.{"error":"...","code":400}
401Credential tidak ada atau salah.API key required (send it in the x-api-key header) atau Invalid API key
403KYC belum disetujui.{"error":"KYC verification is required before using automatic payment gateway","code":"KYC_REQUIRED","kyc_status":"pending"}
403Akun nonaktif atau JWT tidak valid.Account is deactivated, {"error":"merchant account is inactive","code":"account_inactive"}, Invalid or expired token
403Total nominal hari ini sudah mencapai batas akun yang baru lolos KYC. Kode new_account_daily_amount_cap. Hanya kalau diaktifkan admin.Daily payment gateway amount limit reached for a newly verified account
409order_id sudah punya pembayaran gateway (berjalan, gagal, atau kedaluwarsa). Kode gateway_order_id_used.This order_id already has a gateway payment. Use a new order_id to try again.
409order_id dipakai pembayaran lain milik Anda, misalnya QRIS manual. Kode gateway_order_id_used.This order_id is already used by another payment. Use a new order_id to try again.
409Key sedang dipakai request lain untuk order yang sama. Kode idempotency_key_in_use.This Idempotency-Key is already in use for this order. Retry with the same request to get the existing payment.
409Request pertama untuk key ini masih diproses. Kode gateway_creation_in_progress.Kirim ulang request yang sama beberapa detik lagi.
422Key sudah dipakai untuk isi berbeda. Kode idempotency_key_reused.This Idempotency-Key was already used for a different request. Send the original request again to get its payment, or use a new Idempotency-Key.
429Terlalu banyak invoice terbuka. Kode gateway_open_limit.Too many open gateway payments. Wait for some to be paid or expire.
429Terlalu banyak invoice dibuat dalam satu menit (key live). Kode gateway_rate_limited, dengan header Retry-After.Too many gateway payments created in a short time. Try again shortly.
429Kuota harian Sandbox habis (key tq_test_, tanpa code, "mode": "sandbox").Rate limit exceeded
503Semua kode unik untuk nominal ini dipakai. Kode gateway_amount_busy.All unique codes for this amount are in use. Try again in a few minutes or use a different amount.
503Reservasi nominal lepas saat menyiapkan. Kode gateway_amount_reservation_lost.Buat pembayaran baru dengan order_id baru.
503DNS sedang bermasalah saat memeriksa webhook_url. Kode webhook_dns_unavailable.Kirim ulang request yang sama. Replay pembayaran yang sudah ada tidak butuh pemeriksaan ini.
503Gateway dimatikan admin atau belum dikonfigurasi (tanpa code).Payment gateway mode is disabled by admin
500Kesalahan internal saat menyiapkan pembayaran.Failed to create gateway payment. Ulangi dengan key yang sama, lalu cek status.
Respons
400 Bad RequestContent-Type: application/json
{
  "error": "fee amount must not exceed base amount",
  "code": "fee_exceeds_base"
}

Turunkan fee, maksimal sama dengan amount.

Response 429 membawa header Retry-After dalam detik. Response yang lolos membawa X-RateLimit-Limit, X-RateLimit-Remaining, dan X-RateLimit-Reset untuk jendela per menit (key live) atau kuota harian Sandbox (key tq_test_).

Status Gateway

GET/api/payment-gateway/status
  • Key live atau tq_test_
  • Tanpa kuota

Ambil status gateway, akses KYC, tarif biaya layanan, dan jumlah invoice yang masih terbuka. Tetap bisa dipanggil saat gateway dimatikan (enabled: false). Dengan key tq_test_, response menggambarkan Sandbox.

curl https://temanqris.com/api/payment-gateway/status \
  -H "X-API-Key: YOUR_API_KEY"
Respons
200 OKContent-Type: application/json
{
  "enabled": true,
  "payment_mode": "gateway",
  "mode": "live",
  "max_base_amount": 1000000,
  "max_total_amount": 1000999,
  "open_attempt_count": 2,
  "provider_fee": {
    "percent_bps": 80,
    "flat_amount": 0,
    "threshold_amount": 1,
    "below_threshold_percent_bps": 80
  },
  "kyc_status": "approved",
  "gateway_access": "available"
}
FieldArti
enabledGateway live sedang aktif. Selalu true di Sandbox.
open_attempt_countInvoice yang masih terbuka (dibuat atau QR aktif).
provider_feeTarif biaya layanan untuk invoice baru. percent_bps dalam basis poin (80 = 0,8%) berlaku untuk nominal dasar mulai threshold_amount. Di bawahnya biayanya flat_amount ditambah below_threshold_percent_bps dari nominal dasar, dibulatkan ke atas. Saat ini percent_bps dan below_threshold_percent_bps sama-sama 80 dengan threshold_amount 1 dan flat_amount 0, jadi semua nominal dikenai 0,8%.
kyc_statusnot_started, pending, needs_action, approved, rejected, atau expired. Sandbox: not_required.
gateway_accessavailable kalau KYC disetujui, kyc_required kalau belum.

Catatan

Response hanya menampilkan status yang diperlukan untuk integrasi. Detail routing dan rekonsiliasi tetap di server.

Mode Sandbox

Uji seluruh alur gateway tanpa uang sungguhan: buat invoice, buka halaman bayar, terima webhook bertanda tangan, lalu cek hasilnya. Endpoint, body request, dan cara verifikasi webhook sama dengan mode live. Yang menentukan mode hanya API key yang Anda kirim.

Tanpa KYC, tanpa uang sungguhan

Sandbox terbuka untuk semua merchant dan tetap jalan walau gateway live sedang dimatikan. Sandbox tidak menyentuh saldo, wallet, atau pendapatan.

Live dan Sandbox

AspekLiveSandbox
API key64 karakter heksadesimal dari Dashboard Settingstq_test_ + 48 karakter heksadesimal dari console Sandbox
Webhook secret64 karakter heksadesimalwhsec_test_ + 48 karakter heksadesimal
X-TemanQRIS-Mode dan data.modelivesandbox
KYCWajib disetujuiTidak perlu
Uang dan saldoUang sungguhan, masuk wallet sebagai saldo tertahan (H+1)Tidak ada uang, saldo tidak berubah
QRBisa dibayar, berlaku 1 jamSengaja tidak bisa dibayar, hasil disimulasikan
Kode unikUnik di seluruh platformDiacak tanpa reservasi
KuotaKuota harian tier500 panggilan per hari, terpisah
Halaman bayar/p/{linkCode}/p/sb_... berlabel SANDBOX
DataDisimpanDihapus otomatis setelah 30 hari

Mendapatkan sandbox key

  1. Buka dashboard

    Masuk ke Payment Gateway, lalu geser saklar ke Sandbox. Key dibuat otomatis saat pertama kali dibuka.

  2. Tampilkan key

    Key lengkap hanya muncul setelah Anda memasukkan password. Bentuknya tq_test_ diikuti 48 karakter heksadesimal.

  3. Ganti kalau perlu

    Tombol rotate juga meminta password. Key lama langsung berhenti bekerja.

Pakai di endpoint yang sama

Kirim sandbox key di header X-API-Key ke POST /api/payment-gateway/payments dan GET /api/payment-gateway/status. Setiap response berisi "mode": "sandbox" (response live berisi "mode": "live"). Sandbox key hanya diterima di dua endpoint itu dan di dua endpoint sandbox di bawah (cek invoice dan simulasi). Di endpoint API lain key itu ditolak dengan 401.

cURL
curl -X POST https://temanqris.com/api/payment-gateway/payments \
  -H "X-API-Key: tq_test_KEY_SANDBOX_ANDA" \
  -H "Idempotency-Key: INV-2026-0001-attempt-01" \
  -H "Content-Type: application/json" \
  -d '{"order_id":"INV-2026-0001","amount":150000,"webhook_url":"https://merchant.example/webhooks/temanqris"}'

Aturan nominal, fee, biaya layanan, order_id, Idempotency-Key, dan validasi webhook_url sama dengan live, jadi error yang Anda temui di sandbox adalah error yang sama di live. Response create sama dengan live ditambah "paid_late": false. payment_link.payable_until di sandbox adalah expiresAt ditambah masa tenggang live, dan null setelah invoice lunas. Bedanya:

  • Kode unik diacak 0 sampai 999 tanpa reservasi, sehingga dua invoice sandbox bisa punya total yang sama.
  • Invoice sandbox berlaku 1 jam, sama seperti live. Invoice yang lewat waktu tampil expired, dan replay untuk invoice itu ditolak 409 gateway_order_id_used seperti live.
  • order_id sandbox terpisah dari live. Anda boleh memakai order_id yang sama di kedua mode.
  • Link halaman bayar berbentuk /p/sb_....

Kuota sandbox

PanggilanBatas
Buat invoice, simulasi, dan tombol console yang menulis (buat, simulasi, kirim ulang)Kuota sendiri sandbox_daily_limit, bawaan 500 per hari, terpisah dari kuota live. Lewat batas: 429 dengan "mode": "sandbox". Reset 00.00 UTC.
Cek invoice (GET .../sandbox/payments/:order_id)Tidak memakai kuota harian. Maksimal 120 per menit per merchant (429, code: "rate_limited").
Status gateway dengan sandbox keyTidak dibatasi kuota.

Daftar invoice sandbox, kirim ulang webhook, dan hapus data sandbox ada di console dashboard (butuh login), bukan lewat API key.

QR sandbox tidak bisa dibayar

QR di invoice sandbox sengaja tidak valid, jadi tidak ada e-wallet yang bisa membayarnya. Halaman bayar /p/sb_... diberi label SANDBOX, jangan dibayar. Hasil pembayaran Anda simulasikan lewat salah satu cara ini:

  • Tombol di halaman bayar sandbox: Simulasikan bayar, Simulasikan kedaluwarsa, dan Simulasikan bayar telat. Tombol yang sama ada di console dashboard.
  • API simulasi, hanya dengan sandbox key.

Cek invoice sandbox

GET/api/payment-gateway/sandbox/payments/:order_id
  • Sandbox key tq_test_
curl https://temanqris.com/api/payment-gateway/sandbox/payments/INV-2026-0001 \
  -H "X-API-Key: tq_test_KEY_SANDBOX_ANDA"

Response sama dengan saat membuat invoice (dengan existing: true), ditambah status (qr_issued, paid, expired), paid_at, dan paid_late. Invoice terbuka yang melewati waktu kedaluwarsa tampil expired. Tidak ditemukan: 404 sandbox_payment_not_found.

Respons
200 OKContent-Type: application/json
{
  "success": true,
  "existing": true,
  "payment_mode": "gateway",
  "payment_attempt_id": "7b0f3c2e-9a41-4d5e-8c3b-1f2e3d4c5b6a",
  "payment_link": {
    "id": 31,
    "linkCode": "sb_Xk2mQ9aZ3pLw7RtY",
    "orderId": "INV-2026-0001",
    "amount": 150000,
    "feeAmount": 0,
    "provider_fee_amount": 1200,
    "net_amount": 148800,
    "uniqueCode": 87,
    "totalAmount": 150087,
    "description": null,
    "expiresAt": "2026-10-17T03:15:00.000Z",
    "payable_until": "2026-10-17T04:15:00.000Z",
    "url": "/p/sb_Xk2mQ9aZ3pLw7RtY",
    "qr_image": null
  },
  "mode": "sandbox",
  "paid_late": false,
  "status": "qr_issued",
  "paid_at": null
}

Simulasikan hasil pembayaran

POST/api/payment-gateway/sandbox/payments/:order_id/simulate
  • Sandbox key tq_test_
  • Memakai kuota sandbox
curl -X POST https://temanqris.com/api/payment-gateway/sandbox/payments/INV-2026-0001/simulate \
  -H "X-API-Key: tq_test_KEY_SANDBOX_ANDA" \
  -H "Content-Type: application/json" \
  -d '{"result":"paid"}'
resultEfek
paidInvoice yang masih terbuka menjadi paid dan webhook payment.confirmed masuk antrean.
expiredInvoice yang masih terbuka menjadi expired.
late_paidInvoice terbuka atau yang sudah kedaluwarsa menjadi paid dengan paid_late: true, seperti pembayaran telat di masa tenggang live.

Response: bentuk yang sama dengan cek invoice, ditambah changed (true), webhook_queued (true atau false), dan webhook_reason (null kalau webhook masuk antrean; not_paid untuk expired; no_webhook_url; atau no_webhook_secret).

Respons
200 OKContent-Type: application/json
{
  "success": true,
  "existing": true,
  "payment_mode": "gateway",
  "payment_attempt_id": "7b0f3c2e-9a41-4d5e-8c3b-1f2e3d4c5b6a",
  "payment_link": { "linkCode": "sb_Xk2mQ9aZ3pLw7RtY", "orderId": "INV-2026-0001", "totalAmount": 150087, "...": "..." },
  "mode": "sandbox",
  "paid_late": false,
  "changed": true,
  "webhook_queued": true,
  "webhook_reason": null,
  "status": "paid",
  "paid_at": "2026-10-17T03:05:41.000Z"
}

Kode error sandbox

StatusKodeArti
400sandbox_invalid_resultresult bukan paid, expired, atau late_paid.
403wrong_gateway_modeEndpoint ini butuh sandbox key, tetapi Anda mengirim key live.
404sandbox_payment_not_foundTidak ada invoice sandbox dengan order_id itu di akun Anda.
409sandbox_invalid_transitionInvoice sudah dibayar atau sudah kedaluwarsa, jadi hasil itu tidak berlaku. Hanya late_paid yang boleh dipakai pada invoice kedaluwarsa.
409sandbox_webhook_pendingKirim ulang webhook ditolak: webhook sebelumnya masih dalam antrean.
409sandbox_no_webhook_eventKirim ulang webhook ditolak: belum ada pembayaran yang disimulasikan.
409sandbox_no_webhook_urlKirim ulang webhook ditolak: invoice tidak punya webhook_url.
409sandbox_no_webhook_secretKirim ulang webhook ditolak: webhook secret sandbox belum bisa disiapkan. Coba lagi nanti.
429rate_limited atau tanpa codeBatas per menit (cek invoice) atau kuota harian sandbox habis. Body berisi "mode": "sandbox".

Webhook sandbox

  • Ditandatangani dengan webhook secret sandbox (whsec_test_ diikuti 48 karakter hex), bukan webhook secret live. Lihat, salin, atau buat ulang secret ini di console sandbox (butuh password). Server uji Anda harus memverifikasi dengan secret ini.
  • Header sama dengan live (X-TemanQRIS-Signature, X-TemanQRIS-Event, X-TemanQRIS-Idempotency-Key, X-TemanQRIS-Retry) ditambah X-TemanQRIS-Mode: sandbox. Handler production Anda harus menolak setiap webhook dengan X-TemanQRIS-Mode: sandbox. Webhook live selalu membawa X-TemanQRIS-Mode: live dan data.mode bernilai live.
  • Isi data sama dengan live, dengan "mode": "sandbox" dan tambahan "paid_late" (true untuk late_paid).
  • Webhook hanya dikirim kalau invoice punya webhook_url. Secret sandbox dibuat otomatis saat webhook pertama atau saat Anda pertama membuka console. Response simulasi lewat API dan console memuat webhook_queued dan webhook_reason. Halaman bayar sandbox hanya menerima webhook_queued, tanpa alasannya.
  • Dikirim oleh worker, biasanya dalam sekitar satu menit setelah simulasi, dengan jadwal retry yang sama dengan live: 30 detik, 2 menit, 10 menit, maksimal 4 percobaan. Webhook sandbox yang gagal tidak memicu peringatan ke admin.
  • Tombol Kirim ulang webhook di console mengirim event terakhir lagi dengan idempotency key yang sama, jadi Anda bisa menguji penanganan duplikat.
  • Urutan key JSON bisa berbeda dari live. Selalu verifikasi signature terhadap raw body, jangan terhadap JSON yang sudah diserialisasi ulang.
JSON
{
  "event": "payment.confirmed",
  "idempotency_key": "3b1c9d2e-4f5a-4b6c-8d7e-9f0a1b2c3d4e",
  "timestamp": "2026-10-17T03:06:12.000Z",
  "data": {
    "order_id": "INV-2026-0001",
    "base_amount": 150000,
    "total_amount": 150087,
    "status": "paid",
    "mode": "sandbox",
    "paid_late": false
  }
}

(Ringkas. Payload lengkap sama dengan webhook gateway.)

Pindah ke live

Pastikan KYC sudah disetujui, lalu ganti sandbox key dengan key live dan webhook secret sandbox dengan webhook secret live di server Anda. Endpoint, body request, dan cara verifikasi webhook tetap sama. Pastikan handler production hanya menerima X-TemanQRIS-Mode: live. Checklist lengkap ada di Sandbox ke Live.

Data sandbox

Invoice dan log webhook sandbox disimpan 30 hari, lalu dihapus otomatis setiap jam. Anda bisa menghapusnya lebih awal lewat tombol Hapus data sandbox di console (butuh password). Admin hanya melihat jumlah pemakaian sandbox, bukan isi data Anda.

Biaya, Saldo Tertahan, dan Refund

Rincian uang dalam satu pembayaran

KomponenDibayar pelangganMasuk ke wallet AndaKe TemanQRIS
amount (nominal dasar)YaYa
fee_amount (biaya tambahan, opsional)YaYa
unique_code (0 sampai 999)YaYa
provider_fee_amount (biaya layanan)DipotongYa
  • total_amount = amount + fee_amount + unique_code
  • net_amount = amount + fee_amount - provider_fee_amount

Contoh perhitungan biaya layanan (0,8%)

amountfee_amountBiaya layanannet_amount
10.0000809.920
50.000040049.600
50.00040040050.000
99.9990800 (799,992 dibulatkan ke atas)99.199
100.000080099.200
150.00001.200148.800
1.000.00008.000992.000
1010, ditolak amount_below_provider_fee

Mau pelanggan yang menanggung biaya layanan?

Isi fee_amount sebesar ceil(amount x 0,008). Dengan begitu net_amount sama dengan amount. Selalu ambil tarif terbaru dari GET /api/payment-gateway/status.

Saldo tertahan (H+1)

  • Dana gateway masuk ke wallet sebagai saldo tertahan dan bisa ditarik mulai 00.00 WIB hari berikutnya setelah waktu pembayaran.
  • Pembayaran pukul 23.50 WIB tersedia 10 menit kemudian. Pembayaran pukul 00.10 WIB tersedia hampir 24 jam kemudian.
  • Saldo tertahan tetap terlihat di Wallet dan Saldo, tapi belum bisa ditarik.
  • Wallet yang sedang dikunci tetap menerima dana. Yang diblokir hanya penarikan.
  • Webhook payment.confirmed dikirim saat pembayaran terkonfirmasi, bukan saat dana bisa ditarik.
  • Penarikan saldo dikenai biaya 1% dari nominal penarikan (dibulatkan ke atas), minimal Rp2.500 dan maksimal Rp4.500.

Refund dan penarikan kembali dana

  • Refund tidak tersedia lewat API. Kalau pelanggan meminta refund, hubungi support TemanQRIS.
  • Kalau refund terjadi di sisi penyedia pembayaran untuk transaksi yang sudah dikreditkan ke Anda, sistem mencatatnya dan admin meninjaunya. Tidak ada dana yang ditarik otomatis.
  • Kalau admin menyetujui penarikan kembali (reversal), dana diambil dari saldo tertahan lebih dulu, lalu dari saldo tersedia. Jumlahnya tidak pernah melebihi dana yang dikreditkan untuk pembayaran itu.
  • Kalau saldo tidak cukup, kekurangannya dicatat dan wallet dikunci untuk penarikan sampai diselesaikan bersama admin.
  • Tidak ada webhook untuk refund atau reversal. Perubahan terlihat di riwayat wallet.

Pembayaran yang tidak cocok

Pembayaran dengan nominal yang tidak sama dengan total invoice mana pun, pembayaran setelah payable_until (masa tenggang habis), atau pembayaran ke order yang sudah dibatalkan tidak dikreditkan otomatis. Pembayaran itu masuk antrean tinjauan admin. Minta pelanggan menghubungi support dengan bukti transfer.

Webhook

Terima notifikasi real-time saat status pembayaran berubah. Webhook dikirim ke webhook_url yang Anda isi saat membuat pembayaran: lewat POST /api/qris/generate, POST /api/qris/payment-link, atribut widget data-webhook, atau POST /api/payment-gateway/payments.

Wajib: buat webhook secret dulu

Buka Dashboard Settings dan buat webhook secret (64 karakter heksadesimal, butuh password untuk melihat atau membuat ulang). Tanpa secret, TemanQRIS tidak mengirim webhook apa pun, walaupun webhook_url sudah diisi.

Jenis event

EventPemicuArti
payment.awaiting_confirmationPelanggan menekan Sudah Bayar di halaman bayar atau widget (manual saja).Pelanggan mengaku sudah bayar. Cek dana, lalu verifikasi.
payment.confirmedAnda memverifikasi lewat dashboard atau API, atau server gateway selesai mencocokkan pembayaran.Pembayaran sah. Untuk gateway lihat Webhook Gateway.

Tidak ada event untuk kedaluwarsa, pembatalan, atau refund. Pakai expires_at dan GET /api/qris/orders/:orderId untuk itu.

Payload manual

JSON
{
  "event": "payment.awaiting_confirmation",
  "idempotency_key": "a3f1c2d4-5b6e-4f70-8a9b-0c1d2e3f4a5b",
  "timestamp": "2026-10-17T09:00:00.000Z",
  "data": {
    "order_id": "INV-2026-001",
    "link_code": "ABC12345XYZW",
    "amount": 75000,
    "description": "Pembayaran Order #12345",
    "status": "awaiting_confirmation",
    "paid_at": null,
    "created_at": "2026-10-17T08:55:00.000Z",
    "mode": "live"
  }
}
FieldArti
idempotency_keyID unik pengiriman event ini. Sama di setiap percobaan ulang. Simpan untuk membuang duplikat.
timestampWaktu payload dibuat (UTC).
data.amountNominal dasar, tanpa fee. Untuk total, pakai catatan order Anda.
data.paid_atTerisi pada payment.confirmed.
data.modeSelalu live untuk pembayaran sungguhan.

Header

HeaderIsi
Content-Typeapplication/json
X-TemanQRIS-Signaturesha256=<hex>, HMAC-SHA256 dari raw body dengan webhook secret Anda.
X-TemanQRIS-EventNama event, misalnya payment.awaiting_confirmation.
X-TemanQRIS-Idempotency-KeySama dengan idempotency_key di body.
X-TemanQRIS-RetryNomor percobaan ulang (1, 2, 3). Pengiriman pertama webhook gateway berisi 0. Pengiriman pertama webhook manual tidak membawa header ini.
X-TemanQRIS-Modelive untuk pembayaran sungguhan, sandbox untuk uji coba.
User-AgentTemanQRIS-Webhook/1.0

Aturan pengiriman

  • Balas dengan status 2xx setelah data tersimpan. Status lain, timeout, atau redirect (3xx) dianggap gagal. Redirect tidak diikuti.
  • Batas waktu 10 detik per percobaan, dihitung dari awal request sampai response selesai.
  • Gagal? Dikirim ulang sampai 3 kali dengan jeda 30 detik, 2 menit, lalu 10 menit (total 4 percobaan). Payload dan idempotency_key tetap sama.
  • Webhook manual dikirim langsung saat status berubah. Webhook gateway masuk antrean dan biasanya tiba dalam sekitar satu menit.
  • webhook_url harus mengarah ke alamat publik. Alamat private, loopback, link-local, dan range khusus lain ditolak, baik saat URL didaftarkan maupun saat setiap pengiriman (termasuk perlindungan DNS rebinding). Di production wajib HTTPS.
  • Webhook bisa datang lebih dari sekali atau tidak berurutan. Selalu buang duplikat dengan idempotency_key dan jangan turunkan status yang sudah paid.

Verifikasi Signature

TemanQRIS menandatangani byte body persis seperti yang dikirim. Hitung HMAC dari raw body, bukan dari JSON yang sudah di-parse lalu diserialisasi ulang, karena urutan key dan spasi bisa berbeda. Bandingkan dengan fungsi waktu konstan.

Langkah di setiap handler:

  1. Baca raw body.

  2. Hitung sha256= + HMAC-SHA256(raw body, webhook secret) dalam hex.

  3. Bandingkan dengan X-TemanQRIS-Signature secara waktu konstan. Gagal: balas 401.

  4. Parse JSON. Di production, tolak kalau X-TemanQRIS-Mode atau data.mode bukan live.

  5. Buang duplikat dengan idempotency_key.

  6. Proses dalam transaksi, lalu balas 2xx.

const express = require('express');
const crypto = require('crypto');
const app = express();

function verifyTemanQRIS(rawBody, signature, secret) {
  const expected = 'sha256=' + crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
  // timingSafeEqual melempar error kalau panjangnya beda, jadi cek dulu.
  if (typeof signature !== 'string' || signature.length !== expected.length) return false;
  return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}

// express.raw, bukan express.json: kita butuh body mentah.
app.post('/webhooks/temanqris', express.raw({ type: 'application/json' }), async (req, res) => {
  if (!verifyTemanQRIS(req.body, req.get('X-TemanQRIS-Signature'), process.env.TEMANQRIS_WEBHOOK_SECRET)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }
  const payload = JSON.parse(req.body.toString('utf8'));
  if (req.get('X-TemanQRIS-Mode') !== 'live' || payload.data.mode !== 'live') {
    return res.status(400).json({ error: 'Not a live webhook' });
  }
  // Buang duplikat dengan payload.idempotency_key, lalu update order dalam transaksi.
  if (payload.event === 'payment.confirmed') {
    // tandai order lunas
  }
  res.sendStatus(204);
});

Laravel: pakai $request->getContent() untuk raw body dan $request->header('X-TemanQRIS-Signature'). Kecualikan route webhook dari middleware CSRF.

Jangan tandai lunas dari sumber lain

callback_url, parameter redirect widget, dan endpoint publik Sudah Bayar bisa dipicu siapa saja. Satu-satunya bukti adalah webhook bertanda tangan atau GET /api/qris/orders/:orderId dari backend Anda.

Webhook Gateway dan Callback

Gateway memakai sistem webhook yang sama untuk mengirim pembayaran yang sudah dikonfirmasi server.

Alur event gateway

  1. Terbitkan invoice

    POST /api/payment-gateway/payments menerbitkan QR dan menyimpan invoice.

  2. Terima pembayaran

    Pelanggan membayar lewat payment_link.url atau payment_link.qr_image.

  3. Rekonsiliasi server

    Worker mencocokkan total nominal dan mengunci klaim transaksi di database.

  4. Kredit dan antrean webhook

    Dalam satu transaksi, wallet Anda dikreditkan net_amount (saldo tertahan) dan webhook payment.confirmed dimasukkan ke antrean. Kalau kredit gagal, webhook juga tidak ada.

  5. Kirim webhook

    Biasanya dalam sekitar satu menit ke webhook_url.

  6. Arahkan pelanggan

    Pelanggan dapat diarahkan ke callback_url, tapi callback bukan bukti pembayaran.

Payload payment.confirmed gateway

JSON
{
  "event": "payment.confirmed",
  "idempotency_key": "8f4e2b1a-6c3d-4e5f-9a0b-1c2d3e4f5a6b",
  "timestamp": "2026-10-17T03:08:30.000Z",
  "data": {
    "order_id": "INV-2026-0001",
    "link_code": "aZ3kQ9mP2xLw",
    "amount": 150000,
    "description": "Pesanan pelanggan INV-2026-0001",
    "status": "paid",
    "paid_at": "2026-10-17T03:08:12.000Z",
    "created_at": "2026-10-17T03:00:00.000Z",
    "mode": "live",
    "payment_mode": "gateway",
    "payment_attempt_id": "2de4a4d5-3b0e-4b7a-9a3e-4c9f7a2b1e55",
    "base_amount": 150000,
    "fee_amount": 0,
    "unique_code": 321,
    "total_amount": 150321,
    "provider_fee_amount": 1200,
    "net_amount": 148800,
    "confirmed_by": "gateway"
  }
}
FieldArti
total_amountbase_amount + fee_amount + unique_code. Cocokkan dengan totalAmount yang Anda simpan saat membuat invoice.
net_amountbase_amount + fee_amount - provider_fee_amount. Yang dikreditkan ke wallet Anda (saldo tertahan sampai 00.00 WIB hari berikutnya).
provider_fee_amountBiaya layanan gateway TemanQRIS untuk invoice ini.
payment_attempt_idSama dengan response create.
paid_atWaktu pembayaran. Kalau setelah expiresAt invoice, pelanggan membayar dalam masa tenggang. Payload live tidak punya field paid_late.
confirmed_bygateway, baik untuk pembayaran yang dicocokkan otomatis maupun yang diselesaikan admin. Untuk membedakan jalur, tetap pakai payment_mode.

Header

HeaderFungsi
X-TemanQRIS-SignatureHMAC-SHA256 dalam format sha256=<hex>.
X-TemanQRIS-EventNama event, untuk gateway biasanya payment.confirmed.
X-TemanQRIS-Idempotency-KeyKunci pengiriman. Simpan untuk membuang retry ganda.
X-TemanQRIS-Retry0 di pengiriman pertama, 1 sampai 3 di pengiriman ulang.
X-TemanQRIS-Modelive untuk pembayaran sungguhan, sandbox untuk uji coba. Handler production harus menolak sandbox. Payload live juga membawa data.mode: "live".

Handler gateway

const crypto = require('crypto');

function verifyTemanQRIS(rawBody, signature, webhookSecret) {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', webhookSecret)
    .update(rawBody)
    .digest('hex');
  if (typeof signature !== 'string' || signature.length !== expected.length) return false;
  return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}

app.post('/webhooks/temanqris', express.raw({ type: 'application/json' }), async (req, res) => {
  const signature = req.headers['x-temanqris-signature'];
  if (!verifyTemanQRIS(req.body, signature, process.env.TEMANQRIS_WEBHOOK_SECRET)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }
  const payload = JSON.parse(req.body.toString('utf8'));
  // Production hanya menerima pengiriman live.
  if (req.headers['x-temanqris-mode'] !== 'live' || payload.data.mode !== 'live') {
    return res.status(400).json({ error: 'Not a live webhook' });
  }
  if (payload.event === 'payment.confirmed' && payload.data.payment_mode === 'gateway') {
    // Buang duplikat dengan payload.idempotency_key, cocokkan total_amount,
    // lalu update order dalam transaksi.
  }
  return res.sendStatus(204);
});

Tips

Balas 2xx setelah data tersimpan dengan aman. Pengiriman gagal diulang dengan aturan di atas (3 kali, batas waktu 10 detik). Kalau semua percobaan gagal, admin TemanQRIS diberi tahu, tapi jangan bergantung pada itu: jalankan polling cadangan GET /api/qris/orders/:orderId. Jangan pernah menandai order lunas dari callback tanpa tanda tangan atau dari endpoint klaim pelanggan.

Widget.js

Pasang tombol pembayaran QRIS di website Anda dengan satu baris kode, tanpa backend dan tanpa API key. Widget menampilkan modal pembayaran yang responsif.

Pemasangan

HTML
<script
  src="https://temanqris.com/widget.js"
  data-merchant="YOUR_MERCHANT_ID"
></script>

Mendapatkan Merchant ID

Login ke Dashboard > Widget untuk melihat Merchant ID Anda.

Tombol "Bayar dengan QRIS" muncul di tempat script dipasang:

Bayar dengan QRIS
Pratinjau tombol widget

Cara kerja widget

  1. Pelanggan menekan tombol. Kalau data-amount kosong, pelanggan mengisi nominal.

  2. Widget membuat QR dinamis dari QRIS statis Anda dan sebuah order dengan order_id berawalan ORD-W. QR berlaku 60 menit.

  3. Pelanggan membayar, lalu menekan tombol konfirmasi di widget.

  4. Order menjadi awaiting_confirmation dan webhook payment.awaiting_confirmation dikirim ke data-webhook.

  5. Pelanggan diarahkan ke data-callback (kalau diisi) atau melihat pesan sukses.

  6. Anda memverifikasi lewat dashboard atau POST /api/qris/orders/:orderId/verify. Webhook payment.confirmed dikirim.

Widget selalu memakai jalur manual. Dana masuk ke QRIS Anda sendiri.

Batas

  • Setiap QR widget dihitung terhadap batas harian tier Anda (dicatat sebagai widget_generate).
  • 60 QR per menit per IP pengunjung, dan 30 konfirmasi per menit per IP.

Opsi Widget

Atur widget lewat atribut data-*:

NamaTipeStatusKeterangan
data-merchantstringWajibMerchant ID Anda.
data-amountintegerOpsionalNominal tetap dalam rupiah, bilangan bulat. Kalau kosong, pelanggan mengisi sendiri.
data-button-textstringOpsionalTeks tombol. Bawaan: "Bayar dengan QRIS".
data-button-colorstringOpsionalWarna tombol dalam hex (#22c55e) atau nama warna CSS (green). Nilai lain kembali ke bawaan #ff6b35.
data-descriptionstringOpsionalDeskripsi pembayaran (opsional, maksimal 255 karakter).
data-callbackstring (URL)OpsionalCallback URL. Browser pelanggan diarahkan ke sini setelah menekan konfirmasi, dengan query order_id, amount, dan status.
data-webhookstring (URL)OpsionalWebhook URL. Notifikasi server ke server saat status berubah, untuk update database. Harus URL publik (HTTPS).

Contoh lengkap dengan callback dan webhook

HTML
<script
  src="https://temanqris.com/widget.js"
  data-merchant="abc123xyz"
  data-amount="50000"
  data-button-text="Bayar Sekarang"
  data-button-color="#22c55e"
  data-description="Pembayaran Order #123"
  data-callback="https://yoursite.com/thank-you"
  data-webhook="https://yoursite.com/webhook"
></script>

Callback URL (data-callback). Pelanggan diarahkan ke: https://yoursite.com/thank-you?order_id=ORD-W5E1A9C03B7D2F4E6&amount=50000&status=confirmed Nilai status=confirmed diisi oleh browser pelanggan dan hanya berarti pelanggan menekan tombol konfirmasi. Bukan bukti bayar. Cek status lewat webhook atau GET /api/qris/orders/:orderId dari backend.

Webhook URL (data-webhook). Server TemanQRIS mengirim POST ke URL Anda dengan payload standar: { "event": "payment.awaiting_confirmation", "idempotency_key": "...", "timestamp": "...", "data": { "order_id": "ORD-W...", "amount": 50000, ... } } Webhook hanya dikirim kalau Anda sudah membuat webhook secret. Lihat Verifikasi Signature.

Catatan keamanan

Merchant ID memang publik (ada di HTML halaman Anda) dan bukan rahasia. Siapa pun bisa membuat QR atas nama Anda dengan nominal apa pun, tapi dana selalu masuk ke QRIS Anda. Karena itu selalu cocokkan data.amount di webhook dengan harga yang Anda harapkan, dan jangan pernah menandai lunas dari redirect.

Widget API

Endpoint publik yang dipakai widget.js. Bisa dipanggil langsung kalau Anda membuat tampilan pembayaran sendiri di browser tanpa API key. CORS terbuka untuk semua origin.

Buat QR widget

POST/api/widget/generate
  • Publik, tanpa API key
  • 60 request per menit per IP
NamaTipeStatusKeterangan
merchant_idstringWajibMerchant ID, maksimal 64 karakter.
amountintegerWajibManual: 1 sampai 100.000.000. Gateway: maksimal 1.000.000.
descriptionstringOpsionalMaksimal 255 karakter.
webhook_urlstringOpsionalURL publik.
callback_urlstringOpsionalURL http(s).
payment_modestringOpsionalKosongkan untuk manual. Isi "gateway" untuk pembayaran otomatis (butuh KYC disetujui).
idempotency_keystringOpsionalHanya untuk gateway, maksimal 256 karakter. Key yang sama mengembalikan invoice yang sama. Tanpa key, setiap panggilan membuat invoice baru.
curl -X POST https://temanqris.com/api/widget/generate \
  -H "Content-Type: application/json" \
  -d '{
    "merchant_id": "abc123xyz",
    "amount": 50000,
    "description": "Pembayaran Order #123",
    "webhook_url": "https://yoursite.com/webhook",
    "callback_url": "https://yoursite.com/thank-you"
  }'
Respons
200 OKContent-Type: application/json
{
  "success": true,
  "order_id": "ORD-W5E1A9C03B7D2F4E6",
  "link_code": "W8F3A1C7E92B4D605",
  "amount": 50000,
  "merchant_name": "TOKO EXAMPLE",
  "qr_image": "data:image/png;base64,iVBOR...",
  "qris_string": "00020101021226...",
  "expires_at": "2026-10-17T04:00:00.000Z",
  "description": "Pembayaran Order #123"
}

Untuk gateway, amount adalah total yang harus dibayar (sudah termasuk kode unik). Biaya layanan tidak ditampilkan ke pelanggan, Anda melihatnya di webhook dan dashboard. order_id dibuat dari idempotency_key.

Error

StatusBody
400{"error":"merchant_id is required"}, {"error":"amount must be a whole number between 1 and 100000000"}, {"error":"Gateway amount must not exceed Rp1.000.000"}, {"error":"idempotency_key must be at most 256 characters"}
400{"error":"This amount is too small for an automatic payment. Use a larger amount.","code":"amount_too_small"}
400 503{"error":"webhook_url rejected: ...","code":"invalid_webhook_url"} atau webhook_dns_unavailable
400{"error":"webhook_url must use the website or app domain from your approved KYC","code":"webhook_host_mismatch"} atau callback_host_mismatch (gateway saja: webhook_url dan callback_url harus memakai domain website/aplikasi di KYC Anda yang sudah disetujui, atau subdomainnya. Mode manual bebas)
403KYC_REQUIRED (gateway)
403{"error":"Merchant ini sudah mencapai batas transaksi harian. Coba lagi besok.","code":"new_account_daily_amount_cap"} (gateway, hanya kalau batas nominal akun baru diaktifkan admin)
404{"error":"Merchant not available"} (merchant tidak ada, nonaktif, atau belum mengatur QRIS)
409{"error":"This payment attempt already failed or expired. Use a new idempotency_key to try again.","code":"gateway_attempt_terminal"}
429{"error":"Daily limit exceeded for this merchant"} (mode manual) atau batas per IP
503{"error":"Payment gateway mode is disabled by admin"}

Konfirmasi dari widget

POST/api/widget/confirm/:orderId
  • Publik, tanpa API key
  • 30 request per menit per IP

Sama seperti tombol Sudah Bayar: order menjadi awaiting_confirmation. Kirim link_code di body supaya order teridentifikasi tepat.

curl -X POST https://temanqris.com/api/widget/confirm/ORD-W5E1A9C03B7D2F4E6 \
  -H "Content-Type: application/json" \
  -d '{ "link_code": "W8F3A1C7E92B4D605" }'
Respons
200 OKContent-Type: application/json
{
  "success": true,
  "message": "Konfirmasi berhasil. Merchant akan segera memproses pesanan Anda.",
  "status": "awaiting_confirmation"
}

Konfirmasi ulang menjawab 200 dengan "message": "Pesanan sudah dikonfirmasi sebelumnya.". Order gateway menjawab 202 dengan payment_mode: "gateway" tanpa perubahan. Error: 404 Order ID tidak ditemukan, 400 kalau link kedaluwarsa atau status lain, 409 kalau order tidak bisa diidentifikasi unik (kirim link_code).

Info merchant

GET/api/widget/merchant/:merchantId
  • Publik, tanpa API key
curl https://temanqris.com/api/widget/merchant/abc123xyz
Respons
200 OKContent-Type: application/json
{ "success": true, "merchant_name": "TOKO EXAMPLE" }

Tidak ditemukan atau akun nonaktif: 404 {"error":"Merchant not available"}.

Plugin WordPress

Punya toko WordPress? Pasang plugin resmi TemanQRIS untuk menerima pembayaran QRIS tanpa menulis kode. Plugin bekerja dua cara: sebagai metode pembayaran di WooCommerce (checkout klasik maupun blok), dan sebagai tombol bayar lewat blok atau shortcode untuk situs non-WooCommerce.

Plugin atau API langsung?

Panduan lengkap di halaman ini ditujukan untuk developer yang memanggil API TemanQRIS secara langsung. Bagian ini khusus untuk pemakaian lewat plugin WordPress, jadi Anda tidak perlu menyentuh kode API sama sekali.

Sebelum mulai, siapkan:

  • WordPress 6.0 atau lebih baru, PHP 8.1 atau lebih baru.
  • Untuk alur WooCommerce: WooCommerce 8.0 atau lebih baru, dengan mata uang toko Rupiah (IDR).
  • Akun TemanQRIS. Untuk mode Live, verifikasi KYC harus sudah disetujui. Mode Sandbox bisa dipakai lebih dulu tanpa KYC untuk pengujian.
  • Situs dapat diakses dari internet, agar TemanQRIS bisa mengirim notifikasi webhook ke sana.

Pasang dan Aktifkan

Pasang plugin seperti plugin WordPress lainnya, dari direktori atau dengan mengunggah berkas zip.

  1. Di wp-admin, buka Plugin, Tambah Baru, cari "TemanQRIS", lalu pasang. Alternatifnya, pilih Unggah Plugin dan unggah berkas temanqris-payment-gateway.zip.

  2. Klik Aktifkan.

  3. Menu TemanQRIS muncul di sidebar admin. Mulai dari halaman Dashboard.

Sambungkan ke TemanQRIS

Hubungkan plugin ke akun TemanQRIS Anda dengan API key dan webhook secret, lalu pasang Webhook URL-nya.

  1. Masuk ke akun TemanQRIS, lalu buka menu Payment Gateway.

  2. Salin API key dan webhook secret dari sana.

  3. Di halaman Pengaturan plugin, tempel API key dan webhook secret, lalu pilih mode (Sandbox atau Live) sesuai jenis key-nya.

  4. Salin Webhook URL yang ditampilkan plugin, lalu tempel kembali di TemanQRIS, menu Payment Gateway, bagian Opsi Lanjutan (Webhook dan Callback).

  5. Buka halaman Status dan Cek di plugin dan jalankan cek koneksi untuk memastikan semuanya tersambung.

Webhook URL

Webhook URL adalah alamat milik situs Anda sendiri. Biasanya berakhiran /wp-json/temanqris/v1/webhook, atau ?rest_route=/temanqris/v1/webhook jika permalink situs masih bawaan WordPress. Anda tidak perlu menyusunnya sendiri: plugin menampilkan alamat yang tepat lengkap dengan tombol salin di halaman Pengaturan dan Status.

Pakai dengan WooCommerce

  1. Buka WooCommerce, Settings, Payments.

  2. Aktifkan TemanQRIS QRIS, lalu simpan.

  3. Di checkout, pembeli memilih QRIS, memindai QR-nya, dan membayar. Pesanan otomatis menjadi Processing begitu pembayaran terkonfirmasi.

Berlaku untuk checkout klasik maupun checkout blok. QRIS hanya muncul jika mata uang toko Rupiah dan total keranjang berada di bawah batas.

Blok dan Shortcode

Untuk menerima pembayaran tanpa WooCommerce, misalnya donasi atau tombol bayar, gunakan blok "Bayar dengan QRIS" di editor, atau shortcode berikut di halaman maupun postingan.

Nominal tetap:

TEXT
[temanqris_pay amount="50000" title="Donasi"]

Nominal bebas (pembeli yang mengisi, dengan batas):

TEXT
[temanqris_pay mode="dynamic" min="10000" max="500000" title="Bayar sesukamu"]

Atribut yang tersedia:

  • amount: nominal tetap dalam Rupiah (mode tetap).
  • mode: fixed (tetap) atau dynamic (bebas).
  • min, max: batas bawah dan atas untuk mode bebas.
  • title: judul yang tampil di tombol dan jendela pembayaran.
  • reference: kode referensi opsional untuk pencatatan Anda.
  • redirect: URL tujuan setelah pembayaran berhasil.

Nominal maksimum per transaksi adalah Rp 1.000.000. Nilai di atas batas otomatis ditolak.

Webhook dan Status

Begitu pembeli membayar, TemanQRIS mengirim notifikasi bertanda tangan ke Webhook URL toko Anda, dan plugin menandai pesanan sebagai lunas. Jika notifikasi terlambat, plugin juga menanyakan status ke TemanQRIS sebagai cadangan, sehingga pesanan tetap beres. Pantau kesehatannya kapan saja di halaman Status dan Cek: di sana terlihat kapan notifikasi terakhir masuk dan apakah koneksi API sehat.

Penggunaan API

GET/api/qris/usage
  • Auth: X-API-Key
  • Tanpa kuota

Pantau pemakaian API dan sisa kuota harian.

curl https://temanqris.com/api/qris/usage \
  -H "X-API-Key: YOUR_API_KEY"
Respons
200 OKContent-Type: application/json
{
  "tier": "free",
  "daily_limit": 50,
  "usage": {
    "today": {
      "total": 15,
      "remaining": 35,
      "by_endpoint": [
        { "endpoint": "/api/qris/generate", "request_count": 10 },
        { "endpoint": "/api/qris/payment-link", "request_count": 4 },
        { "endpoint": "/api/qris/orders/:orderId/verify", "request_count": 1 }
      ]
    },
    "this_month": {
      "total": 250,
      "by_endpoint": [
        { "endpoint": "/api/qris/generate", "total_requests": "180" },
        { "endpoint": "/api/qris/payment-link", "total_requests": "70" }
      ]
    }
  }
}
  • Hari dihitung per tanggal UTC (reset 07.00 WIB). Bulan dimulai tanggal 1.
  • endpoint berisi pola route, misalnya /api/qris/orders/:orderId/verify. QR dari widget tercatat sebagai widget_generate.
  • remaining diambil dari penghitung kuota harian, sama dengan yang dipakai header X-RateLimit-Remaining.
  • Pembayaran gateway live tercatat di rincian sebagai /api/payment-gateway/payments untuk statistik, tapi tidak memotong kuota harian. Jadi total bisa lebih besar dari jumlah request yang memakai kuota, sementara remaining tetap akurat.
  • Pemakaian Sandbox tidak masuk ke sini. Lihat kartu pemakaian di console Sandbox.

Changelog

Perubahan API yang terlihat dari sisi integrasi. Versi terbaru di atas.

v1.3.4Terbaru

Biaya layanan gateway 0,8% untuk semua nominal

Diubah
  • Biaya layanan gateway 0,8% untuk semua nominal. Dihitung dari amount dan dibulatkan ke atas ke rupiah penuh. Tarif khusus untuk nominal di bawah Rp100.000 tidak berlaku lagi. Di GET /api/payment-gateway/status, percent_bps dan below_threshold_percent_bps bernilai 80, threshold_amount 1, dan flat_amount 0. Invoice yang terbit sebelum perubahan tetap memakai tarif lamanya.
  • QR gateway berlaku 1 jam secara bawaan dan bisa diatur admin. Masa berlaku yang berlaku untuk invoice ada di expiresAt.
  • Field payable_until di response create gateway (payment_link.payable_until) dan GET /api/qris/orders/:orderId. Isinya batas terakhir pembayaran yang masih dikreditkan otomatis, jadi integrasi Anda tidak perlu menebak masa tenggang. null untuk order manual, lunas, atau dibatalkan.
  • Panduan pembatalan saat masa tenggang. Kalau pembeli batal sebelum membayar, batalkan order lewat POST /api/qris/orders/:orderId/cancel, walaupun QR sudah kedaluwarsa. Tanpa itu, pembayaran di masa tenggang tetap dikreditkan.
v1.3.3

Biaya layanan gateway di bawah Rp100.000 jadi 0,6%

Diubah
  • Biaya layanan gateway di bawah Rp100.000 jadi 0,6% mulai 1 November 2026. Mengikuti perubahan aturan dari penyedia (PJP) TemanQRIS. Sampai 31 Oktober 2026 biayanya Rp125 per transaksi. Mulai Minggu, 1 November 2026 pukul 00.00 WIB biayanya 0,6% dari amount, dibulatkan ke atas ke rupiah penuh. Rp100.000 ke atas tetap 0,9%. Invoice yang terbit sebelum tanggal itu tetap memakai biaya saat dibuat. Biaya tetap dipotong dari dana merchant, nominal yang dibayar pelanggan tidak berubah.
Ditambah
  • Field below_threshold_percent_bps di provider_fee pada GET /api/payment-gateway/status. Biaya di bawah threshold_amount adalah flat_amount ditambah persen ini dari nominal dasar. Client lama yang hanya membaca flat_amount tetap jalan, tapi sebaiknya ikut membaca field ini supaya hitungan biaya di sisi Anda tetap tepat setelah 1 November 2026.
v1.3.2

Gateway live tanpa kuota harian, dengan batas per menit

Ditambah
  • Batas pembuatan invoice per menit. Bawaan 60 invoice gateway live per merchant per menit, bisa diubah admin. Lewat batas: 429 dengan code: "gateway_rate_limited", limit, window_seconds, retry_after_seconds, dan header Retry-After.
  • Batas nominal harian untuk akun yang baru lolos KYC. Tidak aktif secara bawaan. Kalau diaktifkan admin, total amount invoice gateway live per hari dibatasi selama 14 hari pertama setelah KYC disetujui. Lewat batas: 403 dengan code: "new_account_daily_amount_cap", limit, used, dan resetTime. Replay dengan Idempotency-Key yang sama tidak dihitung lagi. Berlaku juga untuk Widget API mode gateway.
Diubah
  • Pembayaran gateway live tidak lagi memakai kuota harian. POST /api/payment-gateway/payments dengan key live atau JWT dashboard tidak memotong kuota 50 (Free) atau 1.000 (Premium) per hari. Kuota itu tetap berlaku untuk fitur QRIS manual. Panggilan gateway tetap tercatat di statistik GET /api/qris/usage. Key tq_test_ tetap memakai kuota Sandbox.
  • Header X-RateLimit-* di create gateway live sekarang menggambarkan jendela per menit, bukan kuota harian. X-RateLimit-Reset menunjuk awal menit berikutnya.
v1.3.1

Sandbox, biaya layanan gateway, dan error yang konsisten

Ditambah
  • Mode Sandbox untuk Payment Gateway. Key tq_test_ di endpoint yang sama, response dengan "mode": "sandbox", QR yang sengaja tidak bisa dibayar, halaman bayar /p/sb_..., simulasi paid, expired, dan late_paid lewat POST /api/payment-gateway/sandbox/payments/:order_id/simulate, cek invoice lewat GET /api/payment-gateway/sandbox/payments/:order_id, webhook bertanda tangan dengan secret terpisah whsec_test_, kuota sendiri 500 per hari, tanpa KYC, data dihapus otomatis setelah 30 hari.
  • Header X-TemanQRIS-Mode dan data.mode di setiap webhook. Live selalu live, sandbox selalu sandbox. Handler production harus menolak sandbox.
  • Biaya layanan gateway. 0,9% dari nominal dasar mulai Rp100.000 (dibulatkan ke atas), Rp125 di bawahnya. Dipotong dari dana merchant, bukan dari pelanggan. Field baru provider_fee_amount dan net_amount di response create, webhook, daftar link, dan cek order. Tarif terbaru ada di provider_fee pada GET /api/payment-gateway/status. Error baru amount_below_provider_fee.
  • Saldo tertahan H+1. Dana gateway bisa ditarik mulai 00.00 WIB hari berikutnya.
  • Refund dan reversal. Refund di sisi penyedia dicatat dan ditinjau admin. Reversal mengambil dari saldo tertahan dulu, lalu saldo tersedia, tidak pernah melebihi dana yang dikreditkan.
  • Masa tenggang bayar telat. Pembayaran sampai 60 menit (bawaan) setelah QR kedaluwarsa tetap dicocokkan dan dikreditkan.
  • Status KYC di GET /api/payment-gateway/status. Field kyc_status dan gateway_access. Gateway live tanpa KYC ditolak 403 KYC_REQUIRED.
  • Kode error bertipe. Setiap error gateway yang aman ditampilkan membawa code string. Error internal selalu dijawab 500 generik tanpa detail.
  • Halaman Kode Error dan Changelog di dokumentasi, plus contoh Node.js, PHP, dan Python untuk setiap endpoint.
Diubah
  • Biaya tambahan (fee_amount) dikreditkan ke merchant. Biaya tambahan ditetapkan merchant sendiri, dibayar pelanggan, masuk penuh ke saldo Anda, bersama amount. Hanya kode unik dan biaya layanan yang menjadi pendapatan TemanQRIS.
  • fee_amount tidak boleh melebihi amount (fee_exceeds_base).
  • Kode unik 0 sampai 999 dipilih dari total yang masih bebas di seluruh platform, sehingga dua invoice aktif tidak pernah punya total yang sama. Kalau semua kode untuk satu nominal sedang dipakai: 503 gateway_amount_busy.
  • Idempotency lebih ketat. Key disimpan sebagai hash SHA-256 dari akun, order_id, dan key. Isi request diingat: key yang sama dengan isi berbeda ditolak 422 idempotency_key_reused. Satu order_id hanya untuk satu pembayaran gateway (409 gateway_order_id_used). Request yang masih diproses: 409 gateway_creation_in_progress.
  • webhook_url hanya alamat publik. Alamat private, loopback, link-local, dan range khusus ditolak saat didaftarkan dan saat setiap pengiriman. Gangguan DNS sementara dijawab 503 webhook_dns_unavailable dan aman diulang.
  • Webhook gateway dijamin ada. Antrean webhook ditulis dalam transaksi yang sama dengan kredit wallet. Setiap percobaan dibatasi 10 detik.
  • Pembatalan order gateway menghentikan pencocokan otomatis. Pembayaran yang masuk setelahnya ditinjau admin.
  • Batas invoice terbuka hanya menghitung invoice yang masih berlaku.
  • Kuota harian dihitung tanpa kunci database, reset 00.00 UTC (07.00 WIB). Hanya error 5xx yang dikembalikan ke kuota.
  • Arsip payment link (DELETE /api/qris/payment-link/:id) menjawab {"success": true, "message": "Payment link archived"} dan menolak link yang sudah dibayar (409).
  • API key disimpan dalam bentuk hash untuk pencarian dan terenkripsi untuk ditampilkan ulang. Alur tampilkan key dengan password tidak berubah.
  • Upload QRIS menolak gambar lebih dari 6000 px atau 16 megapiksel sebelum diproses.
  • Rincian GET /api/qris/usage memakai pola route (misalnya /api/qris/orders/:orderId/verify).
  • Response API yang butuh login diberi header Cache-Control: no-store.
Diperbaiki
  • POST /api/qris/generate tidak lagi mengubah order lunas. Request yang sama persis untuk order paid atau awaiting_confirmation mengembalikan order itu apa adanya dengan existing: true. Nominal berbeda ditolak 409.
  • POST /api/qris/payment-link hanya memakai ulang link milik order_id yang sama. Tanpa order_id, yang dipakai ulang hanya link yang juga tanpa order_id.
  • Upload gambar dengan tipe yang tidak didukung (misalnya WebP) dijawab 400, bukan 500.
  • Filter status di GET /api/qris/orders berlaku untuk semua status, termasuk awaiting_confirmation. Nilai yang tidak dikenal ditolak 400.
  • POST /api/qris/generate saat DNS bermasalah menjawab 503 dengan code: "webhook_dns_unavailable", sama seperti gateway.
  • 503 gateway_amount_reservation_lost sekarang meminta order_id baru, karena order_id lama sudah terpakai.
  • Webhook settlement otomatis membawa confirmed_by: "gateway".
v1.3.0

Payment Gateway otomatis

Ditambah
  • Payment Gateway otomatis. Buat QRIS gateway dengan idempotency, nominal dasar sampai Rp1.000.000, total sampai Rp1.000.999, dan webhook bertanda tangan.
  • Dokumentasi publik /docs untuk endpoint create dan status Payment Gateway.
  • Contoh request dan response lengkap untuk kontrak gateway yang tidak bergantung pada penyedia: payment_attempt_id, kode unik, idempotency, checkout lewat payment link, dan status gateway.
  • Dokumentasi webhook settlement gateway bertanda tangan dengan payment.confirmed, field merchant yang netral terhadap penyedia, verifikasi HMAC, header retry, dan aturan keamanan callback. Metadata transaksi penyedia tetap internal.
  • Field operasional penyedia dihapus dari contoh API, webhook, dan dokumentasi publik.
  • Sesi penyedia tersimpan terenkripsi di database dan cursor routing yang tahan multi-worker.
  • Halaman gateway di dashboard diselaraskan dengan QRIS Generator dan memakai idempotency key yang stabil untuk retry.
  • Navigasi dokumentasi bisa dicari, dengan menu hamburger untuk layar kecil.
  • Contoh API lengkap (Full API Examples) untuk alur backend.

Butuh bantuan? Hubungi kami, atau buka Dashboard untuk API key dan webhook secret.

Terakhir diperbarui . API v1.3.4.