☰1. IT
Important note: IT related content is subject to change.
1.1 Escalation path
For IT related questions, please reach out to: embeddedfinance@dllgroup.com
1.2 Links to swagger definitions
Note: Link will be updated
1.3 API overview
Business flow overview
1. Authenticate to DLL Embedded Finance API
Every API consumer will be given a set of credentials: “clientId” and “clientSecret”, “Ocp-Apim-Subscription-Key".
To retrieve Authorization token, the token API has to be called.
Token API URL is: https://login.microsoftonline.com/{{tenantId}}/oauth2/v2.0/token.
The Token API expects a POST request with the following values:
Key
Value
client_id
Client ID you received
clientSecret
Client secret you received
grant_type
“client_credentials”
scope
https://mscb2cparautacc.onmicrosoft.com/app/vendor-finance/.default
When successfully calling the Token API you will find the Authorization token in the “access_token” property of the Token API response. The token can then be cached on the consumer side and will be valid for 1 hour.
You can use the acquired access token to authenticate against DLL Embedded Finance APIs, each request must include the following headers:
The Authorization token can be found in “access_token” property of the Token API response.
It can then be cached on a consumer side and is valid for 1 hour.
To authenticate against DLL Embedded Finance APIs, each request must include:
Key
Value
Authorization
"Bearer {access_token}"
Ocp-Apim-Subscription-Key
The Ocp-Apim-Subscription-Key you've received.
2. Getting finance configuration options
Before getting indicative prices and initial quotes, it first makes sense to get finance configuration options.
Own it or use it
A finance configuration option can be “own” or “use” option.
Payment frequency and contract duration
In each case, a finance configuration option has specific payment options like: 12,13,14…84 months, 12,15…84 months (quarterly payments). Those values should be used to limit partner website UI widget for selecting frequency and duration. E.g. only “monthly, quarterly” values should be possible to select from UI widget. Then, when “monthly” value is selected, only particular values (e.g. 12,13,14…84 months) should be possible to be selected.
Down payment
A finance configuration option has also minimum and maximum down payment percent: e.g. 19%-100%. Those values should be used to limit partner website UI widget for selecting down payment. E.g. minimum down payment possible to select in UI widget should be 19% (can be also expressed in absolute asset price, e.g. 19% * asset price), maximum down payment possible to select in UI widget should be 100% (can be also express in absolute asset price, e.g. 100% * asset price).
Asset price
A finance configuration option also has minimum and maximum asset price. For assets with price outside of those boundaries, financing is not possible, therefore filtering should be done on partner website and for those assets, which are outside of boundaries, indicative price API should not be called, as the asset is ineligible (and any quote cannot be retrieved).
The API to use here is /finance-configuration-options
For details, please check the DLL Embedded Finance OpenAPI spec.
3. Getting indicative prices
Business case:
The product listing page (PLP) on an E-Commerce platform is responsible for listing the products that are being offered. Each PLP is likely to show an x number of products on one page (e.g. 15 products). Whenever a user changes the page, the indicative price API can be called to show the indicative prices for the x number of products that are eligible for financing shown on that particular page.
The indicative price is the ‘starting from’ monthly amount customers will have to pay for assets based on the default DLL Embedded Finance program or the program, which was passed in a configuration object.
The API to use here is /indicative-price. This API returns the indicative prices for any number of eligible assets. All assets that are sent in that are not eligible for financing will also be returned for transparency.
For details, please check the DLL Embedded Finance OpenAPI spec.
4. Getting an initial quote
Business case:
The user wants to make use of financing offered by DLL and would like to have an indication of the monthly payment based on their preferences for term length and financing amount. The finance configuration option combined with the asset and features from which the user can choose from, are used as input for calculating an initial quote.
An Initial Quote is a more accurate and personalized indication of what a user will pay for based on the user’s preferences (e.g. monthly or quarterly payments), in the form of a cost breakdown.
After getting an Initial Quote, it is shown to the user, on the e-commerce platform, for approval.
The API to use here is /initial-quote
For details, please check the DLL Embedded Finance OpenAPI spec.
Asset eligibility
For NA partners: asset is eligible when finance amount (asset price * quantity + asset total shipping price) is smaller than maximum financing
amount defined in the DLL program. Additionally, asset has to be found in DLL system based on Id (of asset).
For EU partners: asset is eligible when finance amount (asset price - asset down payment) is withing range defined in the DLL program. Additionally, asset has to be found in DLL system. The attempt of finding an asset is based on first TypeName (of asset), then Id (of asset).
Cart eligibility
Initial quote API call can result in eligible or ineligible cart.
NA partners
For NA partners, cart eligibility is being determined by the following logic:
Determine eligibility of assets and divide into two categories, eligible and ineligible
Sum the price and shipping price of all eligible assets to get “total eligible assets price and shipping price”
Calculate MSRP Uplift Percentage (e.g. 30%) of “total eligible assets price and shipping price”
Sum the price and shipping price of all ineligible assets and extras to get “total ineligible item price and shipping price”
If “total ineligible item price and shipping price” is less than MSRP Uplift Percentage (e.g., 30%) of “total eligible assets price' then the cart as eligible (otherwise ineligible) and only in that case initial quote is generated.
EU partners
N/A
5. The check-out flow
Note: Checkout Flow related content might be subject to change
Business case:
In the Checkout portal, the user can finish their financing journey with DLL Embedded Finance. There, a credit check will be conducted and the lease agreement will be signed via e-signature.
Requirements for partner:
-Ability to send a POST request to an endpoint
-Ability to receive a redirect response (successful, unsuccessful, and pending)
-Redirect customer to the DLL Embedded Finance
In order to open the Checkout Portal, first you will need to create a JSON object with the data required by the Checkout Portal in the following format:
{
"partnerId": REQUIRED "Unique Partner Identifier that will be shared",
"partnerTransactionId": REQUIRED "Partner transaction Id- (guid)",
"name": REQUIRED "User's first name",
"middlename": "User's middle name",
"surname": "User's last name",
"SSN": "User's SSN",
"phone": "User's Phone Number",
"emailAddress": REQUIRED "User's email address",
"homeAddress": {
"street": "User Address - Street Name",
"number": "User Address - House Number",
"city": "User Address - City Name",
"state": "User Address - State Abbreviation",
"postalCode": "User Address - Zip/Postal Code"
},
"billingAddress": {
"street": "Billing Address - Street Name",
"number": "Billing Address - House Number",
"city": "Billing Address - City",
"state": "Billing Address - State Abbreviation",
"postalCode": "Billing Address - Zip/Postal Code"
},
"deliveryAddress": {
"street": "Delivery Address - Street Name",
"number": "Delivery Address - House Number",
"city": "Delivery Address - City",
"state": "Delivery Address - State Abbreviation",
"postalCode": "Delivery Address - Zip/Postal Code"
},
"company": {
"fullName":"Company/Business Name",
"tradingName" : "Company/Business - Trading Name",
"legalEntityName": "limited-liability-company",
"taxId": "Company/Business - Tax Identifier/Number",
"establishmentDate": "Company/Business - Established On",
"phone": "Company/Business - Phone Number",
"companyAddressChecked": true,
"useCompanyInfoChecked": true,
"tradingNameChecked": true,
"address": {
"street": "Company/Business - Street Name",
"number": "Company/Business - House Number",
"city": "Company/Business - City",
"state": "Company/Business - State Abbreviation",
"postalCode": "Company/Business - Zip/Postal Code"
},
"registeredAddress": {
"street": "Company Registered Address - Street Name",
"number": " Company Registered Address - House Number",
"city": "Company Registered Address - City",
"state": "Company Registered Address - State",
"postalCode": "Company Registered Address - Zip/Postal Code"
}
},
"successRedirectUrl": "{SUCCESS URL}",
"pendingRedirectUrl": "{PENDING URL}",
"failureRedirectUrl": "{FAILURE URL}",
"initialQuote": {
"assets": REQUIRED [
{
"id": REQUIRED "Asset Number",
"assetMasterType": REQUIRED "Asset Master Type",
"assetType": REQUIRED "Asset Type",
"name": REQUIRED "Asset Name",
"brand": REQUIRED "Asset Brand Name",
"model": REQUIRED "Asset Model Name",
"price": REQUIRED 11000.23,
"partnerData": {
"id": "Item1"
},
"Quantity": REQUIRED 1
}
],
"shippingPrice": 10,
"configurationOptions": REQUIRED {
"downPayment": REQUIRED 100,
"frequency": REQUIRED "monthly",
"lengthOfTermInMonths": REQUIRED 24,
"financeConfigurationOptionId": REQUIRED "1.NA.PI.0000180052-0001.3856.2784.",
"financeConfigurationOptionType": OPTIONAL 1 to Use (default), 2 to Own,
"financeAgreementChecked": true
}
},
"dataPrivacyChecks": {
"termsAndConditions": true,
"privacyStatement": true,
"consent": true,
"userPersonalInfoChecked": true
},
"cosigningrequired": false
}
{SUCCESS URL} – User will be redirected to this URL after successful checkout. This means, that the credit application is completed successfully & the contract to finance the product is signed.
{PENDING URL} – User will be redirected to this URL when a manual (credit) check is required by DLL, this can take up to 2 business days. This is an offline process.
{FAILURE URL} – User will be redirected to this URL if the user decides to cancel the process. DLL will never fail a financing application automatically and will always fall back to the manual process if the automatic credit check does not pass.
PartnerId – This is a unique identifier that will be the same as the client id that is shared
Assets – assets master data will be shared ahead of time
ConfigurationOptions – financeConfigurationOptionId will be shared ahead of time
The data shall be sent as a JSON object in the body of the POST request. The above data should be sent to the following endpoint via a POST
request during HTTP Redirect:
https://checkout.dllgroup.com/api/checkout
Authorization Header: the redirect POST call needs to be passed with the Authorization header containing the JWT token received using the OAuth 2.0 \token endpoind provided. (As described in section 1. Authenticate to DLL Embedded Finance API)
An authorization token (partner-specific JWT token) is required to be sent as part of the HTTP Authorization header while redirecting to the Checkout Portal. This token can be received by calling the OAuth Token endpoint using the Client Id, and Client Secret shared.
POSTMAN collection containing the endpoints, authorization header etc. will be provided.
Response & Redirect
After the above POST request, the API will response with the following object:
1.4 FAQ for developers
1. What is the base URL for the vendor finance API?
Base URL
https://apim.dllgroup.com/vendorfinance/{version}/
e.g.,
https://apim.dllgroup.com/vendorfinance/v1/
2. What vendor finance API endpoints are currently available?
API
HTTP Verb
Endpoint
Initial Quote
POST
/initial-quote
Indicative Price
POST
/indicative-price
Finance Configuration Options
GET
/initial-quote/finance-configuration-options
3. Where can I find API specifications/contracts for the vendor finance API endpoints?
You can find it in the Swagger Hub: [Link to Swagger Hub to be updated]
4. What errors can i expect from vendor finance API?
The following HTTP status can be expected:
200 – Successful Operation
400 – Bad Request
401 – Unauthorized
403 – Forbidden
404 – Not Found
405 – Method Not Allowed
500 – Server Error
503 – Server Error
Furthermore, if request resulted in business validation error, the response will have a 400 status code and it will include details in the response body.
5. Are there any postman collections along with payload samples, which can be used by the developers?
Postman Collection has API calls showing basic business cases. The API calls use sample data that demonstrate the header values, a sample request and a sample response.
6. How can the developer accounts be created/onboarded?
Note: To be updated
7. Are there SDKs available which can be used by developers?
Currently we do not offer any SDKs.
8. How does one obtain their client/secret information?
Please refer to embeddedfinance@dllgroup.com for questions on client secret information.
Jump back in
