Terima pembayaran QRIS dari aplikasi Anda

Mulai cepat

BayarBayar.in dipanggil dari backend website atau aplikasi Anda. API key tidak boleh ditempatkan di HTML, JavaScript browser, aplikasi pelanggan, URL pembayaran, atau repository publik.

1. 1Buat transaksiBackend mengirim order dan nominal.
2. 2Buka payment URLPelanggan melihat dan memindai QRIS.
3. 3BayarBayar.in memeriksa mutasiBrowser pelanggan tidak mengakses GoPay.
4. 4Webhook dikirimBackend menerima status bertanda tangan.
5. 5Verifikasi & penuhiPastikan transaksi live benar-benar completed.

Endpoint yang tersedia

• POST/api/transactioncreate/qrisMembuat tagihan QRIS
• GET/api/transactiondetailMembaca status transaksi
• POST/api/transactioncancelMembatalkan transaksi pending
• GET/api/v1/projects/{project}/payment-methodsMembaca metode pembayaran
• GET/pay/t/{payment_token}Halaman pembayaran pelanggan

Contoh transaksi pertama

curl -X POST 'https://boosbayar.com/api/transactioncreate/qris' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: gpk_test_GANTI_DENGAN_KEY_ANDA' \
  -H 'Idempotency-Key: checkout-INV-001' \
  -d '{
    "project": "toko-satu",
    "order_id": "INV-001",
    "amount": 10000,
    "expiry_minutes": 60
  }'

Jika berhasil, buka nilai payment.payment_url dari response pada browser pelanggan. Jangan membuat sendiri URL pembayaran jika response sudah menyediakannya.

A. Persiapan

Daftar atau masuk ke Dashboard BayarBayar.in, lalu buat satu project untuk setiap website atau aplikasi yang akan menerima pembayaran.

A.1. Project

Project memisahkan transaksi, API key, callback URL, webhook secret, dan rate limit. Sumber pembayaran dipilih dari GoPay Merchant yang tersimpan pada akun Anda. Catat dua nilai berikut setelah project dibuat:

• project slug — identitas project pada setiap request API.
• API key — credential rahasia yang hanya ditampilkan saat dibuat.

A.2. QRIS dan akun GoPay Merchant

1. Buka menu Pengaturan Channel, lalu hubungkan GoPay Merchant milik Anda melalui verifikasi OTP.
2. Pada card GoPay Merchant tersebut, pilih Tambah QRIS dan masukkan QRIS statis milik merchant yang sama.
3. Buat project. Setiap project baru otomatis menggunakan mode Sandbox; mode tidak dipilih saat pembuatan project.
4. Buka menu Project, lalu tekan Pilih Chanel dan pilih GoPay Merchant yang akan digunakan.
5. Ubah project ke Live hanya setelah payment channel dipilih dan tes integrasi Sandbox berhasil.

Satu GoPay Merchant hanya memiliki satu konfigurasi QRIS. Beberapa project dalam akun member yang sama boleh memilih GoPay Merchant yang sama, sehingga Merchant ID, QRIS, dan credential provider tetap disimpan satu kali dalam bentuk terenkripsi. Koneksi milik satu akun member tidak dapat dipilih oleh akun member lain.

A.3. Sandbox dan Live

B. Halaman pembayaran

Cara yang disarankan adalah membuat transaksi melalui API, lalu mengarahkan pelanggan ke nilai payment.payment_url dari response. URL ini memakai token acak dan tidak mengekspos tuple invoice.

Endpoint kompatibilitas berikut juga tersedia untuk transaksi yang sudah dibuat. Gunakan total_payment, bukan nominal asli.

https://boosbayar.com/pay/toko-satu/10123?order_id=INV-001&qris_only=1

Halaman pembayaran membaca status dari database BayarBayar.in. Setelah pembayaran terverifikasi, QR dan countdown hilang, lalu diganti tanda berhasil. Jika parameter redirect valid, pelanggan dapat kembali ke website merchant.

Endpoint status tanpa API key yang dipakai oleh halaman pembayaran adalah endpoint internal browser dan bukan kontrak integrasi merchant. Backend merchant harus memeriksa transaksi melalui GET /api/transactiondetail atau webhook.

C. Autentikasi API

Kirim API key melalui header X-API-Key. Header selalu diprioritaskan jika credential lama juga ada di body atau query.

X-API-Key: gpk_live_CONTOH_BUKAN_CREDENTIAL_ASLI

API key memiliki environment dan scope. Key sandbox tidak dapat dipakai setelah project berpindah ke live; simpan key baru yang ditampilkan saat pergantian mode.

C.1. Header yang digunakan

C.2. Scope API key

