Integrasikan pembayaran dengan Valcentra
Valcentra menyediakan API untuk membuat pembayaran dan halaman checkout tempat pelanggan menyelesaikannya. Backend Anda membuat pembayaran, mengarahkan pelanggan ke checkout, lalu menerima perubahan status melalui webhook.
Panduan ini untuk developer yang sudah mengenal HTTP dan memiliki backend, tetapi belum pernah mengintegrasikan pembayaran. Anda akan belajar memakai API tanpa menaruh secret di browser atau menandai pesanan lunas terlalu cepat.
Mulai dengan pembayaran TEST
Semua langkah di panduan ini menggunakan environment TEST. Pembayaran produksi belum tersedia. Hasil simulator bukan transaksi uang nyata atau bukti bahwa integrasi produksi sudah siap.
Gambaran alur integrasi
- Backend Anda menentukan jumlah pembayaran dari pesanan dan mengirim request dengan API key TEST.
- Valcentra mengembalikan ID pembayaran serta
checkout_url. Pelanggan membuka URL tersebut untuk melanjutkan pembayaran. - Webhook mengirim pemberitahuan ke backend ketika terjadi perubahan. Backend memverifikasi pemberitahuan sebelum memperbarui pesanan.
Kembalinya pelanggan dari checkout tidak membuktikan pembayaran berhasil. Gunakan webhook terverifikasi atau ambil status terbaru melalui API di backend.
Istilah yang perlu Anda kenal
| Istilah | Artinya dalam integrasi Anda |
|---|---|
| Workspace | Organisasi tempat Anda mengelola anggota dan project. |
| Project | Konteks integrasi yang memiliki API key, pengaturan checkout, dan endpoint webhook. |
| Payment | Catatan pembayaran di Valcentra. Simpan id-nya bersama pesanan Anda. |
merchant_reference | Referensi pesanan dari sistem Anda, unik dalam project dan environment. |
| Checkout | Halaman pembayaran yang dibuka pelanggan melalui checkout_url. |
| Event | Catatan suatu perubahan, misalnya payment.paid. |
| Webhook | Request HTTP dari Valcentra ke backend Anda yang membawa event. |
API key menentukan project dan environment request. Anda tidak perlu mengirim workspace ID untuk memilih akses.
Ikuti jalur ini untuk integrasi pertama
| Urutan | Panduan | Hasil yang Anda dapatkan |
|---|---|---|
| 1 | Quickstart | Membuat pembayaran TEST, membaca respons, dan memeriksa hasil simulasi. |
| 2 | Checkout | Mengarahkan pelanggan ke halaman pembayaran tanpa membuka secret. |
| 3 | Webhook | Menerima hasil pembayaran di backend dengan aman. |
| 4 | Verifikasi signature | Memastikan event benar-benar ditandatangani dengan secret endpoint Anda. |
| 5 | Pengujian sandbox | Menguji pembayaran gagal, kedaluwarsa, serta penanganan event berulang. |
Sepanjang panduan, kita memakai pesanan contoh order-book-1001 senilai Rp125.000. Semua ID, URL, dan payload contoh bersifat sintetis, bukan credential atau alamat layanan yang bisa langsung dipakai.
Baca detail saat Anda membutuhkannya
- Akses API: autentikasi dan environment.
- Data pembayaran: payment dan statusnya, idempotensi, dan biaya.
- Keandalan integrasi: daftar event, retry webhook, dan penanganan error API.
- Kontrak endpoint: API Reference ↗ untuk field, tipe data, header, dan respons lengkap.
Langkah berikutnya: buat pembayaran TEST pertama.