API Reference
This reference section provides in depth integration details.
Environments
There are two environments: TEST and LIVE
| Environment | URL |
|---|---|
| TEST | http://test-api.billeroo.com/ |
| LIVE | https://api.billeroo.com/ |
Fulfillment Service
There are two environments: TEST and LIVE
| Environment | URL |
|---|---|
| TEST | https://test-fs-api.billeroo.com/ |
| LIVE | https://fs-api.billeroo.com/ |
Transaction Body Payload Data
| Parameter Name | Required? | Description | Format |
|---|---|---|---|
| merchantReference | Required | Reference number of business category/merchant account | Alphabet, numeric, and hypen. Minimum of 30 characters |
| timeOffset | Required | Time offset of transaction | +hh:mm |
| biller | Required | Biller code of specific bills payment | Random generated JSON Web Token (JWT) |
| fields | Required | Container of required field inputs | Refer to Field Data table |
| notify | Required | Container of email notification of transaction | Refer to Notify Data table |
| customParameters | Required | Custom parameter container which is required for EPL (Easy Payment Link) checkout process | Refer to Custom Parameter Data table |
Fulfillment Service
| Parameter Name | Required? | Description | Format |
|---|---|---|---|
| merchantReference | Required | Unique reference generated by the merchant for tracking the transaction. | Alphanumeric |
| gatewayReference | Required | Unique reference generated by the payment gateway | Alphanumeric |
| sku | Required | SKU or product/service identifier. | Alphanumeric |
| billAmount | Required | Original amount to be paid | Decimal (2 digits) |
| serviceFee | Required | Additional service fee applied to the transaction | Decimal (2 digits) |
| paymentDate | Required | Date and time when payment was made (YYYY-MM-DD HH:MM:SS). | YYYY-MM-DD HH:mm:ss |
| postingDate | Required | Date and time when payment was posted (YYYY-MM-DD HH:MM:SS). | YYYY-MM-DD HH:mm:ss |
| option | Required | Payment option or channel used (e.g., GCash). | Enum / String |
| customParameters | Optional | Custom key-value pair defined by the merchant | Key–value pairs |
Field Data
| Parameter Name | Required? | Description | Format |
|---|---|---|---|
| field | Required | Field label | Numeric |
| value | Required | Value of required field input | Alphabet, Numeric, Hypen |
Notify Status Payload Body Claims
| Parameter Name | Description |
|---|---|
| iss | Issuer – claim identifies the principal that issued the JWT |
| sub | Subject – claim identifies the principal that is the subject of the JWT |
| aud | Audience of the notification. Indicates the intended recipient system |
| iat | Issued at – claim identifies the time at which the JWT was issued |
| jti | JWT ID – claim provides a unique identifier for the JWT |
| transaction | Transaction details |
| billerCode | Unique code identifying the biller (e.g., SSS) |
| billerName | Name of the biller (e.g., Social Security System) |
| billingAmount | Original amount billed before any fees are added |
| merchantReference | Unique reference ID generated by the merchant for tracking the transaction |
| processorReference | Reference ID generated by the payment processor/acquirer |
| transactionReference | System-generated unique transaction reference for end-to-end tracking |
| payment | Payment Details |
| totalAmountPaid | Total amount paid by the customer, including fees |
| convenienceFee | Additional fee charged for processing the payment |
| currency | Currency of the transaction |
| timestamp | Date and time of the payment for the transaction in UTC |
| paymentOption | Payment option used to pay for the transaction |
| payorName | Full name of the person who made the payment |
| Customer’s email provided for the transaction | |
| result | Result Details |
| statusCode | Transaction status code indicating the result (e.g., success, error) |
| message | Human-readable description of the transaction result (e.g., Payment Posted) |
| timestamp | Date and time of the payment for the transaction in UTC |
Notify Data
| Parameter Name | Required? | Description | Format |
|---|---|---|---|
| customer | Optional | Condition for sending an email for customer | "EMAIL" |
| merchant | Optional | Condition for sending an email for merchant/business category account | "EMAIL" |
Custom Parameter Data
| Parameter Name | Required? | Description | Format |
|---|---|---|---|
| paymentLinkId | - | - | - |
| paymentOption | - | - | - |
| payorName | - | - | - |
| amountPaid | - | - | - |
| epl_custom_parameters | - | - | - |
| customerId | - | - | - |
Response Messages
| Status Code | Description | Remarks |
|---|---|---|
| OK.00.00 | Payment Successful | Status for a successful payment to biller. |
| OK.00.10 | Payment Pending | Status for pending payment before it reaches to successful payment. |
| OK.00.05 | Payment Posted | Status for posted payment to biller. |
| OK.02.00 | Refund Successful | Status for refunded transactions to the customer. |
| OK.06.00 | Reversal Successful | Status for returning the payment to the customer. |
| OK.01.00 | Transaction Request | Status for transaction that is on process for checkout. |
| OK.00.06 | Manually Posted | Status for transaction that is manually posted with affected transaction. |
| OK.01.20 | For Review | Status for transaction that is being for review before approval. |
Error Messages
| Status Code | Description | Remarks |
|---|---|---|
| 401 Unauthorized | Unauthorized | Integrator will receive this error if an incorrect authorization is provided |
| 429 Too Many Request | Too Many Request | Integrator will receive this error if the request has multiple attempts. |
| ER.00.00 | Payment Failed. Duplicate Reference No. | Integrator will receive this error if provided reference is already present or a duplicate. |
| ER.00.00 | Payment Failed. System Detects Double Transaction / Insufficient Balance. | Integrator will receive this error if the account is low on balance or the amount to be paid has been used in a previous transaction |
| ER.00.00 | Payment Failed. Check the Account No. / Identifier or Invalid Amount. | Integrator will receive this error if the account number provided does not match any existing account number on the selected biller or the amount to be paid does not meet the minimum amount to be paid to the selected biller. |
| ER.00.00 | Payment Failed. Invalid Amount / Check Amount Format | Integrator would receive this error if amount entered is not of numeric format. |
| ER.00.05 | Payment Posting Failed / Cancelled Payment Reference No. | Integrator will receive this error if the payment reference number (PRN) used was cancelled after the checkout or attempting to use the PRN that is already cancelled. |
| ER.00.05 | Payment Posting Failed / Payment Reference No. is already paid | Integrator will receive this error if the payment reference number (PRN) used was already paid after the checkout process or attempting to use the PRN that is already paid. |
| ER.00.05 | Payment Posting Failed / PRN Already Due. When requesting to submit PRN to SSS | Integrator will receive this error if the payment reference number (PRN) used was already due date after the checkout process or attempting to use it that is already due to that date, regardless with the validity of PRN. |
| ER.00.05 | Payment Posting Failed / Response code is null or when requesting to submit PRN to SSS | Integrator will receive this error if the payment reference number (PRN) used was unsuccessful due to technical error from SSS server. |
| ER.00.05 | Payment Posting Failed / Runtime Error Occurred. Runtime Error when requesting to submit PRN to SSS | Integrator will receive this error if the payment reference number (PRN) used was unsuccessful due to downtime server error from SSS. |
| ER.00.05 | Payment Posting Failed / Invalid Token Provided. When requesting to submit PRN to SSS | Integrator will receive this error if the payment reference number (PRN) used was unsuccessful due to invalid token used after the checkout process. |
| ER.00.05 | Payment Posting Failed / Provider Code and Token Not Match. When requesting to submit PRN to SSS | Integrator will receive this error if the payment reference number (PRN) used was unsuccessful due to not match of provider code and token used after the checkout process. |
| ER.00.05 | Payment Posting Failed / Invalid PRN Under LGU-CIS | Integrator will receive this error if the payment reference number (PRN) used was unsuccessful due to invalid PRN under LGU-CIS after the checkout process. |
| ER.00.05 | Payment Posting Failed / Check amount for this PRN | Integrator will receive this error if the payment reference number (PRN) used was unsuccessful due to not match of amount of this given PRN after the checkout process. |