Gunakan key dengan scope minimum yang diperlukan. Jika key diduga bocor, buat key baru dari Dashboard dan cabut key lama.

C.3. Format waktu dan zona

Semua field date-time pada response API dan payload webhook BayarBayar.in menggunakan ISO 8601/RFC 3339 dalam UTC dengan akhiran Z. Nilai tersebut adalah waktu absolut, bukan waktu lokal server atau merchant.

Untuk request expired_at, zona waktu wajib dicantumkan. Gunakan akhiran UTC seperti 2026-07-28T15:37:39Z atau offset seperti 2026-07-28T22:37:39+07:00. Timestamp tanpa zona, misalnya 2026-07-28T15:37:39 atau 2026-07-28 15:37:39, ditolak dengan HTTP 422. BayarBayar.in menormalisasi nilai yang diterima menjadi UTC pada response.

D. API: Transaction Create

Membuat satu transaksi QRIS. Jika kode unik aktif, BayarBayar.in menambah kode tersebut ke nominal asli agar mutasi dapat dicocokkan dengan aman.

D.1. Request

Member dapat menentukan expiry untuk setiap transaksi. Gunakan paling banyak satu field expiry. Rentang yang diterima adalah 5–300 menit (5 menit–5 jam). Jika tidak dikirim, BayarBayar.in menggunakan default 60 menit. Nilai di luar rentang selalu ditolak dengan HTTP 422 dan transaksi tidak dibuat.

curl -X POST 'https://boosbayar.com/api/transactioncreate/qris' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: gpk_live_CONTOH' \
  -H 'Idempotency-Key: checkout-INV-001' \
  -d '{
    "project": "toko-satu",
    "order_id": "INV-001",
    "amount": 10000,
    "expiry_minutes": 90
  }'

E_VALIDATION digunakan untuk bentuk request yang tidak valid, termasuk nilai di bawah batas schema, angka desimal, field tidak dikenal, atau beberapa field expiry sekaligus. Request body create dan cancel menolak field tambahan yang tidak tercantum di dokumentasi. E_INVALID_EXPIRY digunakan saat nilai yang formatnya valid tetap berada di luar kebijakan waktu, misalnya expiry_minutes: 301 atau expired_at di luar 5–300 menit.

{
  "success": false,
  "message": "Waktu kedaluwarsa harus antara 5 menit dan 300 menit.",
  "code": "E_INVALID_EXPIRY",
  "errors": null,
  "request_id": "UUID"
}

D.2. Response sukses

{
  "success": true,
  "payment": {
    "project": "toko-satu",
    "order_id": "INV-001",
    "amount": 10000,
    "fee": 0,
    "total_payment": 10123,
    "payment_method": "qris",
    "payment_number": "000201010212...",
    "expired_at": "2030-01-01T12:00:00.000Z",
    "environment": "live",
    "sandbox": false,
    "payment_url": "https://boosbayar.com/pay/t/OPAQUE_TOKEN"
  }
}

• amount adalah nominal transaksi asli.
• total_payment adalah nominal tepat yang harus dibayar pelanggan.
• fee tetap 0; kode unik bukan fee.
• payment_number berisi payload QRIS dinamis pada mode live.
• payment_url adalah URL siap pakai yang harus dibuka pelanggan.

Create mengembalikan HTTP 201, termasuk saat request idempotent mengembalikan transaksi yang sudah ada. Simpan order_id dan response ini pada database merchant.

D.3. Response gagal

{
  "success": false,
  "message": "Request tidak valid.",
  "code": "E_VALIDATION",
  "errors": {
    "formErrors": [],
    "fieldErrors": {
      "expiry_minutes": [
        "Nilai harus berupa bilangan bulat minimal 5."
      ]
    }
  },
  "request_id": "550e8400-e29b-41d4-a716-446655440000"
}

Untuk error validasi, errors berisi rincian field. Pada error operasional atau autentikasi, nilainya dapat berupa null.

E. API: Transaction Detail

Gunakan endpoint ini sebagai sumber status transaksi. Untuk keputusan fulfillment, cocokkan selalu project, order_id, amount, environment, dan status.

curl --get 'https://boosbayar.com/api/transactiondetail' \
  -H 'X-API-Key: gpk_live_CONTOH' \
  --data-urlencode 'project=toko-satu' \
  --data-urlencode 'order_id=INV-001' \
  --data-urlencode 'amount=10000'

{
  "transaction": {
    "project": "toko-satu",
    "order_id": "INV-001",
    "amount": 10000,
    "total_payment": 10123,
    "refund_amount": 0,
    "status": "pending",
    "payment_method": "qris",
    "completed_at": null,
    "environment": "live",
    "sandbox": false
  }
}

