Dokumentasi › API V1

Simulasi Pembayaran

Menentukan hasil pembayaran uji tanpa uang sungguhan.

POST/v1/payments/simulate
Berlaku 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.

ParameterTipeWajibKeterangan
referencestringTidakNomor referensi ZevalPay, mis. SBX261027A1B2C3. Transaksi sandbox selalu berawalan SBX (transaksi live berawalan TRX).
merchant_refstringTidakNomor order Anda sendiri (sama persis).
outcomestringYapaid 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']; // paid
Node.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); // paid

Contoh 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 pending yang bisa disimulasikan. Hasil akhir tidak bisa diubah lagi.
  • outcome selain tiga nilai di atas, atau mengisi reference dan merchant_ref sekaligus (atau tidak sama sekali), dijawab 422 invalid_request. Pembayaran yang tidak ditemukan dijawab 404 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

  1. 1
    Buat pembayaranPanggil Buat Pembayaran dengan kunci test. Simpan reference.
  2. 2
    Simulasikan hasilPanggil endpoint ini dengan paid. Ulangi dengan pembayaran lain untuk failed dan expired.
  3. 3
    Periksa webhookPastikan server Anda menerima peristiwa payment.paid (atau yang sesuai), memverifikasi signature-nya, dan memperbarui pesanan.