Introduction to Onboarding

Partners can onboard merchants for cash advance via their own user experience powered by YouLend's APIs, or YouLend can host a co-branded experience. This page concerns onboarding a merchant via API.

Partners can choose varying levels of integration with our Onboarding API; they can either submit partial or fully completed applications along with supporting documentation.

Overview

Most integrations with the Onboarding API will cover the following steps:

1. Create an application (create a "lead")

Create a financing application.

🚧

Be aware

YouLend expect partners to have adequate justification for sharing personal detail about a merchant and that the merchant has agreed that their personal details will be shared with YouLend and processed in line with YouLend's Privacy Policy and Terms of Service

📘

Good to know

  1. Partners can use the variable thirdPartyCustomerId to share their own internal customer ID for the merchant, making it easier for partners to match the lead to their internal systems
  2. Partners can use this endpoint alone, at which point either the merchant can be redirected to the signUpURL from the 200 response for them to complete the application, or YouLend can reach out to the applicant to request more information to complete the application

2. Enrich the application to enable a YouLend decision

Provide enough information to YouLend about a merchant that YouLend can provide a decision about whether financing can be offered to the merchant. You will need to ensure that the following minimum information is provided, unless you have agreed otherwise with your YouLend Implementation Manager:

  1. Submit bank statements for the merchant either as files or in JSON format. YouLend requires at least 3 months of history, but if the partner can provide a longer history of data, then YouLend can provide more generous offers.
  2. Submit information about the Directors and Ultimate Beneficial Owners of the business Update significant persons.
  3. Optional Submit information about the merchant's sales with Submit payment data documents or Submit JSON payment data.

📘

Good to know

Merchants will typically receive the most generous offers when YouLend is provided with more than 12 months' of sales or bank data

  1. If merchant is applying for >£/€100,000: Submit management accounts for the merchant.
  2. Finally, YouLend needs consent from the merchant to perform credit checks which are 'soft' in the sense that they do not impact the credit score of the merchant. In some cases, YouLend may need proof of identity which can be copies of government-issued ID such as passports or driver's license.

3. Submit the lead to YouLend for decisioning

Inform YouLend that the lead is completed, and that YouLend should start the automated decisioning process.

YouLend will return a 200 response when the lead has been successfully submitted. See below for an error response example if YouLend is missing data to review the lead.

Example 400 response

{
    "errorType": 11,
    "data": "[\"Payment data\",\"Organisation details\",\"Bankstatement details\"]",
    "description": "Please check that you've submitted the Organisation details and Payment data/bank statements/open banking correctly"
}
ParameterDescription
errorTypePrimarily for YouLend internal use, see data and description parameters for information on the error description
dataBreakdown of the data still required before the lead can be submitted
descriptionNext steps on how to resolve the issue

4. Get decision from YouLend (whether approved or rejected)

Retrieve data from YouLend about whether the lead application has approved or rejected by YouLend.

A successful response will include details of offers from YouLend, including the funding amount, the fee, and the repayment %. You can show this information to your merchants to allow them to choose whether they want to take the financing from YouLend.

👍

Best practice

Most of our partners are currently using webhooks (event code ONB10011) to be notified of this step, find out more information here

Example Offers provided ONB10011 webhook

