# WAGO Payment ID - Buku Panduan Teknis Integrasi (API Guide)

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.

## 1. 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**.

---

## 2. Base URL
Semua request API harus diarahkan ke Base URL utama sistem WAGO Anda.
**Base URL:** `https://wago-payment-id.vercel.app` *(Ganti dengan domain WAGO Anda yang sebenarnya)*

---

## 3. Membuat Transaksi Baru (Create Transaction)
Digunakan untuk meng-generate transaksi baru dan mendapatkan link pembayaran / status transaksi.

- **Endpoint:** `POST /api/order`
- **Content-Type:** `application/json`

### Request Headers
| Header | Tipe | Wajib | Keterangan |
|--------|------|-------|------------|
| `x-api-key` | `string` | **Ya** | API Key Anda (Secret Key) |

### Request Body (JSON)
| Parameter | Tipe | Wajib | Keterangan |
|-----------|------|-------|------------|
| `app_id` | `string` | **Ya** | ID Aplikasi/Toko Anda (Contoh: `TOKO_SAYA`) |
| `order_id` | `string` | **Ya** | ID Transaksi Unik dari sistem Anda (Contoh: `INV-123`) |
| `nominal` | `number` | **Ya** | Jumlah tagihan (Contoh: `150000`) |
| `customer_name` | `string` | Tidak | Nama pembeli |
| `customer_email` | `string` | Tidak | Email pembeli |
| `customer_phone` | `string` | Tidak | Nomor HP pembeli |
| `payment_method` | `string` | Tidak | `QRIS`, `BANK_TRANSFER`, atau `EWALLET` (Bawaan: `QRIS`) |
| `payment_channel` | `string` | Tidak | ID Channel spesifik (contoh: `QRIS`, `SUPERBANK`, `BCA`, dll) |
| `callback_url` | `string` | Tidak | URL Webhook sementara untuk transaksi ini (jika berbeda dari dashboard) |

### Contoh Request (cURL)
```bash
curl -X POST https://wago-payment-id.vercel.app/api/order \
  -H "Content-Type: application/json" \
  -H "x-api-key: WPI_Live_1234567890abcdef" \
  -d '{
    "app_id": "TOKO_SAYA",
    "order_id": "INV-20261001",
    "nominal": 50000,
    "customer_name": "Budi Santoso",
    "payment_method": "QRIS",
    "payment_channel": "QRIS"
  }'
```

### Contoh Response Berhasil (HTTP 201)
```json
{
  "status": "success",
  "data": {
    "order_id": "INV-20261001",
    "nominal": 50000,
    "nominal_unik": 50123,
    "admin_fee": 0,
    "status": "PENDING",
    "payment_method": "QRIS",
    "payment_channel": "QRIS",
    "order_token": "a1b2c3d4e5f6g7h8i9j0"
  }
}
```

> ⚠️ **PENTING:** Simpan `order_token` yang Anda dapatkan di response ini. Token ini bersifat *sekali pakai* per transaksi dan wajib disertakan saat Anda ingin mengarahkan pembeli ke halaman Checkout WAGO.
> **Contoh URL Redirect Pembeli:**
> `https://wago-payment-id.vercel.app/checkout/INV-20261001?token=a1b2c3d4e5f6g7h8i9j0`

---

## 4. Cek Status Transaksi (Check Order Status)
Digunakan untuk mengecek status transaksi atau untuk mendapatkan string/URL QRIS secara real-time.

- **Endpoint:** `GET /api/order?id={order_id}`

### Request Headers
| Header | Tipe | Wajib | Keterangan |
|--------|------|-------|------------|
| `x-api-key` | `string` | **opsional*** | API Key Anda (Secret Key) |
| `x-order-token` | `string` | **opsional*** | Token spesifik milik pesanan ini (didapat saat Create Transaction) |

*\*Anda wajib mengirimkan **salah satu** antara `x-api-key` (untuk akses sistem penuh) ATAU `x-order-token` (untuk akses publik terbatas pada 1 pesanan tersebut, biasanya digunakan dari sisi frontend browser).*

### Contoh Request (cURL)
```bash
curl -X GET "https://wago-payment-id.vercel.app/api/order?id=INV-20261001" \
  -H "x-api-key: WPI_Live_1234567890abcdef"
```

### Contoh Response (HTTP 200)
```json
{
  "order_id": "INV-20261001",
  "status": "SUCCESS",
  "nominal": 50000,
  "nominal_unik": 50123,
  "qris_string": "00020101021226...5405501236304ABCD",
  "paidAt": "2026-10-01T12:30:00Z"
}
```

---

## 5. Webhook (Notifikasi Asinkron)
WAGO akan mengirimkan request `HTTP POST` ke server Anda (Callback URL) segera setelah pelanggan berhasil melakukan pembayaran.

- **Method:** `POST`
- **Content-Type:** `application/json`

### Webhook Headers
WAGO menyertakan header keamanan untuk memvalidasi bahwa notifikasi benar-benar berasal dari sistem WAGO:
- `X-WAGO-Timestamp`: Waktu ketika webhook dikirim (Unix Timestamp)
- `X-WAGO-Signature`: HMAC-SHA256 Signature untuk validasi keamanan data

### Payload Body Webhook
```json
{
  "order_id": "INV-20261001",
  "status": "SUCCESS",
  "nominal_unik": 50123,
  "sn": "WGB-87654321-123",
  "t": "1690000000",
  "sig": "abcdef1234567890..."
}
```

### Cara Memvalidasi Webhook (Signature Verification)
Untuk mencegah *Fake Webhook / Hacking*, Anda **WAJIB** memvalidasi signature yang dikirimkan.

**Format Raw Payload yang di-Hash:**
`{order_id}:{status}:{nominal_unik}:{sn}:{timestamp}`

**Contoh Validasi (PHP):**
```php
$headers = getallheaders();
$signature = $headers['X-WAGO-Signature'];
$timestamp = $headers['X-WAGO-Timestamp'];

$body = json_decode(file_get_contents('php://input'), true);

$orderId = $body['order_id'];
$status = $body['status'];
$nominalUnik = $body['nominal_unik'];
$sn = $body['sn'];

// Gabungkan string
$rawPayload = "{$orderId}:{$status}:{$nominalUnik}:{$sn}:{$timestamp}";

// Buat Hash dengan Callback Secret Anda
$secret = "SecretWebhookAnda123";
$expectedSignature = hash_hmac('sha256', $rawPayload, $secret);

if (hash_equals($expectedSignature, $signature)) {
    // Validasi SUKSES, data aman! Update database Anda.
    http_response_code(200);
    echo json_encode(["status" => "ok"]);
} else {
    // Validasi GAGAL, tolak webhook!
    http_response_code(403);
    echo json_encode(["error" => "Invalid signature"]);
}
```
*Catatan: Webhook yang gagal atau mendapat respon selain HTTP 200 akan terus ditolak dan diabaikan (tidak diretry).*