Integrasi Pembayaran QRIS Dinamis di Node.js: Panduan Lengkap

Pada sebuah proyek untuk klien di Indonesia, saya harus menambahkan QRIS ke alur checkout, dan hal pertama yang membingungkan tim adalah menganggap QRIS itu satu jenis saja. Padahal bukan. Ada versi statis yang Anda cetak jadi stiker, dan versi dinamis yang Anda buat langsung dari backend. Untuk apa pun yang menyerupai aplikasi atau toko online, Anda butuh QRIS dinamis, dan artikel ini membahas persis cara membangunnya di Node.js.

QRIS (Quick Response Code Indonesian Standard) adalah standar QR terpadu dari Bank Indonesia: satu QR yang bisa dipindai dan dibayar oleh e-wallet atau aplikasi mobile banking mana pun yang terdaftar (GoPay, OVO, DANA, ShopeePay, aplikasi bank). Sebagai developer, Anda hampir tidak pernah berbicara langsung dengan jaringan QRIS. Anda lewat PSP berlisensi, dan pekerjaan nyata Anda adalah membuat QR, menampilkannya, dan bereaksi terhadap webhook saat uang masuk.

QRIS statis vs dinamis: mana yang Anda butuhkan?

Perbedaannya penting untuk UX sekaligus rekonsiliasi. Dengan QR statis, pelanggan memindai satu kode cetak Anda dan mengetik nominalnya sendiri — cukup untuk warung, tapi menyulitkan untuk software karena Anda tidak bisa mengaitkan pembayaran ke pesanan tertentu secara andal. QR dinamis dicetak per transaksi dengan nominal terkunci, dan membawa referensi pesanan yang bisa dicocokkan webhook Anda. Berikut perbandingannya.

Membuat QRIS dinamis lewat PSP berlisensi

Anda tidak bisa secara legal membuat QRIS sah dari nol. Setiap QR harus memuat NMID asli dan ditandatangani ke jaringan switching nasional Bank Indonesia, yang hanya bisa dilakukan acquirer dan PJSP berlisensi. Jadi arsitekturnya selalu sama: backend Anda memanggil PSP, PSP mengembalikan QR, dan PSP menyelesaikan dana ke rekening Anda dikurangi MDR. Berikut PSP berlisensi yang biasa dipakai developer Indonesia.

• Midtrans (Core API dan Snap) — cakupan e-wallet paling luas, SDK Node.js yang kuat
• Xendit — API rapi, populer di kalangan startup dan fintech
• DOKU — sudah lama berdiri, kuat untuk kebutuhan enterprise dan biller
• API bank langsung (BRI, BCA, Mandiri) — jika Anda sudah menjadi nasabah dan ingin biaya lebih rendah di volume tinggi

NMID dan onboarding merchant

Sebelum satu QR pun berfungsi, Anda harus di-onboarding sebagai merchant. PSP Anda mengumpulkan dokumen usaha (KTP dan NIK untuk perorangan, NPWP dan akta pendirian untuk perusahaan), memverifikasi legalitas, dan acquirer menerbitkan NMID — National Merchant ID yang tertanam di setiap QR yang Anda tampilkan dan menghubungkan tiap pembayaran ke bisnis Anda di repositori merchant nasional. Siapkan waktu beberapa hari kerja: penerbitan NMID biasanya tiga sampai empat hari kerja dan aktivasi QRIS satu sampai dua hari lagi setelah dokumen lolos. Tidak ada yang bisa bertransaksi sampai ini selesai, jadi mulai onboarding lebih awal.

Alur MPM: membuat QR dinamis di Node.js

QRIS dinamis memakai MPM — Merchant Presented Mode — artinya merchant menampilkan QR dan pelanggan yang memindai (kebalikannya CPM, di mana pelanggan menunjukkan QR aplikasinya ke alat pindai). Alur MPM dalam kode ada tiga langkah: charge, render, konfirmasi. Dengan Midtrans Core API dan SDK Node.js mereka, membuat QR cukup satu panggilan charge dengan payment_type qris.

// Generate a dynamic QRIS via Midtrans Core API
import midtransClient from "midtrans-client";

const core = new midtransClient.CoreApi({
  isProduction: false,
  serverKey: process.env.MIDTRANS_SERVER_KEY,
  clientKey: process.env.MIDTRANS_CLIENT_KEY,
});

const charge = await core.charge({
  payment_type: "qris",
  transaction_details: {
    order_id: `INV-${Date.now()}`,
    gross_amount: 275000, // IDR, integer only — no decimals
  },
  qris: { acquirer: "gopay" }, // or "airpay_shopee" for ShopeePay
});

// The QR to show the customer lives in the actions array (MPM)
const qr = charge.actions.find((a) => a.name === "generate-qr-code");
console.log(charge.transaction_id, qr.url, charge.expiry_time);

Menangani callback/webhook pembayaran

Di sinilah kebanyakan integrasi diam-diam rusak. Aplikasi pelanggan bilang lunas, tapi backend Anda baru benar-benar tahu ketika PSP mengirim webhook ke notification URL Anda. Atur URL itu di dashboard PSP, siapkan endpoint HTTPS publik, dan — yang paling penting — verifikasi signature sebelum mempercayai apa pun. Midtrans menandatangani tiap notifikasi sebagai hash SHA-512 dari order_id, status_code, gross_amount, dan server key Anda. Identitas QR yang dibayar datang sebagai merchant_cross_reference_id.

import crypto from "node:crypto";
import express from "express";

const app = express();
app.use(express.json());

app.post("/webhooks/midtrans", async (req, res) => {
  const { order_id, status_code, gross_amount, signature_key,
          transaction_status, fraud_status } = req.body;

  // gross_amount here is a string like "275000.00"
  const expected = crypto
    .createHash("sha512")
    .update(order_id + status_code + gross_amount + process.env.MIDTRANS_SERVER_KEY)
    .digest("hex");

  if (expected !== signature_key) {
    return res.status(403).json({ error: "invalid signature" });
  }

  if (transaction_status === "settlement" && fraud_status === "accept") {
    // Idempotent: order_id may arrive more than once
    // await orders.markPaidOnce(order_id);
  }

  // Respond 200 fast so the PSP stops retrying
  res.status(200).json({ received: true });
});

Struktur biaya MDR

Terakhir, soal uang. MDR (Merchant Discount Rate) adalah biaya yang dipotong PSP dari tiap settlement — Anda menerima nominal kotor dikurangi MDR. Bank Indonesia mengatur batas atasnya, dan aturannya berubah pada 15 Maret 2025. Verifikasi angka terkini ke Bank Indonesia sebelum mengutipnya ke klien, karena ini didorong kebijakan dan bisa berubah. Sesuai jadwal 2025: