arus.
DOKUMENTASI API · v1

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.

Base URLhttps://qris.qrisasli.biz.id
FormatJSON (UTF-8)
Metode QRQRIS dinamis — nominal terkunci

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:

  1. Store Anda membuat order lewat POST /api/order/create dengan nominal transaksi.
  2. Gateway menambahkan kode unik → total_amount = nominal + kode unik (+ fee).
  3. Pelanggan memindai QR yang nominalnya sudah terkunci — tidak perlu mengetik nominal.
  4. Pembayaran terdeteksi otomatis; order menjadi PAID dan callback order.paid dikirim 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).

Request — login
POST https://qris.qrisasli.biz.id/api/auth/login
Content-Type: application/json

{
  "email": "[email protected]",
  "password": "rahasia-anda"
}
Response — 200 OK
{
  "user": { "id": "...", "email": "[email protected]", "role": "user" },
  "csrfToken": "8f1c..."
}
Set-Cookie: qris_session=...; HttpOnly; SameSite=Strict

Login 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:

Request — buat API Key
POST https://qris.qrisasli.biz.id/api/api-keys/create
Cookie: qris_session=...
X-CSRF-Token: <csrfToken>
Content-Type: application/json

{ "label": "Backend Production" }
Response — 201 Created
{
  "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:

Request dengan API Key
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

EndpointMethodKeterangan
/api/api-keys/listGETDaftar semua API Key (tanpa value, hanya prefix + label + last used)
/api/api-keys/createPOSTBuat API Key baru (maks 5 aktif). Body: {"label": "..."}
/api/api-keys/revokePOSTCabut 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:

  1. Admin membuat merchant baru dan memilih "Pakai QRIS Arus" — menunjuk ke merchant induk yang QRIS-nya akan dipakai bersama.
  2. 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.
  3. Pelanggan memindai QR induk — gateway mencocokkan pembayaran ke order merchant yang tepat.
  4. 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.

Request
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"
}
ParameterWajibTipeKeterangan
amountYaintegerNominal transaksi dalam rupiah bulat (1 – 999.999.999.999). Tanpa kode unik.
ttl_secondsTidakintegerMasa berlaku order, 60–86400 detik. Default: 1800 (30 menit).
sourceTidakstringAsal order: api, webstore, telegram, whatsapp. Default panel.
merchant_idTidak*stringID 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)Yastring8–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.
Response — 201 Created
{
  "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:

Endpoint QR publik (tanpa login)
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
Contoh embed
<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).

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).
Request (session)
GET https://qris.qrisasli.biz.id/api/order/d82dfbd6-...
Cookie: qris_session=...
Response — 200 OK (publik / checkout)
{
  "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.

Request
POST https://qris.qrisasli.biz.id/api/order/d82dfbd6-.../cancel
Cookie: qris_session=...
X-CSRF-Token: <csrfToken>
Response — 200 OK
{
  "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.

HeaderKeterangan
content-typeapplication/json
x-qris-eventNama event: order.paid atau webhook.test
x-qris-timestampEpoch milidetik (string) saat pengiriman.
x-qris-signatureHMAC-SHA256 hex dari timestamp + "." + rawBody memakai webhook secret.
Payload — event order.paid
{
  "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:

Request — set webhook
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"
}
Response — 200 OK
{
  "ok": true,
  "webhook_url": "https://toko-anda.com/webhook/arus"
}
ParameterWajibTipeKeterangan
webhook_urlYastringURL HTTPS yang menerima POST dari gateway. Harus https://.
webhook_secretYastringSecret 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

Node.js / Express
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
<?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

  1. Akun merchant sudah dibuat oleh admin gateway.
  2. Merchant sudah dikonfigurasi (QRIS sendiri atau QRIS Arus).
  3. Anda punya email/username dan password untuk login API.
  4. 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.

Login
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 response

Langkah 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.

Buat Order
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_at

Langkah 3 — Tampilkan QR ke Pelanggan

Pilih salah satu cara (dari termudah):

CaraPenjelasanKapan Dipakai
PopupBuka 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 QRTampilkan gambar QR: <img src="https://qris.qrisasli.biz.id/api/checkout/{order_id}/qris" />Halaman pembayaran custom, mobile app webview.
RedirectRedirect 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:

Gateway POST 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

Alur end-to-end
┌─────────────────┐     ┌──────────────────┐     ┌────────────────┐
│   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.

app/Services/ArusGateway.php
<?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";
    }
}
app/Http/Controllers/CheckoutController.php
<?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'],
        // ]);
    }
}
app/Http/Controllers/WebhookController.php
<?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);
    }
}
routes/web.php
// Webhook tidak perlu CSRF protection
Route::post('/webhook/arus', [WebhookController::class, 'handle'])
    ->withoutMiddleware([\Illuminate\Foundation\Http\Middleware\VerifyCsrfToken::class]);
