Event dan payload webhook
Event mencatat perubahan pada resource. Valcentra mengirim event ke endpoint webhook yang sesuai. Untuk integrasi pembayaran pertama, mulai dengan event payment.paid dan tetap tangani event berulang dengan aman.
Envelope event
| Field | Tipe | Fungsi |
|---|---|---|
id | String | ID event stabil untuk deduplikasi penerimaan. |
type | String | Jenis perubahan, seperti payment.paid. |
created_at | String waktu UTC | Waktu event dibuat, bukan waktu request webhook ditandatangani. |
livemode | Boolean | false untuk TEST. |
data.object | Objek | Snapshot resource yang terkait dengan event. |
Contoh JSON lengkap ada pada panduan webhook. Verifikasi signature sebelum menggunakan field apa pun.
Snapshot menggambarkan resource saat event dicatat; bukan jaminan bahwa itulah keadaan terbaru saat receiver menerima request. Jika perlu memastikan kondisi sekarang, ambil payment melalui API dari backend.
Event pembayaran
| Tipe event | Perubahan | Tindakan integrasi yang lazim |
|---|---|---|
payment.created | Payment dibuat. | Hubungkan dengan pesanan, tetapi jangan tandai lunas. |
payment.pending | Pembayaran menunggu hasil. | Tampilkan kondisi menunggu tanpa menurunkan status akhir yang sudah tersimpan. |
payment.paid | Pembayaran berhasil. | Cocokkan data dan proses pemenuhan pesanan sekali. |
payment.failed | Pembayaran gagal. | Jangan penuhi pesanan; tampilkan hasil gagal. |
payment.expired | Pembayaran kedaluwarsa. | Jangan gunakan payment sebagai pembayaran aktif. |
payment.cancelled | Pembayaran dibatalkan. | Hentikan alur pembayaran untuk payment tersebut. |
Untuk event payment, data.object memiliki id, amount, currency, merchant_reference, status, livemode, created_at, dan updated_at. channel, expires_at, dan paid_at bersifat opsional dalam schema. amount berupa string; checkout_url tidak termasuk snapshot event.
Event refund
Event refund memakai nama refund.requested, bukan refund.created.
| Event | Status resource |
|---|---|
refund.requested | pending |
refund.completed | completed |
refund.rejected | rejected |
refund.failed | failed |
Snapshot refund memiliki id, payment_id, amount, currency, status, created_at, dan updated_at. Refund berbeda dari pembatalan payment; event ini tidak mengubah status payment menjadi cancelled.
Event withdrawal
Event withdrawal memakai nama withdrawal.requested, bukan withdrawal.created.
| Event | Status resource |
|---|---|
withdrawal.requested | pending |
withdrawal.approved | approved |
withdrawal.rejected | rejected |
withdrawal.completed | completed |
withdrawal.failed | failed |
Snapshot withdrawal memiliki id, amount, currency, status, created_at, dan updated_at. Withdrawal adalah penarikan dana, bukan pembayaran pelanggan atau refund.
Event bukan daftar endpoint
Adanya event refund dan withdrawal dalam kontrak tidak berarti API publik menyediakan endpoint untuk membuatnya. Ikuti hanya endpoint yang tercantum dalam API Reference dan alur aplikasi yang tersedia. Produksi tetap dinonaktifkan.
Event, resource, dan delivery berbeda
- Payment ID: satu pembayaran.
- Event ID: satu perubahan. Beberapa event dapat menunjuk payment yang sama.
- Delivery: pengiriman event ke satu endpoint, termasuk percobaan dan hasil pengirimannya.
Gunakan event.id dari body terverifikasi untuk deduplikasi, bukan eventKey internal atau ID delivery dashboard. Pengiriman ulang mempertahankan ID dan snapshot event yang sama.
Urutan penerimaan tidak dijamin. Jangan menentukan urutan bisnis hanya dari urutan request masuk. Simpan status akhir dengan aman dan baca kondisi payment terbaru jika ada pertentangan.
Lanjutkan ke: webhook untuk pola receiver, atau API Reference ↗ untuk schema event lengkap.