Format Response

Semua endpoint Merchant API mengembalikan response dalam format JSON dengan struktur yang konsisten.

Envelope Response

{
  "success": true,
  "message": "Keterangan singkat hasil operasi",
  "rc": "000",
  "data": { ... }
}

Field	Tipe	Keterangan
`success`	Boolean	`true` jika request diproses tanpa error HTTP-level
`message`	String	Pesan singkat yang mendeskripsikan hasil
`rc`	String	Kode respon bisnis — `"000"` = sukses; kode lain lihat Kode Respon
`data`	Object/Array/null	Payload hasil operasi; struktur bervariasi per endpoint

Catatan: success: true berarti HTTP request berhasil diproses, bukan berarti transaksi bisnis berhasil. Selalu cek field rc dan data.status untuk status transaksi.

HTTP Status Codes

HTTP Status	Kapan Terjadi
`200 OK`	Request berhasil diproses (termasuk transaksi FAILED/PENDING)
`400 Bad Request`	Format body tidak valid
`401 Unauthorized`	API Key tidak valid atau signature gagal
`403 Forbidden`	API Key valid tapi tidak punya akses, atau merchant nonaktif
`404 Not Found`	Resource tidak ditemukan (contoh: transaksi tidak ada)
`422 Unprocessable Entity`	Validasi field gagal (contoh: field wajib kosong, format salah)
`500 Internal Server Error`	Error internal server

Response Validasi Error (422)

{
  "success": false,
  "message": "Validation failed",
  "errors": [
    {
      "field": "amount",
      "message": "amount must be a positive integer (digits only)"
    },
    {
      "field": "product_id",
      "message": "product_id is required"
    }
  ]
}

Response Transaksi Sukses

{
  "success": true,
  "message": "Transaction completed successfully",
  "rc": "000",
  "data": {
    "req_id": "TXN-20240501-001",
    "ref_id": "1777946295495371000",
    "product_id": "XL5",
    "cust_id": "08123456789",
    "status": "SUCCESS",
    "rc": "000",
    "description": "Transaksi Sukses",
    "message": "PULSA XL 5000 KE 08123456789 SUKSES",
    "amount": "5000",
    "unit_price": "5500",
    "balance_used": "5500",
    "balance": "494500",
    "serial_no": "REF123456789",
    "data": {}
  }
}

Response Transaksi Gagal

{
  "success": true,
  "message": "Transaction completed",
  "rc": "008",
  "data": {
    "req_id": "TXN-20240501-002",
    "ref_id": "1777946295495372000",
    "status": "FAILED",
    "rc": "008",
    "description": "Insufficient Balance",
    "message": "Saldo deposit tidak mencukupi",
    "balance": "1000",
    "data": {}
  }
}

Field `data` Umum

Hampir semua endpoint transaksi mengembalikan field berikut dalam data:

Field	Tipe	Keterangan
`req_id`	String	ID unik dari merchant (idempotency key)
`ref_id`	String	ID referensi internal sistem
`product_id`	String	Kode produk yang digunakan
`cust_id`	String	ID customer / nomor tujuan
`status`	String	`SUCCESS`, `FAILED`, atau `PENDING`
`rc`	String	Kode respon biller atau sistem
`description`	String	Keterangan RC
`message`	String	Pesan detail dari biller/sistem
`amount`	String	Nominal transaksi dalam IDR
`unit_price`	String	Harga satuan produk
`balance_used`	String	Saldo yang dipotong
`balance`	String	Saldo merchant setelah transaksi
`serial_no`	String	Nomor seri / token dari biller
`data`	Object	Data tambahan dari biller (bervariasi)

Idempotency

Semua endpoint transaksi berbayar mendukung idempotency via field req_id:

Jika request gagal karena timeout atau error jaringan, kirim ulang dengan req_id yang sama — sistem mengembalikan hasil transaksi pertama tanpa debit ganda.
Gunakan req_id berbeda untuk setiap transaksi baru.
Format req_id yang disarankan: {PREFIX}-{YYYYMMDD}-{SEQUENCE} — contoh: TXN-20240501-001.

Strict JSON

Semua endpoint menggunakan strict JSON parsing:

Field yang tidak dikenal dalam request body akan ditolak dengan 422 Unprocessable Entity.
Kirim hanya field yang didokumentasikan.

Keyboard shortcuts

Relay Merchant API