logo
English
English
API ReferenceSign In

BillEase

Last updated 02/10/2021

You may start testing BillEase by following our API Reference. Use the test API key you have generated from Xendit dashboard.

High-Level API Flow

1. Create Customers

Customer objects are made in order to easily link transactions and payment methods to a certain customer.

A. Merchant sends a POST request to Create Customer API with the required parameters. Make sure customer information is accurate because they may be used for processing refunds or chargebacks.

PayLater requires the following parameters to be set for the customer object:

  • first_name
  • last_name
  • email
  • phone
  • address
  • city
  • postal_code
  • phone
  • country_code

B. Xendit will respond with a JSON with the specified properties, if successful. Else, an error message is returned. The id returned will be the customer object ID that will be used in future transactions that are connected to this specific customer.

You only need to create a customer object once for each of your users. If you have already created a customer object for a customer who used another payment method such as Direct Debit, you may reuse the same customer ID when they choose PayLater for a subsequent transaction. Make sure that the mandatory fields for PayLater are complete.

2. Initiate PayLater Plans

Plan objects are used to provide your end-customer information on the available PayLater/installment plans.

  1. Merchant sends a POST request to Initiate PayLater Plans API with the required parameters. Use the customer ID generated from Create Customer API.
  2. Xendit will respond with a JSON containing an array with the PayLater options. The available payment plans will depend on the order amount and details you have provided in the request.

Order Items

Take note of the mandatory parameters for order_items. This should contain all the information from the end-user’s basket or shopping cart. Incomplete details will result in an error.

TypeRequired ParametersOptional Parameters
PRODUCT SERVICEreference_id, name, net_unit_amount, quantity, url, categorysubcategory, description, metadata
FEE DISCOUNTreference_id, name, net_unit_amount (negative value for discounts), quantitydescription, metadata

Below is an illustration of how to compose the order_items array based on the shopping cart.

Note that the sum of net_unit_amount*quantity must be equal to the amount in the request body.

Paylater Plan

For best practice, you are encouraged to display the plans in your payment page during checkout. This would help your customers decide whether BillEase is the most suitable payment option for their purchase.

Note that the options are meant for reference only. These are estimates calculated by BillEase based on the order details in your API Request. \ \ End-customer will choose their preferred PayLater plan and confirm the final amount for payment within BillEase's checkout page.

Simulate PayLater Plans

Sample Request

json
{ "customer_id" : "49d056bd-21e5-4997-85f2-2127544c2196", "channel_code" : "PH_BILLEASE", "currency" : "PHP", "amount" : 2184.56, "order_items" : [{ "type" : "PRODUCT", "reference_id" : "SKU_123-456-789", "name" : "Dyson Vacuum", "net_unit_amount" : 1234.56, "quantity" : 1, "url" : "www.zngmyhome.com/dyson_vacuum", "category" : "Electronics", "subcategory" : "Appliances", "description" : null, "metadata" : null }, { "type" : "SERVICE", "reference_id" : "SKU_123-456-790", "name" : "Home Cleaning Service", "net_unit_amount" : 1000, "quantity" : 1, "url" : "www.zngmyhome.com/home_cleaning", "category" : "Services", "subcategory" : null, "description" : "1 hour deep cleaning up to 2 rooms", "metadata" : null }, { "type" : "FEE", "reference_id" : "Shipping", "name" : "Standard Rate", "net_unit_amount" : 50, "quantity" : 1 }, { "type" : "DISCOUNT", "reference_id" : "100OFF", "name" : "100 Payday Voucher", "net_unit_amount" : -100, "quantity" : 1 }] }

Sample Response

