Dokumentasi › API V1

Status Pembayaran

Melihat satu pembayaran berdasarkan nomor referensi.

POST/v1/payments/status
Berlaku diSandbox (zp_test_)Live (zp_live_)

Melihat satu pembayaran. Data yang dikembalikan sesuai mode kunci: kunci test hanya melihat pembayaran sandbox dan kunci live hanya melihat pembayaran live. Bentuk objeknya sama dengan Buat Pembayaran.

Yang perlu dikirim

Body JSON. Isi salah satu saja.

ParameterTipeWajibKeterangan
referencestringTidakNomor referensi ZevalPay, mis. TRX261027A1B2C3.
merchant_refstringTidakNomor order Anda sendiri (sama persis). Cara paling andal menemukan tagihan setelah permintaan buat pembayaran terputus.

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/status \
  -H "Authorization: Bearer zp_test_KUNCI_ANDA" \
  -H "Content-Type: application/json" \
  -d '{"reference": "TRX261027A1B2C3"}'
PHP
<?php
// Lewat nomor referensi ZevalPay
$result = zevalpay('POST', '/v1/payments/status', ['reference' => 'TRX261027A1B2C3']);

// Atau lewat nomor order Anda
// $result = zevalpay('POST', '/v1/payments/status', ['merchant_ref' => 'INV-1001']);

if (isset($result['error'])) {
    echo $result['error']['message'];
} elseif ($result['data']['status'] === 'paid') {
    echo 'Lunas pada ' . $result['data']['paid_at'];
}
Node.js
// Lewat nomor referensi ZevalPay
const result = await zevalpay('POST', '/v1/payments/status', { reference: 'TRX261027A1B2C3' });

// Atau lewat nomor order Anda
// const result = await zevalpay('POST', '/v1/payments/status', { merchant_ref: 'INV-1001' });

if (result.error) console.log(result.error.message);
else if (result.data.status === 'paid') console.log('Lunas pada', result.data.paid_at);

Contoh respons

Berhasil
HTTP 200 (dipersingkat)
{
  "data": {
    "reference": "TRX261027A1B2C3",
    "merchant_ref": "INV-1001",
    "status": "paid",
    "channel": "va_bca",
    "amount": 150000,
    "fee": 1050,
    "net_amount": 148950,
    "paid_at": "2026-10-27T10:20:41+07:00",
    "available_at": "2026-10-28T15:00:00+07:00",
    "refunded": false,
    "refunded_at": null,
    "livemode": true,
    "payment": { "code": "8277012345678901", "qris_string": null, "url": null }
  }
}
Gagal: tidak ditemukan
HTTP 404
{
  "error": { "code": "not_found", "message": "Pembayaran tidak ditemukan." }
}
Gagal: mengisi keduanya
HTTP 422
{
  "error": { "code": "invalid_request", "message": "Isi salah satu saja: reference atau merchant_ref." }
}

Kapan memakai endpoint ini?

  • Webhook adalah sumber utama. Pakai endpoint ini sebagai pengaman: menyocokkan data bila webhook terlewat, atau saat pembeli kembali ke situs Anda dan Anda ingin memastikan statusnya.
  • Jangan melakukan polling rapat. Satu kunci dibatasi 120 permintaan per menit. Selang 10 sampai 30 detik sudah cukup.
  • Status paid, failed, dan expired bersifat final kecuali pembayaran terlambat di live (lihat Kode Respons).