Versi: 1.0
Produk: QRIS, VA & Transfer
Diperbarui: 1 Juni 2026
Dokumen Teknis API QRIS & Transfer Payment

Panduan pengintegrasian lengkap API QRIS PT MAXIMA SINERGI PRIMA untuk pengembang dan mitra teknis.

1. Gambaran Umum

API QRIS dan Transfer PT MAXIMA SINERGI PRIMA memungkinkan mitra untuk memproses pembayaran QRIS dan Transfer Dana (Quick Response Code Indonesian Standard) secara otomatis. Sistem mendukung dua tipe penggunaan QR Code:

  • QR Code Dinamis: QR Code sekali pakai untuk transaksi spesifik dengan nominal pasti.
  • QR Code Statis: QR Code berulang yang dapat dipindai berkali-kali.

Setiap transaksi terintegrasi dengan mekanisme notifikasi real-time via Callback Webhook setelah pembayaran dikonfirmasi oleh provider.

2. Autentikasi

Setiap HTTP Request ke sistem API wajib menyertakan kredensial autentikasi pada HTTP Header berikut:

Header Tipe Wajib Keterangan
api_key String YA API Key rahasia yang diberikan oleh admin saat registrasi mitra.
pin String YA PIN keamanan mitra untuk validasi transaksi tambahan.
Content-Type String YA Harus diisi application/json
⚠️
Perhatian Keamanan Jaga kerahasiaan api_key dan pin Anda. Jangan pernah menyimpan kredensial di repositori terbuka atau kode sumber di sisi klien (Client-side API Calls).

3. Alur Transaksi

Berikut langkah-langkah lengkap alur integrasi pembayaran QRIS dari sisi mitra:

  1. Buat QRIS: Kirim HTTP POST ke /q4/qris/create membawa nominal, cust_ref_id unik, dan deskripsi pesanan. Simpan ref_id transaksi dari response.
  2. Tampilkan QR Code: Ambil string dari field response qrisCode dan render menjadi gambar QR Code pada UI aplikasi/web Anda. Tampilkan juga waktu expiredAt.
  3. Pembayaran oleh Pelanggan: Pelanggan memindai QR Code dan menyelesaikan pembayaran melalui E-Wallet atau Mobile Banking pilihan mereka.
  4. Penerimaan Callback Webhook: Sistem secara otomatis mengirim HTTP POST ke Callback URL mitra segera setelah status transaksi menjadi PAID.
  5. Verifikasi Status Transaksi (Disarankan): Lakukan pengecekan ganda dengan memanggil endpoint /q4/qris/query sebelum melakukan fulfillment/pengiriman barang.
💡
Catatan Callback Integration Callback URL Anda harus dapat diakses secara publik melalui jaringan internet dan wajib merespons dengan HTTP Status Code 200 OK.

4. API Endpoints QRIS

4.1 Create QRIS

Membuka transaksi baru dan menghasilkan string QR Code untuk pembayaran.

POST /q4/qris/create

Request Body JSON:

Field Tipe Wajib Keterangan
harga Number YA Nominal transaksi (minimal 1). Contoh: 50000
cust_ref_id String YA ID Referensi Unik milik mitra (cth: REQ-20260604-001).
nama_order String YA Deskripsi/Nama Tagihan.
validity_min Number TIDAK Masa berlaku QR (menit). Default: 15.
is_static Boolean TIDAK false = Dinamis, true = Statis. Default: false.
Request Payload JSON 
{
  "harga": 50000,
  "cust_ref_id": "REQ-20260604-001",
  "nama_order": "Pembayaran Voucher Game",
  "validity_min": 15,
  "is_static": false
}
Response Sukses (HTTP 200 OK) 
{
  "cust_ref_id": "REQ-20260604-001",
  "ref_id": "TRX1712200000000000000",
  "nama_order": "Pembayaran Voucher Game",
  "harga": "50000.00",
  "status_pembayaran": "UNPAID",
  "channel": "QRIS",
  "qrisCode": "00020101021226680016COM.NOBUBANK...",
  "qrislink": "https://gudangpayment.online/XyZ123",
  "expiredAt": "2026-04-04 10:30:00",
  "message": "Success",
  "RC": "2001"
}