{
  "transaction": {
    "project": "toko-satu",
    "order_id": "INV-001",
    "amount": 10000,
    "total_payment": 10123,
    "refund_amount": 0,
    "status": "completed",
    "payment_method": "qris",
    "completed_at": "2030-01-01T11:55:00.000Z",
    "environment": "live",
    "sandbox": false
  }
}

Webhook adalah mekanisme utama untuk perubahan status. Endpoint detail cocok sebagai verifikasi tambahan atau rekonsiliasi—bukan untuk polling sangat cepat. Jika perlu polling, gunakan interval wajar dan exponential backoff.

F. API: Transaction Cancel

Membatalkan transaksi yang masih pending. QR dinonaktifkan secara lokal dan kode unik dilepas sesuai guard period. Transaksi completed tidak dapat dibatalkan.

curl -X POST 'https://boosbayar.com/api/transactioncancel' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: gpk_live_CONTOH' \
  -d '{
    "project": "toko-satu",
    "order_id": "INV-001",
    "amount": 10000
  }'

{
  "success": true,
  "status": "cancelled",
  "transaction": {
    "project": "toko-satu",
    "order_id": "INV-001",
    "amount": 10000,
    "total_payment": 10123,
    "refund_amount": 0,
    "status": "cancelled",
    "payment_method": "qris",
    "completed_at": null,
    "environment": "live",
    "sandbox": false
  }
}

G. API: Payment Methods

Membaca metode pembayaran yang aktif untuk project.

curl 'https://boosbayar.com/api/v1/projects/toko-satu/payment-methods' \
  -H 'X-API-Key: gpk_live_CONTOH'

{
  "success": true,
  "data": [
    {
      "code": "qris",
      "name": "QRIS",
      "status": "active"
    }
  ]
}

H. Contoh Integrasi

H.1. Node.js

const response = await fetch(
  'https://boosbayar.com/api/transactioncreate/qris',
  {
    method: 'POST',
    headers: {
      'content-type': 'application/json',
      'x-api-key': process.env.BAYARBAYAR_API_KEY,
      'idempotency-key': `checkout-${order.id}`
    },
    body: JSON.stringify({
      project: 'toko-satu',
      order_id: order.id,
      amount: order.amount,
      expiry_minutes: 60
    })
  }
);

const result = await response.json();
if (!response.ok) throw new Error(result.code);

// Arahkan browser pelanggan ke URL ini.
return result.payment.payment_url;

H.2. PHP

<?php
$orderId = 'INV-001';
$payload = json_encode([
  'project' => 'toko-satu',
  'order_id' => $orderId,
  'amount' => 10000,
  'expiry_minutes' => 60,
]);

$curl = curl_init('https://boosbayar.com/api/transactioncreate/qris');
curl_setopt_array($curl, [
  CURLOPT_POST => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    'Content-Type: application/json',
    'X-API-Key: ' . getenv('BAYARBAYAR_API_KEY'),
    'Idempotency-Key: checkout-' . $orderId,
  ],
  CURLOPT_POSTFIELDS => $payload,
]);

$response = curl_exec($curl);
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
$result = json_decode($response, true);
curl_close($curl);

if ($status < 200 || $status >= 300) {
  throw new RuntimeException($result['code'] ?? 'E_UNKNOWN');
}

header('Location: ' . $result['payment']['payment_url']);
exit;

I. Webhook Pembayaran

BayarBayar.in mengirim HTTP POST ke callback URL project untuk setiap perubahan status yang menghasilkan event. Event disimpan sebelum dikirim dan dicoba ulang dengan exponential backoff sampai menerima HTTP 2xx atau mencapai batas percobaan otomatis.

Konfigurasi default melakukan maksimal 10 percobaan otomatis. Setelah batas tercapai, event berstatus dead, tetap tersimpan, dan dapat dikirim ulang secara manual dari menu Webhook.

Semua field date-time dalam payload, termasuk event_timestamp dan completed_at, dikirim sebagai UTC dengan akhiran Z. Header X-Gateway-Timestamp tetap berupa UNIX timestamp dalam detik.

I.1. Header

I.2. Jenis event

I.3. Payload

{
  "schema_version": "1.0",
  "event_id": "550e8400-e29b-41d4-a716-446655440000",
  "event_type": "transaction.completed",
  "event_timestamp": "2030-01-01T11:55:01.000Z",
  "project": "toko-satu",
  "order_id": "INV-001",
  "amount": 10000,
  "total_payment": 10123,
  "status": "completed",
  "payment_method": "qris",
  "completed_at": "2030-01-01T11:55:00.000Z",
  "refund_amount": 0,
  "environment": "live",
  "sandbox": false
}

I.4. Verifikasi signature

Hitung signature dari raw request body persis seperti diterima:

