### Sample HTTP Request for X Signature Computation Example

Source: https://www.billplz.com/api#introduction/index

An example HTTP GET request from Billplz's X Signature Redirect URL feature, specifically used as input for demonstrating the step-by-step signature computation.

```HTTP
GET {REDIRECT_URL}?billplz[id]=zq0tm2wc&billplz[paid]=true&billplz[paid_at]=2018-09-27%2015%3A15%3A09%20%2B0800&billplz[x_signature]=4aab095fe5a39b1d534500988f9a0cb085cd1b6d5bbb55dd4e02ea6fa102b47b
```

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

### Billplz X Signature Redirect URL HTTP Request Example

Source: https://www.billplz.com/api#introduction/index

Example of an HTTP GET request sent by Billplz to the `redirect_url`, including various bill parameters and the `x_signature` for verification.

```HTTP
GET {REDIRECT_URL}?billplz[id]=ifpgaa&billplz[paid]=true&billplz[paid_at]=2017-01-04%2013%3A10%3A45%20%2B0800&billplz[x_signature]=76de0ad8cc23706d694fd81c9027b8e3ae169e0880d75e1e123c5832c82bf707
```

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

### Billplz API Rate Limit: Example GET Request

Source: https://www.billplz.com/api#introduction/index

Demonstrates how to make a GET request to the Billplz API using curl, including basic authentication with an API key.

```curl
curl https://www.billplz.com/api/v3/bills/8X0Iyzaw \
  -u 73eb57f0-7d4e-42b9-a544-aeac6e4b0f81:
```

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

### Example JSON Response for Get Collection Index

Source: https://www.billplz.com/api#introduction/index

Illustrates the JSON structure returned when successfully retrieving a list of collections. The response includes collection details and pagination information.

```json
{
  "collections": [
    {
      "id": "inbmmepb",
      "title": "My First API Collection",
      "logo": {
        "thumb_url": null,
        "avatar_url": null
      },
      "split_header": false,
      "split_payments": [],
      "status": "active"
    }
  ],
  "page": 1
}
```

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

### Billplz Server-Side Callback HTTP POST Request Example

Source: https://www.billplz.com/api#introduction/index

An example of the HTTP POST request sent by Billplz to the configured `callback_url`. The request body is `application/x-www-form-urlencoded` and contains payment order details along with a checksum for verification.

```HTTP
POST /webhook/ HTTP/1.1
Connection: close
Host: 127.0.0.1
Content-Length: 346
Content-Type: application/x-www-form-urlencoded

  id="0b924e37-7418-4d17-b234-8de424dc48e5"
  &payment_order_collection_id="0c78f8c6-5bd3-4663-8c08-9e2c805418a2"
  &bank_code="PHBMMYKL"
  &bank_account_number="1234567890"
  &name="Michae Yap"
  &description="Maecenas eu placerat ante."
  &email="[email protected]"
  &status="refunded"
  &notification="false"
  &recipient_notification="true"
  &reference_id="My first payment order"
  &display_name=""
  &total=50000
  &epoch=1681895891
  &checksum="2720f5ef16c7d04677829789fb74bccb08b90041e4e27916d85cb6fbbece58a7ab48538e8b62bcedab3b236bd38e6517860b593b8fe9bfa77bed979994f2ca1a"
```

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

### Billplz Server-Side Callback Request Example

Source: https://www.billplz.com/api#introduction/index

An example of the HTTP POST request sent by Billplz to the configured `callback_url` upon payment completion. The request body contains URL-encoded form data with details about the bill and payment status.

```HTTP
POST /webhook/ HTTP/1.1
Connection: close
Host: 127.0.0.1
Content-Length: 346
Content-Type: application/x-www-form-urlencoded

  id="W_79pJDk"
  &collection_id="599"
  &paid="true"
  &state="paid"
  &amount="200"
  &paid_amount="0"
  &due_at="2020-12-31"
  &email="[email protected]"
  &mobile="+60112223333"
  &name="MICHAEL API"
  &metadata[id]="9999"
  &metadata[description]="This is to test bill creation"
  &url="http://billplz.dev/bills/W_79pJDk"
  &paid_at="2015-03-09 16:23:59 +0800"

```

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

### Example Billplz Open Collection Response Body

Source: https://www.billplz.com/api#introduction/index

An example JSON object illustrating the structure and typical values returned by the Billplz API when successfully fetching an open collection.

```JSON
{
  "id": "0pp87t_6",
  "title": "MY FIRST API OPEN COLLECTION",
  "description": "Maecenas eu placerat ante.",
  "reference_1_label": null,
  "reference_2_label": null,
  "email_link": null,
  "amount": 299,
  "fixed_amount": true,
  "tax": null,
  "fixed_quantity": true,
  "payment_button": "pay",
  "photo": {
    "retina_url": null,
    "avatar_url": null
  },
  "split_payment": {
    "email": null,
    "fixed_cut": null,
    "variable_cut": null,
    "split_header": false
  },
  "url": "https://www.billplz.com/0pp87t_6",
  "status": "active"
}
```

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

### Sample Billplz Callback HTTP POST Request

Source: https://www.billplz.com/api#introduction/index

Provides an example of an HTTP POST request body sent by Billplz to a callback URL, illustrating the structure and typical values of the parameters, including the `x_signature`.

```HTTP
POST {CALLBACK_URL}

with POST body,
{:id=>"zq0tm2wc", :collection_id=>"yhx5t1pp", :paid=>true, :state=>"paid", :amount=>100, :paid_amount=>100, :due_at=>"2018-9-27", :email=>"[[email\u00a0protected]](/cdn-cgi/l/email-protection)", :mobile=>nil, :name=>"TESTER", :url=>"http://www.billplz-sandbox.com/bills/zq0tm2wc", :paid_at=>"2018-09-27 15:15:09 +0800", :x_signature=>"0fe0a20b8d557eeae570377783d062a3816a9ea80f368860bacfa7ec3ca4d00e"}
```

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

