# Chiwa Pay API Overview


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

Canonical: https://docs.chiwapay.com/

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](https://docs.chiwapay.com/payments): Create transactions, show QRIS, and guide customers to complete payment.
  - [Track transaction status](https://docs.chiwapay.com/payment-detail): Fetch the latest status by transaction UUID or reference ID.
  - [Refund transactions](https://docs.chiwapay.com/payment-refund): Start a refund for paid transactions and follow the refund status.
  - [Automate notifications](https://docs.chiwapay.com/webhooks): Receive events for paid, expired, failed, refund, and settled transactions.
  - [Manage fees and disbursement](https://docs.chiwapay.com/fees-disbursement): Understand customer total, merchant net amount, refunds, and disbursement.
  - [Handle API errors](https://docs.chiwapay.com/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:

```tsx
<ApiExample
  method="POST"
  path="/payments"
  idempotencyKey="ORDER-1024"
  body={{
    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. |

## Continue From Here

- [Authentication](https://docs.chiwapay.com/authentication): Send the API key and keep access secure.
  - [API Reference](https://docs.chiwapay.com/): Payment, transaction detail, refund, and transaction list endpoints.
  - [Webhooks](https://docs.chiwapay.com/webhooks): Transaction status events and signature headers.
  - [Errors](https://docs.chiwapay.com/errors): Error response format and codes your app should handle.