Getting Started

---

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.

---

Checkout Option

Specifications

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 EUR.
• 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.

---

Communication Flow

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:

1. 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 and redirect_url. The 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_id value 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.

2. The customer completes finloup process, then finloup platform calls the update order endpoint/request handler, by providing the lead_id as a GET parameter. This endpoint/handler must be implemented on the ecommerce platform.

Indicative request

https://example.shop.com/finloup/update_order?l=<lead_id>

3. The customer completes finloup process and is redirected back to the eshop to a redirect page (return page) by providing the lead_id as a GET parameter. This request handler must be implemented on the ecommerce platform.

Indicative request

https://example.shop.com/finloup/user_return?l=<lead_id>

4. 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.

---

API Attributes

The finloup API is organized around REST. It uses standard HTTP methods & response codes and returns JSON-encoded responses.

ATTRIBUTE	VALUE
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
API RESPONSE	JSON
AUTHENTICATION TY	Bearer Token (API KEY)
FINLOUP CERTIFICATE	Valid TLSv1.2 certificate
API KEY TOKEN	String (max_length=41)
API MERCHANT ID	UUID4

---

Token Authentication

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.

HTTP

Token Authentication

Authorization: Bearer <YOUR_API_KEY>

cURL

Token Authentication

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.

---

Webhooks Validation

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.

Webhook signature header

x-finloup-auth: sha512(<YOUR_API_KEY>:<SALT>)

---

Response Codes

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>

---