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.

Endpoint yang tersedia

Contoh transaksi pertama

curl -X POST 'https://bayarbayar.in/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, rate limit, dan QRIS. 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 Keamanan dan hubungkan akun GoPay Merchant milik Anda.
2. Buka menu Project, lalu tambahkan QRIS statis milik merchant yang sama.
3. Mulai dari mode Sandbox. Ubah ke Live setelah tes integrasi berhasil.

Setiap akun member memakai sesi provider dan QRIS miliknya sendiri. Satu Merchant ID provider tidak dapat dipakai oleh dua akun member.

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://bayarbayar.in/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.

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.

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://bayarbayar.in/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. 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://bayarbayar.in/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://bayarbayar.in/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://bayarbayar.in/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://bayarbayar.in/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://bayarbayar.in/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://bayarbayar.in/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 setiap kali status transaksi berubah. Event disimpan sebelum dikirim dan dicoba ulang dengan exponential backoff sampai menerima HTTP 2xx.

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

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