Payments

Lihat Panduan Pembayaran Langsung untuk konsepnya.

Membuat Pembayaran Langsung

Ringkasan

Membuat payment untuk satu metode pembayaran spesifik — tanpa halaman hosting Baiyar.

POST/v1/payments

Autentikasi

Membutuhkan API key — lihat Autentikasi.

Header

Header	Wajib	Deskripsi
Idempotency-Key	Ya	String unik per percobaan pembayaran. Mengulang dengan key dan body yang sama mengembalikan payment yang sama; body berbeda ditolak dengan 409

Request body

Field	Tipe	Wajib	Deskripsi
project_id	string	Ya	Harus cocok dengan project milik API key
reference	string	Ya	ID order Anda sendiri
amount	integer	Ya	IDR, rupiah utuh. Minimum 100 untuk qris, 10.000 untuk virtual_account
payment_method	object	Ya	{ "type": "qris" } atau { "type": "virtual_account", "bank": "bca" }
expires_in_minutes	integer	Tidak	Default 15 (qris) / 1440 (virtual_account). Dibatasi maksimal 60 / 10080

cURL

curl https://api.baiyar.id/v1/payments \
  -H "Authorization: Bearer sk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-2026-0002-attempt-1" \
  -d '{
    "project_id": "018f1f29-7c00-73e4-a310-744d2167fc60",
    "reference": "ORDER-2026-0002",
    "amount": 15000,
    "payment_method": { "type": "qris" }
  }'

Node.js

const response = await fetch("https://api.baiyar.id/v1/payments", {
  method: "POST",
  headers: {
    Authorization: "Bearer sk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({
    project_id: "018f1f29-7c00-73e4-a310-744d2167fc60",
    reference: "ORDER-2026-0002",
    amount: 15000,
    payment_method: { type: "qris" },
  }),
});

Python

import requests
import uuid

response = requests.post(
    "https://api.baiyar.id/v1/payments",
    headers={
        "Authorization": "Bearer sk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "project_id": "018f1f29-7c00-73e4-a310-744d2167fc60",
        "reference": "ORDER-2026-0002",
        "amount": 15000,
        "payment_method": {"type": "qris"},
    },
)

Response — QRIS

{
  "id": "018f1f29-9b21-73e4-a310-744d2167fca1",
  "payment_link_id": null,
  "project_id": "018f1f29-7c00-73e4-a310-744d2167fc60",
  "reference": "ORDER-2026-0002",
  "amount": 15000,
  "currency": "IDR",
  "fee_bearer": "merchant",
  "fee_amount": 105,
  "merchant_net": 14895,
  "status": "pending",
  "checkout_url": "https://checkout.baiyar.id/sandbox/payments/sandbox_018f...",
  "payment_method": { "type": "qris" },
  "instructions": {
    "qr_string": "BAIYAR-SANDBOX-QRIS|sandbox_018f...|15000|IDR",
    "qr_image_url": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
  },
  "customer": { "name": "", "email": "", "phone": "", "address": "" },
  "checkout_context": { "location": {}, "device": {} },
  "expires_at": "2026-09-02T09:15:00Z",
  "paid_at": null,
  "created_at": "2026-09-02T09:00:00Z"
}

Response — Virtual Account (instructions berbeda)

{
  "bank_name": "Bank BNI",
  "virtual_account_number": "8808123456789",
  "payment_steps": [
    "Buka mobile banking.",
    "Pilih transfer virtual account.",
    "Masukkan nomor virtual account."
  ]
}

Error

Status	Code	Arti
400	VALIDATION_ERROR	Field gagal validasi, misal amount di bawah minimum metode
400	IDEMPOTENCY_KEY_REQUIRED	Header Idempotency-Key tidak ada
401	UNAUTHORIZED	API key tidak ada atau tidak valid
403	FORBIDDEN	Project belum bisa dipakai sekarang
404	PROJECT_NOT_FOUND	Tidak ada project tersebut, atau milik API key lain
409	IDEMPOTENCY_CONFLICT	Idempotency-Key sudah dipakai untuk body request yang berbeda

Melihat Daftar Payments

GET/v1/payments

Query parameter

Parameter	Tipe	Deskripsi
page	integer	Default 1
page_size	integer	1–100, default 20
search	string	Mencocokkan reference
payment_link_id	string	Hanya payment yang dibuat lewat payment link ini
status	string	Salah satu dari pending, paid, failed, expired, cancelled
method	string	qris atau virtual_account

Mengambil Payment

GET/v1/payments/{paymentID}

Path Parameter

Parameter	Tipe	Deskripsi
paymentID	string	ID payment

Polling ini untuk mengecek status, atau atur webhook alih-alih polling.

Error

Status	Code	Arti
404	RESOURCE_NOT_FOUND	Tidak ada payment dengan ID tersebut, atau milik project lain selain API key

Mengambil Balance

GET/v1/balance

Perhatian

Endpoint ini khusus dashboard session — selalu mengembalikan 403 untuk API key. Balance dihitung lintas semua project dalam akun merchant, sehingga tidak bisa dibatasi ke satu project yang menjadi cakupan API key.