### Example JSON Response for Creating an Open Collection

Source: https://www.billplz.com/api#introduction/index

Illustrates the JSON structure returned upon successful creation of an open collection. The response includes the collection's ID, URL, and other attributes.

```json
{
  "id": "0pp87t_6",
  "title": "MY FIRST API OPEN COLLECTION",
  "description": "Maecenas eu placerat ante.",
  "reference_1_label": null,
  "reference_2_label": null,
  "email_link": null,
  "amount": 299,
  "fixed_amount": true,
  "tax": null,
  "fixed_quantity": true,
  "payment_button": "pay",
  "photo": {
    "retina_url": null,
    "avatar_url": null
  },
  "split_header": false,
  "split_payments": [],
  "url": "https://www.billplz.com/0pp87t_6",
  "redirect_uri": null
}
```

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

### Billplz API: X Signature Callback URL Example (Transaction Completed)

Source: https://www.billplz.com/api#introduction/index

Another example of a server-side POST request from Billplz to the callback_url, demonstrating additional transaction details like 'transaction_id' and 'transaction_status' for a completed payment.

```HTTP
POST /webhook/ HTTP/1.1
Connection: close
Host: 127.0.0.1
Content-Length: 376
Content-Type: application/x-www-form-urlencoded

  id="pjpetpdy"
  &collection_id="bvgo7ueb"
  &paid="true"
  &state="paid"
  &amount="100"
  &paid_amount="100"
  &due_at="2020-8-7"
  &email="[email protected]"
  &mobile=""
  &name="WILL"
  &url="http://www.billplz.test:3000/bills/pjpetpdy"
  &paid_at="2020-08-07 15:08:19 +0800"
  &transaction_id="711044E05418"
  &transaction_status="completed"
  &x_signature="b5ca81d0f1b87ab3b17580236735c68af92936de9aaa588751a4371ac4944a56"
```

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

### Retrieve Available Payment Methods

Source: https://www.billplz.com/api#introduction/index

This snippet initiates the process of retrieving all available payment methods that can be enabled or disabled for a collection. The provided `curl` example shows the start of the request.

```curl
curl 
```

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

### Create an Open Collection using cURL

Source: https://www.billplz.com/api#introduction/index

Example cURL command to create a new open collection (payment form) with a title, description, and fixed amount. This demonstrates how to send POST data for collection creation.

```shell
# Creates an open collection
curl https://www.billplz.com/api/v4/open_collections \
  -u 73eb57f0-7d4e-42b9-a544-aeac6e4b0f81: \
  -d title="My First API Open Collection" \
  -d description="Maecenas eu placerat ante." \
  -d amount=299
```

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

### Example Request: Create Duitnow::Pay AutoDebit with cURL

Source: https://www.billplz.com/api#introduction/index

Demonstrates how to use cURL to initiate a Duitnow::Pay AutoDebit. The request includes authentication, the target API endpoint, and form data parameters such as `consent_id`, `bill_id`, `epoch`, and the calculated `checksum`.

```curl
# Create an Duitnow::Pay AutoDebit
curl https://www.billplz.com/api/v5/duitnow/pay/auto_debits \
  -u 73eb57f0-7d4e-42b9-a544-aeac6e4b0f81: \
  -d consent_id="29f408bf-c569-4455-a134-1331d9c2bf01" \
  -d bill_id="ad8diu187sbkj" \
  -d epoch=1668149595 \
  -d checksum="92987e17459c6e488b83c02dea1693615011fee049d88a3eb9745538f191e323ac4f067571aa8abc335075470b06693994443b52b78be22fbd12b44cb699b265"
```

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

### Example JSON Response for Get Collection Index with Paging

Source: https://www.billplz.com/api#introduction/index

Illustrates the JSON structure returned when retrieving a list of collections with pagination. The `page` attribute reflects the requested page number.

```json
{
  "collections": [
    {
      "id": "inbmmepb",
      "title": "My First API Collection",
      "logo": {
        "thumb_url": null,
        "avatar_url": null
      },
      "split_header": false,
      "split_payments": [],
      "status": "active"
    }
  ],
  "page": 2
}
```

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

### Billplz Callback HTTP Request with Ruby-like POST Body

Source: https://www.billplz.com/api#introduction/index

An example of an HTTP POST request from a payment order callback, illustrating the request structure and a POST body formatted using Ruby-like hash syntax for the payment order object.

```HTTP
POST {CALLBACK_URL} with POST body

{:id=>"0b924e37-7418-4d17-b234-8de424dc48e5",:payment_order_collection_id=>"0c78f8c6-5bd3-4663-8c08-9e2c805418a2",:bank_code=>"PHBMMYKL",:bank_account_number=>"1234567890",:name=>"Michae Yap",:description=>"Maecenas eu placerat ante.",:email=>"[[email protected]](/cdn-cgi/l/email-protection)",:status=>"refunded",:notification=>true,:recipient_notification=>true,:reference_id=>"My first payment order",:display_name=>nil,:total=>500000,:epoch=>1681895891, :checksum=>"2720f5ef16c7d04677829789fb74bccb08b90041e4e27916d85cb6fbbece58a7ab48538e8b62bcedab3b236bd38e6517860b593b8fe9bfa77bed979994f2ca1a"}
```

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

### Billplz API: X Signature Callback URL Example (Payment Success)

Source: https://www.billplz.com/api#introduction/index

Example of a server-side POST request sent by Billplz to the callback_url upon successful payment completion. This request includes bill details and an 'x_signature' for data integrity verification using HMAC-SHA256.

```HTTP
POST /webhook/ HTTP/1.1
Connection: close
Host: 127.0.0.1
Content-Length: 346
Content-Type: application/x-www-form-urlencoded

  id="W_79pJDk"
  &collection_id="599"
  &paid="true"
  &state="paid"
  &amount="200"
  &paid_amount="0"
  &due_at="2020-12-31"
  &email="[email protected]"
  &mobile="+60112223333"
  &name="MICHAEL API"
  &url="http://billplz.dev/bills/W_79pJDk"
  &paid_at="2015-03-09 16:23:59 +0800"
  &x_signature="f0ff6c564f98d5403e2b26fbd3d45309c76eb68d8c5bcda0d48b541c3502a396"
```

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

