### Example GET Request for Checkout

Source: https://docs.bayar.digital/llms-full.txt

This snippet shows how to make a GET request to the public checkout endpoint to retrieve payment details. No authentication headers are required.

```bash
curl https://api.bayar.digital/checkout/660e8400-e29b-41d4-a716-446655440010
```

--------------------------------

### Get Channel Instructions Request Example

Source: https://docs.bayar.digital/llms-full.txt

Use this cURL command to request payment instructions for a given channel ID. Ensure you include your API Key in the header.

```bash
curl https://api.bayar.digital/gateway/channels/660e8400-e29b-41d4-a716-446655440001/instructions \
  -H "X-Api-Key: pk_..."
```

--------------------------------

### Get Channel Instructions

Source: https://docs.bayar.digital/llms-full.txt

Fetches detailed payment instructions for a given channel ID. This is useful for guiding users through the payment process.

```APIDOC
## GET /gateway/channels/{channel_id}/instructions

### Description
Retrieves step-by-step payment instructions for a specific bank channel.

### Method
GET

### Endpoint
/gateway/channels/{channel_id}/instructions

### Parameters
#### Path Parameters
- **channel_id** (uuid) - Required - The ID of the channel for which to retrieve instructions. This ID can be obtained from the response of `GET /gateway/accounts` or `GET /gateway/payment/create`.

#### Header Parameters
- **X-Api-Key** (string) - Required - Your merchant API Key.

### Request Example
```bash
curl https://api.bayar.digital/gateway/channels/660e8400-e29b-41d4-a716-446655440001/instructions \
  -H "X-Api-Key: pk_..."
```

### Response
#### Success Response (200)
- **channel_id** (uuid) - The ID of the channel.
- **instructions** (array) - A list of payment instructions.
  - **step** (int) - The sequence number of the instruction.
  - **title** (string) - The title of the instruction step.
  - **content** (string) - The detailed content or action for the instruction step.

#### Response Example
```json
{
  "success": true,
  "message": "ok",
  "data": {
    "channel_id": "660e8400-e29b-41d4-a716-446655440001",
    "instructions": [
      {
        "step": 1,
        "title": "Buka aplikasi BCA Mobile",
        "content": "Login ke aplikasi BCA Mobile Anda"
      },
      {
        "step": 2,
        "title": "Pilih m-Transfer",
        "content": "Pilih menu m-Transfer > ke Rekening BCA Virtual Account"
      },
      {
        "step": 3,
        "title": "Masukkan nominal",
        "content": "Transfer sesuai total yang tertera"
      }
    ]
  }
}
```

### Error Handling
- **channel_id is required** (400) - The `channel_id` parameter is missing.
- **tenant_api_key_required** (403) - The provided API Key is invalid.
- **internal_error** (500) - An internal server error occurred. Please try again.
```

--------------------------------

### Complete Webhook Handler Example (Python/FastAPI)

Source: https://docs.bayar.digital/webhook

This example demonstrates a complete webhook handler using Python with the FastAPI framework. It includes signature verification and basic JSON parsing. Ensure the WEBHOOK_SECRET environment variable is set.

```python
from fastapi import FastAPI, Request, HTTPException
import os
import hmac
import hashlib

app = FastAPI()

@app.post("/webhooks/bayar")
async def webhook(request: Request):
    body = await request.body()
    secret = os.environ.get("WEBHOOK_SECRET")
    if secret:
        expected = hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()
        if not hmac.compare_digest(expected, request.headers.get("x-signature", "")):
            raise HTTPException(status_code=401, detail="invalid signature")
    data = await request.json()

    # Cari order di database, validasi amount, dan update status (idempotent)
    return {"status": "received"}
```

--------------------------------

### Webhook Payload Example

Source: https://docs.bayar.digital/webhook

This is an example of the JSON payload that Bayar Digital will send to your server when a payment status changes.

```APIDOC
## Webhook Payload

Bayar Digital akan mengirimkan _request HTTP POST_ ke server Anda setiap kali terjadi perubahan status pembayaran.

Berikut adalah contoh bentuk _payload_ (data JSON) yang akan dikirimkan ke server Anda:

```json
{
  "payment_id": "660e8400-e29b-41d4-a716-446655440010",
  "payment_code": "INV-2026-0001",
  "status": "PAID",
  "amount": 50123,
  "paid_at": "2026-06-11T10:05:00Z"
}
```

### Detail Field

| Field         | Tipe   | Deskripsi                                                                 |
|---------------|--------|---------------------------------------------------------------------------|
| `payment_id`  | uuid   | ID unik _invoice_ di sistem Bayar Digital                                  |
| `payment_code`| string | Kode _invoice_ internal dari sistem Anda                                   |
| `status`      | string | Status pembayaran saat ini: `PAID` / `EXPIRED` / `CANCELLED`              |
| `amount`      | int64  | **Total akhir** yang harus dibayar (nominal asli + kode unik)             |
| `paid_at`     | datetime | Waktu pembayaran sukses (ISO 8601). Hanya muncul jika status `PAID`       |
```