Penjelasan Response:

Field Tipe Keterangan
cust_ref_id String ID referensi transaksi dari sisi Mitra.
ref_id String ID referensi transaksi internal dari sistem Gudang Payment.
nama_order String Nama atau deskripsi tagihan.
harga String Nominal tagihan.
status_pembayaran String Status saat ini (biasanya UNPAID saat baru dibuat).
channel String Metode pembayaran (selalu QRIS).
qrisCode String Data string mentah standar QRIS (dapat Anda konversi menjadi gambar menggunakan library di sisi Mitra).
qrislink String Tautan URL siap pakai yang berisi halaman pembayaran QR Code untuk dibagikan ke pelanggan.
expiredAt String Batas waktu pembayaran kedaluwarsa.
message String Pesan keberhasilan.
RC String Kode response API (2001 berarti sukses).

4.2 Query Status Transaksi

Mengecek status pembayaran transaksi secara real-time ke provider.

POST /q4/qris/query
Request Payload JSON 
{
  "ref_id": "TRX1712200000000000000"
}
Response (Status: PAID) 
{
  "RC": "2001",
  "message": "Success",
  "ref_id": "TRX1712200000000000000",
  "cust_ref_id": "REQ-20260604-001",
  "harga": "50000.00",
  "nama_order": "Pembayaran Voucher Game",
  "status_pembayaran": "PAID",
  "channel": "QRIS",
  "qrisCode": "00020101021226680016COM.NOBUBANK...",
  "expiredAt": "2026-04-04 10:30:00"
}

4.3 Callback Notifikasi Pembayaran

HTTP POST yang dikirim oleh sistem Gudang Payment ke Webhook Mitra saat pembayaran berhasil.

POST {callback_url_mitra}
Webhook Body JSON 
{
  "ref_id": "TRX1712200000000000000",
  "cust_ref_id": "INV-20260404-001",
  "nama_order": "WALLETLINK-Pembayaran Tagihan Listrik",
  "harga": "50000",
  "no_hp": "",
  "status_pembayaran": "PAID",
  "channel": "QRIS",
  "paymentCode": "",
  "message": "Success",
  "RC": "2001"
}

5. API Endpoints Transfer

5.1 Inquiry Transfer

Mengecek detail tujuan transfer dan memastikan ketersediaan saldo sebelum melakukan payment.

POST /transfer/inquiry

Request Body JSON:

Field Tipe Wajib Keterangan
kode_produk String YA Kode Bank Tujuan Transfer.
customer_no String YA Nomor Rekening Tujuan.
nominal Number YA Nominal Transfer.
ref_id String YA ID Referensi Unik Mitra.
Request Payload JSON 
{
  "kode_produk": "CENAIDJA-05",
  "customer_no": "1234567890",
  "nominal": 150000,
  "ref_id": "TRX-TRANSFER-001"
}
Response Sukses (HTTP 200 OK) 
{
  "RC": "201",
  "message": "Inquiry Success",
  "nama_pelanggan": "JOHN DOE",
  "kode_produk": "CENAIDJA-05",
  "no_rekening": "1234567890",
  "nominal": 150000,
  "admin_transfer": 2500,
  "total": 152500,
  "saldo": "1000000"
}

Penjelasan Response:

Field Tipe Keterangan
RC String Response Code (201 berarti sukses inquiry).
message String Pesan status.
nama_pelanggan String Nama pemilik rekening/tujuan transfer.
kode_produk String Kode Bank Tujuan Transfer.
no_rekening String Nomor rekening tujuan.
nominal Number Nominal transfer.
admin_transfer Number Biaya admin transfer.
total Number Total yang akan dipotong dari saldo (Nominal + Admin).
saldo String Sisa saldo akun Mitra.

5.2 Payment Transfer

Melakukan eksekusi transfer dana ke rekening tujuan.

POST /transfer/payment

Request Body JSON:

