Purpose & Scope
This page provides details about the specifications and steps required to connect an ecommerce platform with finloup’s Buy Now Pay Later service as a checkout option. Its purpose is to guide for custom integrations with the use of finloup API endpoints.
Finloup payment option must be presented as a checkout option, along with the rest of the checkout options already available on the ecommerce platform.
finloup as a checkout option should be available if all the following conditions are true:
- Finloup payment method is enabled on the ecommerce platform.
- The total cart value does not exceed a predefined value (max cart value) – this value must be configurable on the ecommerce’s administration panel.
- The total cart value is not lower than a predefined value (min cart value) – this value must be configurable on the ecommerce’s administration panel.
- The order currency is
- Regular receipt has been selected by the customer; no invoice is currently supported.
(The “total cart value” is the final price the customer has to pay, including product values, applicable taxes, discounts and shipping costs.)
Optionally, the merchant may choose to allow only certain products to be purchased with finloup (finloup eligible products). In that case, the finloup checkout option should be available only if all cart products are finloup eligible. Various ecommerce platforms provide different ways to mark products as finloup eligible:
- WooCommerce: Tags, Categories
- Shopify: Tags, Categories
- Magento 2: Categories, Attributes
Currently, finloup’s service as checkout option is offered by redirecting the customer to finloup’s platform. After the customer has completed finloup’s process, the customer is redirected back to the ecommerce platform. When the customer is redirected back, the order should be updated according to the status of the finloup process.
Authentication with finloup’s API is conducted with the use of credentials provided by finloup:
- Merchant ID
- Merchant API Key
Finloup as a checkout option should indicate the total price of the cart divided by 4 and rounded-up to second decimal digit. This value is the instalment amount that the customer will pay each month. The first instalment is paid at the end of the finloup process.
The flow of communications between the customer, the ecommerce platform and finloup’s service is presented on the following diagram:
The endpoint calls between finloup’s service and the ecommerce platform are the following:
The customer selects finloup as a payment option and submits the checkout form. Then the ecommerce platform calls the Create New Lead API endpoint. The response includes
lead_id(UUID4) is a unique identifier for that specific attempt to pay with finloup instalments. Then the ecommerce platform redirects the customer to the
redirect_url. The ecommerce platform should store the
lead_idvalue on a database table along with the order’s id. After the user is redirected to finloup, the eshop order status should change status to “Pending” or similar.
The customer completes finloup process, then finloup platform calls the update order endpoint/request handler, by providing the
lead_idas a GET parameter. This endpoint/handler must be implemented on the ecommerce platform.
- The customer completes finloup process and is redirected back to the eshop to a redirect page (return page) by providing
lead_idas a GET parameter. This request handler must be implemented on the ecommerce platform.
- In both cases, either finloup service calls the eshop update order endpoint or the customer is redirected back to the eshop, the eshop must call finloup Lead Status endpoint. This endpoint returns the status of the finloup process. If status is “COMPLETED”, then the customer should be presented with the “Success” or “Thank you” page and the order should be updated to a relevant status (“Paid” or “Processing”). On any other case the customer should be presented with the checkout page in order to select a different payment method, along with an error message that the finloup process was not completed.
The finloup API is organized around REST. It uses standard HTTP methods & response codes and returns JSON-encoded responses.
|PRODUCTION API GATEWAY URL||https://app.finloup.com/|
|DEMO API GATEWAY URL||https://demo.finloup.com/|
|API GATEWAY PORT||443/TCP|
|API TYPE||REST API|
|AUTHENTICATION TY||Bearer Token (API KEY)|
|FINLOUP CERTIFICATE||Valid TLSv1.2 certificate|
|API KEY TOKEN||String (max_length=41)|
|API MERCHANT ID||UUID4|
The finloup API uses bearer token-based authentication. An active API token (API key) have to be included in the header of the requests in order to be authenticated.
Authorization: Bearer <YOUR_API_KEY>
curl https://app.finloup.com/<FINLOUP_ENDPOINT> -H 'Authorization: Bearer <YOUR_API_TOKEN>'
API keys are provided by finloup and updated yearly. You can view, copy or change your API key through the Developer's Section of the finloup Admin Tool.
Every webhook received by finloup is signed with a validation header (x-finloup-auth). The header is generated by hashing (SHA512) your API key along with a salt that will be provided to you by finloup.
finloup API uses conventional HTTP codes to indicate the status of the request.
2xx codes indicate that the request
was handled successfully.
4xx codes indicate an error that occured in the clint side. Finally,
5xx errors indicate
an unexpected error in the server side, which the server could not handle successfully.
You can read more about Response Codes in the Response Codes section.
comment: <finloup API's Postman collection by clicking here.>
comment: <To import a collection in Postman, select Collections > Import > Upload Files and select>