--------------------------------

### Payment Get

Source: https://docs.bayar.digital/llms-full.txt

Mengecek status pembayaran atau rekonsiliasi order. Gunakan endpoint ini untuk mengecek status invoice kapan saja. Untuk update status real-time, setup Webhook.

```APIDOC
## Payment Get

### Description
Mengecek status pembayaran atau rekonsiliasi order. Gunakan endpoint ini untuk mengecek status invoice kapan saja. Untuk update status real-time, setup [Webhook](./webhook).

Lihat [Status & Error Code](./status-code) untuk daftar lengkap status payment.

### Response
#### Success Response (200)
- **payment_code** (string) - Kode invoice
- **amount_original** (int64) - Nominal asli (tanpa nominal unik)
- **amount_unique** (int64) - Nominal unik
- **amount_total** (int64) - Total yang harus dibayar
- **status** (string) - Status payment
- **expires_at** (datetime) - Batas waktu pembayaran
- **created_at** (datetime) - Waktu pembuatan
- **customer_name** (string) - Nama customer
- **customer_email** (string/null) - Email customer
- **customer_phone** (string/null) - Telepon customer
- **return_url** (string/null) - Redirect URL
- **redirect_url** (string/null) - URL redirect dengan parameter `payment_code`
- **order_items** (string) - Item pesanan (JSON string)
- **account_number** (string) - Nomor rekening tujuan
- **account_name** (string) - Nama pemilik rekening
- **bank_name** (string) - Nama bank
- **bank_type** (string) - `TRANSFER`
- **app_name** (string) - Nama aplikasi mobile banking
- **instructions** (string) - Instruksi pembayaran (JSON string)
```

--------------------------------

### Webhook Payload Examples

Source: https://docs.bayar.digital/webhook

Examples of webhook payloads for different payment statuses: PAID, EXPIRED, and CANCELLED.

```json
{  "payment_id": "660e8400-e29b-41d4-a716-446655440010",  "payment_code": "INV-2026-0001",  "status": "PAID",  "amount": 50123,  "paid_at": "2026-06-11T10:05:00Z"}
```

```json
{  "payment_id": "660e8400-e29b-41d4-a716-446655440010",  "payment_code": "INV-2026-0001",  "status": "EXPIRED",  "amount": 50123}
```

```json
{  "payment_id": "660e8400-e29b-41d4-a716-446655440010",  "payment_code": "INV-2026-0001",  "status": "CANCELLED",  "amount": 50123}
```

--------------------------------

### Webhook Payload Example

Source: https://docs.bayar.digital/webhook

This is an example of the JSON payload that Bayar Digital will send to your server when a payment status changes. It includes essential details about the transaction.

```json
{
  "payment_id": "660e8400-e29b-41d4-a716-446655440010",
  "payment_code": "INV-2026-0001",
  "status": "PAID",
  "amount": 50123,
  "paid_at": "2026-06-11T10:05:00Z"
}
```

--------------------------------

### List Payments Request Example

Source: https://docs.bayar.digital/llms-full.txt

Use this cURL command to fetch a list of payments. Ensure you include your API key in the headers and specify pagination parameters as needed.

```bash
curl "https://api.bayar.digital/gateway/payments?page=1&per_page=20" \
  -H "X-Api-Key: pk_..."
```

--------------------------------

### Complete Webhook Handler with Signature Verification (PHP)

Source: https://docs.bayar.digital/llms-full.txt

This PHP example shows a Laravel route for handling webhooks. It verifies the signature using configuration settings and validates incoming data before processing.

```php
Route::post('webhooks/bayar', function (Request $request) {
    $secret = config('services.bayar.webhook_secret');

    if ($secret) {
        $expected = hash_hmac('sha256', $request->getContent(), $secret);
        if (!hash_equals($expected, $request->header('X-Signature', ''))) {
            return response()->json(['status' => 'invalid signature'], 401);
        }
    }

    $data = $request->validate([
        'payment_code' => 'required|string',
        'status' => 'required|in:PAID,EXPIRED,CANCELLED',
        'amount' => 'required|integer',
    ]);

    // Cari order, validasi amount, update status (idempotent)

    return response()->json(['status' => 'received']);
});
```