### Retrieve List of Billplz Open Collections (Curl)

Source: https://www.billplz.com/api#introduction/index

Initiates a cURL request to fetch a paginated list of all open collection records from the Billplz API. The example is incomplete but shows the start of the command.

```Shell
curl 
```

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

### Retrieve Collection Index using cURL

Source: https://www.billplz.com/api#introduction/index

Example cURL command to fetch a list of collections. This demonstrates basic authentication required for API access.

```shell
# Get collection index
curl https://www.billplz.com/api/v4/collections \
  -u 73eb57f0-7d4e-42b9-a544-aeac6e4b0f81:
```

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

### API Reference for Get Open Collection Index Endpoint

Source: https://www.billplz.com/api#introduction/index

Detailed API documentation for the GET /api/v4/open_collections endpoint, including the HTTP method, base URL, and available optional query parameters for pagination and status filtering.

```APIDOC
GET https://www.billplz.com/api/v4/open_collections

OPTIONAL ARGUMENTS:
  page: Up to 15 open collections will be returned in a single API call per specified page. Default to **1** if not present.
  status: Parameter to filter open collection's status, valid value are `active` and `inactive`.
```

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

### Create Bill with Direct Payment Gateway via cURL

Source: https://www.billplz.com/api#introduction/index

This cURL example demonstrates how to create a new bill using the Billplz API, including parameters for collection ID, description, amount, and specific reference_1_label and reference_1 values to enable direct payment gateway bypass.

```curl
# Creates a bill for RM 2.00 with reference_1_label and reference_1
curl https://www.billplz.com/api/v3/bills \
  -u 73eb57f0-7d4e-42b9-a544-aeac6e4b0f81: \
  -d collection_id="inbmmepb" \
  -d description="Maecenas eu placerat ante." \
  -d email="[email protected]" \
  -d name="Sara" \
  -d amount="200" \
  -d reference_1_label="Bank Code" \
  -d reference_1="BP-FKR01" \
  -d callback_url="http://example.com/webhook/"
```

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

### Duitnow::Pay Consent Failed Response Example

Source: https://www.billplz.com/api#introduction/index

This JSON object shows an example of a failed response from the Billplz API for a Duitnow::Pay consent request. It includes the consent ID, failed status, merchant reference, customer details, consent dates, bank code, maximum amount, frequency, callback URL, and an error object detailing the type and message of the failure.

```json
{
  "id": "29f408bf-c569-4455-a134-1331d9c2bf01",
  "status": "failed",
  "merchant_ref": "C002",
  "customer_name": "Kevin",
  "effective_date": "2025-03-04",
  "expiry_date": "2025-12-31",
  "bank_code": "DNRET-CIBBMYKL",
  "max_amount": 100000,
  "frequency": "01",
  "callback_url": "https://example.com/callback",
  "error": {
    "type": "CREATED",
    "message": {
        "message": "U224",
        "data": {
            "endToEndId": "20250313M0043139811OBW00011694",
            "issuer": "PayNet Simulator Bank"
        }
    }
  }
}
```

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

### Example JSON Response for Open Collection Creation

Source: https://www.billplz.com/api#introduction/index

This JSON object represents a successful response after creating an open collection via the Billplz API. It includes details such as the collection ID, title, description, reference labels, amount, tax, payment button, photo URLs, split payment details, and redirect URI.

```json
{
  "id": "0pp87t_6",
  "title": "MY FIRST API OPEN COLLECTION",
  "description": "Maecenas eu placerat ante.",
  "reference_1_label": "ID No",
  "reference_2_label": "First Name",
  "email_link": "http://www.test.com",
  "amount": null,
  "fixed_amount": false,
  "tax": 1,
  "fixed_quantity": false,
  "payment_button": "buy",
  "photo": {
    "retina_url": "https://sample.net/assets/uploadPhoto.png",
    "avatar_url": "https://sample.net/assets/uploadPhoto.png"
  },
  "split_header": true,
  "split_payments": [
    {
      "email": "[email\u00a0protected]",
      "fixed_cut": null,
      "variable_cut": 20,
      "stack_order": 0
    }
  ],
  "url": "https://www.billplz.com/0pp87t_6",
  "redirect_uri": "http://www.test.com"
}
```

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

### Billplz API: Basic Redirect URL Parameters

Source: https://www.billplz.com/api#introduction/index

Parameters included in the GET request to the redirect_url.

```APIDOC
GET {REDIRECT_URL}
  Parameters:
    billplz[id]:
      Type: string
      Description: ID that represents the bill.
```

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

### Example Response: Successful Duitnow::Pay AutoDebit Creation

Source: https://www.billplz.com/api#introduction/index

Illustrates the JSON response received upon successful creation of a Duitnow::Pay AutoDebit. It includes the unique AutoDebit ID, transaction status, status code, issuer details, and nested objects for the associated consent and bill, along with their respective IDs.

```json
{
  "id": "cc92738f-dfda-4969-91dc-22a44afc7e26",
  "status": "success",
  "status_code": "U000",
  "issuer": "DNRET-CIBBMYKL",
  "consent": {
    "id": "29f408bf-c569-4455-a134-1331d9c2bf01"
  },
  "bill": {
    "id": "ad8diu187sbkj",
    "transaction": {
      "id": "U129ASIDUH12CATC"
    }
  }
}
```

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

### Billplz Callback Verification Steps and Data Format

Source: https://www.billplz.com/api#introduction/index

Outlines the process for verifying Billplz callbacks using HMAC-SHA512. It specifies the strict order of keys for formatting the raw string and provides examples of the raw string, XSignature key, and the expected generated checksum value for verification.

