API Reference
Start typing to search…

About this API

The Liberis Create API

Liberis Create V3 allows external partners to register businesses with Liberis, and provision a multi-product enabled Capital Account - which is a container for all revenue based finance products from Liberis:

Typical Integration Flow

For a merchant to receive financing, this is the typical flow that needs to be completed. Note that most of these steps can be accomplished without an API, but this document assumes that the integrating partner wishes to complete them via API.

  1. Share revenue data with Liberis via API or file transfer. This allows us to generate marketing offers.
  2. Download marketing offers via API or file transfer. This shows a user what they might be able to get if they take financing.
  3. Complete marketing activities. This could be in-dashboard ads, email marketing, marketing through the mail, push notifications, in-app messaging, or any other marketing channel.
  4. Register a business with Liberis and create a capital account.
  5. Generate a quote for the user for the type of cash advance they are interested in.
  6. Apply for the cash advance.
  7. Complete any follow up actions, such as contract signing, required.
  8. Activate the split payment mechanism until the merchant's balance reaches zero.

Using the Marketing Offers Endpoint

The /v3/marketing_offers/{partnerCode}/{partnerClientId} endpoint allows you to retrieve a list of marketing offers for a given partner client ID. These offers are generated in batch over the entire merchant population at an agreed frequency with Liberis.

The purpose of this endpoint is for early positioning of what a user could get, for example to drive a dashboard ad or an email campaign. This endpoint will fail if supplied with a partner client ID (your identifier for a merchant) that is neither registered nor has any revenue data shared with Liberis.

You can use the data supplied on this endpoint to drive marketing activities.

Response Based on Registration Status

  • Registered Users: For users who are registered, the endpoint will return offers that match the available advances from the get capital account endpoint.
  • Unregistered Users: For users who are unregistered, the endpoint will return offers based on their revenue data alone. These offers represent what we believe they can get, in line with the SLAs of the programme.

Scenarios that might change available financing after registration

  1. Credit Bureau Searches: If credit bureau searches are used, the quotes might change for better or for worse to improve the unit economics of the program.
  2. Active Balance and Daily Payments: If a user has an active balance and is making daily payments, it is likely that they will be able to get more and cheaper financing every day.

Weighted Priority

This integer value represents Liberis' reccomendation about which product should be presented to the user based on the goals of the programme, for programmes with multiple products enabled. A higher integer value represents a higher priority.

Do Not Market

The doNotMarket flag is a boolean value, where it is set to true we recommend suspending all credit marketing to this customer. The list of available advances will be empty for customers in this scenario. This flag is typically set when an account is frozen, because they have entered into arrears, because a high impact credit event (such as a bankruptcy or a court judgement) has occured, because there is an ongoing fraud investigation, or because adverse PEPs and Sanctions data has been discovered about the customer.

Approval Type Enum Values

  • PRE_APPROVED: The offer is pre-approved based on the available data, this is a very high confidence offer and would only be declined in exceptional circumstances.
  • ELIGIBLE: The user is eligible for the offer, but additional checks may be required, and the offer may change. This is a lower confidence approval that pre-approved, but almost all eligible merchants will be able to get some level of financing.
  • SPECULATIVE: For partners who want all applicants to be able to apply, you may invite this user to apply speculatively.
  • NO_DECISION: No decision is required for this offer, i.e. it is close to a guarantee. This applies only to Flexi Advances for accounts that have already upgraded to the Flexi Advance account.

Registering a business with Liberis

If a customer has not yet been registered with Liberis, they must be registered before receiving a quote. There is a combined endpoint that allows an integrating partner to simultaneously register a merchant with Liberis and provision them a capital account. This endpoint is /v3/register_business_and_provision_capital_account. This combined endpoint is likely the way you will be registering a merchant, unless you are simultaneously marketing non-revenue based finance products (such as debit cards) to the merchant.

Return values
  • liberisID: This is Liberis' identifier for this merchant. Note that we must enforce uniqueness of merchant, even if they can potentially have multiple accounts in your platform. Subsequent registrations for the same business are likely to fail. If you need to map additional accounts from your platform to an existing merchant, please reach out to your partner manager.
  • capitalAccountID: This is the identifier for the capital account that has been provisioned for this merchant. This is the account that will be used to fund cash advances and will contain the balance for all advances across all revenue based finance products they take up.

Consent

Depending on your own privacy agreement with a merchant, you may need to obtain consent from them to share this data with Liberis. We leave it to partners to decide if their own privacy policies are compatible with Liberis' privacy policy, and to introduce an additional consent check if necessary.

If an additional step is needed, it can be presented as follows

Consent for Data Sharing

(Partner) has partnered with Liberis to provide small business financing to our customers. By (action), you consent for (partner) to share your business details and the details of the owners of your business with Liberis for the purpose of generating fully personalised quotes for your business financing needs. This will have no impact on your credit record.