--------------------------------

### Complete Webhook Handler with Signature Verification (Node.js)

Source: https://docs.bayar.digital/llms-full.txt

This Node.js example demonstrates a complete Express.js webhook handler. It includes signature verification using environment variables and basic request body processing.

```javascript
app.post('/webhooks/bayar', express.json(), (req, res) => {
  // 1. Verifikasi signature
  if (process.env.WEBHOOK_SECRET) {
    const expected = crypto
      .createHmac('sha256', process.env.WEBHOOK_SECRET)
      .update(JSON.stringify(req.body))
      .digest('hex');
    if (req.headers['x-signature'] !== expected) {
      return res.status(401).json({ status: 'invalid signature' });
    }
  }

  const { payment_id, payment_code, status, amount } = req.body;

  // 2. Cari order di DB
  // 3. Validasi amount
  // 4. Update status (idempotent)

  res.json({ status: 'received' });
});
```

--------------------------------

### Get Available Payment Accounts

Source: https://docs.bayar.digital/payment-account

Use this endpoint to retrieve a list of your available payment accounts. The `account_id` from the response is crucial for creating payments. Ensure `account_active` is true and `account_quota` is greater than 0 before proceeding.

```bash
curl -X GET https://api.bayar.digital/gateway/accounts \
  -H "X-Api-Key: pk_..."
```

--------------------------------

### GET /gateway/mutations

Source: https://docs.bayar.digital/llms-full.txt

Retrieves a list of incoming payment mutations. You can filter these mutations to see only those that have not been automatically matched with an invoice.

```APIDOC
## GET /gateway/mutations

### Description
Retrieves a list of incoming payment mutations detected by the Android Worker. This endpoint is useful for reconciliation and manual payment matching, especially when automatic matching fails. You can filter the results to view only unmatched transactions.

### Method
GET

### Endpoint
/gateway/mutations

### Parameters
#### Query Parameters
- **page** (integer) - Optional - The page number for pagination. Defaults to 1.
- **per_page** (integer) - Optional - The number of data entries per page. Maximum is 100. Defaults to 20.
- **only_unmatched** (bool) - Optional - If set to `true`, only mutations that have not been automatically matched will be displayed. Defaults to `false`.

#### Header Parameters
- **X-Api-Key** (string) - Required - Your merchant API Key.

### Request Example
```bash
curl "https://api.bayar.digital/gateway/mutations?only_unmatched=true" \
  -H "X-Api-Key: pk_..."
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **message** (string) - A message indicating the status of the request.
- **data** (array) - An array of mutation objects.
  - **id** (uuid) - The ID of the mutation.
  - **device_id** (uuid) - The ID of the Android Worker that detected the mutation.
  - **title** (string/null) - The title of the transfer notification.
  - **body** (string/null) - The details of the notification.
  - **posted_at** (datetime) - The time of the transaction.
  - **amount_parsed** (int64) - The transfer amount.
  - **sender_parsed** (string/null) - The detected sender's name.
  - **type_parsed** (string/null) - The type of transaction (`CREDIT` or `DEBIT`).
  - **currency_parsed** (string/null) - The currency of the transaction (e.g., `IDR`).
  - **is_matched** (bool) - Whether the mutation has been matched to an invoice.
  - **matched_payment_id** (uuid/null) - The ID of the matched invoice.
  - **matched_payment_code** (string/null) - The code of the matched invoice.
  - **created_at** (datetime) - The time the mutation was detected by the system.
  - **device_name** (string/null) - The name of the Worker device.
  - **package_name** (string/null) - The package name of the banking application.
  - **app_name** (string/null) - The name of the banking application.
  - **app_version** (string/null) - The version of the banking application.
  - **account_number** (string/null) - The destination account number.
  - **account_name** (string/null) - The name of the account holder.
  - **bank_name** (string/null) - The name of the bank.
  - **bank_type** (string/null) - The type of bank transaction (`TRANSFER` or `QRIS`).
- **pagination** (object) - Pagination details.
  - **total** (integer) - Total number of mutations.
  - **count** (integer) - Number of mutations returned in this request.
  - **per_page** (integer) - Number of mutations per page.
  - **current_page** (integer) - The current page number.
  - **total_pages** (integer) - The total number of pages available.

