Note
This guide and the respective APIs are intended for PSP use only, meaning the PSP will make all the calls directly to Billie. Merchants, however, are not a target group for this integration scenario and will in this context never make calls to Billie directly.
Introduction
This is Billie’s Payment Service Provider (PSP) integration guide, which describes how a PSP can integrate Billie payment methods. It includes an overview of the two main flows (SDK, Payment Page) and a detailed documentation of Billie’s PSP APIs.
PSP activation
To be able to make calls to Billie's PSP API, the PSP data needs to be added and activated by Billie's integration team. The data includes e.g. fees, bank account, payout frequency.
Once the PSP is activated, it gets a PSP_ID and API credentials assigned.
Merchant activation
Once the PSP is activated, they can start activating their own merchants with Billie. This happens by calling the merchant activation endpoint. The PSP sends the merchant details and Billie responds back with a merchant ID. The PSP will then store the merchant ID and can start using it for initiating payment sessions, capture, refunds etc.
Payment flows
Billie offers 2 payment flows for PSPs. The first and easiest to integrate is via a redirect to a payment page hosted by Billie. All the interactions with the buyer will happen within the page, and the buyer will get redirected to the merchant shop after a successful or failed authorization.
The second flow is via Billie’s JavaScript SDK, which allows loading Billie's widget in the merchant checkout page. The SDK flow provides a better buyer experience but it requires more development effort for the PSP.
Payment page
This Payment Flow is with a redirect payment flow. The payment is completed with shoppers redirected to the Billie Payment Page to verify and complete the payment. In order to initiate this flow, the PSP should make a call to the create payment page session endpoint. The response contains a URL of the payment page. The shopper should then be redirected to the payment page.
Once the payment is successful, the buyer will be redirected back to the URL provided by the PSP and a webhook containing the details about the authorized order will be sent to the PSP. The payload of the Authorization webhook will include a status property to indicate if it was successful or not.
Here is an example of how this flow would look like:
SDK (widget)
With SDK flow, the payment is completed without the buyer leaving your website or app. Billie’s widget is loaded directly on the merchant’s e-shop. The difference with the payment page flow is that instead of returning a payment page URL, Billie would return a session ID that should be used to load the widget using the Billie SDK. The details about the success or failure of the authorization will be passed back by the SDK to the PSP.
If the order is successfully authorized, the PSP should send the successful order details to Billie by calling the confirm endpoint and including the same order details as received from the SDK.
Here is an example of how this SDK flow would look like:
APIs authentication
The API authentication is done using the API credentials that were issued at the PSP activation and HTTP Basic auth.
The credentials consist of two elements:
Username that consists of your PSP_ID combined with a random string and a password that will be generated using an expiring link sent separately by Billie’s team.
The credentials should be sent as an authorization header for every request with the username and password. You can start exploring Billie’s PSP API here.
Note
API credentials are different for Billie’s sandbox and production environments.
Error Codes
After submitting a call, you receive a response result to inform you that your request was received and processed.
Depending on the HTTP status code of the response message, it is helpful to build some logic to handle any errors that a request or the system may return.
400 - Bad Request
A problem reading or understanding the request.
401 - Unauthorized
Authentication required.
403 - Forbidden
Insufficient permissions to process the request.
409 - Conflict
A request conflict with the current state of the target resource.
422 - Unprocessable Entity
A request validation error.
500 - Internal Server Error
The server could not process the request.
Webhooks
Authorization webhook
The successful result of the purchase authorization in the Billie Payment Page Payment Flow.
Response:
{
“order_id”: UUID
“success”: “true”
}
Buyer post purchase experience
Billie handles the post purchase experience with buyers directly, meaning no involvement from PSP or merchants required when it comes to payment instructions, invoices (where available), order management by buyers or dunning and collections related communications.
Buyer communication
- Payment instructions on capture
- Reminders
- Dunning and collection
Buyer Portal
- Full overview of all Billie payments
- Access to Billie invoices and credit notes
- Buyers can chose to pay by direct debit or transfer even post checkout
- Our customer support is available for your customers’ requests
- Self service with Buyer Portal features or via the help center