canonical: https://jentic.com/apis/billplz.com/billplz

# Billplz Payment API

Jentic publishes the only available OpenAPI specification for Billplz Payment API, keeping it validated and agent-ready. The Billplz Payment API is the programmatic interface to the Malaysian payment platform Billplz, exposing v3, v4, and v5 endpoints for collections, bills, FPX bank routing, card tokenization, and payment orders. Merchants use it to issue payment links to customers, accept FPX online banking and card payments, and manage refunds and webhooks. The spec covers 37 endpoints, with authentication by HTTP Basic using the API Secret Key as the username.

## For AI agents

Issue Malaysian payment links, accept FPX and card payments, tokenize cards, and create payment orders through the Billplz payment platform.

## Scope

Does not handle invoicing for tax-compliance purposes, full accounting, or non-Malaysian cross-border payouts - use for Malaysian payment collection, tokenization, and domestic disbursement only.

## Capabilities

- Create collections to group bills under a single payment page
- Issue bills (payment requests) with email or SMS delivery to customers
- Look up the live FPX bank list to drive online banking payment selection in checkout
- Tokenize cards with POST `/v4/cards` and charge them later via `/v4/bills/{bill_id}/charge`
- Pre-authorize and later capture card payments using `/v4/bills/{bill_id}/preauth` and preauth_capture
- Create payment orders for outbound disbursements via `/v5/payment_orders`
- Configure payment methods, customer receipt delivery, and webhook ranking per collection

## Use cases

### Malaysian E-Commerce Checkout with FPX

Malaysian e-commerce merchants need FPX online banking acceptance alongside cards. The Billplz Payment API creates a bill via POST `/v3/bills` under a collection, returns a hosted payment URL that supports FPX (with the bank list served by `/v3/fpx_banks`) and card payments, and notifies the merchant via webhook. Integration is typically two to three days for a first-time merchant.

Example prompt: Create a collection, then create a bill for 99.90 MYR for customer email buyer@example.com with a redirect URL, and return the resulting Billplz payment URL.

### Card Tokenization and Recurring Charges

SaaS and subscription businesses need to retain a card for recurring billing. The Billplz API supports tokenization via POST `/v4/cards`, then charges saved tokens via POST `/v4/bills/{bill_id}/charge.` Combined with `/v4/bills/{bill_id}/preauth` and preauth_capture, this covers the standard authorise-now, capture-later flow used in fulfilment-driven businesses. Setup takes around three days including webhook handling.

Example prompt: Create a card token via POST `/v4/cards` for the customer, then issue a bill and charge that token via POST `/v4/bills/{bill_id}/charge` for 49.00 MYR.

### Outbound Disbursements via Payment Orders

Marketplaces and platforms need to disburse funds to vendors and beneficiaries. Billplz exposes `/v5/payment_order_collections` and `/v5/payment_orders` for creating and retrieving outbound payouts, plus `/v5/payment_order_limits` to check current sending limits before issuing a batch. This is the supported route for splitting funds out of the platform.

Example prompt: Check current limits via GET `/v5/payment_order_limits`, then create a payment order for 500 MYR to a named beneficiary via POST `/v5/payment_orders.`

### AI Agent Payments Assistant via Jentic

An AI assistant for Malaysian merchants can issue payment links, look up FPX banks, and disburse funds via natural-language requests routed through Jentic. The API Secret Key is held in your Jentic One instance, so the assistant never sees the raw credential. Setup through Jentic is under an hour, versus several days for direct integration.

Example prompt: Search Jentic for 'create a Billplz bill', load the POST `/v3/bills` schema, and execute it for 199.00 MYR to a named customer's email.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/v3/bills` | Create a bill (payment request) |
| GET | `/v3/bills/{bill_id}` | Retrieve a bill |
| POST | `/v3/collections` | Create a collection |
| GET | `/v3/fpx_banks` | List FPX participating banks |
| POST | `/v4/cards` | Create a card token |
| POST | `/v4/bills/{bill_id}/charge` | Charge a tokenized card |
| POST | `/v4/bills/{bill_id}/preauth` | Pre-authorize a card payment |
| POST | `/v5/payment_orders` | Create an outbound payment order |