```APIDOC
1. Format the raw_string with only the values of the following keys in strict order:
   object_keys: [:id, :bank_account_number, :status, :total, :reference_id, :epoch]
   raw_string: "0b924e37-7418-4d17-b234-8de424dc48e51234567890refunded500000My first payment order1681895891"

2. Digest the raw_string together with your account XSignature key using HMAC_SHA512:
   example_XSignature: "S-R5t3Uw6SrwXNWyZV-naVHg"
   generated_checksum_value: "2720f5ef16c7d04677829789fb74bccb08b90041e4e27916d85cb6fbbece58a7ab48538e8b62bcedab3b236bd38e6517860b593b8fe9bfa77bed979994f2ca1a"

3. Compare your generated checksum signature with the one included in the callback.
```

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

### Retrieve Collection Index with Paging and Status Filter using cURL

Source: https://www.billplz.com/api#introduction/index

Example cURL command to fetch a list of collections, demonstrating the use of `page` and `status` query parameters for filtering and pagination. This allows for more specific data retrieval.

```shell
# Get collection index
curl https://www.billplz.com/api/v4/collections?page=2&status=active \
  -u 73eb57f0-7d4e-42b9-a544-aeac6e4b0f81:
```

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

### Duitnow::Pay Consent Successful Response Example

Source: https://www.billplz.com/api#introduction/index

This JSON object illustrates a successful response from the Billplz API after a Duitnow::Pay consent request. It provides the consent ID, current status, merchant reference, customer details, consent dates, bank code, maximum amount, frequency, callback URL, and the URL for customer authorization.

```json
{
  "id": "29f408bf-c569-4455-a134-1331d9c2bf01",
  "status": "pending",
  "merchant_ref": "C001",
  "customer_name": "Kevin",
  "effective_date": "2025-03-04",
  "expiry_date": "2025-12-31",
  "bank_code": "DNRET-CIBBMYKL",
  "max_amount": 100000,
  "frequency": "01",
  "callback_url": "https://example.com/callback",
  "authorize_consent_url":"https://example-consent-url.com/authorize"
}
```

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

### Retrieve Bill Transactions with Paging and Filtering

Source: https://www.billplz.com/api#introduction/index

This snippet demonstrates how to retrieve a list of transactions associated with a specific bill, supporting paging and optional status filtering. It includes `curl` examples for basic retrieval and with additional parameters, along with the corresponding JSON responses. The API documentation details the HTTP method, URL parameters for paging and filtering, and the structure of the transaction objects in the response.

```curl
curl https://www.billplz.com/api/v3/bills/inbmmepb/transactions \
  -u 73eb57f0-7d4e-42b9-a544-aeac6e4b0f81:
```

```json
{
  "bill_id": "inbmmepb",
  "transactions": [
    {
      "id": "60793D4707CD",
      "status": "completed",
      "completed_at": "2017-02-23T12:49:23.612+08:00",
      "payment_channel": "FPX"
    },
    {
      "id": "28F3D3194138",
      "status": "failed",
      "completed_at": null,
      "payment_channel": "FPX"
    }
  ],
  "page": 1
}
```

```curl
curl https://www.billplz.com/api/v3/bills/inbmmepb/transactions?page=1&status=completed \
  -u 73eb57f0-7d4e-42b9-a544-aeac6e4b0f81:
```

```json
{
  "bill_id": "inbmmepb",
  "transactions": [
    {
      "id": "60793D4707CD",
      "status": "completed",
      "completed_at": "2017-02-23T12:49:23.612+08:00",
      "payment_channel": "FPX"
    }
  ],
  "page": 1
}
```

```APIDOC
HTTP REQUEST:
GET https://www.billplz.com/api/v3/bills/{BILL_ID}/transactions

URL PARAMETER:
page: Up to 15 transactions will be returned in a single API call per specified page. Default to *1* if not present.
status: Parameter to filter transaction's status. Valid values are `pending`, `completed` and `failed`.

RESPONSE PARAMETER:
bill_id: ID that represent the bill.
id: ID that represent the transaction.
status: Status that representing the transaction's status, possible statuses are `pending`, `completed` and `failed`.
completed_at: Datetime format when the transaction is completed. ISO 8601 format is used.
payment_channel: Payment channel that the transaction is made. Possible values are `AMEXMBB`, `BANKISLAM`, `BILLPLZ`, `BOOST`, `TOUCHNGO`, `EBPGMBB`, `FPX`, `FPXB2B1`, `ISUPAYPAL`, `MPGS`, `OCBC`, `PAYDEE`, `RAZERPAYWALLET`, `SECUREACCEPTANCE`, `SENANGPAY`, `TWOCTWOP`, `TWOCTWOPIPP`, and `TWOCTWOPWALLET`.
```

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

### Get an open collection index

Source: https://www.billplz.com/api#introduction/index

Retrieves a list of open collections from the Billplz API. This example shows a basic request without optional parameters.

```curl
curl https://www.billplz.com/api/v3/open_collections \
  -u 73eb57f0-7d4e-42b9-a544-aeac6e4b0f81:
```

```json
{
  "open_collections": [
    {
      "id": "0pp87t_6",
      "title": "MY FIRST API OPEN COLLECTION",
      "description": "Maecenas eu placerat ante.",
      "reference_1_label": "ID No",
      "reference_2_label": "First Name",
      "email_link": "http://www.test.com",
      "amount": null,
      "fixed_amount": false,
      "tax": 1,
      "fixed_quantity": false,
      "payment_button": "buy",
      "photo": {
        "retina_url": "https://sample.net/assets/uploadPhoto.png",
        "avatar_url": "https://sample.net/assets/uploadPhoto.png"
      },
      "split_payment": {
        "email": "[email protected]",
        "fixed_cut": null,
        "variable_cut": 20,
        "split_header": false
      },
      "url": "https://www.billplz.com/0pp87t_6",
      "status": "active"
    }
  ],
  "page": 1
}
```

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

### Get an Open Collection by ID

Source: https://www.billplz.com/api#introduction/index

Use this API to query a specific open collection record by its ID. It includes an example `curl` request and a sample JSON response.

