Split Setup & Confirmation Guide

Liberis uses the Split setup procedure during a merchant's Prefunding checks. As a partner, you'll receive a request to set up a split using one of several mechanisms:

• File Exchange via SFTP
• Liberis Create API Merchant Endpoint

Once you receive this request, your task is to process it and convey the outcome of the split setup attempt. Liberis will then evaluate the results, culminating in either a funded or declined application.

File Exchange - Automated Split Setup Request & Response

In an approach very much like our Webhooks, we will publish Notifications via CSV that can be downloaded from Liberis sFTP server, and parsed for you to take action. Based on the Notification action, we may require you to respond, again via CSV uploaded by you to our sFTP server.

The Notification Events and Responses replicate those for Webhooks but the details are replicated here for clarity.

Events: Awaiting Split Validation awaiting_split_validation

This Notification acts as the initiation signal for validating a partner split deal. Upon receipt of this Notification, you are required to conduct preliminary checks to ascertain your capability to apply a split for the merchant. This is a crucial step to proficiently process the partner split deal. It's imperative to confirm each application or removal of a split, ensuring a structured validation process. It is important to note that during this initial checking phase, the actual split should not be applied. The aim is to determine the feasibility of applying a split for this merchant before proceeding to the actual application of the split.

This event will require a Response (detailed below) in order that you acknowledge receipt of the event, and are happy for Liberis to continue with setting up the e-split.

Events: Deal Started deal_started

Triggered when a deal is funded by Liberis, marking it as active.

Events: Deal Complete deal complete

Triggered when an active deal is concluded normally, indicating its inactive status.

Events: Deal Renewed deal_renewed

This Notification is used to inform partners that a merchant's deal is complete because it was renewed by a new deal. The shape of the data is the same as the deal_complete Notification above. If a deal is renewed you should expect a deal_renewed Notification for the original deal and a deal_started Notification for the new deal to arrive in quick succession.

Notification CSV File Format

Each row of the Notification CSV file will represent an Event that will require action by you, the Partner. The columns will be populated based on the event as described in Used for Event

All columns will be strings, however their format is described in Format, so for example event_date will be an ISO 8601 string and look like 2023-02-06T13:40:00Z which can be parsed as a Date/Time

A CSV file containing one or more Notifications will be published on a schedule. The filename will be in the format liberis-outbound-notifications-{partnherCode}-{timestamp}.csvwhere PartnerCode is the pre-shared identifier Liberis uses to reference you, the Partner, and Timestamp is a Date/Time formatted string in the format yyyy-MM-dd-HH-mm-ss

This file can be generated at any time, so it is recommended that Partner's poll for new files as frequently as they are prepared to handle. Any Notifications that have not been published will appear in a new file.

It should not be the case that an Event for a Merchant will occur twice unless there has been manual intervention by either Liberis or you, but it should be considered that the latest Notification supersedes any previous.

Each Notification has a number of identifiers. Partners will know the external_merchant, and Liberis will know the merchant.

Notification Response CSV

Where a Notification requires a Response, it should be uploaded in the following format to Liberis sFTP in the /Notifications/Inbound/{partnerCode}-inbound-notifications-{timestamp}.csvwhere PartnerCode is the pre-shared identifier Liberis uses to reference you, the Partner, and Timestamp is a Date/Time formatted string in the format yyyy-MM-dd-HH-mm-ss

The format of the Response file should be:

Liberis will poll the /Notifications/Inbound/ folder for files that match the agreed filename format regularly - it should be assumed this could be up to every 5 minutes.

Response Errors

A non-exhaustive list of error codes that can be supplied in response to a failed action is as follows:

File Exchange -Manual Split Setup Request & Response

A single file manages the interaction between Liberis and the Partner for split setup requests and responses:

• Columns in Purple: Populated by Liberis to request a split setup.
• Columns in Green: Must be completed by the Partner to indicate the outcome.

Any issues faced during the process are explained in the ‘Failure Reasons’ section.

Access: File transfers occur through the Liberis SFTP, provided during integration.

Template: Daily Settlement Request Template

Flow:

Liberis Create API Merchant Endpoint

The Liberis Create API's Merchant Endpoint enables clients to access Application and Deal details for active or prospective merchants. As applications transition through Liberis KYC/KYB checks, the application.status will reflect the changes. We suggest daily polling of this endpoint, allowing you to stay updated on the status. This ensures timely communication to the merchant or to facilitate a split setup.

When the application status reaches Funded, you should initiate a split using the application.pricing.split_percent.

Flow:

Barriers to Funding

Liberis mandates several checks when establishing a split. If a barrier arises during split setup, you should include this in the returned file to enable Liberis intervention.

By maintaining adherence to this guide, partners ensure a smoother and more efficient split setup process.