Bagian 2

Format data, idempotency, dan error

Tipe data, pagination, retry aman dengan Idempotency-Key, dan kode error.

Tipe data

Elemen	Kontrak v1
Amount	String digit rupiah bulat, contoh `"100000"`. Tanpa titik, koma, tanda Rp, atau desimal. Nilai harus positif dan sesuai limit kanal.
Currency	`IDR`. Field yang nilainya tidak didukung ditolak.
ID dan reference	ID AntaraPay adalah string opaque. Reference merchant 1–64 karakter A–Z, a–z, 0–9, titik, garis bawah, atau tanda hubung; unik per jenis operasi.
Waktu	RFC 3339 UTC, contoh `2026-10-15T05:00:00Z`. Filter `from` inklusif dan `to` eksklusif.
Metadata	Objek opsional, maksimum 10 key dengan nilai string; maksimum 2 KB JSON. Hindari data sensitif.
Pagination	`limit` default 50, maksimum 200; `cursor` opaque. List terbaru lebih dahulu, kecuali jurnal yang berurutan sequence naik.
Response	Sukses memakai `data` dan `request_id`. List menambahkan `pagination.next_cursor` dan `has_more`. `null` berarti nilai belum tersedia.

Bentuk respons list

{
  "data": [ ... ],
  "pagination": { "next_cursor": "opaque_cursor", "has_more": true },
  "request_id": "req_example"
}

Gunakan key 1–128 karakter untuk satu POST. Key sama dan body sama mengembalikan resource yang sama; body berbeda menghasilkan 409 IDEMPOTENCY_CONFLICT. Reference tetap unik meskipun key baru. Jangan membuat reference baru ketika respons timeout. Ulangi dengan key dan body yang sama atau cari resource berdasarkan reference.

Retensi respons idempotency dirancang 7 hari; reference finansial tetap tidak dapat digunakan ulang selama record transaksi dipertahankan. Request yang belum lolos autentikasi atau validasi belum membuat resource. Replay yang diterima mengembalikan ID sama; gunakan GET untuk status terkini.

Pola retry yang disarankan

Simpan Idempotency-Key bersama record pesanan Anda sebelum mengirim request. Jika terjadi timeout, kirim ulang dengan key dan body yang persis sama, atau cari resource berdasarkan reference.

Format dan kode error

Contoh error

{
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Saldo available tidak mencukupi.",
    "retryable": false
  },
  "request_id": "req_example"
}

HTTP	Code	Tindakan client
400 / 422	`VALIDATION_ERROR`	Perbaiki payload; baca `message`.
401 / 403	`UNAUTHORIZED` / `FORBIDDEN`	Periksa key dan scope.
404	`NOT_FOUND`	Periksa ID dan environment.
409	`IDEMPOTENCY_CONFLICT` / `REFERENCE_EXISTS`	Gunakan request awal atau baca resource existing.
409	`INSUFFICIENT_BALANCE` / `INVALID_STATE`	Periksa saldo atau status terbaru.
429	`RATE_LIMITED`	Ikuti `Retry-After` dalam detik.
500 / 503	`INTERNAL_ERROR` / `CHANNEL_UNAVAILABLE`	Retry dengan backoff dan key sama; cek status jika hasil tidak pasti.

Error khusus QR

Endpoint gambar QR mengembalikan error JSON: 409 QR_NOT_READY, 409 INVALID_STATE, 410 QR_EXPIRED, atau 422 CHANNEL_NOT_QR. Lihat bagian Payin.

Format data, idempotency, dan error

Tipe data

Retry yang aman

Format dan kode error

Error khusus QR