#### Response Example
```json
{
  "success": true,
  "message": "ok",
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440020",
      "device_id": "660e8400-e29b-41d4-a716-446655440030",
      "title": "Transfer dari BUDI SANTOSO",
      "body": "BCA ke 1234567890 a/n PT Merchant Contoh",
      "posted_at": "2026-06-11T10:30:00Z",
      "amount_parsed": 50123,
      "sender_parsed": "BUDI SANTOSO",
      "type_parsed": "CREDIT",
      "currency_parsed": "IDR",
      "is_matched": false,
      "matched_payment_id": null,
      "matched_payment_code": null,
      "created_at": "2026-06-11T10:30:05Z",
      "device_name": "HP Kantor",
      "package_name": "com.bca",
      "app_name": "BCA Mobile",
      "app_version": "6.2.0",
      "account_number": "1234567890",
      "account_name": "PT Merchant Contoh",
      "bank_name": "Bank Central Asia",
      "bank_type": "TRANSFER"
    }
  ],
  "pagination": {
    "total": 50,
    "count": 1,
    "per_page": 20,
    "current_page": 1,
    "total_pages": 3
  }
}
```

#### Error Response
- **403** `tenant_api_key_required`: API Key is invalid.
- **500** `internal_error`: Server error, please try again.

```json
{
  "success": false,
  "code": "internal_error",
  "message": "internal server error"
}
```
```

--------------------------------

### Get Payment Accounts Request

Source: https://docs.bayar.digital/llms-full.txt

Use this cURL command to request a list of available payment accounts. Ensure you include your API Key in the header.

```bash
curl https://api.bayar.digital/gateway/accounts \
  -H "X-Api-Key: pk_..."
```

--------------------------------

### Get Webhook Detail

Source: https://docs.bayar.digital/llms-full.txt

Retrieves the details of a specific webhook by its ID.

```APIDOC
## GET /tenant/callbacks/:id

### Description
Retrieves the details of a specific webhook by its ID.

### Method
GET

### Endpoint
/tenant/callbacks/:id
```

--------------------------------

### Get Payment Mutations

Source: https://docs.bayar.digital/payment-mutations

Fetches a list of payment mutations. You can filter by unmatched transactions and paginate the results.

```APIDOC
## GET /gateway/mutations

### Description
Retrieves a list of incoming mutations or transactions from your account that were successfully detected by the Android Worker. This data is useful for reconciliation and manual transaction matching.

### Method
GET

### Endpoint
`https://api.bayar.digital/gateway/mutations`

### Parameters
#### Query Parameters
- **page** (integer) - Optional - Defaults to 1. The page number of the data to display.
- **per_page** (integer) - Optional - Defaults to 20. The number of data entries to retrieve per page (maximum 100).
- **only_unmatched** (bool) - Optional - Defaults to `false`. Filter to display only mutations that have not been automatically matched.

### Headers
#### Required Headers
- **X-Api-Key** (string) - Required - Your merchant API Key

### Request Example
```bash
curl "https://api.bayar.digital/gateway/mutations?only_unmatched=true" \
  -H "X-Api-Key: pk_..."
```

### Response
#### Success Response (200)
- **id** (uuid) - Unique ID of the mutation.
- **device_id** (uuid) - ID of the Android Worker device that detected the transaction.
- **title** (string/null) - Title of the incoming transfer notification from the bank application.
- **body** (string/null) - Detailed content of the transfer notification.
- **posted_at** (datetime) - The time the transaction was recorded by the bank.
- **amount_parsed** (int64) - The successfully extracted transfer amount.
- **sender_parsed** (string/null) - The successfully extracted sender name.
- **type_parsed** (string/null) - Type of mutation: `CREDIT` (funds in) / `DEBIT` (funds out).
- **currency_parsed** (string/null) - Currency (e.g., `IDR`).
- **is_matched** (bool) - Indicator of whether this mutation has been matched with an invoice.
- **matched_payment_id** (uuid/null) - The ID of the invoice matched with this mutation.
- **matched_payment_code** (string/null) - The code of the invoice matched with this mutation.
- **created_at** (datetime) - The time the mutation was detected and recorded by the server system.
- **device_name** (string/null) - Name of the device.

```

--------------------------------

### Failed Response for Payment Accounts

Source: https://docs.bayar.digital/llms-full.txt

These JSON examples illustrate potential error responses when requesting payment accounts, such as a missing API key or an internal server error.

```json
{
  "success": false,
  "code": "tenant_api_key_required",
  "message": "tenant api key required"
}
```

```json
{
  "success": false,
  "code": "internal_error",
  "message": "internal server error"
}
```

--------------------------------

### Get Invoice by Payment Code

Source: https://docs.bayar.digital/llms-full.txt

Use this cURL command to retrieve invoice details by providing the payment code in the URL and your API key in the header.

```bash
curl https://api.bayar.digital/gateway/payments/INV-2026-0001 \
  -H "X-Api-Key: pk_..."