hex(HMAC_SHA256(timestamp + "." + raw_request_body, webhook_secret))

import crypto from 'node:crypto';
import express from 'express';

const app = express();

app.post('/webhook/bayarbayar',
  express.raw({ type: 'application/json' }),
	  (req, res) => {
	    const timestamp = req.get('x-gateway-timestamp') || '';
	    const received = req.get('x-gateway-signature') || '';
	    const timestampSeconds = Number(timestamp);
	    const currentSeconds = Math.floor(Date.now() / 1000);
	    const timestampValid = Number.isSafeInteger(timestampSeconds)
	      && Math.abs(currentSeconds - timestampSeconds) <= 300;

	    if (!timestampValid) return res.sendStatus(401);

	    const expected = crypto
	      .createHmac('sha256', process.env.BAYARBAYAR_WEBHOOK_SECRET)
	      .update(`${timestamp}.${req.body.toString('utf8')}`)
	      .digest();

	    const receivedBuffer = /^[a-f0-9]{64}$/.test(received)
	      ? Buffer.from(received, 'hex')
	      : Buffer.alloc(0);
	    const valid = receivedBuffer.length === expected.length
	      && crypto.timingSafeEqual(receivedBuffer, expected);

    if (!valid) return res.sendStatus(401);

    const event = JSON.parse(req.body.toString('utf8'));
    // Deduplikasi event.event_id sebelum fulfillment.
    res.sendStatus(204);
  }
);

I.5. Urutan aman menerima webhook

1. Baca body sebagai raw bytes sebelum JSON parser mengubah formatnya.
2. Tolak timestamp yang terlalu lama untuk membatasi replay.
3. Hitung HMAC menggunakan webhook secret project dan bandingkan secara constant-time.
4. Simpan X-Gateway-Event-ID pada kolom unik. Event yang sama cukup dibalas HTTP 2xx.
5. Cocokkan project, order ID, amount, status, dan environment dengan data merchant.
6. Simpan perubahan secara atomik, baru balas HTTP 2xx.

Callback URL wajib memakai HTTPS dan domain publik. Host lokal atau loopback, jaringan privat/reserved, serta URL yang memuat username atau password akan ditolak. Respons selain HTTP 2xx dianggap gagal dan akan dicoba ulang.

J. Idempotensi, retry, dan rate limit

Kirim header Idempotency-Key saat membuat transaksi. Gunakan nilai unik dan stabil untuk satu usaha pembuatan pembayaran, misalnya checkout-{order_id}.

• Project, order ID, dan nominal yang sama mengembalikan transaksi yang sudah ada.
• Order ID sama dengan nominal berbeda menghasilkan HTTP 409.
• Idempotency key sama untuk payload berbeda menghasilkan HTTP 409.
• Panjang maksimum idempotency key adalah 128 karakter.

Retry yang aman

• Jika terjadi timeout jaringan, kirim ulang request create dengan body dan Idempotency-Key yang sama.
• Jangan mengganti order_id hanya karena response pertama terlambat.
• Retry otomatis hanya untuk kegagalan sementara seperti timeout, HTTP 429, 502, atau 503.
• Gunakan exponential backoff dengan jitter dan batasi jumlah percobaan.
• Jangan retry otomatis untuk 400, 401, 403, 404, 409, atau 422 sebelum penyebab request diperbaiki.

Rate limit

BayarBayar.in menerapkan batas global dan batas per project. Saat HTTP 429 diterima, hentikan request sementara dan ikuti header Retry-After. Header berikut dapat disertakan pada response:

K. Status dan Error

K.1. HTTP status

Simpan request_id dari response gagal untuk pencarian audit dan troubleshooting.

K.2. Kode error yang sering ditemui

L. Pengujian

1. Pastikan project berada dalam mode Sandbox.
2. Buka menu Tes QRIS dan buat transaksi uji.
3. Gunakan tombol simulasi lunas di dashboard. QR sandbox tidak boleh dibayar dengan aplikasi bank.
4. Pastikan backend menerima webhook dengan environment: "sandbox" dan event_type: "transaction.sandbox_completed".
5. Periksa detail transaksi melalui API sebelum menguji mode Live.

M. Checklist sebelum menerima uang nyata

Selesaikan seluruh pemeriksaan ini sebelum mengubah project ke mode Live.

Status layanan

• GET/healthMenandakan proses aplikasi hidup.
• GET/readyHTTP 200 jika database siap; HTTP 503 jika belum siap.

Gunakan endpoint ini untuk load balancer atau monitoring. Jangan menggunakannya sebagai bukti bahwa akun provider suatu project siap menerima pembayaran; pemeriksaan provider tetap dilakukan saat transaksi live dibuat.

N. Pemecahan masalah