BayarOn API Documentation

REST API untuk terima pembayaran via QRIS, Virtual Account 8 bank, dan Indomaret. Pakai Bearer token authentication. Response JSON.

Authentication

Semua endpoint kecuali public payment + auth public-flow butuh header Authorization: Bearer {token}.

Token didapat dari POST /auth/login atau POST /auth/register.

Authorization: Bearer 5|abc123xyz...
Accept: application/json
Content-Type: application/json

Quick Start — Buat Payment Link

3 langkah dari nol ke first transaction:

curl -X POST https://api.bayaron.com/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","password":"password123"}'

# Response: { "token": "5|abc...", "user": {...}, "merchant": {...} }

curl -X POST https://api.bayaron.com/payments \
  -H "Authorization: Bearer 5|abc..." \
  -H "Content-Type: application/json" \
  -d '{
    "items": [{"name":"Premium Plan","qty":1,"price":99000}],
    "buyer_name": "Budi",
    "buyer_email": "[email protected]",
    "buyer_phone": "081234567890"
  }'

# Response: {
#   "transaction": { "reference_id": "BYRN-01K...", "amount_total":99000, ... },
#   "payment_url": "https://sandbox-payment.ipaymu.com/...",
#   "session_id": "..."
# }

# Body BayarOn kirim ke webhook URL kamu:
{
  "event": "payment.paid",
  "merchant_id": "...",
  "occurred_at": "2026-05-12T14:30:00+07:00",
  "transaction": {
    "reference_id": "BYRN-...",
    "amount_total": 99000,
    "amount_merchant": 96525,
    "fee_amount": 2475,
    "status": "paid",
    "payment_channel": "qris",
    ...
  }
}

# Headers:
# X-BayarOn-Event: payment.paid
# X-BayarOn-Signature: a1b2c3...  (HMAC SHA256 of body, signed with webhook_secret)
# X-BayarOn-Delivery: {uuid}

Auth Endpoints

Payment Endpoints

Public Checkout (No Auth)

Buyer-facing endpoints — pakai untuk build custom checkout. Tidak perlu auth, secured by reference_id ULID obscurity.

Merchant Endpoints

Withdrawal Endpoints

Webhook Forward (BayarOn → Merchant)

Saat transaksi paid, BayarOn forward ke webhook URL kamu (kalau di-set). Verify signature di sisi kamu:

// Node.js example
const crypto = require('crypto');

app.post('/webhook/bayaron', (req, res) => {
  const signature = req.headers['x-bayaron-signature'];
  const payload = JSON.stringify(req.body);
  const expected = crypto.createHmac('sha256', WEBHOOK_SECRET).update(payload).digest('hex');

  if (!crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) {
    return res.status(401).send('Invalid signature');
  }

  const { event, transaction } = req.body;
  if (event === 'payment.paid') {
    // Update order status di DB kamu
    markOrderPaid(transaction.reference_id, transaction.amount_total);
  }
  res.send('OK');
});

Error Handling

Semua error response format JSON dengan key message. Validation errors tambah errors.{field}[].

Rate Limiting

SDK Examples — Bikin Payment Link

Copy-paste snippet di bawah, ganti YOUR_TOKEN dengan Bearer token kamu (dari /auth/login).

PHP (cURL)

$ch = curl_init('https://api.bayaron.com/payments');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer YOUR_TOKEN',
        'Content-Type: application/json',
        'Accept: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'items' => [['name' => 'Premium Plan', 'qty' => 1, 'price' => 99000]],
        'buyer_name' => 'Budi Santoso',
        'buyer_email' => '[email protected]',
        'buyer_phone' => '081234567890',
    ]),
]);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);

// Share URL ke buyer:
echo 'https://bayaron.com/p/' . $response['transaction']['reference_id'];

Node.js (fetch)

const response = await fetch('https://api.bayaron.com/payments', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
    'Accept': 'application/json',
  },
  body: JSON.stringify({
    items: [{ name: 'Premium Plan', qty: 1, price: 99000 }],
    buyer_name: 'Budi Santoso',
    buyer_email: '[email protected]',
    buyer_phone: '081234567890',
  }),
});

const data = await response.json();
const shareUrl = `https://bayaron.com/p/${data.transaction.reference_id}`;
console.log('Bayar di:', shareUrl);

Python (requests)

import requests

response = requests.post(
    'https://api.bayaron.com/payments',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
    json={
        'items': [{'name': 'Premium Plan', 'qty': 1, 'price': 99000}],
        'buyer_name': 'Budi Santoso',
        'buyer_email': '[email protected]',
        'buyer_phone': '081234567890',
    },
)

data = response.json()
share_url = f"https://bayaron.com/p/{data['transaction']['reference_id']}"
print(f'Bayar di: {share_url}')

Verify Webhook Signature (Python Flask)

import hmac, hashlib
from flask import Flask, request

app = Flask(__name__)
WEBHOOK_SECRET = 'whsec_xxx_dari_dashboard_BayarOn'

@app.route('/webhook/bayaron', methods=['POST'])
def webhook():
    signature = request.headers.get('X-BayarOn-Signature')
    raw_body = request.get_data()
    expected = hmac.new(WEBHOOK_SECRET.encode(), raw_body, hashlib.sha256).hexdigest()

    if not hmac.compare_digest(signature, expected):
        return 'Invalid signature', 401

    payload = request.get_json()
    if payload['event'] == 'payment.paid':
        tx = payload['transaction']
        # Update order kamu di DB
        mark_order_paid(tx['reference_id'], tx['amount_total'])
    return 'OK', 200