```

--------------------------------

### Successful Payment Creation Response

Source: https://bayar.digital/

This is an example of a successful response (201 Created) when a payment is created via the API. It includes details of the created payment, such as its unique ID, status, and checkout URL.

```json
{
"success": true,
"message": "created",
"data": {
"id": "019ce681-4321-7abc-700001",
"payment_code": "INV-2024-001",
"amount_original": 150000,
"amount_unique": 3,
"amount_total": 150003,
"status": "PENDING",
"expires_at": "2026-03-14T11:00:00Z",
"checkout_url": "/checkout/019ce681-4321-7abc-700001"
}
}
```

--------------------------------

### Get Payment Accounts

Source: https://docs.bayar.digital/payment-account

Retrieves a list of available payment accounts. This is a prerequisite for creating payments, as the `account_id` from the response is used in the Payment Create endpoint. Ensure the account is active (`account_active = true`) and has available quota (`account_quota > 0`) before proceeding.

```APIDOC
## GET /gateway/accounts

### Description
Endpoint ini digunakan untuk mengambil daftar rekening Anda yang tersedia sebagai tujuan pembayaran. Sebelum membuat invoice, Anda perlu memastikan ketersediaan rekening tujuan. Gunakan nilai `account_id` dari response endpoint ini sebagai parameter saat melakukan [Payment Create](/payment-create).

### Method
GET

### Endpoint
`https://api.bayar.digital/gateway/accounts`

### Parameters
#### Header
- **X-Api-Key** (string) - Required - API Key merchant Anda

### Request Example
```bash
curl -X GET https://api.bayar.digital/gateway/accounts \
  -H "X-Api-Key: pk_..."
```

### Response
#### Success Response (200 OK)
- **account_id** (uuid) - Penting: Gunakan nilai ini sebagai `account_id` saat create payment
- **account_number** (string) - Nomor rekening atau QRIS NMID
- **account_name** (string) - Nama pemilik rekening
- **account_min_amount** (int64) - Minimal nominal pembayaran
- **account_max_amount** (int64 / null) - Maksimal nominal pembayaran (`null` = tak terbatas)
- **account_active** (bool) - Status keaktifan rekening
- **account_quota** (int) - Sisa kuota hari
- **channel_id** (uuid) - ID channel dari sistem perbankan
- **channel_type** (string) - `TRANSFER` (transfer bank) atau `QRIS`
- **channel_name** (string) - Nama bank atau institusi finansial
- **app_id** (uuid) - ID aplikasi mobile banking
- **app_name** (string) - Nama aplikasi mobile banking
- **app_package** (string) - Package name dari aplikasi mobile banking

#### Response Example
(Example response structure would go here if provided in source)
```

--------------------------------

### Initiate Payment

Source: https://bayar.digital/

Send payment data to the bayar.digital system to initiate a payment process. The system will monitor the status of the payment.

```APIDOC
## POST /payments

### Description
Initiates a payment process by sending payment details to the bayar.digital API. The system will then monitor the payment status.

### Method
POST

### Endpoint
/payments

### Request Body
- **payment_data** (object) - Required - The data related to the payment.
  - **amount** (integer) - Required - The amount of the payment.
  - **reference_id** (string) - Required - A unique identifier for the payment.

### Request Example
```json
{
  "payment_data": {
    "amount": 350003,
    "reference_id": "INV-2024-0891"
  }
}
```

### Response
#### Success Response (200)
- **status** (string) - The current status of the payment.
- **fee** (integer) - The fee associated with the payment.
- **amount** (integer) - The total amount of the payment.
- **ref** (string) - The reference ID of the payment.

#### Response Example
```json
{
  "status": "PAID",
  "fee": 0,
  "amount": 350003,
  "ref": "INV-2024-0891"
}
```
```

--------------------------------

### Environment Variables for Bayar Digital API

Source: https://docs.bayar.digital/llms-full.txt

Store your API key and base URL in environment variables for secure access. Avoid hardcoding sensitive information.

```bash
# .env
BAYAR_DIGITAL_API_KEY=pk_550e8400e29b41d4a716446655440000...
BAYAR_DIGITAL_BASE_URL=https://api.bayar.digital
```

--------------------------------

### Get Webhook History

Source: https://docs.bayar.digital/llms-full.txt

Retrieves the history of all webhooks sent to the tenant.

```APIDOC
## GET /tenant/callbacks

