Payment dan status pembayaran

Payment adalah catatan pembayaran di Valcentra. Pesanan tetap berada di sistem Anda; hubungkan keduanya dengan merchant_reference dan simpan payment id dari respons API.

Buat payment

Gunakan POST /v1/payments dengan header Bearer, Content-Type: application/json, dan Idempotency-Key. Lihat Quickstart untuk contoh yang dapat diikuti.

Field	Ketentuan
`amount`	Wajib. Angka bulat positif dalam rupiah, maksimal `Number.MAX_SAFE_INTEGER`.
`currency`	Wajib. Saat ini hanya `IDR`.
`merchant_reference`	Wajib. String 1–255 karakter, unik per project dan environment.
`channel`	Opsional. `qris`, `bca_va`, `bni_va`, `bri_va`, atau `mandiri_bill`. Dukungan aktual mengikuti konfigurasi layanan/project.
`description`	Opsional. Deskripsi 1–255 karakter.
`metadata`	Opsional. Maksimal 20 pasangan key/value string; jangan isi secret atau data pribadi sensitif.
`return_url`	Opsional. URL HTTPS tujuan pelanggan setelah checkout; harus sesuai allowlist project.

Key metadata diawali huruf kecil dan hanya berisi huruf kecil, angka, atau underscore, maksimal 40 karakter. Nilai maksimal 256 karakter. API menolak field di luar schema; fee_bearer bukan field create payment publik.

Jumlah pada request dan respons berbeda tipe

Potongan request

{ "amount": 125000, "currency": "IDR" }

Potongan respons

{ "amount": "125000", "currency": "IDR" }

Keduanya berarti Rp125.000. Respons memakai string desimal agar nilai uang tidak kehilangan presisi. Jangan memakai floating-point untuk perhitungan keuangan. Jika backend JavaScript perlu menghitung, parse string dengan BigInt dan gunakan format tampilan yang sesuai.

Pahami perubahan status

Pembayaran dimulai sebagai awaiting_method, lalu dapat menjadi pending sebelum mencapai hasil akhir.

Status	Artinya	Sikap aplikasi Anda
`awaiting_method`	Payment dibuat, belum memiliki attempt pembayaran yang berjalan.	Tawarkan checkout; jangan penuhi pesanan.
`pending`	Proses pembayaran belum memiliki hasil akhir.	Tampilkan menunggu pembayaran; tunggu event atau ambil status.
`paid`	Pembayaran tercatat berhasil.	Cocokkan payment, pesanan, jumlah, dan environment, lalu proses pemenuhan sekali.
`failed`	Pembayaran berakhir gagal.	Jangan penuhi pesanan; jelaskan bahwa pembayaran tidak berhasil.
`expired`	Pembayaran kedaluwarsa.	Jangan gunakan checkout lama sebagai pembayaran aktif.
`cancelled`	Pembayaran dibatalkan.	Jangan penuhi pesanan dari payment ini.

paid, failed, expired, dan cancelled adalah status akhir. Jangan menurunkan pesanan yang sudah lunas menjadi pending karena event lama datang belakangan. Untuk percobaan pembayaran baru setelah hasil akhir, buat operasi baru dengan referensi yang unik dan tetap kaitkan ke pesanan asal di sistem Anda.

Istilah attempt berarti percobaan memakai metode pembayaran di dalam payment. Anda tidak perlu mengelola record attempt melalui API publik untuk mengikuti quickstart.

Ambil kondisi terbaru

GET payment dari backend

curl "$VALCENTRA_API_URL/v1/payments/$PAYMENT_ID" \
  --header "Authorization: Bearer $TEST_API_KEY"

Respons sukses HTTP 200 berisi resource payment langsung. Cocokkan id, merchant_reference, amount, currency, dan livemode dengan data pesanan yang tersimpan. paid_at terisi saat paid; timestamp memakai UTC. expires_at dapat berupa timestamp atau null.

checkout_url hanya ada pada respons create, bukan retrieve atau snapshot payment dalam event. Simpan URL dari create jika aplikasi perlu membukanya lagi.

Kapan pesanan dianggap lunas?

Perbarui pesanan dari backend berdasarkan webhook yang signature-nya valid atau status paid yang diambil dengan API key Anda. Jangan percaya status dari query string, redirect, atau input browser.

Status paid bukan informasi bahwa dana sudah tersedia untuk ditarik. Saldo dan settlement memiliki alur terpisah; jangan menghitung merchant net hanya dari amount.

Lanjutkan ke: checkout, webhook, atau API Reference ↗ untuk schema lengkap.