WAGO Payment ID - Buku Panduan Teknis Integrasi

Dokumentasi ini ditujukan bagi Developer yang ingin mengintegrasikan layanan pembayaran WAGO Payment ID ke dalam website atau aplikasi mereka.

⚠️ PERATURAN INTEGRASI PENTING:

Merchant WAJIB mengarahkan (redirect) pelanggan ke Link Portal Pembayaran WAGO yang dikembalikan oleh API. Anda TIDAK DIBOLEHKAN melakukan embed (menanamkan) halaman pembayaran langsung ke dalam website Anda (misalnya menggunakan iframe atau menembak API secara langsung untuk ditampilkan di web Anda) tanpa adanya negosiasi dan persetujuan khusus dari pihak WAGO.

Alur Transaksi & Sistem WAGO

Berikut adalah gambaran menyeluruh bagaimana pertukaran data terjadi antara Pelanggan, Website/Server Toko Anda, WAGO Payment Gateway, dan Penyedia Perbankan/QRIS dari pembuatan invoice hingga pesanan dinyatakan lunas.

Geser diagram ke samping untuk melihat alur lengkap ↔

1. Pelanggan

2. Server Toko

3. WAGO Gateway

4. Bank & E-Wallet

5. App Listener

6. Payment Gateway

1. Checkout & Pilih Metode

2. POST /api/order (API Key)

3. Request VA/QRIS ke Provider PG (Opsi PG)

4. order_token & URL Checkout

5. Redirect ke Portal Checkout

6. Scan QRIS Dinamis / Bayar Virtual Account

[Jalur A] 7a. Notif Mutasi Masuk (HP)

[Jalur A] 7b. Listener Forward (POST /listener)

[Jalur B] 8a. Settlement Masuk ke PG

[Jalur B] 8b. Webhook PG (/api/pg-webhook/*)

9. Webhook POST (status: SUCCESS)

10. HTTP 200 OK (Response)

11. "Pesanan Berhasil / Akses Dikirim"

Inisiasi Transaksi (Create Order)

Server Toko ➔ WAGO API

Pelanggan menekan tombol checkout di website Anda. Backend server Anda mengirimkan HTTP request ke API WAGO membawa data tagihan (order_id, nominal, payment_method) dan diautentikasi dengan x-api-key. WAGO membuat transaksi berstatus PENDING dan mengembalikan order_token aman beserta URL portal pembayaran.

POST/api/orderHTTP 201 Createdorder_token

Pengalihan Pelanggan ke Portal Checkout

Browser Pelanggan ➔ Portal WAGO

Website Anda mengarahkan (redirect) browser pembeli ke Link Portal Pembayaran WAGO resmi menggunakan token yang didapat (misal: https://pay.wago-id.web.id/checkout/:order_id?token=...). Pembeli melihat halaman pembayaran resmi berstandar PCI dengan instruksi QRIS dinamis dan hitung mundur tanpa risiko iframe atau modifikasi kode pihak ketiga.

HTTP 302 RedirectWajib Redirect (No-Embed)Portal UI Otomatis

Pembayaran oleh Pelanggan

Pelanggan ➔ Bank / E-Wallet Provider

Pelanggan membuka aplikasi Mobile Banking (BCA, Mandiri, BRI, BNI) atau dompet digital (GoPay, OVO, Dana, ShopeePay) untuk melakukan pemindaian kode QRIS atau transfer tepat hingga digit nominal_unik. Jaringan perbankan segera memproses dan membukukan mutasi pembayaran.

QRIS DinamisNominal Unik 3 DigitInstant Settlement

Notifikasi Webhook Realtime (Callback)

WAGO Gateway ➔ Server Toko

Sistem WAGO mendeteksi mutasi masuk secara instan dan langsung mengirimkan HTTP POST Webhook ke URL callback yang Anda daftarkan di dashboard. Notifikasi memuat status SUCCESS, nominal_unik, nomor seri referensi bank (sn), dan diproteksi header keamanan X-WAGO-Signature (HMAC-SHA256).

POST[callback_url]X-WAGO-Signaturestatus: SUCCESS

Validasi Signature & Penyelesaian Pesanan

Server Toko ➔ Database & Pelanggan

Server backend Anda memvalidasi X-WAGO-Signature menggunakan Callback Secret Anda untuk memastikan notifikasi 100% valid bukan dari penyerang. Setelah valid, status pesanan di database toko Anda diubah menjadi PAID / SUCCESS, hak akses/barang diserahkan, dan server Anda membalas respon HTTP 200 OK.

HMAC-SHA256 VerificationHTTP 200 OKTransaksi Sukses

Persiapan Awal

Sebelum memulai, pastikan Anda telah memiliki:

APP ID (ID Toko Anda, contoh: TOKO_SAYA_APP)
API Key (Secret Key untuk autentikasi, contoh: WPI_Live_xxxxxxxx)
Callback Secret (Kunci rahasia untuk validasi webhook dari WAGO)

Semua kredensial ini bisa didapatkan melalui Dashboard WAGO > Menu Integrasi > API Key & Webhook.

Autentikasi Mudah

Semua request dilindungi menggunakan Bearer Token dari API Key Anda.

Realtime Webhooks

Dapatkan notifikasi instan ke server Anda setiap kali ada transaksi berhasil.