Winpay — QRIS

Gerbang Pay menyediakan layanan pembuatan QRIS MPM Dynamic via Winpay. QRIS ini unik untuk setiap transaksi (nominal sudah terisi) sehingga pelanggan tidak bisa mengubah jumlah yang harus dibayar.

Cara Pembuatan (Create)

Untuk membuat QRIS, set method_type menjadi qris dan berikan method_detail dengan type: qris. Tidak ada channel atau bank spesifik yang perlu dipilih, karena QRIS bersifat universal (dapat di-scan oleh aplikasi m-banking atau e-wallet apa pun yang tergabung dalam jaringan QRIS).

POST /v1/payments/create

{
  "amount": 2500000, 
  "currency": "IDR",
  "method_type": "qris",
  "method_detail": {
    "type": "qris"
  },
  "customer_name": "Budi Santoso",
  "expiry_minutes": 15
}

Catatan Penting Request

• Amount: Gunakan format sen (2500000 = Rp 25.000).
• Expiry Minimal: Winpay mewajibkan batas waktu minimal 2 menit untuk QRIS. Jika Anda mengirim expiry_minutes kurang dari 2, API akan menolak request tersebut dengan error validasi.

Response

Jika berhasil, Anda akan menerima response berupa objek Payment dengan method_data yang berisi data QRIS.

{
  "success": true,
  "data": {
    "id": "...",
    "status": "pending",
    "method_data": {
      "type": "qris",
      "qr_string": "00020101021126660016ID.CO.WINPAY.WWW0118936009121111979927021111119799270303UMI51440014ID.CO.QRIS.WWW0215ID10200214693950303UMI5204481453033605406250.005802ID5913GERBANG PAY6008JAKARTA61051234562300109TX-1234560709TX-1234566304CA11",
      "qr_image_url": "https://gerbang-pay-api.gai.co.id/qr/image?data=000201..."
    }
  }
}

Cara Menampilkan QR Code ke Pelanggan

Ada dua pendekatan yang dapat Anda gunakan di frontend:

1. Gunakan qr_string (Direkomendasikan)

   • String ini adalah raw payload QRIS standar. Anda dapat merendernya menjadi gambar QR Code secara langsung di aplikasi atau web Anda menggunakan library QR generator lokal (misal: qrcode.react, zxing, atau sejenisnya).
   • Cara ini paling cepat dan aman.

2. Gunakan qr_image_url (Alternatif)

   • Jika Anda tidak ingin/bisa merender QR code secara lokal di client, Anda bisa menggunakan URL gambar yang disediakan oleh Gerbang Pay. Cukup pasang string URL tersebut di tag <img src="...">.

---

Alur Pembayaran End-to-End

1. Aplikasi Klien: Mengirim POST /v1/payments/create dengan method qris.
2. Gerbang Pay: Mengembalikan qr_string.
3. Aplikasi Klien: Merender QR Code di layar.
4. Pelanggan: Membuka aplikasi e-wallet (DANA, OVO, GoPay) atau M-Banking dan memindai (scan) QR code tersebut. Nominal akan langsung muncul di HP pelanggan.
5. Pelanggan: Memasukkan PIN/konfirmasi pembayaran.
6. Winpay: Mendeteksi dana masuk dan mengirim callback ke Gerbang Pay.
7. Gerbang Pay: Mengubah status transaksi menjadi paid dan mengirimkan Webhook ke server Anda.