### Description
Retrieves the history of all webhooks sent to the tenant.

### Method
GET

### Endpoint
/tenant/callbacks
```

--------------------------------

### GET /gateway/accounts

Source: https://docs.bayar.digital/llms-full.txt

Retrieves a list of active payment accounts. The `account_id` from the response is crucial for creating payments.

```APIDOC
## GET /gateway/accounts

### Description
Retrieves a list of active payment accounts that can be used as payment destinations. The `account_id` obtained from this endpoint is required for the Payment Create operation.

### Method
GET

### Endpoint
/gateway/accounts

### Headers
- **X-Api-Key** (string) - Required - Merchant API Key

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **message** (string) - A message indicating the status of the request.
- **data** (array) - An array of payment account objects.
  - **account_id** (uuid) - The ID of the payment account. Use this for creating payments.
  - **account_number** (string/null) - The account number. For QRIS, this is the merchant label/name.
  - **account_name** (string/null) - The account holder's name.
  - **account_min_amount** (int64) - The minimum payment amount.
  - **account_max_amount** (int64/null) - The maximum payment amount (null indicates unlimited).
  - **account_active** (boolean) - The active status of the account.
  - **account_quota** (int) - The remaining quota days.
  - **channel_id** (uuid) - The ID of the bank channel.
  - **channel_type** (string) - The type of channel (`TRANSFER` or `QRIS`).
  - **channel_name** (string/null) - The name of the bank.
  - **app_id** (uuid/null) - The ID of the mobile banking application.
  - **app_name** (string/null) - The name of the mobile banking application.
  - **app_package** (string/null) - The Android package name for the mobile banking application.

#### Response Example (Success)
{
  "success": true,
  "message": "ok",
  "data": [
    {
      "account_id": "550e8400-e29b-41d4-a716-446655440000",
      "account_number": "1234567890",
      "account_name": "PT Merchant Contoh",
      "account_min_amount": 10000,
      "account_max_amount": 10000000,
      "account_active": true,
      "account_quota": 30,
      "channel_id": "660e8400-e29b-41d4-a716-446655440001",
      "channel_type": "TRANSFER",
      "channel_name": "Bank Central Asia",
      "app_id": "990e8400-e29b-41d4-a716-446655440002",
      "app_name": "BCA Mobile",
      "app_package": "com.bca"
    },
    {
      "account_id": "550e8400-e29b-41d4-a716-446655440003",
      "account_number": "QRIS-001",
      "account_name": "PT Merchant Contoh",
      "account_min_amount": 1000,
      "account_max_amount": 5000000,
      "account_active": true,
      "account_quota": 30,
      "channel_id": "660e8400-e29b-41d4-a716-446655440004",
      "channel_type": "QRIS",
      "channel_name": "QRIS",
      "app_id": null,
      "app_name": null,
      "app_package": null
    }
  ]
}

#### Error Response
- **tenant_api_key_required** (403) - API Key is invalid.
- **internal_error** (500) - Server error, please try again.

#### Response Example (Error)
{
  "success": false,
  "code": "tenant_api_key_required",
  "message": "tenant api key required"
}

```
```

--------------------------------

### Created Response Format

Source: https://docs.bayar.digital/llms-full.txt

This format is returned for successful resource creation requests.

```json
{
  "success": true,
  "message": "created",
  "data": { ... }
}
```

--------------------------------

### Account Not Owned Error

Source: https://docs.bayar.digital/status-code

This error occurs if the provided `account_id` is incorrect. Retrieve a valid ID using `GET /gateway/accounts`.

```text
`account_not_owned`

403

`account_id` salah. Ambil ID yang sah melalui `GET /gateway/accounts`.

Tidak
```

--------------------------------

### CANCELLED Status Webhook Payload

Source: https://docs.bayar.digital/llms-full.txt

Example of a webhook payload when a payment status changes to CANCELLED. The 'paid_at' field is absent in this status.

```json
{
  "payment_id": "660e8400-e29b-41d4-a716-446655440010",
  "payment_code": "INV-2026-0001",
  "status": "CANCELLED",
  "amount": 50123
}
```

--------------------------------

### EXPIRED Status Webhook Payload

Source: https://docs.bayar.digital/llms-full.txt

Example of a webhook payload when a payment status changes to EXPIRED. The 'paid_at' field is absent in this status.

```json
{
  "payment_id": "660e8400-e29b-41d4-a716-446655440010",
  "payment_code": "INV-2026-0001",
  "status": "EXPIRED",
  "amount": 50123
}
```

