Skip to content
Baiyar Docs

Payments

See the Direct Payments guide for the concept.

Create a Direct Payment

Section titled “Create a Direct Payment”

Overview

Section titled “Overview”

Creates a payment for one specific payment method — no hosted Baiyar page.

POST/v1/payments

Authentication

Section titled “Authentication”

Requires an API key — see Authentication.

Headers

Section titled “Headers”
Header Required Description
Idempotency-Key Yes A unique string per payment attempt. Retrying with the same key and body returns the original payment; a different body is rejected with 409

Request body

Section titled “Request body”
Field Type Required Description
project_id string Yes Must match the API key’s own project
reference string Yes Your own order ID
amount integer Yes IDR, whole rupiah. Minimum 100 for qris, 10,000 for virtual_account
payment_method object Yes { "type": "qris" } or { "type": "virtual_account", "bank": "bca" }
expires_in_minutes integer No Defaults to 15 (qris) / 1440 (virtual_account). Capped at 60 / 10080
Terminal window
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" }
  }'

Response — QRIS

Section titled “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 differs)

Section titled “Response — Virtual Account (instructions differs)”
{
  "bank_name": "Bank BNI",
  "virtual_account_number": "8808123456789",
  "payment_steps": [
    "Open mobile banking.",
    "Choose virtual account transfer.",
    "Enter the virtual account number."
  ]
}

Errors

Section titled “Errors”
Status Code Meaning
400 VALIDATION_ERROR A field failed validation, e.g. amount below the method’s minimum
400 IDEMPOTENCY_KEY_REQUIRED The Idempotency-Key header is missing
401 UNAUTHORIZED Missing or invalid API key
403 FORBIDDEN The project isn’t usable right now
404 PROJECT_NOT_FOUND No such project, or it belongs to a different API key
409 IDEMPOTENCY_CONFLICT The Idempotency-Key was already used for a different request body

List Payments

Section titled “List Payments”
GET/v1/payments

Query parameters

Section titled “Query parameters”
Parameter Type Description
page integer Defaults to 1
page_size integer 1–100, defaults to 20
search string Matches reference
payment_link_id string Only payments made through this payment link
status string One of pending, paid, failed, expired, cancelled
method string qris or virtual_account

Get a Payment

Section titled “Get a Payment”
GET/v1/payments/{paymentID}

Path Parameters

Section titled “Path Parameters”
Parameter Type Description
paymentID string The payment ID

Poll this to check status, or configure a webhook instead.

Errors

Section titled “Errors”
Status Code Meaning
404 RESOURCE_NOT_FOUND No payment with that ID, or it belongs to a different project than the API key’s

Get Balance

Section titled “Get Balance”
GET/v1/balance