## Key resources

- **Collections** — Create, list, activate, and deactivate collections that group bills
- **Open Collections** — Create open collections for crowdfunding or open-ended payment pages
- **Bills** — Create, retrieve, and delete bills (payment requests) and list their transactions
- **Payment Methods** — List and update accepted payment methods on a collection
- **FPX Banks** — Get the live list of FPX participating banks for online banking checkouts
- **Tokenization** — Create and delete card tokens, then charge or pre-authorize them
- **Payment Orders** — Create and retrieve outbound payment orders and check disbursement limits
- **Customer Receipts** — Configure receipt delivery behaviour per collection

## Why Jentic

- **Setup:** Wiring the Billplz Payment API by hand means sending your API Secret Key as HTTP Basic auth on every call and building each bill, collection, and card path across its v3, v4, and v5 surfaces yourself. Through Jentic you install once, import Billplz from the API Directory, store the secret key once, and your agent calls it.
- **Permission scoping:** Billplz puts the bill id in the URL path (`/v3/bills/{bill_id}`, `/v4/bills/{bill_id}/charge`), so a rule can pin your agent to one bill. You choose the operations it may call, so charging a bill or running a pre-authorisation is not included unless you add them.
- **Credential handling:** Your Billplz API Secret Key is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'create a Billplz bill' or 'list FPX banks', and Jentic returns the matching Billplz operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Stripe** — Global card and wallet processor without native FPX
- **Adyen Checkout** — Global checkout service that supports many local payment methods
- **PayPal Payments** — Global wallet and card processor
- **PayPal Payouts** — Cross-border payouts service for global beneficiaries

## FAQ

### Why is there no official OpenAPI spec for Billplz Payment API?

Billplz does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call Billplz Payment API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the Billplz Payment API use?

The Billplz Payment API uses HTTP Basic authentication, with your Billplz API Secret Key as the username and an empty password. When called via Jentic, the secret key is held in your Jentic One instance so the raw Basic credentials never reach the agent's context.

### Can I accept FPX online banking payments through the Billplz API?

Yes. Bills created via POST `/v3/bills` under a collection that has FPX enabled in its payment methods will display the FPX bank picker in the hosted payment page. Use GET `/v3/fpx_banks` to retrieve the live list of participating banks for your own checkout UI.

### What are the rate limits for the Billplz Payment API?

The OpenAPI spec does not declare explicit numeric rate limits. Billplz's standard practice is to throttle abusive callers and return 429 responses when limits are exceeded. The Jentic SDK retries on 429 with back-off so high-volume bill issuance jobs do not have to handle this manually.

### How do I tokenize a card and charge it later through Jentic?

Search Jentic for 'tokenize a card on Billplz', which surfaces POST `/v4/cards.` Load the schema, supply the card details, and execute to receive a card_id. Later, create a bill and call POST `/v4/bills/{bill_id}/charge` with the card_id. The Python flow is: pip install jentic, then await client.search, await client.load, await client.execute.

### Can I use Billplz to disburse money to vendors or beneficiaries?

Yes. The v5 payment-order endpoints handle outbound disbursements: POST `/v5/payment_orders` creates a payment order, GET `/v5/payment_orders/{id}` retrieves status, and GET `/v5/payment_order_limits` returns current sending limits before you issue a batch.

### Can I limit what my agent is allowed to do with the Billplz Payment API?

Yes. Jentic One runs on your own infrastructure, and you decide which Billplz operations and credentials the agent may use. Because Billplz puts the bill id in the URL path, such as `/v3/bills/{bill_id}` and `/v4/bills/{bill_id}/charge`, your rules can pin the agent to a single bill. You choose the operations it can call, so charging a card or running a pre-authorisation via `/v4/bills/{bill_id}/preauth` is excluded unless you explicitly allow it.