Request Payload JSON 
{
  "kode_produk": "CENAIDJA-05",
  "customer_no": "1234567890",
  "nominal": 150000,
  "ref_id": "TRX-TRANSFER-001"
}
Response Sukses Diterima (HTTP 200 OK) 
{
  "RC": "00",
  "message": "Success",
  "status": "success",
  "kode_produk": "CENAIDJA-05",
  "customer_no": "1234567890",
  "nominal": 150000,
  "admin_transfer": 2500,
  "total": 152500,
  "saldo": "847500",
  "ref_id": "TRX-TRANSFER-001",
  "trx_status": "PENDING"
}

Penjelasan Response:

Field Tipe Keterangan
RC String Response Code (00 berarti request berhasil diterima).
message String Pesan status.
status String Status request (success).
kode_produk String Kode Bank Tujuan Transfer.
customer_no String Nomor Rekening Tujuan.
nominal Number Nominal transfer.
admin_transfer Number Biaya admin transfer.
total Number Total saldo yang dipotong.
saldo String Sisa saldo akun setelah dipotong.
ref_id String ID Referensi Unik Mitra.
trx_status String Status awal transaksi di sistem (PENDING).
Catatan Penting: Pemrosesan transaksi Transfer saat ini bersifat Asynchronous. Response di atas hanya menandakan bahwa transaksi Anda telah sukses masuk antrean dengan status PENDING dan saldo terpotong. Untuk mengetahui status akhir transaksi (Sukses atau Gagal), sistem kami akan mengirimkannya secara otomatis via Webhook (Callback Notifikasi).

5.3 Advice Transfer

Mengecek status akhir dari transaksi transfer yang sedang pending.

POST /transfer/advice

Request Body JSON:

Field Tipe Wajib Keterangan
ref_id String YA ID Referensi Unik Mitra saat transaksi Payment.
Request Payload JSON 
{
  "ref_id": "TRX-TRANSFER-001"
}
Response (Status: SUCCESS) 
{
  "jenis_callback": "PAYMENT_NOTIFICATION",
  "total_diproses": 1,
  "success_count": 1,
  "failed_count": 0,
  "processed_at": "2026-09-14T08:21:24.048Z",
  "transaksi": [
    {
      "ref_id": "TEST-1789374060479",
      "kode_produk": "CENAIDJA-05",
      "customer_no": "1090873331",
      "nominal": 10000,
      "status": "SUCCESS",
      "sn": "260914060479",
      "reference_code": "CBILLER260914060479",
      "message": "Transaksi Success",
      "cust_name": "RENDY FIRMANSYAH"
    }
  ]
}

Penjelasan Response:

Field Tipe Keterangan
jenis_callback String Jenis callback (contoh: PAYMENT_NOTIFICATION).
total_diproses Number Jumlah total transaksi yang diproses.
success_count Number Jumlah transaksi yang berstatus sukses.
failed_count Number Jumlah transaksi yang berstatus gagal.
processed_at String Waktu pemrosesan.
transaksi Array Daftar transaksi yang dilaporkan statusnya.
transaksi[].ref_id String ID Referensi Unik Mitra.
transaksi[].kode_produk String Kode Bank Tujuan Transfer.
transaksi[].customer_no String Nomor Rekening Tujuan.
transaksi[].nominal Number Nominal transaksi.
transaksi[].status String Status akhir transaksi (SUCCESS atau FAILED).
transaksi[].sn String Serial Number dari bank / provider.
transaksi[].reference_code String Kode referensi internal.
transaksi[].message String Pesan akhir transaksi.
transaksi[].cust_name String Nama pemilik rekening.

5.4 Callback Notifikasi Transfer

Karena API Transfer berjalan secara Asynchronous, hasil akhir transaksi akan dikirimkan ke URL Callback Transfer Anda.