```curl
# Get an open collection
curl https://www.billplz.com/api/v4/open_collections/0pp87t_6 \
  -u 73eb57f0-7d4e-42b9-a544-aeac6e4b0f81:
```

```json
{
  "id": "0pp87t_6",
  "title": "MY FIRST API OPEN COLLECTION",
  "description": "Maecenas eu placerat ante. Fusce ut neque justo, et aliquet enim. In hac habitasse platea dictumst.",
  "reference_1_label": null,
  "reference_2_label": null,
  "email_link": null,
  "amount": 299,
  "fixed_amount": true,
  "tax": null,
  "fixed_quantity": true,
  "payment_button": "pay",
  "photo": {
    "retina_url": null,
    "avatar_url": null
  },
  "split_header": false,
  "split_payments": [],
  "url": "https://www.billplz.com/0pp87t_6",
  "status": "active",
  "redirect_uri": null
}
```

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

### Create Billplz Bill via cURL (Optional Parameters)

Source: https://www.billplz.com/api#introduction/index

This cURL command showcases creating a Billplz bill with an extended set of optional parameters. It demonstrates how to specify due_at, mobile, reference_1_label, reference_2_label, reference_1, reference_2, deliver, and redirect_url to customize the bill creation process.

```curl
curl https://www.billplz.com/api/v3/bills \
  -u 73eb57f0-7d4e-42b9-a544-aeac6e4b0f81: \
  -d collection_id=inbmmepb \
  -d email=[email protected] \
  -d name="Sara" \
  -d amount=200 \
  -d callback_url="http://example.com/webhook/" \
  -d description="Maecenas eu placerat ante." \
  -d due_at="2020-12-31" \
  -d mobile="+60112223333" \
  -d reference_1_label="First Name" \
  -d reference_2_label="Last Name" \
  -d reference_1="Sara" \
  -d reference_2="Dila" \
  -d deliver=false \
  -d redirect_url="http://example.com/redirect/"
```

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

### Billplz API: POST /api/v3/open_collections Endpoint Reference

Source: https://www.billplz.com/api#introduction/index

This section provides a detailed reference for the `POST /api/v3/open_collections` endpoint, outlining the HTTP method, required arguments, and optional arguments with their descriptions, data types, and default values for creating an open collection.

```APIDOC
HTTP METHOD: POST
URL: https://www.billplz.com/api/v3/open_collections

REQUIRED ARGUMENTS:
- Parameter: title
  Description: The collection title. It's showing up on the payment form. String format. (Max of 50 characters)
- Parameter: description
  Description: The collection description. Will be displayed on payment form. String format. (Max of 200 characters)
- Parameter: amount
  Description: A positive integer in the smallest currency unit (e.g 100 cents to charge RM 1.00). Required if fixed_amount is true; Ignored if fixed_amount is false

OPTIONAL ARGUMENTS:
- Parameter: fixed_amount
  Description: Boolean value. Set this to false for Open Amount. Default value is `true`
- Parameter: fixed_quantity
  Description: Boolean value. Set this to false for Open Quantity. Default value is `true`
- Parameter: payment_button
  Description: Payment button's text. Available options are `buy` and `pay`. Default value is `pay`
- Parameter: reference_1_label
  Description: Label #1 to reconcile payments (Max of 20 characters). Default value is `Reference 1`.
- Parameter: reference_2_label
  Description: Label #2 to reconcile payments. (Max of 20 characters). Default value is `Reference 2`.
- Parameter: email_link
  Description: A URL that email to customer after payment is successful.
- Parameter: tax
  Description: Tax rate in positive integer format.
- Parameter: photo
  Description: This image will be resized to retina (Yx960) and avatar (180x180) dimensions. Whitelisted formats are jpg, jpeg, gif and png.
- Parameter: split_payment[email]
  Description: The email address of the split rule's recipient. (The account must be a verified account.)
- Parameter: split_payment[fixed_cut]
  Description: A positive integer in the smallest currency unit that is going in your account (e.g 100 cents to charge RM 1.00). This field is required if `split_payment[variable_cut]` is not present
- Parameter: split_payment[variable_cut]
  Description: Percentage in positive integer format that is going in your account. This field is required if `split_payment[fixed_cut]` is not present
- Parameter: split_payment[split_header]
  Description: Boolean value. All bill and receipt templates will show split rule recipient's infographic if this was set to true.
```

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

### Tokenization Providers Overview

Source: https://www.billplz.com/api#introduction/index

Provides an overview of available tokenization providers, detailing their type and eligibility criteria for Billplz users.

```APIDOC
| Provider | Type | Eligibility |
| --- | --- | --- |
| Senangpay | 3DS | Any paid membership plan |
```

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

### Get Billplz Collection by ID with cURL

Source: https://www.billplz.com/api#introduction/index

This cURL command demonstrates how to retrieve a specific collection record using its unique ID. It sends a GET request to the /api/v4/collections/{id} endpoint, authenticating with a user key to query the collection details.

```curl
curl https://www.billplz.com/api/v4/collections/inbmmepb \
-u 73eb57f0-7d4e-42b9-a544-aeac6e4b0f81:
```

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

### Billplz X Signature Redirect URL Parameter Reference

Source: https://www.billplz.com/api#introduction/index

Detailed reference for the URL parameters included in Billplz X Signature Redirect URL requests, their descriptions, and possible values.

```APIDOC
Parameter | Description
--- | ---
billplz[id] | ID that represents bill.
billplz[paid] | Boolean value to tell if a bill has paid. It will return `false` for `due` and `deleted` bills; `true` for paid bills.
billplz[paid_at] | Date time when the bill was paid, in format `YYYY-MM-DD HH:MM:SS TimeZone`. Example, `2017-01-04 13:10:45 +0800`.
billplz[transaction_id] | ID that represent the transaction. (Enable `Extra Payment Completion Information` option to receive this parameter)
billplz[transaction_status] | Status that representing the transaction's status, possible statuses are `pending`, `completed` and `failed`. (Enable `Extra Payment Completion Information` option to receive this parameter)
billplz[x_signature] | Digital signature computed with passing parameters and shared XSignature Key.
```

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