json
{ "id" : "plp_3d88d952-9505-4ed7-84d3-e8639e99e9c4", "customer_id" : "49d056bd-21e5-4997-85f2-2127544c2196", "channel_code" : "PH_BILLEASE", "currency" : "PHP", "amount" : 2184.56, "order_items" : [{ "type" : "PRODUCT", "reference_id" : "SKU_123-456-789", "name" : "Dyson Vacuum", "net_unit_amount" : 1234.56, "quantity" : 1, "url" : "www.zngmyhome.com/dyson_vacuum", "category" : "Electronics", "subcategory" : "Appliances", "description" : null, "metadata" : null }, { "type" : "SERVICE", "reference_id" : "SKU_123-456-790", "name" : "Home Cleaning Service", "net_unit_amount" : 1000, "quantity" : 1, "url" : "www.zngmyhome.com/home_cleaning", "category" : "Services", "subcategory" : null, "description" : "1 hour deep cleaning up to 2 rooms", "metadata" : null }, { "type" : "FEE", "reference_id" : "Shipping", "name" : "Standard Rate", "net_unit_amount" : 50, "quantity" : 1 }, { "type" : "DISCOUNT", "reference_id" : "100OFF", "name" : "100 Payday Voucher", "net_unit_amount" : -100, "quantity" : 1 }], "options" : [{ "downpayment_amount" : 400, "installment_amount" : 600, "interest_rate" : 0, "total_amount" : 1000, "interval" : "MONTH", "interval_count" : 1, "total_recurrence" : 1, "description" : "Buy Now, Pay Later" }, { "downpayment_amount" : 400, "installment_amount" : 100, "interest_rate" : 0.025, "total_amount" : 1015, "interval" : "MONTH", "interval_count" : 1, "total_recurrence" : 6, "description" : "6 month installment plan" }], "created" : "2020-11-11T16:23:52Z" }

3. Create Charges (One-Time Payments)

  1. Merchant sends a POST request to Create Charges API with the required parameters. Use the plan ID generated from Initiate PayLater Plans API.
  2. Xendit will respond with a JSON containing the charge details with a PENDING status, along with BillEase’s checkout URL where Customer will confirm payment.
  3. Xendit will send a POST to Merchant’s callback_url once PayLater charge status is confirmed SUCCEEDED or FAILED 

Simulate Charges

Sample Request

json
{ "plan_id" : "plp_9d78f88i-4835-4ed7-84d3-d6329e99gh76", "reference_id" : "order_id_456", "checkout_method" : "ONE_TIME_PAYMENT", "success_redirect_url" : "https://merchant.com/order/confirm", "metadata" : { "campaign" : "0%_installment" } }

Sample Response

json
{ "id" : "plc_8cb12305-9bcf-4441-a087-ee0d446e297b", "customer_id" : "49d056bd-21e5-4997-85f2-2127544c2196", "plan_id" : "plp_9d78f88i-4835-4ed7-84d3-d6329e99gh76", "business_id" : "5f27a14a9bf05c73dd040bc8", "reference_id" : "order_id_456", "channel_code" : "PH_BILLEASE", "checkout_method" : "ONE_TIME_PAYMENT", "currency" : "PHP", "amount" : 1284.56, "order_items" : [{ "type" : "PRODUCT", "reference_id" : "SKU_123-456-789", "name" : "Dyson Vacuum", "net_unit_amount" : 1234.56, "quantity" : 1, "url" : "www.zngmyhome.com/dyson_vacuum", "category" : "Electronics", "subcategory" : "Appliances", "description" : null, "metadata" : null, }, { "type" : "FEE", "reference_id" : "Shipping", "name" : "Standard Rate", "net_unit_amount" : 50, "quantity" : 1 }], "success_redirect_url" : "https://redirect.co/goodstuff", "status" : "PENDING", "created" : "2020-11-11T16:23:52Z", "updated" : "2020-11-11T16:23:52Z", "actions" : { "desktop_web_checkout_url" : "https://webcheckout.this/", "mobile_web_checkout_url" : "https://webcheckout.this/", "mobile_deeplink_checkout_url" : "app://deeplinkcheckout.this/" }, "callback_url" : "https://webhook.me/gethooked", "payment_method_id" : null, "voided_at" : null, "metadata" : { "campaign" : "0%_installment" } }
Was this page helpful?
Yes No