Simulasi Pembayaran
Menentukan hasil pembayaran uji tanpa uang sungguhan.
POST
/v1/payments/simulateBerlaku diSandbox (zp_test_)
Di sandbox tidak ada pembeli sungguhan, jadi Anda yang menentukan hasil pembayaran. Endpoint ini mengubah pembayaran pending menjadi berhasil, gagal, atau kedaluwarsa, lalu langsung mengirim webhook ke alamat sandbox Anda.
Hanya kunci testKunci live ditolak dengan
403 wrong_environment. Pembayaran live selesai karena pembeli membayar, bukan karena simulasi.Yang perlu dikirim
Body JSON. Untuk pembayaran, isi salah satu dari reference atau merchant_ref.
| Parameter | Tipe | Wajib | Keterangan |
|---|---|---|---|
reference | string | Tidak | Nomor referensi ZevalPay, mis. SBX261027A1B2C3. Transaksi sandbox selalu berawalan SBX (transaksi live berawalan TRX). |
merchant_ref | string | Tidak | Nomor order Anda sendiri (sama persis). |
outcome | string | Ya | paid pembayaran berhasil, failed pembayaran gagal, atau expired melewati batas waktu. |
Mengisi keduanya (reference dan merchant_ref sekaligus), atau tidak mengisi satu pun, dijawab 422 invalid_request.
Contoh kode
cURL
curl -X POST https://api-sandbox.zevalpay.com/v1/payments/simulate \
-H "Authorization: Bearer zp_test_KUNCI_ANDA" \
-H "Content-Type: application/json" \
-d '{"reference": "TRX261027A1B2C3", "outcome": "paid"}'PHP
<?php
$result = zevalpay('POST', '/v1/payments/simulate', ['reference' => 'TRX261027A1B2C3', 'outcome' => 'paid']);
// Atau lewat nomor order: ['merchant_ref' => 'INV-1001', 'outcome' => 'paid']
echo $result['data']['status']; // paidNode.js
const result = await zevalpay('POST', '/v1/payments/simulate', { reference: 'TRX261027A1B2C3', outcome: 'paid' });
// Atau lewat nomor order: { merchant_ref: 'INV-1001', outcome: 'paid' }
console.log(result.data.status); // paidContoh respons
Berhasil
HTTP 200 (dipersingkat)
{
"data": {
"reference": "TRX261027A1B2C3",
"status": "paid",
"paid_at": "2026-10-27T10:22:05+07:00",
"livemode": false
}
}Gagal: reference dan merchant_ref dikirim bersamaan
HTTP 422
{
"error": {
"code": "invalid_request",
"message": "Isi salah satu saja: reference atau merchant_ref."
}
}Gagal: sudah bukan menunggu
HTTP 409
{
"error": {
"code": "conflict",
"message": "Hanya transaksi yang masih menunggu yang bisa disimulasikan."
}
}Aturan
- Hanya pembayaran sandbox berstatus
pendingyang bisa disimulasikan. Hasil akhir tidak bisa diubah lagi. outcomeselain tiga nilai di atas, atau mengisi reference dan merchant_ref sekaligus (atau tidak sama sekali), dijawab422 invalid_request. Pembayaran yang tidak ditemukan dijawab404 not_found.- Simulasi tidak menyentuh saldo, settlement, atau penarikan. Hanya status transaksi dan webhook yang berubah.
- Webhook hasil simulasi memakai alamat dan secret Sandbox dengan
"livemode": false.
Alur uji yang disarankan
- 1Buat pembayaranPanggil Buat Pembayaran dengan kunci test. Simpan
reference. - 2Simulasikan hasilPanggil endpoint ini dengan
paid. Ulangi dengan pembayaran lain untukfaileddanexpired. - 3Periksa webhookPastikan server Anda menerima peristiwa
payment.paid(atau yang sesuai), memverifikasi signature-nya, dan memperbarui pesanan.