Introduction

This guide should help you to understand the flow of a BNPL transaction with Billie and how to get your system to interact properly with Billies system to guarantee a smooth money flow.

In general, you need to authenticate as a merchant to be able to initiate a transaction. With the Authentication Token you can interact with Billie.

The lifecycle of a transaction starts with the creation of an order. For that you can start from different channels. There is a flow to create an order from a frontend like a shop as well as directly out of your backend servers.

Order creation with customer interaction

To create an order, a checkout session needs to be initiated with the order data. After that, the buyer is redirected to the Billie Hosted Payment Page to authorise the order. After that, the buyer is returned to you. To finalise the order you need to confirm the order with the data sent to you with the authorised order.

Order creation from a back end system

If you create the order from the backend, you just need to send the order data to Billie and you get the response if it was created or declined.

The order

Once an order is created the processes are joined to ease up the manageability of the orders in all lifecycle states. Fom here you just need to follow one path.

Now you have a confirmed order in your system, as well as Billie. You have the option to update the order with your own Invoice Number or to reduce the amount of the order after creation. Also, you have the option to cancel the order completely.

Confirm Shipping and Capture an Order

The next step is to send the message to Billie, that the order is shipped and to submit the invoice regarding the shipping. At this point it is important that your invoice does not contain your bank details and that the payment instructions point out to follow the instructions Billie is sending the customer in a follow up mail.

You can announce a full shipment as well as a partial shipment. If it is a partial shipment, the invoice amount has to be the regarding partial amount, not the full amount. With telling Billie that the order is (partially) shipped you will receive the invoiced amount in a time according to the agreement with Billie. It is mandatory that you first ship the goods and afterwards send the notification to Billie. In the documentation this process is referred to as Capture as it is the call to receive the money. In the API it is the resource invoice.

The state of the capture is always available by request, and you have to add your own invoice Number and invoice document during or after the capture call. This information is helpful in Billies communication with the customer to match the Billie Payment Request with your invoice.

Managing Captures

If there is a need to extend the due date of the invoice due to a valid reason you can do this also by request. To do so you have to submit the full length of the payment term, not only the additional time.

If the customer paid you by accident, you have to tell Billie. You will send a request with the paid amount and Billie will reduce the outstanding amount accordingly and debit the amount you provided from your upcoming settlement.

If you need to refund a capture, you can refund the capture partially or full. If you cancel a capture this is equal to a full refund.

During the order lifecycle Billie is sending proactive state changes to you that you need for your own systems to validate that Billie and your systems are in sync. The messages are related to order states and about the customers payment behavior.