### Get Supported Payment Gateways List

Source: https://www.billplz.com/api#introduction/index

Use this API to get a complete list of supported payment gateways' bank codes required for setting `reference_1` in direct payment gateway bypass. This list includes online banking and other supported payment gateways. It should be pulled hourly.

```APIDOC
HTTP REQUEST:
GET https://www.billplz.com/api/v4/payment_gateways

RESPONSE PARAMETER:
  code: This is the bank code that need to set to `reference_1`. Case sensitive.
  active: `true` or `false` boolean that represents payment gateway's availability. If an inactive / invalid payment gateway was set to `reference_1`, the payment process will show Billplz page for payer to choose another payment option from the list.
  category: Category this payment gateway belongs to.
```

```curl
curl https://www.billplz.com/api/v4/payment_gateways \
  -u 73eb57f0-7d4e-42b9-a544-aeac6e4b0f81:
```

```json
{
  "payment_gateways": [
    {
      "code": "MBU0227",
      "active": true,
      "category": "fpx"
    },
    {
      "code": "OCBC0229",
      "active": false,
      "category": "fpx"
    },
    {
      "code": "BP-FKR01",
      "active": true,
      "category": "billplz"
    },
    {
      "code": "BP-PPL01",
      "active": true,
      "category": "paypal"
    },
    {
      "code": "BP-2C2P1",
      "active": false,
      "category": "2c2p"
    },
    {
      "code": "BP-OCBC1",
      "active": true,
      "category": "ocbc"
    }
  ]
}
```

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

### Get a Payment Order Collection by ID with Billplz API (curl)

Source: https://www.billplz.com/api#introduction/index

This snippet demonstrates how to retrieve an existing payment order collection using its ID via the Billplz API. It provides the curl command for a GET request, including epoch and checksum parameters, and shows the expected JSON response. The API documentation for the endpoint is also provided.

```curl
curl -G https://www.billplz.com/api/v5/payment_order_collections/8f4e331f-ac71-435e-a870-72fe520b4563 \
  -u 73eb57f0-7d4e-42b9-a544-aeac6e4b0f81: \
  -d epoch=1668147747 \
  -d checksum="2bc6333ac9539e8fc5e520432373991403155f80315c7f3c601bd6a5535ee9ae70b0d8c29823ccf3be73a251caced9f5a165d6c0e9cadd451931ec3c1ede006d"
```

```json
{
  "id": "8f4e331f-ac71-435e-a870-72fe520b4563",
  "title": "My First API Payment Order Collection",
  "payment_orders_count": "0",
  "paid_amount": "0",
  "status": "active",
  "callback_url": "https://example.com/payment_order_collection_callback"
}
```

```APIDOC
HTTP REQUEST:
GET https://www.billplz.com/api/v5/payment_order_collections/{payment_order_collection_id}

REQUIRED ARGUMENTS:
- payment_order_collection_id: The Payment Order Collection ID. A string.
- epoch: The current time in UNIX epoch time format.
- checksum: Required values for [checksum signature](#v5-checksum) in this order: [ payment_order_collection_id, epoch ]
```

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

### API Reference for Activate Customer Receipt Delivery Endpoint

Source: https://www.billplz.com/api#introduction/index

Detailed API documentation for the POST /api/v4/collections/{COLLECTION_ID}/customer_receipt_delivery/activate endpoint, including the HTTP method, URL structure, and required URL parameters.

```APIDOC
POST https://www.billplz.com/api/v4/collections/{COLLECTION_ID}/customer_receipt_delivery/activate

URL PARAMETER:
  COLLECTION_ID: Collection ID returned in Collection object.
```

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

### Billplz API: Create Open Collection Endpoint Details

Source: https://www.billplz.com/api#introduction/index

Detailed API documentation for the POST /api/v4/open_collections endpoint, outlining the HTTP method, URL, and comprehensive descriptions of all required and optional parameters for creating an open collection.

```APIDOC
HTTP REQUEST:
  POST https://www.billplz.com/api/v4/open_collections

REQUIRED ARGUMENTS:
  title:
    Description: The collection title. Will be displayed on payment form. String format (Max of 50 characters).
  description:
    Description: The collection description. Will be displayed on payment form. String format (Max of 200 characters).
  amount:
    Description: A positive integer in the smallest currency unit (e.g 100 cents to charge RM 1.00). Required if fixed_amount is true; Ignored if fixed_amount is false.

OPTIONAL ARGUMENTS:
  fixed_amount:
    Description: Boolean value. Set fixed_amount to false for Open Amount. Default value is true.
  fixed_quantity:
    Description: Boolean value. Set fixed_quantity to false for Open Quantity. Default value is true.
  payment_button:
    Description: Payment button's text. Available options are buy and pay. Default value is pay.
  reference_1_label:
    Description: Label #1 to reconcile payments (Max of 20 characters). Default value is Reference 1.
  reference_2_label:
    Description: Label #2 to reconcile payments (Max of 20 characters). Default value is Reference 2.
  email_link:
    Description: A URL that email to customer after payment is successful.
  tax:
    Description: Tax rate in positive integer format.
  photo:
    Description: This image will be resized to retina (960x960) and avatar (180x180) dimensions. Whitelisted formats are jpg, jpeg, gif and png.
  split_payments[][email]:
    Description: The email address of the split rule's recipient (The account must be a verified account).
  split_payments[][fixed_cut]:
    Description: A positive integer in the smallest currency unit that is going in your account (e.g 100 cents to charge RM 1.00) This field is required if split_payment[variable_cut] is not present.
  split_payments[][variable_cut]:
    Description: Percentage in positive integer format that is going in your account. This field is required if split_payment[fixed_cut] is not present.
  split_payments[][stack_order]:
    Description: Integer format that defines the sequence of the split rule recipients. This field is required and must be in correct order starts from 0 and increment by 1 subsequently if you want to set a split rule. This input is crucial to determine a precise recipient's order.
  split_header:
    Description: Boolean value. All bill and receipt templates will show split rule recipient's infographic if this was set to true.
  redirect_uri:
    Description: URL to redirect the customer after payment (completed or failed). Billplz will do a GET to redirect_uri, with bill's ID appended to the URL (additional paid, paid_at and x_signature if [x_signature](#x-signature) is enabled).
```

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

