Overview

Panduan lengkap untuk dengan cepat mengintegrasikan sistem Anda dengan layanan Chiwa Pay

Chiwa Pay menyediakan layanan untuk memenuhi kebutuhan sistem pembayaran aplikasi Anda. Anda dapat memanfaatkan fitur-fitur yang Chiwa Pay sediakan yang dapat Anda sesuaikan dengan kebutuhan.

Yang Dapat Anda Lakukan

Terima pembayaran QRIS

Buat tagihan pembayaran kepada customer Anda.

Terima notifikasi perubahan status

Terima notifikasi perubahan status pembayaran ke sistem Anda.

Mendapatkan status transaksi

Mendapatkan status transaksi berdasarkan ID transaksi.

Refund transaksi

Apabila Anda ingin melakukan refund pembayaran ke customer.

Account Profile

Anda dapat melihat informasi akun dan saldo merchant Anda.

Informasi biaya dan pencairan dana

Informasi terkait biaya layanan dan pencairan dana.

Sebelum Memulai

Anda perlu memenuhi beberapa kondisi di bawah sebelum dapat melakukan integrasi.

Kebutuhan	Keterangan
Merchant aktif	Pengajuan merchant harus sudah disetujui sebelum API key dapat digunakan untuk transaksi.
API key	Yang dapat Anda dapatkan pada halaman API Key yang digunakan pada header `Authorization Bearer <token>` di setiap permintaan.
Metode pembayaran	Pastikan metode pembayaran yang ingin digunakan sudah aktif untuk merchant.
Webhook URL	Disarankan untuk menerima update status otomatis dari Chiwa Pay.

URL API

Setiap contoh endpoint menggunakan base URL berikut.

<origin>

Quick Start

Contoh singkat untuk membuat tagihan pembayaran:

cURL

curl -X POST "<origin>/api/payments" \  -H "Authorization: Bearer sk_xxx" \  -H "Content-Type: application/json" \  -H "Idempotency-Key: kirarin-1234" \  -d '{  "amount": 150000,  "payment_method": "qris",  "merchant_reference_id": "kirarin-1234",  "customer": {    "name": "Chiwa",    "email": "chiro@chiwa.dev"  }}'

Response API pembuatan tagihan akan memiliki beberapa informasi untuk melakukan pembayaran. Anda dapat menemukan detail dan penjelasan-nya di sini

Alur Integrasi

Langkah	Keterangan
1	Simpan API key dengan aman di server Anda.
2	Merchant membuat transaksi melalui `POST /api/payments`.
3	Chiwa Pay mengembalikan instruksi pembayaran seperti QRIS payload atau QR image URL.
4	Customer membayar sesuai instruksi pembayaran sebelum `expires_at`.
5	Merchant melakukan polling status transaksi atau menerima webhook saat status berubah, misalnya `payment.paid` atau `payment.expired`.
6	Sistem merchant memvalidasi webhook, memperbarui order, dan melakukan rekonsiliasi dengan dashboard atau API detail transaksi.

Status Transaksi

Status	Keterangan
`created`	Transaksi dibuat.
`pending`	Menunggu pembayaran.
`paid`	Customer sudah membayar.
`expired`	Batas waktu pembayaran berakhir.
`settled`	Dana sudah masuk proses settlement dan tidak dapat di-cancel.
`failed`	Pembayaran gagal.
`cancelled`	Transaksi dibatalkan.
`refund_processing`	Refund sedang diproses.
`refund_failed`	Refund gagal dan perlu dicoba ulang atau ditangani manual.
`refunded`	Refund berhasil.

Konsep Dasar

Konsep	Ringkasan
`merchant_reference_id`	ID order dari sistem merchant. Gunakan nilai yang mudah kamu cocokkan saat rekonsiliasi.
`reference_id`	ID transaksi dari Chiwa Pay yang dapat digunakan untuk lookup pembayaran.
`Idempotency-Key`	Mencegah pembuatan transaksi dobel saat request create payment diulang.
`total_amount`	Nominal yang harus dibayar customer. Nilainya dapat berbeda dari `amount` jika fee dibebankan ke buyer.
`net_amount`	Nominal yang dicatat untuk merchant setelah aturan fee diterapkan.