--------------------------------

### Successful Channel Instructions Response

Source: https://docs.bayar.digital/llms-full.txt

This JSON object represents a successful response when retrieving payment instructions. It includes the channel ID and a list of steps with titles and content.

```json
{
  "success": true,
  "message": "ok",
  "data": {
    "channel_id": "660e8400-e29b-41d4-a716-446655440001",
    "instructions": [
      {
        "step": 1,
        "title": "Buka aplikasi BCA Mobile",
        "content": "Login ke aplikasi BCA Mobile Anda"
      },
      {
        "step": 2,
        "title": "Pilih m-Transfer",
        "content": "Pilih menu m-Transfer > ke Rekening BCA Virtual Account"
      },
      {
        "step": 3,
        "title": "Masukkan nominal",
        "content": "Transfer sesuai total yang tertera"
      }
    ]
  }
}
```

--------------------------------

### Create Payment

Source: https://bayar.digital/

This endpoint allows merchants to create a new payment. It requires an API Key for authentication and accepts payment details such as code, amount, expiration, customer name, and email. The response includes details of the created payment, such as its unique ID, status, and checkout URL.

```APIDOC
## POST /gateway/payments

### Description
Creates a new payment transaction. This endpoint is used by merchants to initiate a payment request.

### Method
POST

### Endpoint
https://api.bayar.digital/gateway/payments

### Parameters
#### Headers
- **X-Api-Key** (string) - Required - The API key for merchant authentication.
- **Content-Type** (string) - Required - Must be set to 'application/json'.

#### Request Body
- **payment_code** (string) - Required - The unique identifier for the payment (e.g., invoice number).
- **amount_original** (number) - Required - The original amount of the payment.
- **expired_at** (integer) - Required - The Unix timestamp when the payment expires.
- **customer_name** (string) - Optional - The name of the customer.
- **customer_email** (string) - Optional - The email address of the customer.

### Request Example
{
  "payment_code": "INV-2024-001",
  "amount_original": 150000,
  "expired_at": 1735689600000,
  "customer_name": "Budi Santoso",
  "customer_email": "[email protected]"
}

### Response
#### Success Response (201 Created)
- **success** (boolean) - Indicates if the payment creation was successful.
- **message** (string) - A message indicating the result of the operation.
- **data** (object) - Contains the details of the created payment:
  - **id** (string) - The unique ID of the payment.
  - **payment_code** (string) - The payment code provided in the request.
  - **amount_original** (number) - The original amount of the payment.
  - **amount_unique** (number) - A small unique amount added for reconciliation.
  - **amount_total** (number) - The total amount including the unique amount.
  - **status** (string) - The current status of the payment (e.g., 'PENDING').
  - **expires_at** (string) - The ISO 8601 formatted expiration timestamp.
  - **checkout_url** (string) - The URL for the payment checkout page.

#### Response Example
{
  "success": true,
  "message": "created",
  "data": {
    "id": "019ce681-4321-7abc-700001",
    "payment_code": "INV-2024-001",
    "amount_original": 150000,
    "amount_unique": 3,
    "amount_total": 150003,
    "status": "PENDING",
    "expires_at": "2026-03-14T11:00:00Z",
    "checkout_url": "/checkout/019ce681-4321-7abc-700001"
  }
}
```

--------------------------------

### Send Payment Data via API

Source: https://bayar.digital/

Initiate a payment by sending payment data to the bayar.digital API. This is the first step in the payment process.

```HTTP
POST /payments
```

--------------------------------

### Successful Response for Get Invoice

Source: https://docs.bayar.digital/llms-full.txt

This JSON structure represents a successful retrieval of invoice details, including payment information, customer details, and account information.

```json
{
  "success": true,
  "message": "ok",
  "data": {
    "payment_id": "660e8400-e29b-41d4-a716-446655440010",
    "payment_code": "INV-2026-0001",
    "payment_amount": 50000,
    "payment_unique": 123,
    "payment_total": 50123,
    "payment_status": "PAID",
    "payment_expired_at": "2026-10-11T12:00:00Z",
    "payment_updated_at": "2026-06-11T10:05:00Z",
    "payment_webhook_url": "https://yourserver.com/webhooks/bayar",
    "payment_checkout_url": "https://bayar.digital/checkout/660e8400-e29b-41d4-a716-446655440010",
    "payment_return_url": "https://yourserver.com/orders/INV-2026-0001",
    "customer_name": "Budi Santoso",
    "customer_email": "budi@example.com",
    "customer_phone": "081234567890",
    "customer_orders": [
      {
        "name": "Produk A",
        "price": 50000,
        "quantity": 1,
        "subtotal": 50000
      }
    ],
    "account_id": "550e8400-e29b-41d4-a716-446655440000",
    "account_number": "1234567890",
    "account_name": "PT Merchant Contoh",
    "channel_id": "660e8400-e29b-41d4-a716-446655440001",
    "channel_name": "Bank Central Asia",
    "channel_type": "TRANSFER",
    "channel_instructions": [],
    "is_manual_match": false,
    "manual_matched_mutation_id": null
  }
}
```

