Renewing a deal

What is a Renewal?

A renewal is the process of existing merchants with active or recently active deals topping up or taking out additional finance with Liberis.

Who can renew?

The rules for renewal eligibility change based on jurisdiction or country. The minimum paid down % before a merchant can be processed for eligibility is 50%. This does not guarantee they will be eligible however as many other factors are considered based on their existing deal.

Initial vs Renewal applications

A renewal application is intrinsically similar to initial applications, however they rely on existing data held by Liberis in order to populate application data and calculate potential offers. This greatly simplifies the requirements of the API in contract to initials applications.

In initial applications, Liberis requires a large payload of merchant onboarding data to be provided as seen in the offers endpoint documentation. This is the first time Liberis has known about the merchant, and so we need a lot of data to satisfy KYC/KYB checks, run our auto-decisioning software and calculate offers.

At the point of renewal, Liberis already has historic and accurate data on the merchant, including revenues and payment history. This allows us to process an application end-to-end without any additional data provided by the partner.

The Liberis ID

Renewing hinges primarily on the use of the Liberis Id. When first creating an initial application for a merchant using the /offers accept endpoint, the API returns a liberis_id:

/offers/accept response

{
  "application_id": "e28867f5-3730-488b-970e-ce5567999b5c",
  "liberis_id": "88054d65-aa2d-4ff8-a1c3-209c2b66a353",
  "offer": {
    ...
  },
  "links": {
    ...
  }
}

This is Liberis' own identifier for the merchant after the point of application. It is used to query the /merchant endpoint which acts as the primary initiator for the renewals flow. It is therefore of paramount importance this identifier is stored at the point of initial application, as it is used throughout the lifetime of the merchant with Liberis regardless of number of initial or renewal applications.

Requirements to renew through the API

There are two mandatory requirements to be able to renew via the API:

A connection to the /merchant endpoint or renewal eligibility webhook (TBD)
The merchant endpoint returns a list of deals. A single merchant can only have one active deal at a time, and so the partner must base any renewal attempt on that particular deal. On the JSON below, we can see an active deal highlighted by the 'active' field being true. This is the deal we therefore want to show the merchant via a dashboard, including their eligibility to renew through the performance.renewal_eligibility boolean.

Merchant endpoint response with renewal eligibility

{
  "deals": [
    {
      "id": "5001a000002bsyxcch",
      "application_id": "6df65a6e-e6f5-e372-b157-e06b5427defb",
      "type": "Initial",
      "status": "Funded",
      "active": true,
      "balance": 13500,
      "currency": "GBP",
      "performance": {
        "performance": 80.5,
        "progress": 10,
        "renewal_eligibility": true
      },
      "pricing": {
        ...
      },
      "transactions": [
        ...
      ]
    }
  ]
}

A connection to the offers endpoint and the ability to submit a liberis_id to it.
- This is dependent on the caching/storing of the liberis_id by the partner for merchants created from the initials flow.

API Flow

Following the flow highlighted below, the basic renewal flow consists of:

Merchant accesses partner dashboard / landing page
Partner identifies merchant has a Liberis Id saved against them in their system
Partner requests merchant data from the /merchant endpoint using merchants Liberis Id.
Partner checks the merchants currently active deal performance.renewal_eligibility
If deal performance.renewal_eligibility = true, show a 'You're eligible to renew' advert / widget.
When a merchant clicks the CTA to start a renewal application, the partner calls the /offers endpoint with the liberis_id on record for that merchant.
Liberis pulls data from previous/existing deals, calculates offers and returns them to the partner.
Partner displays offers to merchant
Merchant accepts offer on UI
Partner calls /offers accept endpoint with offerId
Liberis fills application with existing data and submits to team for fulfilment.
Application is fulfilled and funded.

API Request

As discussed earlier, the API request body for the POST /offers endpoint differs between initials and renewals, with initials requiring a full set of merchant profile information to process an application.

Initial example request

curl --request POST \
     --url https://api.eu.liberis.com/v2/offers \
     --header 'content-type: application/json' \
     --data '
{
  "application": {
    "merchant_id": "XO1234567890",
    "liberis_id": null,
    "intended_use_of_funds": "Purchase Stock",
    "currency": "GBP"
  },
  "consents": {
   ...
  },
  "applicants": [
    {
      ...
    }
  ],
  "company": {
   ...
  }
}'

In contrast, a renewal application request simply requires the merchants Liberis Id to be passed and basic application information:

Renewal example request

curl --request POST \
     --url https://api.eu.liberis.com/v2/offers \
     --header 'content-type: application/json' \
     --data '
{
  "application": {
    "merchant_id": "XO1234567890",
    "liberis_id": "73df26ae-2033-40da-9a04-3820f6653b24,
    "intended_use_of_funds": "Purchase Stock",
    "currency": "GBP"
  }
}'

The response for both initials and renewals are exactly the same, a payload of all potential offers. In the case of renewals, we've just calculated the merchants offers based on the existing data we have on them.

Offers example response for initial and renewal

{
  "products": [
    {
      "product_id": "fc12964d-0880-41fa-ba21-8bb41f90cdae",
      "name": "BCA",
      "description": "Business cash advance, repay in line with your revenue.",
      "decision": "Accepted",
      "repayment_mechanism": "terminal_split",
      "limits": {
        "minimum": 5000,
        "maximum": 25000
      },
      "offers": [
        {
          "offer_id": "c1390cb3-fbdb-4564-8d68-acd80863f5af",
          "offer_status": "Eligible",
          "description": "Fastest Repayment",
          "split_percentage": 7,
          "term_length": 3.89,
          "repayment_amount": 54500,
          "funded_amount": 50000,
          "factor_rate": 1.09,
          "currency": "GBP"
        }
      ]
    }
  ],
  "expiresAt": "2022-10-27T00-00-000Z"
}

Accepting a renewal offer

Accepting an offer is exactly the same as in the case of an initial, simply POST the offerId to the /offers accept endpoint. Related links for the renewal application will be returned in this payload, Click2Sign links for example.