BE Merchants. Transactions Callback (1.4.0)

Download OpenAPI specification:Download

IT Department: [email protected] URL: https://www.billease.ph

Billease Merchants. Callback API. This API has to be implemented on the merchants side

Documentation: https://docs.billease.ph/

1.4.0 - Add Deals section: POST /trx/transaction for Billease Deals partners who fulfil physical goods. A successful response is the merchant's confirmation that the order is accepted; Billease approves and disburses only after it. Merchants using standard checkout are unaffected.

ping

Information about service

Get information about service

Authorizations:

Authentication

Responses

Response samples

200
401
500

Content type

application/json

{"nam": "api name",
"env": "prod",
"ver": "1.0.1",
"srv": "2018-10-25T13:12:01"
}

Transactions

Transactions' operations

Update transaction

Update transaction status on the merchant's side

Authorizations:

Authentication

path Parameters

id

required

any

Transaction ID

Request Body schema: application/json

Transaction update

status required	string Enum: "REJ" "CAN" "EXP" "HOL" "APR" "REF" Transaction status REJ - Rejected CAN - Canceled EXP - Expired HOL - Hold amount APR - Approved REF - Refunded
order_id required	string Order ID
message	string Any message from Billease system
trx_id required	string Transaction ID
current_time required	string <date-time> Current time (response timestamp)
	object (Root Type for instInstallment) Installment
	object (Root Type for downpayOptions) Down payment options for checkout page.

Responses

Request samples

Payload

Content type

application/json

{"current_time": "2019-02-10T19:32:25.000+08:00",
"status": "HOL",
"order_id": "xyz-123-abc",
"trx_id": "0b240df0-5501-11e9-8647-d663bd873d93",
"message": "Any message from Billease system"
}

Response samples

200
400
401
500

Content type

application/json

{"message": "OK"
}

Account

Connect Billiease customer account

Receive customer token

Get customer's Billease account token

Authorizations:

Authentication

Request Body schema: application/json

Token

internal_user_id required	string User ID in the merchant's system
token required	string Token
token_id required	string Token/Request ID
email	string Customer email in the merchant's system
phone	string Customer phone in the merchant's system

Responses

Request samples

Payload

Content type

application/json

{"internal_user_id": "user_2345",
"token": "dsjhkDFsjhdf3298shkjdfh38924ybsdfjkDHDqiuewrcnaifGD",
"token_id": "ff1ca792-54fb-11e9-8647-d663bd873d93"
}

Response samples

200
400
401
500

Content type

application/json

Example

OK

{"status": "OK"
}

Deals

Billease Deals fulfilment. Implemented only by partners whose products appear in the Deals catalog; merchants using standard checkout can ignore this section.

Create transaction

Billease Deals partners only. Merchants using standard checkout do not implement this.

We call this when a customer buys one of your Deals products. One call covers exactly one product. The transaction UUID travels in the body as trx_id, not in the path.

Your response is the approval gate

We do not approve the transaction or disburse until this call returns 200. Your success response is the merchant's confirmation that the order is accepted; only then does money move on our side.

That makes the ordering explicit: accept the order, respond 200, and we disburse. If you cannot accept it, return an error and nothing is approved and nothing is disbursed.

What you must do

Authenticate the caller and validate the payload.
If the product is out of stock, do not create the transaction: return 409 with code: OUT_OF_STOCK. We treat that as a soft failure: we set the product's stock to 0 in the Deals catalog and cancel the transaction without raising an integration error.
Otherwise create it and respond 200 with the product's remaining in_stock.

One attempt, no retries

We call this endpoint exactly once; there are no retries. We wait up to 40 seconds for your response; a 4xx, 5xx, or timeout is treated as a failure, and we cancel the customer's transaction on our side without approving or disbursing. Return 200 only once the order is durably committed.

Stock write-back

We read in_stock from your response and write it straight into the Deals catalog. Return the true post-decrement count.

Authorizations:

Authentication

Request Body schema: application/json

The transaction to create

order_id required	string Order ID. Echo it back on every `POST /trx/{id}/update` call.
trx_id required	string <uuid> Transaction ID (UUID). It also goes in the path of the delivery-status update calls.
product_id required	string Your product id, the same `id` you send us on `POST /products/sync`.
amount required	number Amount paid by the customer, in major currency units. Check it against your live price before fulfilling; Billease catalog prices can lag yours while a change awaits approval.
currency required	string Currency. `PHP` by default.
created required	string <date-time> Timestamp when the transaction order creation was initiated on partner side
required	object (Root Type for dealsCustomer) Recipient of the goods, and where they ship. At least one of `email` or `phone` is always provided; for physical goods we send both.
	object (Root Type for dealsSender) The buyer, when the goods were purchased for someone else; sent only for gift purchases such as vouchers, and absent otherwise. Carries no delivery address; the goods ship to the `customer`.

Responses

Request samples

Payload

Content type

application/json

Example

Physical item bought for oneself

{"order_id": "order-123",
"trx_id": "9f1c2b7a-3e5d-4c11-8a6f-2b9d0e7c1a42",
"product_id": "1000001",
"amount": 24999,
"currency": "PHP",
"created": "2026-07-23T08:30:00+08:00",
"customer": {"full_name": "Juan Dela Cruz",
"first_name": "Juan",
"last_name": "Dela Cruz",
"email": "[email protected]",
"phone": "+639171234567",
"adr_shipping": {"addr_type": "shipping",
"country": "PH",
"region": "NCR",
"province": "Metro Manila",
"city": "Makati",
"barangay": "Poblacion",
"street": "123 Rizal St.",
"postal_code": "1210",
"address": "123 Rizal St., Poblacion, Makati, Metro Manila 1210"
}
}
}

Response samples

200
400
401
409
500

Content type

application/json

Example

OK

{"status": "OK",
"in_stock": 41
}

Check a Deals transaction exists (manual)

Billease Deals partners only. Not part of any flow.

A lightweight read-only existence check for a transaction order you created via POST /trx/transaction. Nothing automated calls it; we use it only as a manual, out-of-band way to check, while debugging, whether a given transaction order reached your side. It is not a confirmation or approval step; your 200 on POST /trx/transaction remains the only approval gate.

We look only at the HTTP status code and ignore the body:

any 2xx: the transaction order exists on your side;
any 4xx / 5xx: it does not, or could not be confirmed.

trx_id is the same transaction UUID we sent on POST /trx/transaction. Secure it with the same scheme as your other callback endpoints. The path shown is only a default; choose the exact path as you see fit, the same way you do for POST /trx/transaction.

Authorizations:

Authentication

path Parameters

trx_id

required

string <uuid>

The transaction UUID we sent on POST /trx/transaction.

Responses

Response samples

401

Content type

application/json

"{\n \"message\": \"no Route matched with those values\"\n}"