Chiwa Pay API Overview

Chiwa Pay integration overview for creating transactions, accepting payments, and tracking payment status.

Chiwa Pay helps merchants create payment transactions, show payment instructions to customers, and track status changes through webhooks or the API. Use this page as a quick map before opening the endpoint-level guides.

What You Can Build

Accept QRIS payments

Create transactions, show QRIS, and guide customers to complete payment.

Track transaction status

Fetch the latest status by transaction UUID or reference ID.

Refund transactions

Start a refund for paid transactions and follow the refund status.

Automate notifications

Receive events for paid, expired, failed, refund, and settled transactions.

Manage fees and disbursement

Understand customer total, merchant net amount, refunds, and disbursement.

Handle API errors

Recognize error response formats and codes your app should handle.

Before You Start

Requirement	Description
Active merchant	The merchant application must be approved before its API key can create transactions.
API key	The secret key is available in the merchant dashboard and sent with the `Authorization` header.
Payment method	Make sure the payment method you want to use is enabled for the merchant.
Webhook URL	Recommended for automatic payment status updates from Chiwa Pay.

API URL

Every endpoint example uses the following base URL.

https://api.chiwapay.com

Quick Start

The shortest path to create a QRIS transaction:

cURL

curl -X POST "https://api.chiwapay.com/payments" \  -H "Authorization: Bearer sk_xxx" \  -H "Content-Type: application/json" \  -H "Idempotency-Key: ORDER-1024" \  -d '{  "amount": 150000,  "payment_method": "qris",  "merchant_reference_id": "ORDER-1024",  "customer": {    "name": "Nara",    "email": "nara@example.com"  }}'

The create payment response includes payment.id, reference_id, status, qris_payload, qris_image_url, and expires_at. Show the QRIS to the customer, then fulfill the order after the status changes to paid.

Integration Flow

Step	Description
1	Store the API key on your server and never expose the secret key to the frontend.
2	Merchant creates a transaction with `POST /payments`.
3	Chiwa Pay returns payment instructions such as a QRIS payload or QR image URL.
4	Customer pays using the payment instruction before `expires_at`.
5	Chiwa Pay sends a webhook when status changes, for example `payment.paid` or `payment.expired`.
6	Merchant verifies the webhook, updates the order, and reconciles with the dashboard or transaction detail API.

Transaction Status

Status	Description
`created`	Transaction was created.
`pending`	Waiting for payment.
`paid`	Customer has paid.
`expired`	Payment deadline has passed.
`settled`	Funds are in settlement and the transaction cannot be cancelled.
`failed`	Payment failed.
`cancelled`	Transaction was cancelled.
`refund_processing`	Refund is being processed.
`refund_failed`	Refund failed and needs retry or manual handling.
`refunded`	Refund succeeded.

Webhook or Polling

Mechanism	Use When	Notes
Webhook	Your system can receive requests from Chiwa Pay.	This is the primary way to process status changes in real time.
Transaction detail polling	Your system cannot receive webhooks yet or needs a fallback check.	Use as a fallback and add delay between requests to avoid rate limits.
Dashboard	Operations teams need to inspect transactions manually.	Useful for investigation, support, and reconciliation.

Key Concepts

Concept	Summary
`merchant_reference_id`	The order ID from the merchant system. Use a value that is easy to reconcile.
`reference_id`	Chiwa Pay transaction ID that can be used to look up a payment.
`Idempotency-Key`	Prevents duplicate transaction creation when a create payment request is retried.
`total_amount`	The amount the customer must pay. It can differ from `amount` when the buyer pays the fee.
`net_amount`	The amount recorded for the merchant after fee rules are applied.