Buat pembayaran

Membuat pembayaran dengan satu metode dan mengembalikan instruksi untuk menyelesaikannya.

POST/v1/payments

Membutuhkan izin payments:write.

Idempotency-Keystringwajib

Contoh: order-1001-attempt-1

Wajib. String unik untuk request ini. Lihat Idempotensi.

Body request

project_idstringopsional

Proyek tempat pembayaran dibuat. Wajib dengan key merchant; key proyek sudah menyebut proyeknya.

Contoh: prj_01k7q3m8x2v5t9n4b6c1d0e7fa

Diawali prj_.

amountintegerwajib

Nominal dasar pembayaran sebelum biaya, dalam satuan terkecil currency (Rp125.000 adalah 12500000).

Contoh: 12500000

Minimum: 1

Maksimum: 100000000000

currencystringwajib

Mata uang, kode ISO 4217. Saat ini hanya IDR.

Contoh: IDR

Nilai: IDR

payment_methodstringwajib

Metode yang dipakai pembayar: payment.qris, payment.va.<bank>, payment.ewallet.<wallet>, atau payment.retail.<gerai>. Lihat Daftar metode pembayaran.

Contoh: payment.qris

Pola: ^payment\.(qris|(va|ewallet|retail)\.[a-z0-9_]+)$

merchant_referencestringopsional

Referensimu sendiri untuk pembayaran ini, misalnya nomor order, sampai 100 karakter. Pakai untuk menemukan pembayarannya lagi.

Contoh: order-1001

Panjang minimum: 1

Panjang maksimum: 100

descriptionstringopsional

Catatan tentang pembayaran yang dilihat pembayar, sampai 500 karakter.

Contoh: Pesanan kopi 1001

Panjang minimum: 1

Panjang maksimum: 500

expires_inintegeropsional

Detik sampai pembayaran kedaluwarsa, dari 300 (5 menit) sampai 604800 (7 hari). Bawaannya bergantung metode.

Contoh: 3600

Minimum: 300

Maksimum: 604800

customerobjectopsional

Data pembayar. Beberapa metode, seperti OVO, memerlukan nomor telepon.

namestringopsional

Nama pembayar yang dicatat pada pembayaran dan diteruskan ke metode pembayaran bila diperlukan.

Contoh: Budi Santoso

Panjang minimum: 1

Panjang maksimum: 120

emailstringopsional

Email pembayar. Baiyar mengirim struk ke sini di live.

Contoh: budi@example.com

Format: email

Panjang maksimum: 254

phonestringopsional

Nomor telepon pembayar, dengan atau tanpa +, 6 sampai 20 digit.

Contoh: +628123456789

Pola: ^\+?[0-9]{6,20}$

metadataobjectopsional

Sampai 20 pasangan milikmu (nama sampai 40 karakter, nilai sampai 500) yang ikut kembali bersama pembayaran dan event-nya.

Nilai: string

Key maksimum: 20

Respons (201)

dataobjectwajib

Objek yang dikembalikan, atau array objek untuk operasi daftar.

idstringwajib

Id pembayaran (pay_…).

Contoh: pay_01k7q3m8x2v5t9n4b6c1d0e7fa

Diawali pay_.

livemodebooleanwajib

true berarti objek ini ada di live dan bisa melibatkan pembayaran sungguhan; false berarti objek ini ada di sandbox.

statusstringwajib

created (belum memilih metode), pending (menunggu pembayar), paid, failed, atau expired.

Contoh: pending

Nilai yang mungkin: created, pending, paid, failed, expired

project_idstringwajib

Proyek tempat objek ini berada. Pengaturannya menentukan metode pembayaran dan batas yang berlaku.

Contoh: prj_01k7q3m8x2v5t9n4b6c1d0e7fa

Diawali prj_.

payment_link_idstring | nullwajib

Payment link tempat pembayaran ini dibuat; null kalau bukan dari link.

Contoh: lnk_01k7q3m8x2v5t9n4b6c1d0e7fa

Diawali lnk_.

amountintegerwajib

Nominal dasar pembayaran sebelum biaya, dalam satuan terkecil currency (Rp125.000 adalah 12500000).

Contoh: 12500000

currencystringwajib

Mata uang, kode ISO 4217. Saat ini hanya IDR.

Contoh: IDR

Nilai: IDR

payment_methodstring | nullwajib

Metode yang dipakai pembayar: payment.qris, payment.va.<bank>, payment.ewallet.<wallet>, atau payment.retail.<gerai>. Lihat Daftar metode pembayaran.

Contoh: payment.qris

feeobject | nullwajib

Biaya Baiyar yang ditetapkan saat pembayar melihat nominal. Null sampai metode pembayaran dipilih.

amountintegerwajib

Biayanya, dalam satuan terkecil currency (Rp125.000 adalah 12500000).

Contoh: 7000

bearerstringwajib

Siapa yang menanggung biaya: merchant atau customer.

Contoh: merchant

Nilai yang mungkin: merchant, customer

charged_amountinteger | nullwajib

Total yang dibayar pembayar, termasuk biaya jika ditanggung pembayar, dalam satuan terkecil currency (Rp125.000 adalah 12500000).

Contoh: 1000000

net_amountinteger | nullwajib

Nominal yang dikreditkan setelah biaya Baiyar, dalam satuan terkecil currency (Rp125.000 adalah 12500000).

Contoh: 993000

merchant_referencestring | nullwajib

Referensimu sendiri untuk pembayaran ini, misalnya nomor order, sampai 100 karakter. Pakai untuk menemukan pembayarannya lagi.

Contoh: order-1001

descriptionstring | nullwajib

Catatan tentang pembayaran yang dilihat pembayar, sampai 500 karakter.

Contoh: Pesanan kopi 1001

