API Documentation - AWH Payment Gateway

Authentication (Host-Based)

API Payment Gateway ini menggunakan metode autentikasi berbasis Host (Host-Based Authentication). Tidak diperlukan API Key di setiap request, karena sistem akan otomatis mengenali client dari mana request tersebut berasal.

Penting: Pastikan pengaturan Client Host di menu Clients sudah sesuai dengan origin aplikasi/server yang mengirimkan request (misalnya: 192.168.1.10 atau my-client.local).

Cara Kerja:

Kirimkan request HTTP ke endpoint API.
Sistem akan mengekstrak header Host secara otomatis.
Jika header Host tidak dikenali karena menggunakan reverse proxy, Anda dapat mengirimkan header khusus: X-Client-Host: <host-klien>.

Create Transaction

Endpoint utama untuk membuat transaksi baru. Pilih tipe pembayaran di bawah ini untuk melihat spesifikasi detail dari request dan response yang dibutuhkan.

POST /api/v1/transactions

Headers

Key	Value
Accept	`application/json`
Content-Type	`application/json`

Request Body Parameters

Parameter	Description
reference_idstringRequired	ID referensi/Order ID unik dari sistem Anda. (Maksimal 100 karakter)
nominalobjectRequired	Objek yang berisi rincian nominal pembayaran.
nominal.subtotalintegerRequired	Nominal dasar pembayaran.
nominal.totalintegerRequired	Nominal total yang harus dibayar oleh pelanggan (termasuk pajak/fee jika ada). Parameter ini yang akan ditagihkan ke QRIS.
no_hpstringOptional	Nomor HP pelanggan (jika ada).
expires_atdatetimeOptional	Waktu kadaluarsa transaksi dalam format ISO (misal: `2026-12-31T23:59:59Z`).

Example Request

{
    "reference_id": "ORDER-123456",
    "nominal": {
        "subtotal": 50000,
        "total": 50000
    },
    "no_hp": "08123456789",
    "expires_at": "2026-10-10T12:00:00Z"
}

Example Response (201 Created)

{
    "success": true,
    "message": "Transaksi berhasil dibuat.",
    "data": {
        "transaction_id": 105,
        "order_id": "ORDER-123456",
        "status": "PENDING",
        "amount": 50000,
        "currency": "IDR",
        "mode": "production",
        "payment_type": "QRIS",
        "qr_string": "00020101021226670016ID.CO.SHOPEE.WWW0118936000003000...53033605405500005802ID5908MERCHANT6007JAKARTA6105123456254051...63048590",
        "qr_image_url": "https://api.gateway.com/qr/img/ORDER-123456",
        "redirect_url": null,
        "token": null,
        "external_id": "ext-qris-893"
    }
}

Under Development
Dokumentasi API untuk pembuatan Virtual Account (VA) sedang dalam tahap pengembangan dan akan segera dirilis.

Under Development
Dokumentasi API untuk metode pembayaran E-Wallet (OVO, Dana, dll) sedang dalam tahap pengembangan.

Webhook Notification (Callback to Client)

Ketika pembayaran QRIS berhasil dilakukan oleh pelanggan, Payment Gateway akan menerima notifikasi dari provider (seperti Xendit/Doku), lalu meneruskannya secara otomatis (forward) ke Webhook URL milik Client.

Perhatian: URL Webhook Anda harus bisa diakses secara publik dan harus merespon dengan HTTP Status 200 OK untuk menandakan bahwa notifikasi telah diterima.

Format Webhook yang Dikirimkan

Method: POST
Headers:
- Content-Type: application/json
- X-Source: awh-payment-gateway

Field	Description
eventstring	Jenis event. Nilai konstan: `transaction.update`
transaction_idinteger	ID internal transaksi di tabel AWH Payment Gateway.
order_idstring	Sama dengan `reference_id` yang Anda kirim saat membuat transaksi. Gunakan ini untuk memperbarui database Anda.
external_idstring	ID unik dari sisi provider payment (contoh ID Xendit/Doku).
statusstring	Status pembayaran terbaru. (Contoh: `SUCCEEDED`, `PAID`, `FAILED`).
amountinteger	Nominal yang dibayarkan.
payment_typestring	Tipe pembayaran (Contoh: `QRIS`).

Example Webhook Payload (Received by Client)

{
    "event": "transaction.update",
    "transaction_id": 105,
    "order_id": "ORDER-123456",
    "external_id": "ext-qris-893",
    "status": "SUCCEEDED",
    "amount": 50000,
    "currency": "IDR",
    "payment_type": "QRIS",
    "gateway": "xendit",
    "timestamp": "2026-10-10T12:05:30+07:00"
}