POST [Callback URL Mitra]
Format Payload Callback JSON 
{
  "jenis_callback": "PAYMENT_NOTIFICATION",
  "total_diproses": 1,
  "success_count": 1,
  "failed_count": 0,
  "processed_at": "2026-09-14T08:21:24.048Z",
  "transaksi": [
    {
      "ref_id": "TEST-1789374060479",
      "kode_produk": "CENAIDJA-05",
      "customer_no": "1090873331",
      "nominal": 10000,
      "status": "SUCCESS",
      "sn": "260914060479",
      "reference_code": "CBILLER260914060479",
      "message": "Transaksi Success",
      "cust_name": "RENDY FIRMANSYAH"
    }
  ]
}

Penjelasan Response:

Field Tipe Keterangan
jenis_callback String Jenis callback (contoh: PAYMENT_NOTIFICATION).
total_diproses Number Jumlah total transaksi yang diproses.
success_count Number Jumlah transaksi yang berstatus sukses.
failed_count Number Jumlah transaksi yang berstatus gagal.
processed_at String Waktu pemrosesan.
transaksi Array Daftar transaksi yang dilaporkan statusnya.
transaksi[].ref_id String ID Referensi Unik Mitra.
transaksi[].kode_produk String Kode Bank Tujuan Transfer.
transaksi[].customer_no String Nomor Rekening Tujuan.
transaksi[].nominal Number Nominal transaksi.
transaksi[].status String Status akhir transaksi (SUCCESS atau FAILED).
transaksi[].sn String Serial Number dari bank / provider.
transaksi[].reference_code String Kode referensi internal.
transaksi[].message String Pesan akhir transaksi.
transaksi[].cust_name String Nama pemilik rekening.

5.5 Kode Produk Transfer

Daftar kode produk Bank Tujuan yang didukung oleh sistem.

Kode Produk Nama Bank
Loading data...

6. API Endpoints E-Wallet

E-Wallet menggunakan format dan struktur tabel yang hampir sama dengan Transfer, namun kode produknya spesifik untuk E-Wallet seperti DANA, GOPAY, OVO, dll.

6.1 Inquiry E-Wallet

Mengecek nama tujuan/pemilik akun e-wallet sebelum melakukan eksekusi pembayaran.

POST /ewallet/inquiry

Request Body JSON:

Field Tipe Wajib Keterangan
kode_produk String YA Kode e-wallet tujuan (lihat daftar kode).
customer_no String YA Nomor handphone/akun e-wallet tujuan.
nominal Number YA Nominal Topup E-Wallet.
ref_id String YA ID Referensi Unik Mitra.
Request Payload JSON 
{
  "kode_produk": "DANA-P-05",
  "customer_no": "081234567890",
  "nominal": 50000,
  "ref_id": "TRX-EWALLET-001"
}
Response Sukses (HTTP 200 OK) 
{
  "RC": "201",
  "message": "Inquiry Success",
  "nama_pelanggan": "JOHN DOE",
  "kode_produk": "DANA-P-05",
  "no_rekening": "081234567890",
  "nominal": 50000,
  "admin_transfer": 500,
  "total": 50500,
  "saldo": "1000000"
}

Penjelasan Response:

Field Tipe Keterangan
RC String Response Code (201 berarti sukses inquiry).
message String Pesan status.
nama_pelanggan String Nama pemilik akun e-wallet tujuan.
kode_produk String Kode e-wallet tujuan.
no_rekening String Nomor handphone/akun e-wallet tujuan.
nominal Number Nominal topup.
admin_transfer Number Biaya admin.
total Number Total yang akan dipotong dari saldo.
saldo String Sisa saldo akun Mitra.

6.2 Payment E-Wallet

Melakukan eksekusi topup ke e-wallet tujuan.

POST /ewallet/payment
Request Payload JSON 
{
  "kode_produk": "DANA-P-05",
  "customer_no": "081234567890",
  "nominal": 50000,
  "ref_id": "TRX-EWALLET-001"
}
Response Sukses Diterima (HTTP 200 OK) 
{
  "RC": "00",
  "message": "Success",
  "status": "success",
  "kode_produk": "DANA-P-05",
  "customer_no": "081234567890",
  "nominal": 50000,
  "admin_transfer": 500,
  "total": 50500,
  "saldo": "949500",
  "ref_id": "TRX-EWALLET-001",
  "trx_status": "PENDING"
}