### API HTTP Request for Get Open Collection

Source: https://www.billplz.com/api#introduction/index

Specifies the HTTP method and endpoint for retrieving a single open collection.

```APIDOC
GET https://www.billplz.com/api/v4/open_collections/{COLLECTION_ID}
```

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

### Query Payment Order Limit (Billplz API)

Source: https://www.billplz.com/api#introduction/index

This snippet illustrates how to query the available payment order limit. It provides a curl command for the request, a sample JSON response, and API documentation detailing the HTTP method, URL, required parameters (epoch, checksum), and the total response parameter, along with usage constraints.

```curl
curl -G https://www.billplz.com/api/v5/payment_order_limit \
  -u 73eb57f0-7d4e-42b9-a544-aeac6e4b0f81: \
  -d epoch=1685591208 \
  -d checksum="e18c50ca130db623d350123ed9cc0c83120361d1045737eb172396b3b41b0141c24c26de6ca41b66dfa476c2c5299a31df21c1fdbf6e0b585ea6e7a975fbd555"
```

```json
{
  "total": "9600"
}
```

```APIDOC
HTTP REQUEST:
GET https://www.billplz.com/api/v5/payment_order_limit

REQUIRED ARGUMENTS:
  epoch: The current time in UNIX epoch time format.
  checksum: Required values for checksum signature in this order: [ epoch ]

RESPONSE PARAMETER:
  total: Total amount available in your Payment Order Limit that you can use to perform payment order. A positive integer in the smallest currency unit (e.g 100 cents to charge RM 1.00).
```

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

### Billplz API V5 Endpoints Overview

Source: https://www.billplz.com/api#introduction/index

Overview of Billplz API Version 5 endpoints, including functionalities for payment order flow, collections, payment orders, limits, Duitnow::Pay, and payment gateways.

```APIDOC
V5:
  Payment Order Flow
  Payment Order Collections:
    Create a Payment Order Collection
    Get a Payment Order Collection
  Payment Order:
    Create a Payment Order
    Get a Payment Order
    SWIFT Bank Code Table
  Payment Order Limit:
    Get a Payment Order Limit
  Duitnow::Pay
  Duitnow::Pay Consents:
    Create a Consent
    Get a Consent
    Terminate a Consent
  Duitnow::Pay AutoDebit:
    Create an AutoDebit
    Get an AutoDebit index
  Payment Gateways
```

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

### Get Collection Customer Receipt Delivery Status

Source: https://www.billplz.com/api#introduction/index

Use this API to retrieve a Collection's Customer Receipt Notification status. The status can be `active`, `inactive`, or `global`.

```APIDOC
HTTP REQUEST:
GET https://www.billplz.com/api/v4/collections/{COLLECTION_ID}/customer_receipt_delivery

URL PARAMETER:
  COLLECTION_ID: Collection ID returned in Collection object.

RESPONSE PARAMETER:
  id: ID that represents a collection.
  customer_receipt_delivery: Collection's Customer Receipt Notification status, it is either `active`, `inactive` or `global`.
```

```curl
# Get a collection's customer receipt delivery
curl https://www.billplz.com/api/v4/collections/qag4fe_o6/customer_receipt_delivery \
  -u 73eb57f0-7d4e-42b9-a544-aeac6e4b0f81:
```

```json
{
  "id": "qag4fe_o6",
  "customer_receipt_delivery": "global"
}
```

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

### API Reference: Get Open Collections

Source: https://www.billplz.com/api#introduction/index

Details the HTTP method, endpoint, and optional query parameters for retrieving open collections, including their descriptions and default values.

```APIDOC
HTTP REQUEST:
GET https://www.billplz.com/api/v3/open_collections

OPTIONAL ARGUMENTS:
- Parameter: page
  Description: Up to 15 open collections will be returned in a single API call per specified page. Default to 1 if not present.
- Parameter: status
  Description: Parameter to filter open collection's status, valid value are `active` and `inactive`.
```

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

### Billplz Collection Creation Response (Optional Args)

Source: https://www.billplz.com/api#introduction/index

This JSON object shows the response after successfully creating a Billplz collection with optional arguments, including a logo URL and configured split payment details. It reflects the values provided in the request.

```json
{
  "id": "inbmmepb",
  "title": "My First API Collection",
  "logo": {
    "thumb_url": "https://sample.net/assets/uploadPhoto.png",
    "avatar_url": "https://sample.net/assets/uploadPhoto.png"
  },
  "split_payment": {
    "email": "[email protected]",
    "fixed_cut": 100,
    "variable_cut": null,
    "split_header": true
  }
}
```

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

### Billplz API Endpoint: Get Single Open Collection

Source: https://www.billplz.com/api#introduction/index

Specifies the HTTP method and URL path for retrieving a single open collection record from the Billplz API.

```APIDOC
GET https://www.billplz.com/api/v3/open_collections/{COLLECTION_ID}
```

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

### Create Billplz Open Collection with Basic Parameters (curl)

Source: https://www.billplz.com/api#introduction/index

This `curl` command demonstrates how to create a new open collection on Billplz with essential parameters like title, description, and amount. It uses basic form data (`-d`) for submission.

```curl
curl https://www.billplz.com/api/v3/open_collections \
  -u 73eb57f0-7d4e-42b9-a544-aeac6e4b0f81: \
  -d title="My First API Open Collection" \
  -d description="Maecenas eu placerat ante." \
  -d amount=299
```

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

### API Reference: POST /v5/payment_orders - Create Payment Order

