Billplz API

https://support.billplz.com/api
Admin
The Billplz API is a REST API for creating bills and collecting payments programmatically, returning...
Tokens:29,191
Snippets:198
Trust Score:10
Update:3 months ago
Show doc for...
Tokens:
Raw
### Webhook Request Examples

Source: https://support.billplz.com/api

Full HTTP request examples received from Billplz for webhook 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="W_79pJDk"
  &collection_id="599"
  &paid="true"
  &state="paid"
  &amount="200"
  &paid_amount="0"
  &due_at="2020-12-31"
  &email="api@billplz.com"
  &mobile="+60112223333"
  &name="MICHAEL API"
  &url="http://billplz.dev/bills/W_79pJDk"
  &paid_at="2015-03-09 16:23:59 +0800"
  &x_signature="f0ff6c564f98d5403e2b26fbd3d45309c76eb68d8c5bcda0d48b541c3502a396"
```

```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="api@billplz.com"
  &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"
```

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

### HTTP GET Request with X Signature

Source: https://support.billplz.com/api

Example of a redirect URL containing bill status data and the x_signature parameter.

```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
```

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

### Sample POST body

Source: https://support.billplz.com/api

Example of the raw POST body received from a Billplz callback.

```text
{:id=>"zq0tm2wc", :collection_id=>"yhx5t1pp", :paid=>true, :state=>"paid", :amount=>100, :paid_amount=>100, :due_at=>"2018-9-27", :email=>"tester@test.com", :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 Server Side Request from Billplz

Source: https://support.billplz.com/api

A sample HTTP POST request received at the callback URL, formatted for readability.

```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="api@billplz.com"
  &status="refunded"
  &notification="false"
  &recipient_notification="true"
  &reference_id="My first payment order"
  &display_name=""
  &total=500000
  &epoch=1681895891
  &checksum="2720f5ef16c7d04677829789fb74bccb08b90041e4e27916d85cb6fbbece58a7ab48538e8b62bcedab3b236bd38e6517860b593b8fe9bfa77bed979994f2ca1a"
```

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

### Pre-auth capture response example

Source: https://support.billplz.com/api

Represents the JSON response structure returned upon a successful pre-auth capture.

```json
{
  "amount": 10000,
  "status": "success",
  "reference_id": "15681981586116610",
  "preauth_id": "732d8sdk778912e81003946192b0b6aa4b754b3c8addd5",
  "hash_value": "1b66606732d846192b0b6aa4b754b3c8addd59072fce4bdd066b5d631c31d5e8",
  "message": "Payment was successful"
}
```

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

### Collection Response Structure

Source: https://support.billplz.com/api

Example JSON response returned when successfully retrieving a collection.

```json
{
  "id": "inbmmepb",
  "title": "My First API Collection",
  "logo": {
    "thumb_url": null,
    "avatar_url": null
  },
  "split_header": false,
  "split_payments": [
    {
      "email": "verified@account.com",
      "fixed_cut": 100,
      "variable_cut": 2,
      "stack_order": 0
    },
    {
      "email": "verified2@account.com",
      "fixed_cut": 200,
      "variable_cut": 3,
      "stack_order": 1
    }
  ],
  "status": "active"
}
```

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

### Collection Index Response with Arguments

Source: https://support.billplz.com/api

Example JSON response structure when using pagination and filtering.

```json
{
  "collections": [
    {
      "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"
    }
  ],
  "page": 2
}
```

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

### Collection index response structure

Source: https://support.billplz.com/api

Example JSON response returned by the collections endpoint.

```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
}
```

```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
}
```

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

### Handle 3D Secure callback

Source: https://support.billplz.com/api

Example of the POST request sent by Billplz to your callback URL containing the card status and checksum.

```bash
# POST request sent by Billplz to your callback_url
curl https://www.example.com/callback \
  -d id="a35296ad-b50c-4179-8024-036da00c1aee" \
  -d card_number="1118" \
  -d provider="mastercard" \
  -d token="77d62ad5a3ae56aafc8e3529b89d0268afa205303f6017afbd9826afb8394740" \
  -d status="active" \
  -d checksum="ef5e54a22af0925cba88fab467119742e90262e3646eea1dee3949938daf3a38"
```

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

### View API Response Headers

Source: https://support.billplz.com/api

Examples of response headers indicating rate limit status.

```http
RateLimit-Limit: unlimited
RateLimit-Remaining: unlimited
RateLimit-Reset: unlimited
Content-Type: application/json;
```

```http
RateLimit-Limit: 100
RateLimit-Remaining: 99
RateLimit-Reset: 299
Content-Type: application/json;
```

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

### Perform a Billplz API Request

Source: https://support.billplz.com/api

Example of a cURL request to retrieve bill details using basic authentication.

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

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

### Collection Index Response

Source: https://support.billplz.com/api

Example JSON response structure for a collection index request.

```json
{
  "collections": [
    {
      "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"
    }
  ],
  "page": 1
}
```

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

### Payment Order Limit Response

Source: https://support.billplz.com/api

Example JSON response containing the total available balance in the smallest currency unit.

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

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

### Transaction index response

Source: https://support.billplz.com/api

Example JSON response structure returned by the transaction index endpoint.

```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
}
```

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

### Handle Rate Limit Exceeded Response

Source: https://support.billplz.com/api

Example response structure when the 429 Too Many Requests error is triggered.

```json
RateLimit-Limit: 100
RateLimit-Remaining: 0
RateLimit-Reset: 299
Content-Type: application/json;
{
  "error": {
    "type": "RateLimit",
    "message": ["Too many requests"]
  }
}
```

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

### HTTP POST Callback Request

Source: https://support.billplz.com/api

Example of the HTTP POST request sent by Billplz to the configured webhook endpoint upon payment completion.

```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="api@billplz.com"
  &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"
```

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

### GET /api/v4/payment_gateways

Source: https://support.billplz.com/api

Returns a complete list of supported payment gateway codes. It is recommended to pull this list on an hourly basis to ensure active status reflects current availability.

```APIDOC
## GET /api/v4/payment_gateways

### Description
Returns a complete list of supported payment gateway codes for use as reference_1 when using the Direct payment gateway feature.

### Method
GET

### Endpoint
https://www.billplz.com/api/v4/payment_gateways

### Response
#### Success Response (200)
- **code** (string) - The gateway code to set as reference_1.
- **active** (boolean) - true if the gateway is available; false if unavailable.
- **category** (string) - Category this payment gateway belongs to.

#### Response Example
{
  "payment_gateways": [
    {
      "code": "MBU0227",
      "active": true,
      "category": "fpx"
    }
  ]
}
```

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

### GET {REDIRECT_URL}

Source: https://support.billplz.com/api

Billplz redirects the browser to your configured redirect_url with bill status parameters appended. You should verify the x_signature to ensure the request originated from Billplz.

```APIDOC
## GET {REDIRECT_URL}

### Description
Billplz redirects the browser to your specified redirect_url with bill status data appended as URL parameters. Each redirect includes an x_signature for verification.

### Method
GET

### Endpoint
{REDIRECT_URL}

### Parameters
#### Query Parameters
- **billplz[id]** (string) - Required - ID that represents the Bill.
- **billplz[paid]** (boolean) - Required - Indicates whether the Bill has been paid.
- **billplz[paid_at]** (string) - Required - Date time when the Bill was paid (YYYY-MM-DD HH:MM:SS TimeZone).
- **billplz[transaction_id]** (string) - Optional - ID that represents the transaction (requires Extra Payment Completion Information).
- **billplz[transaction_status]** (string) - Optional - Transaction status (pending, completed, failed) (requires Extra Payment Completion Information).
- **billplz[x_signature]** (string) - Required - Digital signature computed with URL parameter data and your X Signature key.
```

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

### Create a Collection with Optional Arguments

Source: https://support.billplz.com/api

Request demonstrating how to include a logo file and split payment configuration during collection creation.

```bash
curl https://www.billplz.com/api/v3/collections \
  -u 73eb57f0-7d4e-42b9-a544-aeac6e4b0f81: \
  -F title="My First API Collection" \
  -F logo=@/Users/Billplz/Documents/uploadPhoto.png \
  -F split_payment[email]="verified@account.com" \
  -F split_payment[fixed_cut]=100 \
  -F split_payment[split_header]=true
```

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

### GET /api/v5/payment_order_limit

Source: https://support.billplz.com/api

Retrieves your current Payment Order Limit.

```APIDOC
## GET /api/v5/payment_order_limit

### Description
Retrieves your current Payment Order Limit.

### Method
GET

### Endpoint
https://www.billplz.com/api/v5/payment_order_limit

### Parameters
#### Query Parameters
- **epoch** (integer) - Required - The current time in UNIX epoch time format.
- **checksum** (string) - Required - Required values for checksum signature in this order: [ epoch ]

### Response
#### Success Response (200)
- **total** (integer) - Total amount available in your Payment Order Limit. A positive integer in the smallest currency unit (e.g., 100 cents to charge MYR 1.00).

#### Response Example
{
  "total": "9600"
}
```

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

### Create a Payment Order with Optional Arguments

Source: https://support.billplz.com/api

Request including optional parameters like email, notifications, and reference ID.

```bash
# Create a Payment Order for RM 20.00
curl https://www.billplz.com/api/v5/payment_orders \
  -u 73eb57f0-7d4e-42b9-a544-aeac6e4b0f81: \
  -d payment_order_collection_id="8f4e331f-ac71-435e-a870-72fe520b4563" \
  -d bank_code="MBBEMYKL" \
  -d bank_account_number="543478924652" \
  -d name="Michael Yap" \
  -d description="Maecenas eu placerat ante." \
  -d total=2000 \
  -d email="recipient@email.com" \
  -d notification=true \
  -d recipient_notification=false \
  -d reference_id="paymentOrder1" \
  -d epoch=1668148796 \
  -d checksum="fce47038896eb5c70fd33a8faf91529023cf67fa48afcc31adb20263e45a37b5cd0211fd95377a1053b9bbf70de0245c9117576998264eebb932f8244c878eed"
```

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

### GET /collections/{COLLECTION_ID}

Source: https://support.billplz.com/api

Retrieves a single Collection record by its ID.

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

### Description
Retrieves a single Collection record.

### Method
GET

### Endpoint
https://www.billplz.com/api/v3/collections/{COLLECTION_ID}

### Parameters
#### Path Parameters
- **COLLECTION_ID** (string) - Required - Collection ID returned in Collection object.

### Response
#### Success Response (200)
- **id** (string) - ID that represents a collection.
- **title** (string) - The collection's title in string format.
- **logo[thumb_url]** (string) - The thumbnail URL (180x180).
- **logo[avatar_url]** (string) - The avatar URL (40x40).
- **split_payment[email]** (string) - The first recipient's email.
- **split_payment[fixed_cut]** (integer) - The first recipient's fixed cut in smallest and positive currency unit.
- **split_payment[variable_cut]** (integer) - The first recipient's percentage cut in positive integer format.
- **split_payment[split_header]** (boolean) - All Bill and receipt templates will show split rule recipient's infographic if this is set to true.
- **status** (string) - Collection's status, either active or inactive.

#### Response Example
{
  "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"
}
```

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

### Filtered transaction response

Source: https://support.billplz.com/api

Example JSON response when filtering transactions by status.

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

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

### GET /api/v5/payment_orders/{payment_order_id}

Source: https://support.billplz.com/api

Retrieves a single Payment Order record by its ID.

```APIDOC
## GET /api/v5/payment_orders/{payment_order_id}

### Description
Retrieves a single Payment Order record. This endpoint is subject to Rate limit restrictions.

### Method
GET

### Endpoint
https://www.billplz.com/api/v5/payment_orders/{payment_order_id}

### Parameters
#### Path Parameters
- **payment_order_id** (String) - Required - Payment Order ID.

#### Query Parameters
- **epoch** (Integer) - Required - The current time in UNIX epoch time format.
- **checksum** (String) - Required - Required values for checksum signature in this order: [ payment_order_id, epoch ]

### Response
#### Success Response (200)
- **id** (String) - ID that represents a Payment Order.
- **payment_order_collection_id** (String) - Payment Order Collection ID.
- **bank_code** (String) - SWIFT bank code that represents a bank.
- **bank_account_number** (String) - Bank account number.
- **name** (String) - Payment Order's recipient name.
- **description** (String) - The Payment Order's description.
- **email** (String) - The email address of the recipient.
- **status** (String) - Payment Order status (processing, enquiring, executing, reviewing, completed, refunded).
- **notification** (Boolean) - Sender will receive email notification if true.
- **recipient_notification** (Boolean) - Recipient will receive email notification if true.
- **total** (Integer) - Total amount transferred to the recipient in the smallest currency unit.
- **reference_id** (String) - Payment Order's reference ID.
- **display_name** (String) - Bank account owner's name.

#### Response Example
{
  "id": "cc92738f-dfda-4969-91dc-22a44afc7e26",
  "payment_order_collection_id": "8f4e331f-ac71-435e-a870-72fe520b4563",
  "bank_code": "MBBEMYKL",
  "bank_account_number": "543478924652",
  "name": "Michael Yap",
  "description": "Maecenas eu placerat ante.",
  "email": "recipient@email.com",
  "status": "enquiring",
  "notification": true,
  "recipient_notification": false,
  "total": "2000",
  "reference_id": "paymentOrder1",
  "display_name": "Michael Yap"
}
```

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

### X Signature Verification Steps

Source: https://support.billplz.com/api

Step-by-step process for constructing the source string and computing the HMAC-SHA256 signature.

```text
billplz[id]="zq0tm2wc"
billplz[paid]="true"
billplz[paid_at]="2018-09-27 15:15:09 +0800"
```

```text
billplzidzq0tm2wc
billplzpaidtrue
billplzpaid_at2018-09-27 15:15:09 +0800
```

```text
billplzidzq0tm2wc
billplzpaid_at2018-09-27 15:15:09 +0800
billplzpaidtrue
```

```text
billplzidzq0tm2wc|billplzpaid_at2018-09-27 15:15:09 +0800|billplzpaidtrue
```

```text
Sample X Signature key: S-s7b4yWpp9h7rrkNM1i3Z_g
Computed x_signature: 4aab095fe5a39b1d534500988f9a0cb085cd1b6d5bbb55dd4e02ea6fa102b47b
```

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

### GET /api/v4/collections

Source: https://support.billplz.com/api

Retrieves a list of your collections. Supports pagination and filtering by status.

```APIDOC
## GET /api/v4/collections

### Description
Retrieves your Collections list. To utilize paging, append a `page` parameter to the URL. If there are 15 records in the response, check if there is any more data by fetching the next page.

### Method
GET

### Endpoint
https://www.billplz.com/api/v4/collections

### Parameters
#### Query Parameters
- **page** (integer) - Optional - Up to 15 collections will be returned in a single API call per specified page. Defaults to 1 if not present.
- **status** (string) - Optional - Parameter to filter collection's status. Valid values are `active` and `inactive`.

### Request Example
curl https://www.billplz.com/api/v4/collections?page=2&status=active -u API_KEY:

### Response
#### Success Response (200)
- **collections** (array) - List of collection objects
- **page** (integer) - Current page number

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

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

### GET /collections/{COLLECTION_ID}

Source: https://support.billplz.com/api

Retrieves a single Collection record by its unique identifier.

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

### Description
Retrieves a single Collection record.

### Method
GET

### Endpoint
https://www.billplz.com/api/v4/collections/{COLLECTION_ID}

### Parameters
#### Path Parameters
- **COLLECTION_ID** (string) - Required - Collection ID returned in the Collection object.

### Response
#### Success Response (200)
- **id** (string) - ID that represents a Collection.
- **title** (string) - The Collection's title in string format.
- **logo[thumb_url]** (string) - The thumbnail URL (180x180).
- **logo[avatar_url]** (string) - The avatar URL (40x40).
- **split_header** (boolean) - All Bill and receipt templates will show Split Rule recipient's infographic if this is set to true.
- **split_payments** (array) - Array of Split Rule recipients.
- **status** (string) - Collection's status, either active or inactive.

#### Response Example
{
  "id": "inbmmepb",
  "title": "My First API Collection",
  "logo": {
    "thumb_url": null,
    "avatar_url": null
  },
  "split_header": false,
  "split_payments": [
    {
      "email": "verified@account.com",
      "fixed_cut": 100,
      "variable_cut": 2,
      "stack_order": 0
    }
  ],
  "status": "active"
}
```

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

### GET /api/v3/collections

Source: https://support.billplz.com/api

Retrieves a list of your collections. Supports pagination and filtering by status.

```APIDOC
## GET /api/v3/collections

### Description
Retrieves your Collections list. To utilize paging, append a `page` parameter to the URL. You can also filter by collection status.

### Method
GET

### Endpoint
https://www.billplz.com/api/v3/collections

### Parameters
#### Query Parameters
- **page** (integer) - Optional - Up to 15 collections will be returned in a single API call per specified page. Defaults to 1.
- **status** (string) - Optional - Parameter to filter collection's status. Valid values are `active` and `inactive`.

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

### Response
#### Success Response (200)
- **collections** (array) - List of collection objects
- **page** (integer) - Current page number

#### Response Example
{
  "collections": [
    {
      "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"
    }
  ],
  "page": 2
}
```

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

### Create a Payment Order Collection via cURL

Source: https://support.billplz.com/api

Use this request to initialize a new collection. Ensure the checksum is calculated correctly using the title, callback URL, and epoch timestamp.

```bash
# Create a Payment Order collection
curl https://www.billplz.com/api/v5/payment_order_collections \
  -u 73eb57f0-7d4e-42b9-a544-aeac6e4b0f81: \
  -d title="My First API Payment Order Collection"  \
  -d epoch=1668147670 \
  -d callback_url="https://example.com/payment_order_collection_callback" \
  -d checksum="7ea7b8aed3093b058bfee1d67387f0d6f3be1d776ae3ebd82462237ccf2ffc1ae8b9bf38ad43a81bb2b15f817970afdf656dc622258230b08aa26c7418274041"
```

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

### Create a Collection with Split Payments

Source: https://support.billplz.com/api

Request to create a collection including optional split payment configurations for multiple recipients.

```bash
curl https://www.billplz.com/api/v4/collections \
  -u 73eb57f0-7d4e-42b9-a544-aeac6e4b0f81: \
  -F title="My First V4 API Collection" \
  -F split_payments[][email]="verified@account.com" \
  -F split_payments[][fixed_cut]=100 \
  -F split_payments[][variable_cut]=2 \
  -F split_payments[][stack_order]=0 \
  -F split_payments[][email]="verified2@account.com" \
  -F split_payments[][fixed_cut]=200 \
  -F split_payments[][variable_cut]=3 \
  -F split_payments[][stack_order]=1
```

```json
{
  "id": "inbmmepb",
  "title": "My First V4 API Collection",
  "logo": {
    "thumb_url": null,
    "avatar_url": null
  },
  "split_header": false,
  "split_payments": [
    {
      "email": "verified@account.com",
      "fixed_cut": 100,
      "variable_cut": 2,
      "stack_order": 0
    },
    {
      "email": "verified2@account.com",
      "fixed_cut": 200,
      "variable_cut": 3,
      "stack_order": 1
    }
  ]
}
```

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

### Signature Verification Constants

Source: https://support.billplz.com/api

Sample key and computed signature values for verification testing.

```text
Sample X Signature key: S-s7b4yWpp9h7rrkNM1i3Z_g
Computed x_signature: 0fe0a20b8d557eeae570377783d062a3816a9ea80f368860bacfa7ec3ca4d00e
```

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

### GET /api/v5/payment_order_collections/{payment_order_collection_id}

Source: https://support.billplz.com/api

Retrieves a single Payment Order Collection record by its ID.

```APIDOC
## GET /api/v5/payment_order_collections/{payment_order_collection_id}

### Description
Retrieves a single Payment Order Collection record.

### Method
GET

### Endpoint
https://www.billplz.com/api/v5/payment_order_collections/{payment_order_collection_id}

### Parameters
#### Path Parameters
- **payment_order_collection_id** (string) - Required - The Payment Order Collection ID.

#### Query Parameters
- **epoch** (integer) - Required - The current time in UNIX epoch time format.
- **checksum** (string) - Required - Checksum signature calculated from [payment_order_collection_id, epoch].

### Response
#### Success Response (200)
- **id** (string) - ID that represents a Payment Order Collection.
- **title** (string) - The Collection's title.
- **payment_orders_count** (integer) - The number of Payment Orders that belong to this Collection.
- **paid_amount** (integer) - Total paid amount for Payment Orders in this Collection (smallest currency unit).
- **status** (string) - Collection's status (active or inactive).
- **callback_url** (string) - Webhook URL called after a Payment Order transaction completes.

#### Response Example
{
  "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"
}
```

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

### Create a Payment Order

Source: https://support.billplz.com/api

Standard request to create a payment order using cURL.

```bash
# Create a Payment Order for RM 20.00
curl https://www.billplz.com/api/v5/payment_orders \
  -u 73eb57f0-7d4e-42b9-a544-aeac6e4b0f81: \
  -d payment_order_collection_id="8f4e331f-ac71-435e-a870-72fe520b4563" \
  -d bank_code="MBBEMYKL" \
  -d bank_account_number="543478924652" \
  -d name="Michael Yap" \
  -d description="Maecenas eu placerat ante." \
  -d total=2000 \
  -d epoch=1668148460 \
  -d checksum="1516c31cd226119732b66dd423a5ae8d9741594953dfb4bd510efc7349cd7579dc885014bbb67baf8398150cdba5ac42c35196ef1a1acea437386711e159ce62"
```

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

### GET /api/v3/fpx_banks

Source: https://support.billplz.com/api

Retrieves a list of FPX bank codes and their current availability status.

```APIDOC
## GET https://www.billplz.com/api/v3/fpx_banks

### Description
Returns a list of FPX bank codes for use as `reference_1` when using the Direct payment gateway feature. It is recommended to pull this list on an hourly basis to ensure `active` status reflects current bank availability.

### Method
GET

### Endpoint
https://www.billplz.com/api/v3/fpx_banks

### Response
#### Success Response (200)
- **name** (string) - The bank code to set as `reference_1`. Case sensitive.
- **active** (boolean) - `true` if the bank is available; `false` if unavailable.

#### Response Example
{
  "banks": [
    {
      "name": "MBU0227",
      "active": true
    },
    {
      "name": "OCBC0229",
      "active": false
    },
    {
      "name": "MB2U0227",
      "active": true
    }
  ]
}
```

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

### Parameter Extraction and Processing

Source: https://support.billplz.com/api

Steps to prepare the source string for signature verification.

```text
id="zq0tm2wc"
collection_id="yhx5t1pp"
paid="true"
state="paid"
amount="100"
paid_amount="100"
due_at="2018-9-27"
email="tester@test.com"
mobile=""
name="TESTER"
url="http://www.billplz-sandbox.com/bills/zq0tm2wc"
paid_at="2018-09-27 15:15:09 +0800"
```

```text
idzq0tm2wc
collection_idyhx5t1pp
paidtrue
statepaid
amount100
paid_amount100
due_at2018-9-27
emailtester@test.com
mobile
nameTESTER
urlhttp://www.billplz-sandbox.com/bills/zq0tm2wc
paid_at2018-09-27 15:15:09 +0800
```

```text
amount100
collection_idyhx5t1pp
due_at2018-9-27
emailtester@test.com
idzq0tm2wc
mobile
nameTESTER
paid_amount100
paid_at2018-09-27 15:15:09 +0800
paidtrue
statepaid
urlhttp://www.billplz-sandbox.com/bills/zq0tm2wc
```

```text
amount100|collection_idyhx5t1pp|due_at2018-9-27|emailtester@test.com|idzq0tm2wc|mobile|nameTESTER|paid_amount100|paid_at2018-09-27 15:15:09 +0800|paidtrue|statepaid|urlhttp://www.billplz-sandbox.com/bills/zq0tm2wc
```

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

### Basic Redirect URL

Source: https://support.billplz.com/api

Describes the GET request sent by Billplz to the redirect_url when a payment is completed.

```APIDOC
## GET {REDIRECT_URL}

### Description
If `redirect_url` exists, Billplz redirects the browser to the specified URL with the Bill ID appended as a query parameter.

### Method
GET

### Parameters
#### Query Parameters
- **billplz[id]** (string) - Required - ID that represents the Bill.
```

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

### Create a Collection

Source: https://support.billplz.com/api

Basic request to create a new collection using cURL.

```bash
# Creates a collection
curl https://www.billplz.com/api/v4/collections \
  -u 73eb57f0-7d4e-42b9-a544-aeac6e4b0f81: \
  -F title="My First V4 API Collection"
```

```json
{
  "id": "inbmmepb",
  "title": "My First V4 API Collection",
  "logo": {
    "thumb_url": null,
    "avatar_url": null
  },
  "split_header": false,
  "split_payments": []
}
```

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

### GET /collections/{COLLECTION_ID}/customer_receipt_delivery

Source: https://support.billplz.com/api

Returns the customer receipt delivery status for a specific Collection.

```APIDOC
## GET /collections/{COLLECTION_ID}/customer_receipt_delivery

### Description
Returns the customer receipt delivery status for a specific Collection.

### Method
GET

### Endpoint
https://www.billplz.com/api/v4/collections/{COLLECTION_ID}/customer_receipt_delivery

### Parameters
#### Path Parameters
- **COLLECTION_ID** (string) - Required - Collection ID returned in the Collection object.

### Response
#### Success Response (200)
- **id** (string) - ID that represents a collection.
- **customer_receipt_delivery** (string) - Collection's customer receipt delivery status. Returns active, inactive, or global.

#### Response Example
{
  "id": "qag4fe_o6",
  "customer_receipt_delivery": "global"
}
```

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

### POST {CALLBACK_URL}

Source: https://support.billplz.com/api

Handles the 3D Secure update callback sent by Billplz to your specified URL.

```APIDOC
## POST {CALLBACK_URL}

### Description
Billplz sends a POST request to the provided callback_url to notify about 3D Secure verification status updates.

### Method
POST

### Endpoint
{CALLBACK_URL}

### Parameters
#### Request Body
- **id** (string) - Required - ID that represents the card.
- **card_number** (string) - Required - Last 4 digits of the card number.
- **provider** (string) - Required - Card provider.
- **token** (string) - Required - Card token.
- **status** (string) - Required - Card status (pending, active, failed, deleted).
- **checksum** (string) - Required - Digital signature for verification.
```

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

### Create a Bill with Optional Arguments

Source: https://support.billplz.com/api

Advanced request including optional fields such as due date, custom reference labels, and redirect URLs.

```bash
# Create a bill for RM 2.00
curl https://www.billplz.com/api/v3/bills \
  -u 73eb57f0-7d4e-42b9-a544-aeac6e4b0f81: \
  -d collection_id=inbmmepb \
  -d email=api@billplz.com \
  -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/"
```

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

### Retrieve payment method index

Source: https://support.billplz.com/api

Fetches all payment methods for a specific collection, showing their current enabled status.

```bash
# Get payment method index
curl https://www.billplz.com/api/v3/collections/0idsxnh5/payment_methods \
  -u 73eb57f0-7d4e-42b9-a544-aeac6e4b0f81:
```

```json
{
  "payment_methods": [
    {
      "code": "paypal",
      "name": "PAYPAL",
      "active": true
    },
    {
      "code": "fpx",
      "name": "Online Banking",
      "active": false
    }
  ]
}
```

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

### Sample Callback Payment Order Object

Source: https://support.billplz.com/api

A JSON representation of the Payment Order object received in a callback.

```json
{
  "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": "api@billplz.com",
  "status": "refunded",
  "notification": "false",
  "recipient_notification": "true",
  "reference_id": "My first payment order",
  "display_name": "",
  "total": 500000,
  "epoch": 1681895891,
  "checksum": "2720f5ef16c7d04677829789fb74bccb08b90041e4e27916d85cb6fbbece58a7ab48538e8b62bcedab3b236bd38e6517860b593b8fe9bfa77bed979994f2ca1a"
}
```

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

### Retrieve Collection Index with Arguments

Source: https://support.billplz.com/api

Request to fetch collections using optional page and status filtering parameters.

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

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

### FPX Banks API Response

Source: https://support.billplz.com/api

Example JSON response containing a list of banks with their respective names and active status.

```json
{
  "banks": [
    {
      "name": "MBU0227",
      "active": true
    },
    {
      "name": "OCBC0229",
      "active": false
    },
    {
      "name": "MB2U0227",
      "active": true
    }
  ]
}
```

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

### GET /bills/{BILL_ID}/transactions

Source: https://support.billplz.com/api

Retrieves a list of transactions for a specific bill. Supports pagination and filtering by transaction status.

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

### Description
Retrieves a Bill's transactions. To use paging, append a page parameter to the URL. If there are 15 records in the response, check for more data by fetching the next page.

### Method
GET

### Endpoint
https://www.billplz.com/api/v3/bills/{BILL_ID}/transactions

### Parameters
#### Path Parameters
- **BILL_ID** (string) - Required - The unique identifier of the bill.

#### Query Parameters
- **page** (integer) - Optional - Page number for pagination. Up to 15 transactions are returned per page. Defaults to 1.
- **status** (string) - Optional - Filters transactions by status. Valid values are pending, completed, and failed.

### Response
#### Success Response (200)
- **bill_id** (string) - The Bill ID.
- **transactions** (array) - List of transaction objects.
- **page** (integer) - The current page number.

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

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

### Create a card token via cURL

Source: https://support.billplz.com/api

Initiates the card tokenization process by sending cardholder details to the Billplz API. The response includes an authentication_redirect_url for 3DS verification.

```bash
# Create a card token
curl https://www.billplz.com/api/v4/cards \
  -u 73eb57f0-7d4e-42b9-a544-aeac6e4b0f81: \
  -d name="Michael" \
  -d email="api@billplz.com" \
  -d phone="60122345678" \
  -d callback_url="https://example.com/callback_url"
```
Tokens:
Raw