config/services.php
'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.

lib/arus.ts
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";
}
app/api/checkout/route.ts — Buat order
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,
  });
}
app/api/webhook/arus/route.ts — Terima webhook
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 });
}
Halaman checkout — buka popup
"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)

arus_gateway.py
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 True
Flask — webhook endpoint
from 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", 200

Contoh Integrasi: Bot Telegram (Node.js)

Contoh bot Telegram yang menerima perintah /bayar, membuat order di Arus, dan mengirim QR ke chat pelanggan.

bot.js (node-telegram-bot-api)
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.");
  }
});
Webhook handler — kirim notif ke pelanggan
// 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/stats otomatis difilter berdasarkan merchant yang ditautkan ke akun Anda. Tidak mungkin melihat atau membuat order untuk merchant lain.
  • Webhook: callback order.paid hanya 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

StatusMakna
PENDINGOrder aktif, QR tersedia, menunggu pembayaran.
WAITING_PAYMENTOrder aktif menunggu konfirmasi pencocokan.
PAIDPembayaran terdeteksi dan dicocokkan otomatis (paid_at terisi).
EXPIREDMasa berlaku habis — terjadi otomatis, tanpa perlu dipanggil.
CANCELLEDDibatalkan lewat endpoint cancel.
FAILED / REFUNDEDStatus khusus penanganan lanjutan.

Kode Error

Semua error berformat JSON: {"error": {"code": "ORDER_NOT_FOUND", "message": "Order not found"}}

HTTPCodeMakna
400INVALID_AMOUNTNominal bukan rupiah bulat positif di bawah 1 triliun.
400INVALID_EXPIRYttl_seconds di luar rentang 60–86400 detik.
400INVALID_INPUTBody/query tidak sesuai skema (field tak dikenal, duplikat, dsb.).
401UNAUTHENTICATEDSession cookie tidak ada/kadaluarsa — login ulang.
403FORBIDDENRole akun tidak berhak mengakses endpoint ini.
404ORDER_NOT_FOUNDOrder tidak ditemukan atau bukan milik akun Anda.
405METHOD_NOT_ALLOWEDMethod HTTP salah untuk endpoint ini.
409IDEMPOTENCY_CONFLICTIdempotency-Key sudah dipakai dengan nominal berbeda.
409PAYMENT_CAPACITY_EXHAUSTEDSemua kode unik sedang terpakai — coba beberapa saat lagi.
409ORDER_NOT_PENDINGOrder sudah PAID/EXPIRED/CANCELLED, tidak bisa dibatalkan.
409QR_NO_LONGER_VALIDQR sudah lunas — tidak bisa dibayar ulang (dari endpoint QR).
410QR_NO_LONGER_VALIDQR single-use sudah nonaktif karena order EXPIRED/CANCELLED.
409ACTIVE_WITHDRAWAL_EXISTSSudah ada penarikan aktif — tunggu selesai/ditolak.
400INSUFFICIENT_BALANCESaldo available tidak cukup untuk penarikan.
429RATE_LIMITEDBatas request terlampaui — tunggu dan coba lagi.
503MERCHANT_NOT_CONFIGUREDGateway belum punya merchant QRIS aktif — hubungi admin.

Rate Limit

EndpointBatas
Login (/api/auth/login)5 percobaan per email + 20 per IP / 15 menit
Endpoint session — GET240 request/menit per akun
Endpoint session — POST/mutasi60 request/menit per akun
API Key — semua endpointSama 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.