Integrasi Arus QRIS Gateway
Terima pembayaran QRIS di store Anda dengan QR nominal terkunci dan pencocokan otomatis. Alur integrasi: buat order → tampilkan QR → pembayaran terdeteksi otomatis → order berubah PAID → callback dikirim ke server Anda.
Pendahuluan
Arus QRIS Gateway (ARUS Gatepay) adalah gateway pembayaran QRIS yang mencocokkan pembayaran secara otomatis lewat nominal unik. Setiap order diberi kode unik (1–3 digit) sehingga total yang harus dibayar pelanggan selalu berbeda — begitu dana masuk, sistem mencocokkan nominal dan menandai order PAID tanpa konfirmasi manual.
Cara kerja singkat:
- Store Anda membuat order lewat
POST /api/order/createdengan nominal transaksi. - Gateway menambahkan kode unik →
total_amount= nominal + kode unik (+ fee). - Pelanggan memindai QR yang nominalnya sudah terkunci — tidak perlu mengetik nominal.
- Pembayaran terdeteksi otomatis; order menjadi
PAIDdan callbackorder.paiddikirim ke webhook store Anda.
QR bersifat single-use dan berbatas waktu (default 30 menit). Order yang sudah dibayar/kedaluwarsa/dibatalkan tidak lagi menyajikan QR.
Autentikasi
Semua endpoint order menggunakan session cookie qris_session yang didapat dari login. Setiap request non-GET wajib membawa header X-CSRF-Token (nilai csrfToken dari respons login).
POST https://qris.qrisasli.biz.id/api/auth/login
Content-Type: application/json
{
"email": "[email protected]",
"password": "rahasia-anda"
}{
"user": { "id": "...", "email": "[email protected]", "role": "user" },
"csrfToken": "8f1c..."
}
Set-Cookie: qris_session=...; HttpOnly; SameSite=StrictLogin bisa memakai email atau username. Jika 2FA (TOTP) aktif, respons pertama hanya {"totp_required": true} — kirim ulang ke POST /api/auth/login-totp dengan field tambahan "code": "123456".
Akun panel diberikan admin gateway. Simpan session seperti session login biasa; jika mendapat 401 UNAUTHENTICATED, login ulang.
API Key (Server-to-Server)
Selain session cookie, Anda bisa menggunakan API Key untuk akses server-to-server tanpa perlu login. API Key cocok untuk integrasi backend-to-backend yang berjalan terus-menerus (cron job, webhook handler, bot).
Membuat API Key
Buat API Key di tab Integrasi & API pada panel merchant, atau lewat API:
POST https://qris.qrisasli.biz.id/api/api-keys/create
Cookie: qris_session=...
X-CSRF-Token: <csrfToken>
Content-Type: application/json
{ "label": "Backend Production" }{
"key": "arus_a1b2c3d4_e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0",
"id": "uuid-...",
"label": "Backend Production",
"key_prefix": "arus_a1b2",
"created_at": 1790023500000
}Simpan key segera — setelah ditutup, key tidak bisa ditampilkan lagi. Hanya hash yang tersimpan di database. Maksimum 5 API Key aktif per merchant.
Menggunakan API Key
Kirim API Key sebagai header Authorization. Tidak perlu CSRF token atau session cookie:
POST https://qris.qrisasli.biz.id/api/order/create
Authorization: Bearer arus_a1b2c3d4_e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0
Content-Type: application/json
Idempotency-Key: order-20240517-0001
{ "amount": 50000, "source": "api" }Daftar & Revoke API Key
| Endpoint | Method | Keterangan |
|---|---|---|
/api/api-keys/list | GET | Daftar semua API Key (tanpa value, hanya prefix + label + last used) |
/api/api-keys/create | POST | Buat API Key baru (maks 5 aktif). Body: {"label": "..."} |
/api/api-keys/revoke | POST | Cabut API Key. Body: {"key_id": "uuid-..."} |
API Key yang di-revoke langsung berhenti bekerja. Key yang hilang tidak bisa di-recover — buat key baru dan revoke yang lama.
QRIS Arus (Shared QRIS)
Arus Gateway mendukung dua mode QRIS untuk setiap merchant:
- QRIS sendiri — merchant punya QRIS statis sendiri. Pembayaran masuk langsung terdeteksi di QRIS merchant tersebut.
- QRIS Arus — merchant tidak punya QRIS sendiri dan menggunakan QRIS milik merchant induk (misalnya Shafstore). Transaksi masuk di QRIS induk, tapi gateway otomatis mencocokkan ke order merchant yang benar berdasarkan nominal unik.
Cara kerja QRIS Arus:
- Admin membuat merchant baru dan memilih "Pakai QRIS Arus" — menunjuk ke merchant induk yang QRIS-nya akan dipakai bersama.
- Saat order dibuat, kode unik dihasilkan dari pool bersama (shared pool) sehingga tidak ada tabrakan nominal antara merchant A dan merchant B yang sama-sama pakai QRIS Arus.
- Pelanggan memindai QR induk — gateway mencocokkan pembayaran ke order merchant yang tepat.
- Di dashboard, setiap merchant hanya melihat order dan transaksi miliknya sendiri. Merchant A tidak bisa melihat order merchant B, meskipun keduanya pakai QRIS yang sama.
QRIS Arus cocok untuk user yang belum punya QRIS BCA sendiri. Kapan saja merchant bisa di-upgrade ke QRIS sendiri oleh admin.
Membuat Order
Endpoint: POST /api/order/create — membuat order pembayaran QRIS dengan QR nominal terkunci.
POST https://qris.qrisasli.biz.id/api/order/create
Content-Type: application/json
Cookie: qris_session=...
X-CSRF-Token: <csrfToken>
Idempotency-Key: order-20240517-0001
{
"amount": 50000,
"ttl_seconds": 1800,
"source": "api"
}| Parameter | Wajib | Tipe | Keterangan |
|---|---|---|---|
amount | Ya | integer | Nominal transaksi dalam rupiah bulat (1 – 999.999.999.999). Tanpa kode unik. |
ttl_seconds | Tidak | integer | Masa berlaku order, 60–86400 detik. Default: 1800 (30 menit). |
source | Tidak | string | Asal order: api, webstore, telegram, whatsapp. Default panel. |
merchant_id | Tidak* | string | ID merchant tujuan order. Wajib jika akun Anda ditautkan ke lebih dari satu merchant. Jika hanya punya satu merchant, bisa dikosongkan (otomatis). Untuk integrasi API, selalu sertakan agar jelas merchant mana yang menerima pembayaran. |
Idempotency-Key (header) | Ya | string | 8–128 karakter (A-Z a-z 0-9 _ : -). Kirim ulang key yang sama dengan nominal sama akan mengembalikan order yang sama (aman di-retry); nominal beda → 409 IDEMPOTENCY_CONFLICT. |
{
"id": "d82dfbd6-e4ec-42fb-8c80-c7a3e0359360",
"invoice_number": "INV-260921-XTFVC6",
"user_id": "81261836-...",
"merchant_id": "92d97c90-...",
"idempotency_key": "order-20240517-0001",
"amount": 50000,
"unique_code": 137,
"fee_amount": 0,
"total_amount": 50137,
"status": "PENDING",
"created_at": 1790022726199,
"updated_at": 1790022726199,
"expired_at": 1790024526199,
"paid_at": null,
"cancelled_at": null,
"transaction_id": null,
"qr_transaction_id": "CPTHWTH4",
"source": "api"
}Penting: nominal yang harus dibayar pelanggan adalah total_amount (amount + unique_code + fee_amount). Kode unik menjamin nominal tidak pernah tabrakan antar order aktif sehingga pencocokan otomatis akurat.
Mendapatkan QR
QR PNG nominal terkunci bisa diambil dengan session (/api/order/{id}/qris) atau lewat endpoint publik checkout tanpa login — yang terakhir cocok untuk <img> langsung di halaman pembayaran store Anda:
GET https://qris.qrisasli.biz.id/api/checkout/{order_id}/qris
→ 200 image/png (360×360) — QR nominal terkunci
→ 409/410 QR_NO_LONGER_VALID jika order sudah tidak PENDING<img
src="https://qris.qrisasli.biz.id/api/checkout/d82dfbd6-.../qris"
alt="QR QRIS nominal terkunci"
width="256" height="256"
/>QR dibangun dari payload QRIS statis merchant — tanpa layanan pihak ketiga. QR hanya disajikan selama status PENDING/WAITING_PAYMENT; setelah itu single-use policy menonaktifkan QR (tidak bisa dibayar ulang).
Endpoint checkout publik dibatasi 120 request/menit per IP dan hanya mengekspos field aman (tidak ada data akun/kredensial).
Checkout Popup (Cara Termudah)
Halaman checkout publik /pay/{order_id} sudah menyediakan QR + timer + status otomatis. Store cukup membuka popup dan mendengarkan postMessage — tanpa perlu render QR sendiri:
const orderId = "d82dfbd6-..."; // dari POST /api/order/create
const popup = window.open(
"https://qris.qrisasli.biz.id/pay/" + orderId + "?origin=" + encodeURIComponent(location.origin),
"qris-payment",
"width=480,height=720"
);
window.addEventListener("message", (e) => {
if (e.origin !== "https://qris.qrisasli.biz.id" || !e.data || e.data.source !== "qris-checkout") return;
switch (e.data.event) {
case "onPending": break; // menunggu pembayaran
case "onSuccess": // e.data.order.status === "PAID"
popup?.close();
window.location.href = "/terima-kasih";
break;
case "onError": // EXPIRED / CANCELLED / gagal
console.warn("Order batal/gagal", e.data.order);
break;
case "onClose": // user menutup popup
break;
}
});| Event | Makna |
|---|---|
onPending | QR tampil, menunggu pembayaran. |
onSuccess | Pembayaran terdeteksi — e.data.order.status = PAID. |
onError | Order berakhir gagal (EXPIRED/CANCELLED/FAILED). |
onClose | Pelanggan menutup popup sebelum terminal. |
Selalu validasi e.data.source === "qris-checkout" dan origin pengirim. Payload e.data.order berisi proyeksi publik order (invoice, nominal, total, status).
Cek Status Order
Tiga cara memantau status:
GET /api/order/{order_id}— detail penuh (butuh session).GET /api/order/check/{invoice_number}— cari berdasarkan invoice (butuh session).GET /api/checkout/{order_id}— endpoint publik untuk polling halaman pembayaran (tanpa login, field terbatas).
GET https://qris.qrisasli.biz.id/api/order/d82dfbd6-...
Cookie: qris_session=...{
"order_id": "d82dfbd6-...",
"invoice_number": "INV-260921-XTFVC6",
"merchant_name": "Shaf Store",
"amount": 50000,
"fee_amount": 0,
"unique_code": 137,
"total_amount": 50137,
"status": "PAID",
"created_at": 1790022726199,
"expired_at": 1790024526199,
"paid_at": 1790023500000
}Polling disarankan tiap 3–5 detik sampai status terminal. Semua stempel waktu adalah epoch milidetik (WIB untuk tampilan manusia). Untuk notifikasi real-time tanpa polling, gunakan callback webhook.
Membatalkan Order
Endpoint: POST /api/order/{order_id}/cancel — batalkan order yang masih PENDING/WAITING_PAYMENT. QR langsung dinonaktifkan.
POST https://qris.qrisasli.biz.id/api/order/d82dfbd6-.../cancel
Cookie: qris_session=...
X-CSRF-Token: <csrfToken>{
"id": "d82dfbd6-...",
"status": "CANCELLED",
"cancelled_at": 1790022981348,
"...": "field order lengkap lainnya"
}Order yang sudah PAID, EXPIRED, atau CANCELLED tidak dapat dibatalkan — respons 409 ORDER_NOT_PENDING. Order yang lewat masa berlaku otomatis menjadi EXPIRED tanpa perlu dipanggil.
Callback / Webhook
Set webhook per merchant di panel (menu Merchants → Edit: Webhook URL + Webhook Secret). Setiap pembayaran yang berhasil dicocokkan otomatis dikirim ke URL Anda sebagai POST JSON dengan signature HMAC-SHA256.
| Header | Keterangan |
|---|---|
content-type | application/json |
x-qris-event | Nama event: order.paid atau webhook.test |
x-qris-timestamp | Epoch milidetik (string) saat pengiriman. |
x-qris-signature | HMAC-SHA256 hex dari timestamp + "." + rawBody memakai webhook secret. |
{
"event": "order.paid",
"order_id": "d82dfbd6-...",
"invoice_number": "INV-260921-XTFVC6",
"merchant_id": "92d97c90-...",
"merchant_name": "Shaf Store",
"source": "webstore",
"amount": 50000,
"fee_amount": 0,
"unique_code": 137,
"total_amount": 50137,
"paid_at": 1790023500000,
"transaction_id": "3f9c...",
"reference_number": "CPQRIS...",
"provider_trx_id": "CPTHWTH4"
}Event webhook.test dikirim dari tombol "Test" di panel — payload berisi merchant_id, target_url, dan timestamp; gunakan untuk memverifikasi penerimaan sebelum go-live.
Ketentuan pengiriman: balas HTTP 2xx dalam 10 detik. Kegagalan di-retry otomatis dengan backoff eksponensial (3 detik → 1 jam), maksimum 30 percobaan. Webhook bersifat at-least-once — buat handler Anda idempotent berdasar order_id.
Konfigurasi Webhook (Self-Service)
Merchant user bisa mengatur sendiri Webhook URL dan Secret melalui tab Integrasi & API di panel merchant, atau lewat API:
POST https://qris.qrisasli.biz.id/api/merchant/{merchant_id}/webhook
Cookie: qris_session=...
X-CSRF-Token: <csrfToken>
Content-Type: application/json
{
"webhook_url": "https://toko-anda.com/webhook/arus",
"webhook_secret": "rahasia-webhook-anda-min-16-karakter"
}{
"ok": true,
"webhook_url": "https://toko-anda.com/webhook/arus"
}| Parameter | Wajib | Tipe | Keterangan |
|---|---|---|---|
webhook_url | Ya | string | URL HTTPS yang menerima POST dari gateway. Harus https://. |
webhook_secret | Ya | string | Secret untuk HMAC-SHA256 signature. Minimal 16 karakter, generate random. |
Setelah diset, gunakan tombol Test Webhook di panel untuk memverifikasi server Anda menerima dan membalas 200 OK. Event test berisi webhook.test — bukan data order sungguhan.
Webhook URL hanya bisa https://. Gateway menolak URL private/internal (localhost, 10.x.x.x, 192.168.x.x, dsb.) untuk mencegah SSRF.
Verifikasi Signature
import { createHmac, timingSafeEqual } from "node:crypto";
app.post("/webhook/arus", express.raw({ type: "application/json" }), (req, res) => {
const secret = process.env.ARUS_WEBHOOK_SECRET;
const timestamp = req.headers["x-qris-timestamp"];
const signature = String(req.headers["x-qris-signature"] || "");
const expected = createHmac("sha256", secret)
.update(timestamp + ".")
.update(req.body) // raw body, BUKAN req.body yang sudah di-parse
.digest("hex");
const ok = signature.length === expected.length
&& timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
// anti-replay: tolak timestamp lebih dari 5 menit lalu
const fresh = Date.now() - Number(timestamp) < 5 * 60_000;
if (!ok || !fresh) return res.status(401).end();
const payload = JSON.parse(req.body.toString());
if (payload.event === "order.paid") tandaiOrderLunas(payload.order_id);
res.status(200).end();
});<?php
$raw = file_get_contents("php://input");
$ts = $_SERVER["HTTP_X_QRIS_TIMESTAMP"] ?? "";
$sig = $_SERVER["HTTP_X_QRIS_SIGNATURE"] ?? "";
$secret = getenv("ARUS_WEBHOOK_SECRET");
$expected = hash_hmac("sha256", $ts . "." . $raw, $secret);
if (!hash_equals($expected, $sig) || abs(time()*1000 - (int)$ts) > 300000) {
http_response_code(401);
exit;
}
$payload = json_decode($raw, true);
if ($payload["event"] === "order.paid") {
// tandai order lunas berdasarkan $payload["order_id"]
}
http_response_code(200);Selalu verifikasi signature di sisi penerima — jangan percaya payload webhook tanpa signature valid.
Panduan Integrasi Step-by-Step
Panduan ini menjelaskan langkah lengkap untuk mengintegrasikan Arus sebagai payment gateway di project Anda — dari setup awal sampai pembayaran otomatis berjalan.
Prasyarat
- Akun merchant sudah dibuat oleh admin gateway.
- Merchant sudah dikonfigurasi (QRIS sendiri atau QRIS Arus).
- Anda punya email/username dan password untuk login API.
- Server backend Anda bisa mengirim HTTP request ke
https://qris.qrisasli.biz.id.
Langkah 1 — Login & Simpan Session
Server Anda perlu login sekali untuk mendapat session cookie. Simpan cookie ini dan pakai untuk semua request selanjutnya. Session berlaku 8 jam — login ulang jika mendapat 401.
POST https://qris.qrisasli.biz.id/api/auth/login
Content-Type: application/json
{ "login": "username_anda", "password": "password_anda" }
→ Simpan cookie "qris_session" dan nilai "csrfToken" dari responseLangkah 2 — Buat Order Saat Customer Checkout
Saat pelanggan checkout di toko Anda, server panggil endpoint buat order. Gateway akan menambahkan kode unik otomatis ke nominal.
POST https://qris.qrisasli.biz.id/api/order/create
Cookie: qris_session=...
X-CSRF-Token: <csrfToken>
Idempotency-Key: checkout-123456
Content-Type: application/json
{ "amount": 52000, "source": "webstore" }
→ Response: order_id, total_amount (52000 + kode unik), expires_atLangkah 3 — Tampilkan QR ke Pelanggan
Pilih salah satu cara (dari termudah):
| Cara | Penjelasan | Kapan Dipakai |
|---|---|---|
| Popup | Buka https://qris.qrisasli.biz.id/pay/{order_id} di popup window. Sudah lengkap: QR + timer + auto-detect bayar. Lihat Checkout Popup. | Website, landing page, WordPress — tanpa render QR sendiri. |
| Embed QR | Tampilkan gambar QR: <img src="https://qris.qrisasli.biz.id/api/checkout/{order_id}/qris" /> | Halaman pembayaran custom, mobile app webview. |
| Redirect | Redirect pelanggan ke https://qris.qrisasli.biz.id/pay/{order_id} langsung di browser. | Flow sederhana tanpa popup. |
Langkah 4 — Terima Notifikasi Pembayaran (Webhook)
Ini kunci otomatisasi. Set Webhook URL + Secret di panel merchant. Saat pembayaran berhasil dicocokkan, gateway langsung kirim data ke server Anda:
POST https://toko-anda.com/webhook/arus
Content-Type: application/json
x-qris-event: order.paid
x-qris-timestamp: 1790023500000
x-qris-signature: <HMAC-SHA256 hex>
{
"event": "order.paid",
"order_id": "d82dfbd6-...",
"invoice_number": "INV-260921-XTFVC6",
"amount": 52000,
"unique_code": 137,
"total_amount": 52137,
"paid_at": 1790023500000
}Server Anda terima webhook → verifikasi signature → update status pesanan → kirim notifikasi ke pelanggan. Semuanya otomatis, tanpa pengecekan manual.
Langkah 5 — Verifikasi Signature (Wajib!)
Jangan percaya payload webhook tanpa verifikasi. Lihat contoh lengkap di Verifikasi Signature.
Diagram Alur Lengkap
┌─────────────────┐ ┌──────────────────┐ ┌────────────────┐
│ Toko Online │ │ Arus Gateway │ │ Pelanggan │
│ (Server) │ │ │ │ │
└────────┬────────┘ └────────┬─────────┘ └───────┬────────┘
│ │ │
1. POST /api/order/create │ │
─────────────────────────────► │
│ │ │
2. Response: order_id, │ │
total_amount, QR URL │ │
◄───────────────────────────── │
│ │ │
3. Tampilkan QR / popup │ │
─────────────────────────────────────────────────────►
│ │ │
│ 4. Pelanggan scan & bayar │
│ ◄───────────────────────┤
│ │ │
│ 5. Gateway deteksi & cocokkan │
│ status → PAID │
│ │ │
6. Webhook: order.paid │ │
◄───────────────────────────── │
│ │ │
7. Update pesanan │ │
Notif ke pelanggan │ │
│ │ │Tanpa webhook? Anda tetap bisa polling status via GET /api/checkout/{order_id} setiap 3-5 detik. Tapi webhook lebih efisien dan real-time — sangat direkomendasikan untuk production.
Contoh Integrasi: Laravel (PHP)
Contoh lengkap integrasi Arus di project Laravel — dari buat order sampai terima webhook.
<?php
namespace App\Services;
use Illuminate\Support\Facades\Http;
use Illuminate\Support\Facades\Cache;
class ArusGateway
{
private string $baseUrl;
private string $login;
private string $password;
public function __construct()
{
$this->baseUrl = config('services.arus.url'); // https://qris.qrisasli.biz.id
$this->login = config('services.arus.login'); // username/email
$this->password = config('services.arus.password');
}
/**
* Login dan cache session + CSRF token (berlaku 7 jam)
*/
private function getSession(): array
{
return Cache::remember('arus_session', 7 * 3600, function () {
$res = Http::post("$this->baseUrl/api/auth/login", [
'login' => $this->login,
'password' => $this->password,
]);
abort_unless($res->successful(), 502, 'Arus login gagal');
$cookie = collect($res->cookies()->toArray())
->firstWhere('Name', 'qris_session');
return [
'cookie' => $cookie['Value'],
'csrf' => $res->json('csrfToken'),
];
});
}
/**
* Buat order pembayaran
*/
public function createOrder(int $amount, string $idempotencyKey, string $source = 'webstore'): array
{
$session = $this->getSession();
$res = Http::withCookies(['qris_session' => $session['cookie']], parse_url($this->baseUrl, PHP_URL_HOST))
->withHeaders([
'X-CSRF-Token' => $session['csrf'],
'Idempotency-Key'=> $idempotencyKey,
])
->post("$this->baseUrl/api/order/create", [
'amount' => $amount,
'source' => $source,
]);
// Session expired? Clear cache dan retry sekali
if ($res->status() === 401) {
Cache::forget('arus_session');
return $this->createOrder($amount, $idempotencyKey, $source);
}
abort_unless($res->successful(), 502, 'Gagal buat order: ' . $res->body());
return $res->json();
}
/**
* URL QR untuk ditampilkan ke pelanggan
*/
public function qrUrl(string $orderId): string
{
return "$this->baseUrl/api/checkout/$orderId/qris";
}
/**
* URL halaman pembayaran (popup / redirect)
*/
public function payUrl(string $orderId): string
{
return "$this->baseUrl/pay/$orderId";
}
}<?php
namespace App\Http\Controllers;
use App\Services\ArusGateway;
use Illuminate\Http\Request;
class CheckoutController extends Controller
{
public function pay(Request $request, ArusGateway $arus)
{
$request->validate(['amount' => 'required|integer|min:1000']);
// Buat order di Arus
$order = $arus->createOrder(
amount: $request->amount,
idempotencyKey: 'order-' . $request->order_number,
source: 'webstore'
);
// Simpan order_id di database lokal
\DB::table('payments')->insert([
'order_number' => $request->order_number,
'arus_order_id' => $order['id'],
'total_amount' => $order['total_amount'],
'status' => 'pending',
]);
// Redirect ke halaman pembayaran Arus
return redirect($arus->payUrl($order['id']));
// ATAU tampilkan QR di halaman sendiri:
// return view('payment', [
// 'qrUrl' => $arus->qrUrl($order['id']),
// 'amount' => $order['total_amount'],
// 'expiry' => $order['expired_at'],
// ]);
}
}<?php
namespace App\Http\Controllers;
use Illuminate\Http\Request;
class WebhookController extends Controller
{
public function handle(Request $request)
{
$raw = $request->getContent();
$timestamp = $request->header('x-qris-timestamp', '');
$signature = $request->header('x-qris-signature', '');
$secret = config('services.arus.webhook_secret');
// 1. Verifikasi signature
$expected = hash_hmac('sha256', $timestamp . '.' . $raw, $secret);
if (!hash_equals($expected, $signature)) {
return response('Invalid signature', 401);
}
// 2. Anti-replay: tolak jika lebih dari 5 menit
if (abs(now()->getTimestampMs() - (int)$timestamp) > 300000) {
return response('Timestamp expired', 401);
}
// 3. Proses event
$payload = json_decode($raw, true);
if ($payload['event'] === 'order.paid') {
// Update status pesanan di database
\DB::table('payments')
->where('arus_order_id', $payload['order_id'])
->update([
'status' => 'paid',
'paid_at' => now(),
]);
// Kirim notifikasi ke pelanggan
// Mail::to(...)->send(new PaymentConfirmation(...));
}
return response('OK', 200);
}
}// Webhook tidak perlu CSRF protection
Route::post('/webhook/arus', [WebhookController::class, 'handle'])
->withoutMiddleware([\Illuminate\Foundation\Http\Middleware\VerifyCsrfToken::class]);'arus' => [
'url' => env('ARUS_GATEWAY_URL', 'https://qris.qrisasli.biz.id'),
'login' => env('ARUS_LOGIN'),
'password' => env('ARUS_PASSWORD'),
'webhook_secret' => env('ARUS_WEBHOOK_SECRET'),
],Contoh Integrasi: Next.js (TypeScript)
Contoh untuk project Next.js App Router — API route buat order + webhook handler.
const ARUS_URL = process.env.ARUS_GATEWAY_URL!; // https://qris.qrisasli.biz.id
const ARUS_LOGIN = process.env.ARUS_LOGIN!;
const ARUS_PASSWORD = process.env.ARUS_PASSWORD!;
let sessionCache: { cookie: string; csrf: string; expiresAt: number } | null = null;
async function getSession() {
if (sessionCache && Date.now() < sessionCache.expiresAt) return sessionCache;
const res = await fetch(ARUS_URL + "/api/auth/login", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ login: ARUS_LOGIN, password: ARUS_PASSWORD }),
});
if (!res.ok) throw new Error("Arus login gagal: " + res.status);
const data = await res.json();
const cookie = res.headers.getSetCookie()
.find(c => c.startsWith("qris_session="))?.split(";")[0] ?? "";
sessionCache = {
cookie,
csrf: data.csrfToken,
expiresAt: Date.now() + 7 * 3600_000, // cache 7 jam
};
return sessionCache;
}
export async function createArusOrder(amount: number, idempotencyKey: string) {
const session = await getSession();
const res = await fetch(ARUS_URL + "/api/order/create", {
method: "POST",
headers: {
"Content-Type": "application/json",
Cookie: session.cookie,
"X-CSRF-Token": session.csrf,
"Idempotency-Key": idempotencyKey,
},
body: JSON.stringify({ amount, source: "webstore" }),
});
// Session expired? Retry sekali
if (res.status === 401) {
sessionCache = null;
return createArusOrder(amount, idempotencyKey);
}
if (!res.ok) throw new Error("Gagal buat order: " + (await res.text()));
return res.json();
}
export function payUrl(orderId: string) {
return ARUS_URL + "/pay/" + orderId;
}
export function qrUrl(orderId: string) {
return ARUS_URL + "/api/checkout/" + orderId + "/qris";
}import { NextResponse } from "next/server";
import { createArusOrder, payUrl } from "@/lib/arus";
export async function POST(req: Request) {
const { amount, orderNumber } = await req.json();
const order = await createArusOrder(amount, "order-" + orderNumber);
// Simpan ke database Anda
// await db.insert(payments).values({ orderNumber, arusOrderId: order.id, ... });
return NextResponse.json({
paymentUrl: payUrl(order.id),
totalAmount: order.total_amount,
expiresAt: order.expired_at,
});
}import { createHmac, timingSafeEqual } from "node:crypto";
import { NextResponse } from "next/server";
const SECRET = process.env.ARUS_WEBHOOK_SECRET!;
export async function POST(req: Request) {
const raw = await req.text();
const timestamp = req.headers.get("x-qris-timestamp") ?? "";
const signature = req.headers.get("x-qris-signature") ?? "";
// 1. Verifikasi HMAC signature
const expected = createHmac("sha256", SECRET)
.update(timestamp + "." + raw)
.digest("hex");
const sigBuf = Buffer.from(signature);
const expBuf = Buffer.from(expected);
if (sigBuf.length !== expBuf.length || !timingSafeEqual(sigBuf, expBuf)) {
return NextResponse.json({ error: "Invalid signature" }, { status: 401 });
}
// 2. Anti-replay
if (Math.abs(Date.now() - Number(timestamp)) > 5 * 60_000) {
return NextResponse.json({ error: "Timestamp expired" }, { status: 401 });
}
// 3. Proses
const payload = JSON.parse(raw);
if (payload.event === "order.paid") {
// await db.update(payments).set({ status: "paid" }).where(eq(payments.arusOrderId, payload.order_id));
console.log("Pembayaran berhasil:", payload.order_id, payload.total_amount);
}
return NextResponse.json({ received: true });
}"use client";
export default function PayButton({ orderId }: { orderId: string }) {
const handlePay = () => {
const popup = window.open(
"https://qris.qrisasli.biz.id/pay/" + orderId + "?origin=" + encodeURIComponent(location.origin),
"qris-payment",
"width=480,height=720"
);
const handler = (e: MessageEvent) => {
if (e.origin !== "https://qris.qrisasli.biz.id" || e.data?.source !== "qris-checkout") return;
if (e.data.event === "onSuccess") {
popup?.close();
window.location.href = "/terima-kasih";
}
};
window.addEventListener("message", handler);
};
return <button onClick={handlePay}>Bayar Sekarang</button>;
}Contoh Integrasi: Python (Flask / FastAPI)
import requests
import hmac
import hashlib
import time
import os
ARUS_URL = os.environ["ARUS_GATEWAY_URL"] # https://qris.qrisasli.biz.id
ARUS_LOGIN = os.environ["ARUS_LOGIN"]
ARUS_PASSWORD = os.environ["ARUS_PASSWORD"]
ARUS_WEBHOOK_SECRET = os.environ["ARUS_WEBHOOK_SECRET"]
_session_cache = {"cookie": None, "csrf": None, "expires": 0}
def _login():
res = requests.post(f"{ARUS_URL}/api/auth/login", json={
"login": ARUS_LOGIN,
"password": ARUS_PASSWORD,
})
res.raise_for_status()
_session_cache["cookie"] = res.cookies.get("qris_session")
_session_cache["csrf"] = res.json()["csrfToken"]
_session_cache["expires"] = time.time() + 7 * 3600
def _get_session():
if time.time() >= _session_cache["expires"]:
_login()
return _session_cache
def create_order(amount: int, idempotency_key: str, source: str = "webstore") -> dict:
s = _get_session()
res = requests.post(
f"{ARUS_URL}/api/order/create",
json={"amount": amount, "source": source},
cookies={"qris_session": s["cookie"]},
headers={
"X-CSRF-Token": s["csrf"],
"Idempotency-Key": idempotency_key,
},
)
if res.status_code == 401: # session expired
_session_cache["expires"] = 0
return create_order(amount, idempotency_key, source)
res.raise_for_status()
return res.json()
def qr_url(order_id: str) -> str:
return f"{ARUS_URL}/api/checkout/{order_id}/qris"
def pay_url(order_id: str) -> str:
return f"{ARUS_URL}/pay/{order_id}"
def verify_webhook(raw_body: bytes, timestamp: str, signature: str) -> bool:
expected = hmac.new(
ARUS_WEBHOOK_SECRET.encode(),
timestamp.encode() + b"." + raw_body,
hashlib.sha256,
).hexdigest()
if not hmac.compare_digest(expected, signature):
return False
if abs(time.time() * 1000 - int(timestamp)) > 300_000:
return False
return Truefrom flask import Flask, request, jsonify
from arus_gateway import verify_webhook
import json
app = Flask(__name__)
@app.route("/webhook/arus", methods=["POST"])
def webhook():
raw = request.get_data()
ts = request.headers.get("x-qris-timestamp", "")
sig = request.headers.get("x-qris-signature", "")
if not verify_webhook(raw, ts, sig):
return "Unauthorized", 401
payload = json.loads(raw)
if payload["event"] == "order.paid":
# Update status pesanan di database
# db.execute("UPDATE orders SET status='paid' WHERE arus_order_id=?", (payload["order_id"],))
print(f"Pembayaran berhasil: {payload['order_id']} - Rp {payload['total_amount']}")
return "OK", 200Contoh Integrasi: Bot Telegram (Node.js)
Contoh bot Telegram yang menerima perintah /bayar, membuat order di Arus, dan mengirim QR ke chat pelanggan.
const TelegramBot = require("node-telegram-bot-api");
const { createArusOrder, qrUrl } = require("./arus"); // sama seperti contoh Next.js
const bot = new TelegramBot(process.env.TELEGRAM_BOT_TOKEN, { polling: true });
// /bayar 52000
bot.onText(//bayar (d+)/, async (msg, match) => {
const chatId = msg.chat.id;
const amount = parseInt(match[1]);
if (amount < 1000) {
return bot.sendMessage(chatId, "Minimal pembayaran Rp 1.000");
}
try {
// Buat order di Arus
const order = await createArusOrder(amount, `tg-${chatId}-${Date.now()}`);
// Kirim QR ke pelanggan
await bot.sendPhoto(chatId, qrUrl(order.id), {
caption: [
"💳 *Pembayaran QRIS*",
"━━━━━━━━━━━━━━━━",
"Invoice: " + order.invoice_number,
"Nominal: Rp " + order.amount.toLocaleString("id-ID"),
"Kode Unik: " + order.unique_code,
"*Total Bayar: Rp " + order.total_amount.toLocaleString("id-ID") + "*",
"",
"⏳ Berlaku 30 menit",
"Scan QR di atas untuk membayar.",
].join("\n"),
parse_mode: "Markdown",
});
// Simpan mapping order_id → chatId untuk notif webhook
// await db.set(order.id, chatId);
} catch (err) {
bot.sendMessage(chatId, "Gagal membuat pembayaran. Coba lagi nanti.");
}
});// Di webhook handler Express Anda
if (payload.event === "order.paid") {
// Cari chatId dari database berdasarkan order_id
const chatId = await db.get(payload.order_id);
if (chatId) {
bot.sendMessage(chatId, [
"✅ *Pembayaran Berhasil!*",
"",
"Invoice: " + payload.invoice_number,
"Total: Rp " + payload.total_amount.toLocaleString("id-ID"),
"",
"Terima kasih! Pesanan Anda sedang diproses.",
].join("
"), { parse_mode: "Markdown" });
}
}Untuk bot Telegram, set source: "telegram" saat membuat order agar mudah difilter di dashboard. Webhook URL bisa mengarah ke server yang sama dengan bot — cukup tambahkan route /webhook/arus.
Isolasi Transaksi per Store
Setiap merchant di Arus Gateway memiliki ruang transaksi yang sepenuhnya terisolasi. Ini berlaku baik saat menggunakan QRIS sendiri maupun QRIS Arus (shared).
- Dashboard: merchant user hanya melihat statistik, order, dan transaksi milik merchant-nya sendiri. Nominal, jumlah order, pending, paid, expired — semuanya dihitung per-merchant.
- API: endpoint
/api/order/create,/api/orders, dan/api/statsotomatis difilter berdasarkan merchant yang ditautkan ke akun Anda. Tidak mungkin melihat atau membuat order untuk merchant lain. - Webhook: callback
order.paidhanya dikirim ke webhook URL merchant pemilik order tersebut. Merchant A tidak menerima notifikasi pembayaran merchant B. - QRIS Arus: meskipun dua merchant pakai QRIS fisik yang sama, pencocokan berbasis nominal unik memastikan pembayaran masuk ke order yang benar. Transaksi yang masuk di QRIS induk untuk order merchant B tidak akan muncul di dashboard atau API merchant A.
Untuk integrasi multi-store (misalnya webstore + bot Telegram), buat order dengan source yang sesuai (webstore, telegram) agar mudah difilter di dashboard. Kedua store bisa menggunakan akun dan merchant yang sama.
Status Order
| Status | Makna |
|---|---|
PENDING | Order aktif, QR tersedia, menunggu pembayaran. |
WAITING_PAYMENT | Order aktif menunggu konfirmasi pencocokan. |
PAID | Pembayaran terdeteksi dan dicocokkan otomatis (paid_at terisi). |
EXPIRED | Masa berlaku habis — terjadi otomatis, tanpa perlu dipanggil. |
CANCELLED | Dibatalkan lewat endpoint cancel. |
FAILED / REFUNDED | Status khusus penanganan lanjutan. |
Kode Error
Semua error berformat JSON: {"error": {"code": "ORDER_NOT_FOUND", "message": "Order not found"}}
| HTTP | Code | Makna |
|---|---|---|
400 | INVALID_AMOUNT | Nominal bukan rupiah bulat positif di bawah 1 triliun. |
400 | INVALID_EXPIRY | ttl_seconds di luar rentang 60–86400 detik. |
400 | INVALID_INPUT | Body/query tidak sesuai skema (field tak dikenal, duplikat, dsb.). |
401 | UNAUTHENTICATED | Session cookie tidak ada/kadaluarsa — login ulang. |
403 | FORBIDDEN | Role akun tidak berhak mengakses endpoint ini. |
404 | ORDER_NOT_FOUND | Order tidak ditemukan atau bukan milik akun Anda. |
405 | METHOD_NOT_ALLOWED | Method HTTP salah untuk endpoint ini. |
409 | IDEMPOTENCY_CONFLICT | Idempotency-Key sudah dipakai dengan nominal berbeda. |
409 | PAYMENT_CAPACITY_EXHAUSTED | Semua kode unik sedang terpakai — coba beberapa saat lagi. |
409 | ORDER_NOT_PENDING | Order sudah PAID/EXPIRED/CANCELLED, tidak bisa dibatalkan. |
409 | QR_NO_LONGER_VALID | QR sudah lunas — tidak bisa dibayar ulang (dari endpoint QR). |
410 | QR_NO_LONGER_VALID | QR single-use sudah nonaktif karena order EXPIRED/CANCELLED. |
409 | ACTIVE_WITHDRAWAL_EXISTS | Sudah ada penarikan aktif — tunggu selesai/ditolak. |
400 | INSUFFICIENT_BALANCE | Saldo available tidak cukup untuk penarikan. |
429 | RATE_LIMITED | Batas request terlampaui — tunggu dan coba lagi. |
503 | MERCHANT_NOT_CONFIGURED | Gateway belum punya merchant QRIS aktif — hubungi admin. |
Rate Limit
| Endpoint | Batas |
|---|---|
Login (/api/auth/login) | 5 percobaan per email + 20 per IP / 15 menit |
| Endpoint session — GET | 240 request/menit per akun |
| Endpoint session — POST/mutasi | 60 request/menit per akun |
| API Key — semua endpoint | Sama dengan session (rate limit per user ID) |
Checkout publik (/api/checkout/*) | 120 request/menit per IP |
Melebihi batas → 429 RATE_LIMITED. Body request dibatasi 4 KB (kecuali upload QRIS admin). Gunakan Idempotency-Key agar retry aman.