Penjelasan Response:

Field Tipe Keterangan
RC String Response Code (00 berarti request berhasil diterima).
message String Pesan status.
status String Status request (success).
kode_produk String Kode e-wallet tujuan.
customer_no String Nomor handphone/akun e-wallet tujuan.
nominal Number Nominal topup.
admin_transfer Number Biaya admin.
total Number Total saldo yang dipotong.
saldo String Sisa saldo akun setelah dipotong.
ref_id String ID Referensi Unik Mitra.
trx_status String Status awal transaksi di sistem (PENDING).
Catatan Penting: Sama seperti API Transfer, transaksi E-Wallet ini berjalan secara Asynchronous. Saldo Anda akan langsung terpotong. Untuk mengetahui status akhir transaksi (Sukses atau Gagal), pantau kiriman data melalui URL Callback / Webhook Anda.

6.3 Advice E-Wallet

Digunakan untuk mengecek status akhir transaksi E-Wallet secara manual menggunakan ref_id.

POST /ewallet/advice
Request Payload JSON 
{
  "ref_id": "TRX-EWALLET-001"
}
Response (Status: SUCCESS) 
{
  "jenis_callback": "PAYMENT_NOTIFICATION",
  "total_diproses": 1,
  "success_count": 1,
  "failed_count": 0,
  "processed_at": "2026-09-14T08:30:42.165Z",
  "transaksi": [
    {
      "ref_id": "TEST-1789374600991",
      "kode_produk": "DANA-P-05",
      "customer_no": "081280737373",
      "nominal": 10000,
      "status": "SUCCESS",
      "sn": "2026091410121481030100166648281795151",
      "reference_code": "CBILLER-2026091410121481030100166648281795151",
      "message": "Transaksi Success",
      "cust_name": "DNID RENXX FIRXXXXXXX"
    }
  ]
}

Penjelasan Response:

Field Tipe Keterangan
jenis_callback String Jenis callback (contoh: PAYMENT_NOTIFICATION).
total_diproses Number Jumlah total transaksi yang diproses.
success_count Number Jumlah transaksi yang berstatus sukses.
failed_count Number Jumlah transaksi yang berstatus gagal.
processed_at String Waktu pemrosesan.
transaksi Array Daftar transaksi yang dilaporkan statusnya.
transaksi[].ref_id String ID Referensi Unik Mitra.
transaksi[].kode_produk String Kode E-Wallet Tujuan.
transaksi[].customer_no String Nomor Akun E-Wallet Tujuan.
transaksi[].nominal Number Nominal transaksi.
transaksi[].status String Status akhir transaksi (SUCCESS atau FAILED).
transaksi[].sn String Serial Number dari bank / provider.
transaksi[].reference_code String Kode referensi internal.
transaksi[].message String Pesan akhir transaksi.
transaksi[].cust_name String Nama pemilik e-wallet.

6.4 Callback Notifikasi E-Wallet

Karena API E-Wallet berjalan secara Asynchronous, hasil akhir transaksi akan dikirimkan ke URL Callback Transfer Anda.

POST [Callback URL Mitra]
Format Payload Callback JSON 
{
  "jenis_callback": "PAYMENT_NOTIFICATION",
  "total_diproses": 1,
  "success_count": 1,
  "failed_count": 0,
  "processed_at": "2026-09-14T08:30:42.165Z",
  "transaksi": [
    {
      "ref_id": "TEST-1789374600991",
      "kode_produk": "DANA-P-05",
      "customer_no": "081280737373",
      "nominal": 10000,
      "status": "SUCCESS",
      "sn": "2026091410121481030100166648281795151",
      "reference_code": "CBILLER-2026091410121481030100166648281795151",
      "message": "Transaksi Success",
      "cust_name": "DNID RENXX FIRXXXXXXX"
    }
  ]
}

Penjelasan Response:

Field Tipe Keterangan
jenis_callback String Jenis callback (contoh: PAYMENT_NOTIFICATION).
total_diproses Number Jumlah total transaksi yang diproses.
success_count Number Jumlah transaksi yang berstatus sukses.
failed_count Number Jumlah transaksi yang berstatus gagal.
processed_at String Waktu pemrosesan.
transaksi Array Daftar transaksi yang dilaporkan statusnya.
transaksi[].ref_id String ID Referensi Unik Mitra.
transaksi[].kode_produk String Kode E-Wallet Tujuan.
transaksi[].customer_no String Nomor Akun E-Wallet Tujuan.
transaksi[].nominal Number Nominal transaksi.
transaksi[].status String Status akhir transaksi (SUCCESS atau FAILED).
transaksi[].sn String Serial Number dari bank / provider.
transaksi[].reference_code String Kode referensi internal.
transaksi[].message String Pesan akhir transaksi.
transaksi[].cust_name String Nama pemilik e-wallet.

6.5 Kode Produk E-Wallet

Daftar kode produk E-Wallet yang didukung oleh sistem.

Kode Produk E-Wallet Nama E-Wallet
Loading data...

7. API Endpoints Virtual Account

Layanan Virtual Account (VA) memungkinkan mitra menerbitkan nomor rekening virtual sekali pakai untuk menerima pembayaran dari pelanggan melalui transfer bank (ATM, Mobile Banking, Internet Banking, atau Teller). Setiap nomor VA terikat pada satu transaksi dengan nominal pasti (closed amount) dan memiliki masa berlaku.

7.1 Alur Transaksi VA

  1. Buat VA: Kirim HTTP POST ke /q4/va/create dengan kode_produk (bank), harga, cust_ref_id unik, dan nama_order. Simpan ref_id dari response.
  2. Tampilkan Nomor VA: Tampilkan nilai field paymentCode (nomor VA), nama bank, nominal, dan expiredAt kepada pelanggan.
  3. Pembayaran oleh Pelanggan: Pelanggan mentransfer nominal yang tepat ke nomor VA melalui kanal bank yang dipilih.
  4. Callback Webhook: Sistem mengirim HTTP POST ke Callback URL mitra segera setelah status transaksi menjadi PAID.
  5. Verifikasi (Disarankan): Panggil /q4/va/query untuk memastikan status sebelum melakukan fulfillment.
💡
Callback URL yang Digunakan Notifikasi VA dikirim ke Callback URL yang sama dengan QRIS (callback cash-in) yang terdaftar pada profil mitra.

7.2 Create VA

Menerbitkan nomor Virtual Account baru untuk sebuah tagihan.

POST /q4/va/create

Request Body JSON:

Field Tipe Wajib Keterangan
kode_produk String YA Kode bank VA (lihat 7.5 Kode Produk VA). Contoh: MT-VA-BCA
harga Number YA Nominal tagihan yang harus dibayar pelanggan. Contoh: 100000
cust_ref_id String YA ID referensi unik milik mitra. Tidak boleh dipakai ulang.
nama_order String YA Nama pelanggan / deskripsi tagihan (tampil saat pelanggan membayar).
no_hp String TIDAK Nomor handphone pelanggan.
Request Payload JSON 
{
  "kode_produk": "MT-VA-BCA",
  "harga": 100000,
  "cust_ref_id": "INV-20261012-001",
  "nama_order": "Budi Santoso",
  "no_hp": "081234567890"
}
Contoh cURL 
curl -X POST https://api.gudangpayment.online/q4/va/create \
  -H "Content-Type: application/json" \
  -H "api_key: YOUR_API_KEY" \
  -H "pin: YOUR_PIN" \
  -d '{
    "kode_produk": "MT-VA-BCA",
    "harga": 100000,
    "cust_ref_id": "INV-20261012-001",
    "nama_order": "Budi Santoso",
    "no_hp": "081234567890"
  }'
Response Sukses (HTTP 200 OK) 
{
  "RC": "2001",
  "message": "Success",
  "ref_id": "INV8120261012212608",
  "cust_ref_id": "INV-20261012-001",
  "nama_order": "Budi Santoso",
  "harga": "100000",
  "no_hp": "081234567890",
  "status_pembayaran": "UNPAID",
  "channel": "MT-VA-BCA",
  "paymentCode": "3333938066631678",
  "expiredAt": "2026-10-13 21:26:08"
}

