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

Column	Description	Format	Used for event
`event_date`	The date of the event in string format.	ISO 8601-compliant string	All
`event`	The type of event (e.g., notification type).	one of: `awaiting_split_validation`, `deal_started` , `deal_complete` , `deal_renewed`	All
`application_id`	The unique identifier for the application.	Liberis Application ID	All
`merchant`	The Liberis unique identifier associated with the merchant.	Liberis ID	All
`external_merchant`	The external identifier for the merchant, as known to the Partner.	Partner Merchant ID	All
`deal_id`	The unique identifier for the deal.	Liberis Deal ID	All
`action`	Requires a Response action from Partner (detailed below)	one of: `ps-notify`	`awaiting_split_validation`
`type`	The type of notification or event.	Deal type	`deal_started`
`balance`	The balance amount associated with the notification.	decimal	`deal_started`
`currency`	The currency of the balance (e.g., "USD").	3 char ISO code	`awaiting_split_validation` , `deal_started`
`start_date`	The start date of the deal or event.	ISO 8601-compliant string	`deal_started`
`repayment_amount`	The repayment amount associated with the deal.	decimal	`deal_started`
`funded_amount`	The funded amount for the deal.	decimal	`deal_started`
`split_percent`	The percentage split for repayments.	decimal	`deal_started`
`factor_rate`	The factor rate applied to the deal.	decimal	`deal_started`
`estimated_length_months`	The estimated length of the deal in months.	integer	`deal_started`
`end_date`	The end date of the deal or event.	ISO 8601-compliant string	`deal_renewed`, `deal_complete`

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 /Inbound/Notifications/{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:

Column	Description	Format
`event_date`	The date of the event in string format.	ISO 8601-compliant string
`action`	The type of action	one of: `ps-notify`
`success`	Whether the Partner response to the notification should be considered successful or not	`true` or `false`
`external_merchant`	The Partner's identifier for the Merchant.
`deal_id`	Liberis Deal ID - used for cross-referencing
`errors`	A piped array of Errors that indicate why the action should not be considered successful. Must be empty if `success` is `true`	one or more of Response Errors listed below in the format `error 1\|error 2`

Liberis will poll the /Inbound/Notifications/ 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:

Error Message	Definition
MultiSettlement	Partner unable to be set up due to issues with MID hierarchy
MIDNotFound	Liberis MID on file does not match Partner MID
ExistingSplit	Existing split on MID will prevent Liberis' Split being applied
LegalEntityNotFound	Liberis legal entity on file does not match Partner legal entity for this merchant
FasterFunding	Merchant has faster funding facility in place which prevents Partner from applying Liberis' Split
Enforcement	Merchant account is subject to enforcement authority measures
BankDetailsNotFound	Liberis bank details on file do not match Partner bank details
SignatoryNotFound	Liberis primary applicant is not the account holder/primary on Partner system
CDDChecks	Partner undertaking additional customer due diligence checks
DebtDiverts	Partner fees are taken from the merchant before they receive their transactions so split can't be applied
WAF	Withhold all funds
NotTransacting	Merchant does not meet transaction check requirements

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.

Failure Reason (Readable)	Enum Response	Explanation
Multi Settlement	MultiSettlement	Challenges related to MID hierarchy.
MID Mismatch	MIDNotFound	Discrepancy between Liberis and Partner MID.
Existing Split	ExistingSplit	A current split on MID blocks Liberis' Split.
Legal Entity Mismatch	LegalEntityNotFound	Disparity between Liberis' and Partner's legal entity records.
Faster Funding Active	FasterFunding	A faster funding facility is active, hindering Liberis' Split.
Net Settlement	NetSettlement	Processor deducts fees prior to merchant payout.
Enforcement Measures Active	Enforcement	Merchant's account is under enforcement authority scrutiny.
Inconsistent Bank Details	BankDetailsNotFound	Mismatch between Liberis' and Partner's bank records.
Signatory Discrepancy	SignatoryNotFound	The primary applicant in Liberis doesn't match the primary record in the Partner's system.
CDD (Customer Due Diligence) Checks	CDDChecks	Partner conducts additional customer due diligence checks.
Debt Diverts or Net Settlement	DebtDiverts	Partner fees deducted from the merchant before they see their transaction, preventing split application.
WAF (Withhold All Funds)	WAF	Account is on a full hold.
Insufficient Transactions	NotTransacting	Merchant fails transaction checks.

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