Get capital account

The endpoint /v3/capital_account/{liberisID} allows you to retrieve the capital account for a given Liberis ID. This endpoint is intended to drive a live journey.

A number of items will be returned with this request.

Balance and last 5 advances

The current balance for this merchant across all advances, and the previous 5 advances taken (including any advances not yet funded).

The balance is broken down into the total balance repayable, and the breakdown of this total in terms of principal and fees.

Advances may be in the following states:

  • PENDING_DECISION: Liberis is making a credit decision on this advance.
  • PENDING_FULFILMENT: The advance is approved, but there are steps to be taken by either Liberis or the Merchant to complete it. If there are steps the merchant needs to take, these are visible in the oustandingActions list.
  • PENDING_DISBURSEMENT: All actions are complete and Liberis will disburse this advance. Depending on the banking rail in use, this may take seconds to days.
  • FUNDED: The amount has been disbursed and the user has received the funds. Note that on some banking rails (such as ACH), it may take several days for Liberis' to be able to confirm that funds have actually been received.
  • REJECTED: Liberis has rejected this advance.
  • CANCELLED: The advance was cancelled by the merchant or because of a long period of inactivity on the outstanding actions.

Advances may have actions listed in outstandingActions, such as contract signature. The integrating partner can usually present these to the customer for self-service fulfilment through the http/iframe, http/web link, or application/json resources specified on the action. If the integrating partner does not get the user to complete these in the application flow, Liberis will follow up directly with the customer to complete.

Only one advance can be in a non-terminal state at any time. Terminal states are CANCELLED, REJECTED, FUNDING_CONFIRMED. Further advances cannot be applied for until the most recent advance reaches a terminal state.

Available Advances

These are the advances available to the merchant right now. Note that unlike the offers endpoint, this is not based on batch data but on a real time analysis of the merchants position. If a merchant has made payments towards a balance since they received marketing, it is likely we will be able to offer them higher amounts at this stage. Each available advance contains a list of resources, which are the ways that the merchant can be directed to take the advance. The simplest way is to show them a web-link following the http/web resource, but you can build a fully embedded journey using the application/json resource instead.

Account Actions

These are actions available to the merchant to take at their account level, such as upgrading their account to a Flexi account if this product is enabled for your partnership. These actions follow the same resources pattern as taking an advance or taking an outstanding action against an advance, with a range of integration options.

Applying for an advance

Each product will require different information to generate a quote.

Applying for a BCA Advance

To apply for a BCA advance, you must

  1. Generate a quote
  2. Use the returned quoteId to apply for the advance
  3. (Optional) complete any outstanding actions. If these are not completed in journey within 1 hour, Liberis will follow up directly with the merchant.

Generate a quote

To generate a quote, you can use the v3/capital_account/{capitalAccountId}/advances/bca/quote endpoint. The endpoint accepts the desired amount, whether or not consent for a bureau search has been given, and the intended use of funds.

The API will return a number of different quotes that correspond to different split levels that the customer can be offered. For example, there might be a value at 5%, at 10%, and at 20%. These represent the amount of the merchants daily receivables that will be diverted to Liberis.

Each quote has a different identifier, which will start with the prefix BCAQUOTE. Note that these quotes are intended to be presented and consumed in journey, so will expire 1 hour after they are generated.

Note that if the maximum or minimum amounts are requested, it is likely that there will only be one level of split available.

Apply for the BCA Advance

To apply for the advance, you can use the v3/capital_account/{capitalAccountId}/advances/bca/apply endpoint. You need to supply the quoteId representing the split option that the merchant wishes to take out.

After hitting the endpoint, an advance will be created immediately either in the PENDING_DECISION state (if a credit decision is outstanding) or the PENDING_FULFILMENT state, if a credit decision has been automatically made.

The advance will not be funded until the merchant completes the outstanding actions, which will be returned in the response, and also listed against the advance in any subsequent calls to the get capital account endpoint.

We recommend building an integration against at least the SIGN_DOCUMENT action, as this is a common outstanding action and will substantially increase your conversion rate.

If the required actions are not completed within one hour, Liberis will chase the merchant directly to complete the actions needed. After one week of inactivity, the advance will be marked as CANCELLED and the merchant will need to be taken through the quoting flow again if they wish to continue.

Hybrid integrations

Partners can choose to only integrate against part of the API. The following integration options are independently available. This can be accomplished by giving the user links (identified by the http/web resource type in each section of the API where resources are listed); which will be per-user links to complete the action.

  • Registering a business
  • Getting a quote and applying for an advance per product
  • Showing the active balance and statements for a merchant.
  • Taking all actions at the account or the advance level.

This may be useful if you want to break up your delivery programme into smaller parts, or you want to launch a new Liberis product without committing to the API integration from day 1.