Dokumentasi › API V1

Kode Respons

Bentuk jawaban server dan arti setiap kode galat.

Status HTTP menunjukkan hasil secara umum, isi JSON menjelaskan detailnya. Semua respons memakai Content-Type: application/json.

Respons berhasil

Isi utama ada di data. Endpoint daftar menambahkan meta berisi informasi halaman.

HTTP 200 / 201
{
  "data": { "reference": "TRX261027A1B2C3", "status": "pending" },
  "meta": { "page": 1, "limit": 20, "total": 1 }
}

Respons galat

error.code untuk dibaca program, error.message untuk dibaca manusia (bahasa Indonesia, aman ditampilkan). Tentukan alur program dari code, jangan dari teks pesan.

HTTP 422
{
  "error": {
    "code": "invalid_request",
    "message": "Nominal untuk channel ini harus antara Rp 10.000 dan Rp 10.000.000."
  }
}

Daftar kode galat

KodeHTTPArti dan tindakan
invalid_json400Isi permintaan bukan objek JSON yang valid. Periksa format body.
invalid_api_key401Kunci API tidak ada atau tidak valid, atau sudah dibuat ulang. Lihat Autentikasi.
wrong_environment403Kunci tidak cocok dengan alamat, atau aksi tidak tersedia di mode ini (saldo di sandbox, simulasi di live).
merchant_not_active403Merchant belum lolos verifikasi usaha. Kunci live baru berlaku setelah disetujui.
ip_not_allowed403IP pemanggil tidak ada di daftar IP kunci API. Ubah di halaman Kunci API pada dashboard.
merchant_suspended403Merchant ditangguhkan. Hubungi tim ZevalPay.
not_found404Pembayaran atau alamat tidak ditemukan di mode kunci Anda.
conflict409Konflik keadaan: nomor order sudah dipakai, atau pembayaran bukan lagi berstatus menunggu saat disimulasikan.
invalid_request422Isian tidak memenuhi aturan: nominal, channel, data pembeli, atau penolakan dari penyedia pembayaran. Baca message.
rate_limited429Melebihi 120 permintaan per menit. Tunggu sebentar lalu coba lagi.
channel_unavailable503Channel sedang dalam pemeliharaan terjadwal. message memuat jam tersedia kembali. Coba lagi setelah jam itu atau tawarkan channel lain.
server_error500Kesalahan di server kami. Coba lagi. Bila berulang, hubungi tim ZevalPay.

Status pembayaran

StatusArtiFinal?
pendingMenunggu pembayaran. Tampilkan instruksi bayar kepada pembeli.Tidak
paidSudah dibayar. Dana masuk ke saldo merchant (live).Ya
failedGagal dibuat atau ditolak.Ya
expiredMelewati batas waktu bayar.Ya
Pembayaran terlambatDi mode live, pembayaran yang baru diterima setelah status expired atau failed tetap dikreditkan dan statusnya menjadi paid. Karena itu selalu percayai status terbaru dari webhook atau endpoint status, bukan status yang Anda simpan sebelumnya.

Menangani galat dengan aman

  • invalid_request dan conflict tidak akan berhasil bila diulang tanpa perubahan. Perbaiki permintaan dulu.
  • server_error atau timeout jaringan saat membuat pembayaran: cek dulu lewat POST /v1/payments/status dengan merchant_ref sebelum mengulang, agar tidak membuat tagihan ganda.
  • Beri merchant_ref sendiri pada setiap tagihan. Mengulang permintaan dengan nomor yang sama dijawab 409 conflict, bukan tagihan baru.