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
- 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- 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:
- 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.
- Submit information about the Directors and Ultimate Beneficial Owners of the business Update significant persons.
- 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
- If merchant is applying for >£/€100,000: Submit management accounts for the merchant.
- 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
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"
}
Parameter | Description |
---|---|
errorType | Primarily for YouLend internal use, see data and description parameters for information on the error description |
data | Breakdown of the data still required before the lead can be submitted |
description | Next 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
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
andMinFundingAmount
returned in theONB10011
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
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
200
response{
"eligibleForInstantSigning": false
}
Boolean | Description |
---|---|
True | If 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 |
False | If 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:
The response will include the financial documents ("contracts") that YouLend require the merchant to sign before financing the merchant.
Example 200
response
200
response[
{
"id": "93c43433-d749-4c05-804a-c67462dc003e",
"name": "Test Name TA Test Company Limited - Receivables Purchase Agreement.pdf",
"document": "JVBERi0xLjQKJdPr6eEKMSAwIG9iago8PC9DcmVhdGlvbkRhdGUgKEQ6MjA",
"documentType": "Loan Agreement"
}
]
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 signedONB10022
webhook event codes to keep track of what steps the merchant has completed. See our webhook events guide to learn more about this