instructionobject | nullwajib

Kode QR, nomor rekening, atau detail lain yang dibutuhkan pembayar. Null jika tidak ada instruksi yang perlu ditampilkan.

typestringwajib

va, qr, ewallet_link, ewallet_push, atau retail_code. Menentukan field lain yang ada.

Nilai yang mungkin: va, qr, ewallet_link, ewallet_push, retail_code

bank_codestringwajib

Bank virtual account, misalnya bca.

Contoh: bca

Jika type adalah va.

account_numberstringwajib

Nomor virtual account tujuan transfer pembayar.

Contoh: 8277012345678901

Jika type adalah va.

expires_atstringwajib

Kapan instruksi berhenti berlaku (RFC 3339, UTC).

Contoh: 2026-10-26T03:04:05.000Z

Format: date-time

qr_contentstringwajib

Isi QRIS: gambar sebagai kode QR untuk dipindai pembayar.

Contoh: 00020101021226670016COM.BAIYAR.WWW01189360091400000001230210000000000303UMI51440014ID.CO.QRIS.WWW0215ID10200000000010303UMI5204581253033605802ID5906Toko6007Jakarta6304ABCD

Jika type adalah qr.

payment_urlstringwajib

Ke mana mengarahkan pembayar untuk menyetujui pembayaran di dompetnya.

Contoh: https://pay.example.com/wallet/abc123

Jika type adalah ewallet_link.

wallet_codestringwajib

Dompet yang meminta pembayar menyetujui di aplikasinya sendiri, misalnya ovo.

Contoh: ovo

Jika type adalah ewallet_push.

phone_last4string | nullwajib

Empat digit terakhir nomor telepon yang menerima permintaan persetujuan wallet.

Contoh: 6789

Jika type adalah ewallet_push.

payment_codestringwajib

Kode yang disebutkan pembayar di gerai.

Contoh: ALFA123456

Jika type adalah retail_code.

expires_atstring | nullwajib

Waktu objek ini kedaluwarsa (RFC 3339, UTC). Pada pembayaran, ini batas waktu pembayar; pada link, ini waktu link berhenti menerima pembayaran.

Contoh: 2026-10-26T03:04:05.000Z

Format: date-time

paid_atstring | nullwajib

Waktu pembayaran dikonfirmasi lunas (RFC 3339, UTC); null sebelum itu.

Contoh: 2026-10-26T03:04:05.000Z

Format: date-time

settlement_statusstringwajib

not_applicable (belum dibayar), awaiting (sudah dibayar, settlement belum cocok), atau settled (sudah cocok dan masuk saldo tersedia).

Contoh: awaiting

Nilai yang mungkin: not_applicable, awaiting, settled

reversalobject | nullwajib

Rincian nominal pembayaran lunas yang dibalik oleh penyedia atau tim operasi Baiyar; null jika tidak ada reversal.

amountintegerwajib

Nominal yang dikurangi dari saldo karena reversal, dalam satuan terkecil currency (Rp125.000 adalah 12500000).

Contoh: 993000

reversed_atstringwajib

Waktu reversal dicatat (RFC 3339, UTC).

Contoh: 2026-10-26T03:04:05.000Z

Format: date-time

metadataobjectwajib

Sampai 20 pasangan milikmu (nama sampai 40 karakter, nilai sampai 500) yang ikut kembali bersama pembayaran dan event-nya.

Nilai: string

Key maksimum: 20

created_atstringwajib

Waktu objek ini dibuat (RFC 3339, UTC). Gunakan untuk mengurutkan objek berdasarkan waktu pembuatan.

Contoh: 2026-10-26T03:04:05.000Z

Format: date-time

metaobjectwajib

Detail request seperti id dan kursor paginasi.

request_idstringwajib

Id request ini. Sebutkan saat bertanya ke dukungan.

Contoh: req_Hy3k9QzT2LmN8vXa

Request yang gagal dijawab dengan bentuk error yang sama; lihat Error.

Request
Respons

curl -X POST "https://api.baiyar.com/v1/payments" \
  -H "Authorization: Bearer $BAIYAR_KEY" \
  -H "Idempotency-Key: order-1001-attempt-1" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 12500000,
    "currency": "IDR",
    "payment_method": "payment.qris",
    "merchant_reference": "order-1001",
    "description": "Pesanan kopi 1001"
  }'

{
  "data": {
    "id": "pay_01k7q3m8x2v5t9n4b6c1d0e7fa",
    "livemode": false,
    "status": "pending",
    "project_id": "prj_01k7q3m8x2v5t9n4b6c1d0e7fa",
    "payment_link_id": "lnk_01k7q3m8x2v5t9n4b6c1d0e7fa",
    "amount": 12500000,
    "currency": "IDR",
    "payment_method": "payment.qris",
    "fee": {
      "amount": 7000,
      "bearer": "merchant"
    },
    "charged_amount": 1000000,
    "net_amount": 993000,
    "merchant_reference": "order-1001",
    "description": "Pesanan kopi 1001",
    "instruction": {
      "type": "qr",
      "bank_code": "bca",
      "account_number": "8277012345678901",
      "expires_at": "2026-10-26T03:04:05.000Z"
    },
    "expires_at": "2026-10-26T03:04:05.000Z",
    "paid_at": "2026-10-26T03:04:05.000Z",
    "settlement_status": "awaiting",
    "reversal": {
      "amount": 993000,
      "reversed_at": "2026-10-26T03:04:05.000Z"
    },
    "metadata": {
      "order_id": "1001"
    },
    "created_at": "2026-10-26T03:04:05.000Z"
  },
  "meta": {
    "request_id": "req_Hy3k9QzT2LmN8vXa"
  }
}

Buat pembayaran

Header

Body request

Respons (201)