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
| Kode | HTTP | Arti dan tindakan |
|---|---|---|
invalid_json | 400 | Isi permintaan bukan objek JSON yang valid. Periksa format body. |
invalid_api_key | 401 | Kunci API tidak ada atau tidak valid, atau sudah dibuat ulang. Lihat Autentikasi. |
wrong_environment | 403 | Kunci tidak cocok dengan alamat, atau aksi tidak tersedia di mode ini (saldo di sandbox, simulasi di live). |
merchant_not_active | 403 | Merchant belum lolos verifikasi usaha. Kunci live baru berlaku setelah disetujui. |
ip_not_allowed | 403 | IP pemanggil tidak ada di daftar IP kunci API. Ubah di halaman Kunci API pada dashboard. |
merchant_suspended | 403 | Merchant ditangguhkan. Hubungi tim ZevalPay. |
not_found | 404 | Pembayaran atau alamat tidak ditemukan di mode kunci Anda. |
conflict | 409 | Konflik keadaan: nomor order sudah dipakai, atau pembayaran bukan lagi berstatus menunggu saat disimulasikan. |
invalid_request | 422 | Isian tidak memenuhi aturan: nominal, channel, data pembeli, atau penolakan dari penyedia pembayaran. Baca message. |
rate_limited | 429 | Melebihi 120 permintaan per menit. Tunggu sebentar lalu coba lagi. |
channel_unavailable | 503 | Channel sedang dalam pemeliharaan terjadwal. message memuat jam tersedia kembali. Coba lagi setelah jam itu atau tawarkan channel lain. |
server_error | 500 | Kesalahan di server kami. Coba lagi. Bila berulang, hubungi tim ZevalPay. |
Status pembayaran
| Status | Arti | Final? |
|---|---|---|
pending | Menunggu pembayaran. Tampilkan instruksi bayar kepada pembeli. | Tidak |
paid | Sudah dibayar. Dana masuk ke saldo merchant (live). | Ya |
failed | Gagal dibuat atau ditolak. | Ya |
expired | Melewati 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_requestdanconflicttidak akan berhasil bila diulang tanpa perubahan. Perbaiki permintaan dulu.server_erroratau timeout jaringan saat membuat pembayaran: cek dulu lewatPOST /v1/payments/statusdenganmerchant_refsebelum mengulang, agar tidak membuat tagihan ganda.- Beri
merchant_refsendiri pada setiap tagihan. Mengulang permintaan dengan nomor yang sama dijawab409 conflict, bukan tagihan baru.