{
    "EventCode": "ONB10011",
    "Message": "Offers Provided",
    "EventProperties": {
  "LeadId": "a668561b-4998-4240-a647-a35df722ca42",
  "ThirdPartyCustomerId": "rndtkezrrxq",
  "MaxFundingAmount": 38900,
  "MinFundingAmount": 7710,
  "Offers": [
    {
      "OfferId": "f29d76d6-2cda-431e-bde9-a231260a1899",
      "YouWillGet": "30800",
      "YouWillRepay": "36960",
      "CurrencyISOCode": "GBP",
      "Sweep": "20",
      "DaysUntilRepayment": 207
    },
    {
      "OfferId": "23b182e4-6039-4117-b715-28b60b30154b",
      "YouWillGet": "34800",
      "YouWillRepay": "42456",
      "CurrencyISOCode": "GBP",
      "Sweep": "21",
      "DaysUntilRepayment": 227
    },
    {
      "OfferId": "c477dddd-8acc-4757-ac5f-aeca15606862",
      "YouWillGet": "38900",
      "YouWillRepay": "48236",
      "CurrencyISOCode": "GBP",
      "Sweep": "22",
      "DaysUntilRepayment": 246
    }
  ]
}

📘

Good to know

The MaxFundingAmount and MinFundingAmount returned in the ONB10011 webhook event are used to calculate flexible offers


5. Enable merchants to accept an offer (including generating flexible offers)

Once the offers have been provided, partners have the option to present the fixed offers to the merchant using their own UI. In addition to this, partners can also allow the merchant to customise their offer by using the calculate loan offers endpoint. The amount requested needs to between the MaxFundingAmount and MinFundingAmount returned in the ONB10011 webhook.

Example 200 response of the calculate loan offers endpoint

{
    "leadId": "cd2fdea3-ac7e-4110-b3b6-e787a4f7b0ab",
    "providedOffers": [
        {
            "offerId": "192acccd-bea2-409e-9738-175f3e9653bd",
            "youWillGet": 15000,
            "youWillRepay": 18405,
            "sweep": 11,
            "daysUntilRepayment": 234,
            "currencyISOCode": "GBP"
        },
        {
            "offerId": "57d0c65b-d214-49d1-a0a6-4d11bddf0606",
            "youWillGet": 15000,
            "youWillRepay": 18060,
            "sweep": 12,
            "daysUntilRepayment": 211,
            "currencyISOCode": "GBP"
        },
        {
            "offerId": "ea4c5834-721e-4dbb-b7f7-fc8f6e2ef430",
            "youWillGet": 15000,
            "youWillRepay": 18210,
            "sweep": 11.5,
            "daysUntilRepayment": 222,
            "currencyISOCode": "GBP"
        }
    ],
    "errorMessage": null
}

Once the merchant has chosen an offer (either using the offers returned in the ONB10011 webhook, or through the generated flexible offer), the partner informs YouLend of the offer accepted by sending a request to the accept a loan offer endpoint using the relevant offerId.

The response will return a boolean to let you know if the merchant is eligible for instant signing, this will be either true or false.

Example 200 response

{
    "eligibleForInstantSigning": false
}
BooleanDescription
TrueIf the merchant is eligible for instant signing, partners have the option of allowing the merchant to electronically sign documents inside your own UI via the instant signing endpoint
FalseIf the merchant is not eligible for instant signing, the standard docusign flow will take place. YouLend will email the merchant with the documents to sign, the partner can track the progress of the signing via webhook notifications. See our webhook events guide to learn more about this

6. Enable merchants to sign an offer either via instant signing (clicksign) or Docusign

📘

Good to know

Instant signing is only supported in certain geographies and for certain levels of integration, please speak to your integration manager about what is available for your solution. Below is an indicative example

i) Instant signing (clicksign) flow

Enable merchants to review the contract associated with YouLend's offer, and to sign it. There are two endpoints associated with this step:

  1. Retrieve the documents to sign for the lead

The response will include the financial documents ("contracts") that YouLend require the merchant to sign before financing the merchant.

Example 200 response

[
    {
        "id": "93c43433-d749-4c05-804a-c67462dc003e",
        "name": "Test Name TA Test Company Limited - Receivables Purchase Agreement.pdf",
        "document": "JVBERi0xLjQKJdPr6eEKMSAwIG9iago8PC9DcmVhdGlvbkRhdGUgKEQ6MjA",
        "documentType": "Loan Agreement"
    }
] 
  1. Sign documents via 'instant signing'

Send a request to this endpoint to inform YouLend that the merchant has signed the contract within your own UI.

🚧

Be aware

Using this endpoint requires approval from YouLend. There are certain requirements you'll need to meet for (a) how the signing flow is presented to the user, (b) how you manage logins and permissions, and (c) what would count as a robust enough verificationId

👋

Please get in touch

If you would to learn more about who can sign a Loan Agreement, please get in touch via your implementation manager, or via [email protected]

ii) Docusign flow

If the merchant is not eligible for instant signing (see above), YouLend will instead send a contract via to the merchant to review and sign. This process is handled completely by YouLend, and requires no technical work from the partner.

👍

Best practice

We recommend subscribing to the Contract sent ONB10038 and Contract signed ONB10022 webhook event codes to keep track of what steps the merchant has completed. See our webhook events guide to learn more about this