A partner client is a "Marketing profile“ of a potential or existing customer. It can be an individual (sole trader) or a registered business (partnership, limited company) entity.
Revenue data sharing is an important step for a partner integrating with Liberis. It allows partners to:
- See which partner clients are eligible for revenue based finance and allow Liberis to curate a selection file containing specific offers to be returned to the partner for marketing purposes.
- Link revenue data to a partner client identifier when an offer is created via the 'Get offers' API. This allows us to provide quotes using the revenue data provided in these files.
Ideally, this financial overview of each partner client will be shared using the partner client service revenue API. However, if this is not possible, Liberis will instead accept two files sent via SFTP:
- Partner Clients
- Revenue Claims
* SFTP credentials and allowlist are provided during partner integration and onboarding
The Partner Clients File
The partner clients file gives Liberis a set of pseudonymised rows containing partner client identifiers and entity metadata without exposing personally identifiable information. Liberis combines this with the revenue claims data to build a financial image of each partner client.
When a partner spans multiple geographic jurisdictions, Liberis will treat each country as a separate partner. Therefore we only expect each partner to send partner clients for the single jurisdiction that they are legally registered in. A partner client must represent a legal entity within this jurisdiction.
Constraints:
- The file must be encoded in UTF8
- There must only be one row per partner client. i.e
partner_client_idmust uniquely identify a partner client within a file - Null values, where accepted, are represented by the empty string: “”
- All columns must be present, even if some or all the values are NULL
File Naming
All partner clients files should use the following naming convention:
{partner_name}_partner_client_{timestamp}.csv
Where:
partner_nameis the name of the partner sharing data with us. Liberis will tell you this value.timestampis a ISO 8601 timestamp, with colons and hyphens omitted, indicating when the file was generated.
Fields
| Name | Used to uniquely identify each row | Description | Accepted values | Nullable | Example |
|---|---|---|---|---|---|
| partner_client_id | Yes | Partner client identifier | Any Alphanumeric that uniquely identifies a partner client. it can also contain hyphens, the length limitation is min_length=1 max_length=100 | No | ABC-11111 |
| entity_type | No | Legal entity type of partner client | For UK, one of: - LimitedBusiness - Partnership - SoleTrader - LLP - LLC - OtherCorporation - UnknownFor US: one of: - LimitedBusiness - Unknown - LimitedPartnership - OtherCorporation - SoleProprietor - LLC - Partnership | No | LimitedBusiness |
| trading_start_date | No | Date partner client started trading | ISO 8601 Date | Yes | 2023-02-10 |
| client_start_date | No | Date partner client became a customer of partner | ISO 8601 Date | No | 2023-02-10 |
Definitions
partner_client_id - This is one of two key identifiers used for partner clients. In the campaign processing; the aggregation of a partner clients revenue & other information will centre around this ID. Liberis will always prefer you use an internal (to the partner) ID so that processes around passing data to/from Liberis and the partner are kept as simple as possible. A partner client must represent a legal entity within a single jurisdiction.
entity_type - The legal entity type of a partner client can have an impact on how they’re segmented in the marketing (depending on combined segment choices for a campaign) as well as the risk scoring & decisioning at the point of marketing. For regions other than UK/US, please contact your partner manager for an accepted list of values.
trading_start_date - If known, the date the partner client started trading.
client_start_date - The date the partner client became a customer of a partner. Our underwriting rules require partner clients to have been in business for >=4 months and Liberis uses the date they start with the partner as a proxy for that if the trading start date is not known.
Example
partner_client_id,entity_type,trading_start_date,client_start_date
9fe2c4e93f654fdbb24c02b15259716c,LimitedPartnership,2000-06-29,2022-07-12
c701b7e9c58547949552624528dbb3f8,LimitedPartnership,2009-07-06,2009-07-06
554a17bdeef1461893c965e4f1599496,LLC,2009-07-28,2010-07-06
c91c74c62e1c4626a74824a85de7da2f,SoleProprietor,2020-08-03,2020-08-03
fa4ba750bfbe4df3b560740582b897e7,LLC,2013-08-03,2013-09-03
705882c2c55d4263908cfc0b10fe9bec,Unknown,2024-08-03,2024-08-12
The Revenue Claims file
The revenue summary file contains daily or monthly aggregated information about a partner clients revenue. Liberis uses this data to assess performance and check eligibility, while also apply pricing logic to give a set of offers back to the partner for marketing, or to power our own marketing.
Each row in this file provides a revenue claim - a description of the total monetary amount made and number of transactions completed for a given partner client in a particular currency on a particular day/month, for a given transaction type and particular terminal type.
Multiple revenue claims for a single partner client may exist in a single file. This is to allow a file to contain a break down of a partner clients revenue within a given time period. Note, that each revenue claim that shares the same partner_client_id, payment_channel_id and time_period must describe a unique, non overlapping subdivision of a partner clients overall revenue within that time period, such that aggregating overlapping revenue claims for a particular time period should provide an accurate total for that day or month.
For example, for one partner client there might be separate rows that describe, for the same month:
- EUR, Sales, Card Present
- EUR, Sales, Ecommerce
- EUR, Refunds, Ecommerce
Constraints
- The file must be encoded in UTF8
- There must be at most one row per:
partner_client_id,payment_channel_id,currency_Code,time_period,transaction_type, andterminal_type(i.e these fields, taken together, uniquely identify a row.) - Null values, where accepted, are represented by the empty string: “”
- All columns must be present, even if some or all the values are NULL
File Naming
All revenue claims file should use the following naming convention:
{partner_name}_revenue_claims_{granularity}_{timestamp}.csv
Where:
partner_nameis the name of the partner sharing data with us.granularityindicates the time grain to which transactions are summarised. It can be eitherdailyormonthly.timestampis a ISO 8601 timestamp, with colons and hyphens omitted, indicating when the file was generated
Fields
| Field Name | Used to uniquely identify each row | Description | Accepted values | Nullable | Example |
|---|---|---|---|---|---|
| partner_client_id | Yes | Alphanumeric partner client identifier | Any string that uniquely identifies a partner client. | No | ABC11111 |
| payment_channel_id | Yes | Alpha numeric identifier for card terminal | Any string | Yes | XYZ123 |
| payment_channel_start_date | No | The open date for the specific payment_channel. | ISO 8601 Date | Yes | 2023-02-10 |
| terminal_type | Yes | Whether the terminal is card present, ecommerce, etc. | One of: - CardPresent - CardNotPresent - Ecommerce | Yes | CardNotPresent |
| industry_category_scheme | No | Industry categorisation scheme | One of: - MCC - SIC - Unspecified | No | MCC |
| industry_category_code | No | Code used to identify industry category. Should follow the scheme specified in industry_category_scheme | A valid MCC or SIC code or ‘Unspecified’ if the industry_category_scheme is Unspecified. | No | 5735 |
| currency_code | Yes | Currency in which the transactions are completed in | ISO 4217 alpha-3 currency code | No | GBP |
| time_period | Yes | Month or day covered by the revenue claim | ISO 8601 Date, must be the start of a month for monthly data e.g 2024-08-01 or any valid date for daily data 2024-08-28 | No | 2023-02-01 |
| transaction_type | Yes | Type of transaction - Sales, returns or chargebacks | One of: - Sales - Returns - Chargebacks | No | Sales |
| total_amount | No | Sum of transactions within revenue claim | Positive decimal currency value, without commas | No | 1234.56 |
| transaction_count | No | Number of transactions within revenue claim | Positive integer | No | 102 |
Definitions
partner_client_id - This is one of two key identifiers used for partner clients. In the campaign processing; the aggregation of a partner clients revenue & other information will centre around this ID. Liberis prefers you use an internal (to the partner) ID so that processes around passing data to/from Liberis and the partner are kept as simple as possible. Fundamentally this should be at the legal entity level, as it is one BCA per legal entity.
payment_channel_id – This is the identifying ID for the payment channel being referenced in the record. Can be null if the concept of a payment channel is not applicable.
payment_channel_start_date – This is the start date (with the Partner) of the payment channel. This is used within the offer creation process to identify where revenue volumes are missing whether it’s due to the payment channel not existing, or whether it’s actually not transacting. If the concept of a payment channel is not applicable, leave this column empty.
terminal_type – Where possible we’d like to identify whether a payment channel is F2F, e-commerce, virtual etc. However for some partners this information won’t be available.
industry_category - This is a field used to classify businesses or merchants based on their primary activities, It typically consists of two parts:
industry_category_scheme – A "scheme" which can be either MCC, SIC, or in some cases "Unspecified. MCC (Merchant Category Code) is used by payment brands to classify merchants and businesses by the type of goods or services provided. SIC (Standard Industrial Classification) is designed to describe business entities rather than transactions. In some cases, when the industry category is unknown or not provided, it can be set as "Unspecified"
industry_category_code - A "code" which is the specific classification number within that scheme, it can be “Unspecified” in case the scheme is set as “Unspecified”
currency_code - This is currency that the payments were processed in; enables Liberis to process & price customers correctly without mixing currencies. Whether you separate currencies or not depends on split capabilities – if you are able to apply a split on all currencies within the remit of a single BCA; you can group revenue up into a common currency.
time_period - Date value indicating the month or day of the revenue is is for.
- When sending monthly data, this will be the month, e.g
2024-02 - When sending daily data, this will be a specific day, e.g
2024-02-12
transaction_type - This is used to identify what type of payment record it is. For many of our partners only Sales is available, which is not an issue. Sales is the most crucial whilst Returns and Chargebacks are used to fine-tune the offers and identify potential risks.
total_amount - The value of transactions recorded within a specific time period (e.g., a month or day)
transaction_count - The total number of transactions recorded within a specific time period (e.g., a month or day).
Example
partner_client_id,payment_channel_id,payment_channel_start_date,terminal_type,industry_category_scheme,industry_category_code,currency_code,time_period,transaction_type,total_amount,transaction_count
9fe2c4e93f654fdbb24c02b15259716c,9fe2c4e93f654fdbb24c02b15259716c,2000-06-29,CardPresent,MCC,1111,USD,2023-02-01,Sales,323.45,1330
9fe2c4e93f654fdbb24c02b15259716c,9fe2c4e93f654fdbb24c02b15259716c,2000-06-29,CardPresent,MCC,1111,USD,2023-02-02,Sales,92.20,4443
9fe2c4e93f654fdbb24c02b15259716c,9fe2c4e93f654fdbb24c02b15259716c,2000-06-29,CardNotPresent,SIC,1111,USD,2023-02-03,Sales,45.00,2301
c701b7e9c58547949552624528dbb3f8,c701b7e9c58547949552624528dbb3f8,2009-07-06,Ecommerce,Unspecified,Unspecified,USD,2023-02-02,Sales,53.45,1233
c701b7e9c58547949552624528dbb3f8,c701b7e9c58547949552624528dbb3f8,2009-07-06,Ecommerce,MCC,1121,USD,2023-02-02,Chargebacks,12.46,233
554a17bdeef1461893c965e4f1599496,554a17bdeef1461893c965e4f1599496,2009-07-28,Ecommerce,MCC,1121,USD,2023-02-02,Sales,7.45,920
554a17bdeef1461893c965e4f1599496,554a17bdeef1461893c965e4f1599496,2009-07-28,CardPresent,SIC,1131,USD,2023-02-03,Sales,23.73,2333
c91c74c62e1c4626a74824a85de7da2f,c91c74c62e1c4626a74824a85de7da2f,2020-08-03,CardNotPresent,MCC,1131,USD,2023-02-02,Sales,333.00,4554
c91c74c62e1c4626a74824a85de7da2f,c91c74c62e1c4626a74824a85de7da2f,2020-08-03,CardNotPresent,MCC,1131,USD,2023-02-02,Returns,1000.00,1233
c91c74c62e1c4626a74824a85de7da2f,c91c74c62e1c4626a74824a85de7da2f,2020-08-03,CardPresent,MCC,2231,USD,2023-02-03,Sales,5676.00,678
fa4ba750bfbe4df3b560740582b897e7,fa4ba750bfbe4df3b560740582b897e7,2013-08-03,Ecommerce,SIC,2231,USD,2023-02-01,Sales,985.98,42
fa4ba750bfbe4df3b560740582b897e7,fa4ba750bfbe4df3b560740582b897e7,2013-08-03,Ecommerce,Unspecified,Unspecified,USD,2023-02-03,Sales,6452.00,434
705882c2c55d4263908cfc0b10fe9bec,705882c2c55d4263908cfc0b10fe9bec,2024-08-03,CardNotPresent,MCC,4441,USD,2023-02-01,Sales,8454.45,344
partner_client_id,payment_channel_id,payment_channel_start_date,terminal_type,industry_category_scheme,industry_category_code,currency_code,time_period,transaction_type,total_amount,transaction_count
9fe2c4e93f654fdbb24c02b15259716c,9fe2c4e93f654fdbb24c02b15259716c,2000-06-29,CardPresent,MCC,1111,USD,2023-02-01,Sales,323.45,1330
9fe2c4e93f654fdbb24c02b15259716c,9fe2c4e93f654fdbb24c02b15259716c,2000-06-29,CardPresent,MCC,1111,USD,2023-03-01,Sales,92.20,4443
9fe2c4e93f654fdbb24c02b15259716c,9fe2c4e93f654fdbb24c02b15259716c,2000-06-29,CardNotPresent,SIC,1111,USD,2023-05-01,Sales,45.00,2301
c701b7e9c58547949552624528dbb3f8,c701b7e9c58547949552624528dbb3f8,2009-07-06,Ecommerce,Unspecified,Unspecified,USD,2023-02-01,Sales,53.45,1233
c701b7e9c58547949552624528dbb3f8,c701b7e9c58547949552624528dbb3f8,2009-07-06,Ecommerce,MCC,1121,USD,2023-02-01,Chargebacks,12.46,233
554a17bdeef1461893c965e4f1599496,554a17bdeef1461893c965e4f1599496,2009-07-28,Ecommerce,MCC,1121,USD,2023-02-01,Sales,7.45,920
554a17bdeef1461893c965e4f1599496,554a17bdeef1461893c965e4f1599496,2009-07-28,CardPresent,SIC,1131,USD,2023-03-01,Sales,23.73,2333
c91c74c62e1c4626a74824a85de7da2f,c91c74c62e1c4626a74824a85de7da2f,2020-08-03,CardNotPresent,MCC,1131,USD,2023-02-01,Sales,333.00,4554
c91c74c62e1c4626a74824a85de7da2f,c91c74c62e1c4626a74824a85de7da2f,2020-08-03,CardNotPresent,MCC,1131,USD,2023-02-01,Returns,1000.00,1233
c91c74c62e1c4626a74824a85de7da2f,c91c74c62e1c4626a74824a85de7da2f,2020-08-03,CardPresent,MCC,2231,USD,2023-03-01,Sales,5676.00,678
fa4ba750bfbe4df3b560740582b897e7,fa4ba750bfbe4df3b560740582b897e7,2013-08-03,Ecommerce,SIC,2231,USD,2023-02-01,Sales,985.98,42
fa4ba750bfbe4df3b560740582b897e7,fa4ba750bfbe4df3b560740582b897e7,2013-08-03,Ecommerce,Unspecified,Unspecified,USD,2023-03-01,Sales,6452.00,434
705882c2c55d4263908cfc0b10fe9bec,705882c2c55d4263908cfc0b10fe9bec,2024-08-03,CardNotPresent,MCC,4441,USD,2023-02-01,Sales,8454.45,344
Updating data
Over time, the data you share with Liberis might become out of date. For instance, transaction counts might change due to pending transactions settling. To provide updated data to Liberis, include the revised data in a new CSV file, ensuring that the primary key of the new record matches the one to be updated. Liberis will then use the latest version of each partner client or revenue claim when calculating eligibility and offers.