--------------------------------

### Create Payment

Source: https://docs.bayar.digital/payment-create

Initiates the creation of a payment. Handles potential conflicts and internal server errors.

```APIDOC
## POST /payments

### Description
Creates a new payment. This endpoint is used to initiate a payment transaction. It handles potential conflicts such as duplicate payment codes or unique amount issues, as well as internal server errors.

### Method
POST

### Endpoint
/payments

### Parameters
#### Request Body
- **customer_name** (string) - Required - The name of the customer.
- **amount** (number) - Required - The payment amount.
- **payment_code** (string) - Optional - A unique identifier for the payment. If not provided, the system will generate one.

### Request Example
```json
{
  "customer_name": "John Doe",
  "amount": 10000,
  "payment_code": "INV-12345"
}
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the operation was successful.
- **code** (string) - The response code.
- **message** (string) - A message describing the response.
- **data** (object) - Contains payment details if successful.

#### Response Example
```json
{
  "success": true,
  "code": "payment_created",
  "message": "Payment created successfully",
  "data": {
    "payment_id": "pay_abc123",
    "payment_code": "INV-12345",
    "amount": 10000,
    "status": "pending"
  }
}
```

### Error Handling
#### Validation Error (400)
- **success** (boolean) - false
- **code** (string) - "validation_error"
- **message** (string) - "validation error"
- **errors** (object) - Contains validation errors for specific fields.
  - **customer_name** (string) - "customer name is required"

#### Conflict (409) - Payment Code
- **success** (boolean) - false
- **code** (string) - "payment_code_conflict"
- **message** (string) - "payment code already used (Idempotency conflict)"

#### Conflict (409) - Unique Amount
- **success** (boolean) - false
- **code** (string) - "unique_amount_conflict"
- **message** (string) - "unique amount conflict"

#### Internal Server Error (500)
- **success** (boolean) - false
- **code** (string) - "internal_error"
- **message** (string) - "An internal error occurred on the server, please try again in a moment."
```

--------------------------------

### Create Payment Request - cURL

Source: https://docs.bayar.digital/payment-create

Use this cURL command to send a POST request to the Bayar.Digital Gateway API to create a new payment. Ensure you replace 'pk_...' with your actual API key and fill in the customer and order details.

```bash
curl -X POST https://api.bayar.digital/gateway/payments \
  -H "X-Api-Key: pk_..." \
  -H "Content-Type: application/json" \
  -d '{ \
    "account_id": "550e8400-e29b-41d4-a716-446655440000", \
    "payment_code": "INV-2026-0001", \
    "payment_amount": 50000, \
    "payment_expired_at": "2026-10-11T12:00:00Z", \
    "customer_name": "Budi Santoso", \
    "customer_email": "[email protected]", \
    "customer_phone": "081234567890", \
    "customer_orders": [ \
      { \
        "sku": "SKU001", \
        "name": "Produk A", \
        "price": 50000, \
        "quantity": 1, \
        "subtotal": 50000 \
      } \
    ] \
  }'
```

--------------------------------

### Full Webhook Handler (Node.js / Express)

Source: https://docs.bayar.digital/webhook

A complete Express.js endpoint for handling Bayar Digital webhooks. Includes signature verification and basic request handling structure.

```javascript
app.post('/webhooks/bayar', express.json(), (req, res) => {
  // 1. Verifikasi signature
  if (process.env.WEBHOOK_SECRET) {
    const expected = crypto
      .createHmac('sha256', process.env.WEBHOOK_SECRET)
      .update(JSON.stringify(req.body))
      .digest('hex');
    if (req.headers['x-signature'] !== expected) {
      return res.status(401).json({ status: 'invalid signature' });
    }
  }

  const { payment_id, payment_code, status, amount } = req.body;

  // 2. Cari order di database
  // 3. Validasi amount
  // 4. Update status (pastikan penanganan bersifat idempotent)

  res.json({ status: 'received' });
});
```