Buka checkout untuk pelanggan

Checkout adalah halaman pembayaran yang dikelola Valcentra. Integrasi Anda membuat payment dari backend, lalu menggunakan checkout_url dari respons agar pelanggan dapat melanjutkan.

1. Berikan URL, bukan API key

Backend mengambil pesanan tepercaya dan membuat payment.
Backend menyimpan payment id, merchant_reference, dan checkout_url.
Backend memberikan checkout URL kepada frontend untuk navigasi pelanggan.

Frontend tidak perlu menerima API key, webhook secret, atau konfigurasi provider. Jangan membuat payment langsung dari browser dengan key TEST.

Pembagian tanggung jawab

Backend: POST /v1/payments menggunakan API key
Frontend: membuka checkout_url yang diberikan backend
Backend: menerima webhook atau GET status payment

2. Gunakan checkout_url apa adanya

URL mengandung pengenal checkout yang berbeda dari payment id. Jangan membangun /c/{payment_id}, mengganti hostname, atau mengubah bagian URL untuk mencoba payment lain.

Perlakukan checkout URL sebagai tautan akses pembayaran. Jangan memasukkannya ke log publik atau alat analitik yang tidak membutuhkannya. Contoh https://pay.example.test/... di dokumentasi bukan alamat layanan nyata.

Metode dan biaya yang terlihat mengikuti pengaturan payment serta project. Field channel pada create request bukan bukti pembayaran sudah dimulai atau lunas.

3. Jika memakai return_url

return_url adalah alamat aplikasi Anda yang dituju pelanggan setelah checkout. Kirim URL HTTPS dan daftarkan tujuan yang diperbolehkan pada pengaturan project.

Potongan body dengan tujuan kembali, memakai URL ilustrasi

{
	"amount": 125000,
	"currency": "IDR",
	"merchant_reference": "order-book-1001",
	"return_url": "https://shop.example.test/orders/order-book-1001"
}

Jangan menerima return URL bebas dari browser. Backend harus menentukan tujuan yang aman untuk pesanan tersebut. Lihat error API jika request ditolak; tidak semua kesalahan konfigurasi project memiliki kode validasi khusus.

Redirect bukan konfirmasi pembayaran

Pelanggan bisa menutup checkout, kembali sebelum webhook diterima, atau membuka halaman hasil secara langsung. Kunjungan ke return_url tidak boleh mengubah pesanan menjadi lunas.

4. Tampilkan hasil berdasarkan backend

Pada halaman pesanan, minta backend membaca status tersimpan atau mengambil payment melalui API. Jangan meminta browser mengirim status pembayaran sebagai kebenaran.

Kondisi	Yang ditampilkan kepada pelanggan
`awaiting_method` atau `pending`	Pembayaran belum selesai; beri opsi memeriksa kembali atau melanjutkan checkout jika masih berlaku.
`paid`	Konfirmasi pembayaran setelah backend mencocokkannya dengan pesanan.
`failed`, `expired`, atau `cancelled`	Jelaskan hasilnya; jangan menawarkan URL lama sebagai transaksi baru.
Status belum dapat dibaca	Jelaskan bahwa status sedang diperiksa, bukan bahwa pembayaran gagal.

Expiry mengikuti pengaturan project. Jangan menganggap hitung mundur di browser sebagai bukti payment sudah berubah status. Gunakan status terbaru dari backend.

Checklist checkout

Jumlah dan referensi pesanan sesuai data backend.
Tidak ada credential dalam frontend atau URL kembali.
Navigasi checkout menggunakan URL dari respons create.
Menutup halaman atau kembali dari checkout tidak membuat pesanan otomatis lunas.
Payment kedaluwarsa atau gagal tidak memicu pemenuhan pesanan.

Lanjutkan ke: webhook untuk menerima hasil meskipun pelanggan tidak kembali ke aplikasi Anda.