Source: https://www.billplz.com/api#introduction/index

Detailed API specification for creating a Payment Order. This section outlines the HTTP method, endpoint, all required and optional parameters with their types and descriptions, and the structure of the successful response parameters. It also includes a note on sandbox testing.

```APIDOC
HTTP REQUEST:
  POST https://www.billplz.com/api/v5/payment_orders

REQUIRED ARGUMENTS:
  payment_order_collection_id: The Payment Order Collection ID. A string.
  bank_code: [SWIFT Bank Code](#v5-payment-order-swift-bank-code-table) that represents bank, in string value. Case sensitive.
  bank_account_number: Bank account number, in string value.
  name: Payment Order API's recipient name. Useful for identification on recipient part.
  description: The Payment Order API's description. Will be displayed on bill template. String format (Max of 200 characters). Special characters are not allowed.
  total: Total amount you would like to transfer to the recipient. A positive integer in the smallest currency unit (e.g 100 cents to charge RM 1.00).
  epoch: The current time in UNIX epoch time format.
  checksum: Required values for [checksum signature](#v5-checksum) in this order: [ payment_order_collection_id, bank_account_number, total, epoch ]

  Note for sandbox testing: please use bank_code: DUMMYBANKVERIFIED for a successful payment-order result, any other bank_codes used in sandbox will result in a transaction failure for payment orders.

OPTIONAL ARGUMENTS:
  email: The email address of recipient (it default to sender's email if not present). A receipt will be sent to this email once the Payment Order has been processed.
  notification: Boolean value. As a sender, you can opt-in for email notification by setting this to true. Sender will receive email once a Payment Order has been completed. Default value is false.
  recipient_notification: Boolean value. If this is set to true, recipient of the Payment Order will receive email notification once the Payment Order has been completed. Default value is true. Set to false if you do not like the recipient to receive any email notifications.
  reference_id: Payment Order's unique reference ID scoped by [Payment Order Collection](#v5-payment-order-collections). This helps maintain data integrity by ensuring that no two rows of data in a payment order collection have identical reference_id value. Useful to prevent unintentional payment order creation. (Max of 255 characters).

RESPONSE PARAMETER:
  id: ID that represents a Payment Order.
  payment_order_collection_id: The Payment order collection's title in string format.
  bank_code: SWIFT Bank Code that represents bank, in string value. Case sensitive.
  bank_account_number: Bank account number, in string value.
  name: Payment Order's recipient name.
  description: The Payment Order's description.
  email: The email address of recipient (it default to sender's email if not present).
  status: Payment Order status. It is either processing or enquiring or executing or reviewing or completed or refunded.
  notification: Boolean value. Sender will receive email notification if this is true.
  recipient_notification: Boolean value. Recipient will receive email notification if this is true.
  total: Total amount transfer to the recipient. A positive integer in the smallest currency unit (e.g 100 cents to charge RM 1.00).
  reference_id: Payment Order's reference ID. Useful for identification on recipient part.
```

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

### Get an open collection index with pagination and status filter

Source: https://www.billplz.com/api#introduction/index

Retrieves a list of open collections from the Billplz API, allowing filtering by page number and collection status (active/inactive).

```curl
curl https://www.billplz.com/api/v3/open_collections?page=2&status=active \
  -u 73eb57f0-7d4e-42b9-a544-aeac6e4b0f81:
```

```json
{
  "open_collections": [
    {
      "id": "0pp87t_6",
      "title": "MY FIRST API OPEN COLLECTION",
      "description": "Maecenas eu placerat ante. Fusce ut neque justo, et aliquet enim. In hac habitasse platea dictumst.",
      "reference_1_label": "ID No",
      "reference_2_label": "First Name",
      "email_link": "http://www.test.com",
      "amount": null,
      "fixed_amount": false,
      "tax": 1,
      "fixed_quantity": false,
      "payment_button": "buy",
      "photo": {
        "retina_url": "https://sample.net/assets/uploadPhoto.png",
        "avatar_url": "https://sample.net/assets/uploadPhoto.png"
      },
      "split_payment": {
        "email": "[email protected]",
        "fixed_cut": null,
        "variable_cut": 20,
        "split_header": false
      },
      "url": "https://www.billplz.com/0pp87t_6",
      "status": "active"
    }
  ],
  "page": 2
}
```

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

### Get a Single Billplz Collection by ID

Source: https://www.billplz.com/api#introduction/index

Use this API endpoint to query a specific collection record by its unique ID. The response includes detailed attributes of the requested collection.

```shell
# Get a collection
curl https://www.billplz.com/api/v3/collections/inbmmepb \
  -u 73eb57f0-7d4e-42b9-a544-aeac6e4b0f81:
```

```json
{
  "id": "inbmmepb",
  "title": "My First API Collection",
  "logo": {
    "thumb_url": null,
    "avatar_url": null
  },
  "split_payment": {
    "email": null,
    "fixed_cut": null,
    "variable_cut": null,
    "split_header": false
  },
  "status": "active"
}
```

```APIDOC
HTTP REQUEST:
GET https://www.billplz.com/api/v3/collections/{COLLECTION_ID}

URL PARAMETER:
COLLECTION_ID: Collection ID returned in Collection object.

RESPONSE PARAMETER:
id: ID that represents a collection.
title: The collection's title in string format.
logo[thumb_url]: The thumb dimension's (180x180) URL.
logo[avatar_url]: The avatar dimension's (40x40) URL.
split_payment[email]: The 1st recipient's email. It only returns the 1st recipient eventhough there is multiple recipients being set. If you wish to have 2 recipients, please refer to V4 [Create a Collection](#v4-collections-create-a-collection).
split_payment[fixed_cut]: The 1st recipient's fixed cut in smallest and positive currency unit.
split_payment[variable_cut]: The 1st recipient's percentage cut in positive integer format.
split_payment[split_header]: Boolean value. All bill and receipt templates will show split rule recipient's infographic if this was set to true.
status: Collection's status, it is either active and inactive.
```