Two Types of Order Creation

Order creation can be done in two ways.

You can enable your customers to place orders by themselves through the Billie checkout widget. This is normally the use case for online shops. This is described in scenario 1.

You can create orders directly from your backend without customer interactions. This is normally the case for orders coming from other sources or channels, such as telesales. This is described in scenario 2.

If you are receiving the order from other sources or channels (such as telesales), you can create orders directly from your backend without customer interaction. This is described in scenario2.

Scenario 1: Using the Widget
If the customer is present and creating the order by itself you will be using the Billie Widget to let the customer interact with Billie to provide its consent to the transaction.

Scenario 2: API-only
If the customer is placing and confirming an order via a channel directly connected to your backend and you only need to submit the order to Billie, then you can use a direct API call to create the order.

In both cases, Billie will then do a risk check in real time. Based on the risk check, you will receive a result in the form of an order state.

Order States

❗️

Declined

This order state is final for both Widget and Direct API. Declined customers need to choose another payment method. This option needs to be built into the flow as declined orders are expected to happen from time to time.

👍

Approved

This state is only available for the Widget. After an order is approved by the customer and Billie, you need to submit the order confirmation from your backend to finalize it and make it confirmed.

☑️

Confirmed

This order state is final for both Widget and Direct API. If the order was created through the Billie Widget, this state happens after approved. If the order was created through a direct API call, this state will be an instant answer for a outcome is positive.

Confirmed and Declined are the final state for both flows, Widget and Direct API.

At the end of the order creation process, you will receive a UUID that you need to store, as it is the main identifier for all orders in regards to Billie. You will also receive bank details that your customers must use to pay their invoice.

🟦

The bank details must be added to the invoice you send to your customers, or at least a note that Billie will send payment details soon.

🟨

Do not print your own bank details on the invoice. The customer must pay Billie, not you.

Authenticating yourself

All API operations are secured by OAuth 2. This is following the default process of this well-known industry standard. Obtaining a token is described in the section Request OAuth Token.

Using the widget

After obtaining the token for authorization, you will need to create a Session ID. This Session ID is needed to initiate the widget that the customer uses to give his consent to the transaction. The call is issued from your backend system.

The used API call is Checkout Session Create.

The Session ID you receive as result will be used to initiate the widget. Here is the data required to initiate the Widget:

You can find details about the widget initialization in the Billie Docs: Checkout Client.

The widget returns the state of the order after Billie and the customer approved the order. On Success, the next step is to confirm the order from your backend. This is the last step of gathering the consent of all parties (Billie, customer and merchant), so it is really important to finalize the order confirmation.

🟨

The amount that you submit in the confirmation call must not be higher than the amount submitted in the widget. If you have something like rounding errors from time to time, be aware that this can prevent a successful confirmation if the amount in the confirmation is higher than in the initialization.

🟨

Be aware that the response object of the widget contains data that you need to use in the order confirmation call. You have to read the response and transform it to the request object format of the order confirmation.

You can copy the duration, objects delivery_address and amount to the new request object. The debtor object needs to be refactored.

"debtor_company": {

   "name": "Billie GmbH",

   "address_house_number": "4",

   "address_street": "Charlottenstr.",

   "address_postal_code": "10969",

   "address_city": "Berlin",

   "address_country": "DE"

 }

"debtor": {

     "name": "Billie GmbH",

     "company_address": {

       "house_number": "4",

       "street": "Charlottenstr.",

       "postal_code": "10969",

       "city": "Berlin",

       "country": "DE"

     }

}

To confirm the order you will use the Checkout Session Confirm API call

Backend order creation

You can create orders from your backend after the customer has placed an order with you via another channel like telesales, email etc.

For that, you have to call the Create Order API call. This is the only call needed from the backend and it will be instantly answered with either confirm or decline.

Here is the data required to create an order via backend:

🟦

Save and attach the returned UUID of the order creation or order confirmation to your own order data, as it will be the main identifier used to manage the order during its lifecycle.

Legal Forms

For a successful order creation call, you have to submit the legal form of the customer. You can get the legal forms and the associated codes by calling the the Get Legal Forms endpoint. As a response to this request, you will receive a list of legal forms that you can use to match against the legal form of your customer. The list of legal forms contains a code for each legal form. You will use use these codes to match the information your customer submitted.

Best Practise:

• Keep the list of legal forms somewhere accessible and refresh it once a day.
• Do not call the Get Legal Forms endpoint before each Create Order call.

You will use the API call Get Legal Forms.