Penjelasan Response:

Field Tipe Keterangan
ref_id String ID transaksi dari sistem Gudang Payment. Simpan untuk Query Status.
cust_ref_id String ID referensi dari sisi mitra.
status_pembayaran String UNPAID saat VA baru diterbitkan.
channel String Kode bank VA yang digunakan.
paymentCode String Nomor Virtual Account yang harus ditransfer oleh pelanggan.
expiredAt String Batas waktu pembayaran (format YYYY-MM-DD HH:mm:ss, WIB).
RC String 2001 berarti sukses.

Response Gagal:

HTTP Contoh Body Penyebab
401 {"message":"API Key atau PIN tidak valid...","RC":"4021"} Kredensial salah / mitra tidak aktif.
403 {"message":"Access denied. IP ... is not whitelisted.","RC":"4031"} IP server mitra belum didaftarkan.
409 {"message":"cust_ref_id sudah digunakan","cust_ref_id":"...","ref_id":"..."} cust_ref_id duplikat. Response menyertakan ref_id transaksi sebelumnya.
422 {"message":"kode_produk, harga, cust_ref_id, nama_order wajib diisi"} Field wajib tidak lengkap.
500 {"message":"Internal server error"} Gangguan sistem / bank. Silakan coba kembali.

7.3 Query Status VA

Mengecek status pembayaran VA. Jika status masih UNPAID, sistem akan melakukan pengecekan ulang secara real-time ke bank/provider.

POST /q4/va/query
Field Tipe Wajib Keterangan
ref_id String YA ref_id yang diperoleh dari response Create VA.
Request Payload JSON 
{
  "ref_id": "INV8120261012212608"
}
Response Sukses (HTTP 200 OK) 
{
  "RC": "2001",
  "message": "Success",
  "ref_id": "INV8120261012212608",
  "cust_ref_id": "INV-20261012-001",
  "harga": "100000.00",
  "nama_order": "Budi Santoso",
  "status_pembayaran": "PAID",
  "channel": "VA BCA",
  "paymentCode": "3333938066631678",
  "expiredAt": "2026-10-13 21:26:08"
}
⚠️
Transaksi Tidak Ditemukan Jika ref_id tidak ditemukan atau bukan milik mitra Anda, API mengembalikan HTTP 404 dengan body {"message":"Transaction not found"}.

7.4 Callback Notifikasi VA

Saat pelanggan berhasil membayar, sistem mengirim HTTP POST ke Callback URL mitra dengan payload berikut:

Callback Payload (POST ke URL Mitra) 
{
  "RC": "2001",
  "message": "Success",
  "ref_id": "INV8120261012212608",
  "cust_ref_id": "INV-20261012-001",
  "nama_order": "Budi Santoso",
  "harga": "100000",
  "no_hp": "081234567890",
  "status_pembayaran": "PAID",
  "channel": "MT-VA-BCA",
  "paymentCode": "",
  "issuer": "",
  "nama_pembayar": "",
  "customer_pan": "",
  "rrn": "",
  "tgl_bayar": "2026-10-12T21:28:23+07:00"
}
Field Keterangan
status_pembayaran Selalu PAID untuk notifikasi pembayaran berhasil.
tgl_bayar Waktu pembayaran (format ISO 8601).
ref_id / cust_ref_id Gunakan untuk mencocokkan dengan transaksi di sistem mitra.
Response yang Diharapkan dari Mitra (HTTP 200) 
{
  "status": "success",
  "message": "Callback diterima"
}
⚠️
Idempotensi & Timeout Callback dikirim dengan timeout 5 detik. Pastikan endpoint mitra merespons cepat dengan HTTP 200 dan memproses callback secara idempoten (callback yang sama dapat diterima lebih dari sekali). Jika callback tidak diterima, gunakan /q4/va/query.

7.5 Kode Produk VA

Daftar bank Virtual Account yang didukung:

Kode Produk Nama Bank
MT-VA-BCA VA BCA
MT-VA-BNI VA BNI
MT-VA-BRI VA BRI
MT-VA-MANDIRI VA MANDIRI
MT-VA-PERMATA VA PERMATA
MT-VA-CIMB VA CIMB
💡
Biaya Transaksi VA Biaya transaksi VA dihitung per transaksi PAID dengan rumus: (persentase biaya VA × harga) + biaya admin VA. Besaran persentase dan biaya admin mengikuti kesepakatan kerja sama masing-masing mitra.

8. Response Code

Tabel kode status spesifik yang dikembalikan oleh API:

RC HTTP Status Keterangan
2001 200 OK Transaksi atau Query Berhasil
4021 401 Unauthorized API Key atau PIN tidak valid, atau Mitra tidak aktif
4031 403 Forbidden Akses ditolak, IP tidak terdaftar pada Whitelist Mitra
- 422 Unprocessable Entity Parameter wajib (harga, cust_ref_id, nama_order) tidak diisi
- 409 Conflict Duplikat cust_ref_id
- 404 Not Found Transaksi tidak ditemukan (saat Query)

9. Status Pembayaran

Status Code Deskripsi Transaksi
UNPAID QRIS telah dibuat, menunggu scan dan pembayaran oleh pelanggan.
PAID Pembayaran berhasil dikonfirmasi dan dana telah diterima.

10. API Endpoints Akun

10.1 Cek Saldo Transfer

Mengecek sisa saldo transfer yang tersedia pada akun Mitra secara real-time.

GET /account/balance

Request Body: Kosong (Tidak memerlukan payload JSON).

Response Sukses (HTTP 200 OK) 
{
  "RC": "00",
  "message": "Success",
  "data": {
    "saldo_transfer": 9252500
  }
}

Penjelasan Response:

Field Tipe Keterangan
RC String Response Code, 00 berarti sukses.
message String Pesan status.
data.saldo_transfer Number Sisa saldo transfer aktual.

11. Error Handling

Contoh skenario kegagalan dan struktur error response:

Validasi Param Gagal (HTTP 422 Unprocessable Entity):

{ "message": "harga wajib diisi dan harus lebih dari 0" }

Duplikat Reference ID (HTTP 409 Conflict):

{
  "message": "cust_ref_id sudah digunakan",
  "cust_ref_id": "INV-20260404-001",
  "ref_id": "TRX1712200000000000000"
}

12. Contoh Implementasi Kode

PHP Implementation (cURL & Webhook)

PHP Create QRIS Transaction 
<?php
$baseUrl = "https://api.gudangpayment.online";
$apiKey  = "YOUR_API_KEY";
$pin     = "YOUR_PIN";

$payload = [
    "harga"        => 50000,
    "cust_ref_id"  => "REQ-" . date("Ymd") . rand(1000, 9999),
    "nama_order"   => "Pembayaran Voucher Game",
    "validity_min" => 15,
    "is_static"    => false,
];

$ch = curl_init("$baseUrl/q4/qris/create");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => json_encode($payload),
    CURLOPT_HTTPHEADER     => [
        "Content-Type: application/json",
        "api_key: $apiKey",
        "pin: $pin"
    ]
]);

$response = curl_exec($ch);
$result   = json_decode($response, true);
curl_close($ch);

if (isset($result['RC']) && $result['RC'] === '2001') {
    echo "QR String: " . $result['qrisCode'] . "
";
    echo "Ref ID: " . $result['ref_id'] . "
";
} else {
    echo "Error: " . ($result['message'] ?? 'Unknown Error') . "
";
}
?>

13. Frequently Asked Questions (FAQ)

Q: Berapa lama durasi kedaluwarsa QR Code?

A: Default masa berlaku adalah 15 menit. Anda dapat menyesuaikannya via parameter validity_min saat pembuatan transaksi.

Q: Bagaimana cara mendapatkan API Key dan PIN?

A: Hubungi Tim Support / Technical Admin PT MAXIMA SINERGI PRIMA saat pendaftaran akun mitra.