About Our Van Finance API
Our Van Finance API creates finance instalment calculations for:
- Business Contract Hire
- Business Contract Purchase
- Business Hire Purchase
- Business Finance Lease
- Business Balloon Lease
- Personal Contract Hire
- Personal Contract Purchase
- Personal Hire Purchase
Users can select the:
- type of finance
- finance term
- finance plan (number of adv_ance/remaining payments)
- annual vehicle mileage
This page explains the {GET} request sequences to calculate finance based on the user's vehicle and finance selections.
For the finance calculator to function your site will need facilities for the user to:
- select the vehicle
- obtain a residual value forecast (e.g. for contract hire and personal contract purchase)
- choose the finance term, repayment plan and mileage.
Optionally the API can also include the cost of user selected factory or dealer fitted options in the calculation.
Each of these are explained in our Help pages for:
The cost of dealer fitted options can be sent as component value in the {GET} request.
In addition the finance rate will need to be set - this can be done in the background either as your own finance rate sent in the {GET} request or from a rate table held by us on your behalf.
We can also hold finance rental tables where the vehicle selections will be for standard models without factory or dealer fitted options.
Dataset:
The dataset can be provided in 'JSON' or 'XML' format.
You can choose the type of data returned in your HTTPS request by declaring 'json' or 'xml' in the 'd_Type' element of the request string.
JSON is the default type for the dataset if no 'd_Type' is set.
Our Demo
Our demonstrator provides an illustration of how the API delivers a finance calculation using XML.
In our help pages on car, option, residual value and finance selection we set out the relative HTTPS {GET} requests for each stage of van and finance selection; this page deals with the finance calculation itself.
You can copy and paste the sample request strings into a browser address bar to see the raw XML data returned for the request (right click on the browser page displayed and you will see the XML dataset).
You can also substitute XML for JSON when you perform the 'copy|paste' exercise.
{GET} Requirements
The {GET} request follows standard HTTPS key:value pair protocols. No response will be given for an HTTP request.
The {GET} request requires our standard security login/session token, the van's CAPID and the finance selections.
The manufacturer, range and model name are not required for the calculation, but these items will be returned as part of the dataset for verification purposes.
Where a residual value forecast forms part of the calculation (e.g. for contract hire or personal contract purchase) the CAPID must be for a vehicle currently for sale new in the UK - a CAPID for a discontinued model or retired derivative will not return a dataset.
Where the user supplies the residual value forecast or where this is not required due to the type of finance selected (e.g. hire purchase) the finance calculation will be based on the supplied residual value or a '0' residual valu as appropriate.
If our APIs are being used to create the vehicle (manufacturer, range, model, options etc) a return dataset will only be provided where CAP-HPI has a published vehicle dataset - new vehicle model ranges/derivatives may not return a dataset.
Data Retrieval
Once you have selected a vehicle, finance type, term, mileage and finance plan below click on the 'Calculate' button to see a returned dataset.
You will also see the entire {GET} request string as an example and the returned dataset structured as a typical online representation of XML for the van.
This will include the dataset XML node descriptions so that you can see the schema.
VAT
The values to be provided in the {GET} request are VAT inclusive.
If your own price etc dataset is VAT exclusive then multiply the VAT exclusive values by 1.2 for the VAT inclusive equivalents (exclude the registration fee and VED as these items do not attract VAT).
Security
A session token is created on initial login and must be included as a cookie with all HTTPS requests or the request will fail.
If the user's browser does not allow functional cookies then the {GET} request will become orphaned and the request cannot be linked to any other requests in the same session.
If the session token is not included then the session will be terminated, any data created in the session may be erased at the server and the user may need to re-authenticate with a new session.
For security reasons the HTTPS protocol must be used for all {GET} requests so that all data passed between the browser and the server is encrypted, including the session token.
Pair:Value Summary
All
d_type: xml or json for the required return data type (json if not specified)
CAPID: the vehicle's CAP ID code (an integer only)
Finance
f_type: a two or three letter code for the type of finance from the following:
- CH - Business Contract Hire
- CP - Business Contract Purchase
- HP - Business Hire Purchase
- FL - Business Finance Lease
- BL - Business Balloon Leasse
- PCH - Personal Contract Hire
- PCH - Personal Contract Purchase
- PHP - Personal Hire Purchase
Finance Rate and Plan
f_rate: a 'double' type variable for the interest rate (e.g. 5.55 - this will be returned as a decimal in the verification dataset)
f_term: an integer type variable for the finance term in months (e.g. 12, 24, 36, 48, 60)
f_plan: an integer type variable for the number of advance payments from 1 to 12 (e.g. 3 for '3+35' or 9 for '9+23')
Optional - finance dependent
f_oh: a 'double' type variable for a monthly finance overhead either instead of, or in addition to, the interest rate (e.g. 10.50)
f_a_miles: an integer type value for the number of annual contract miles for business or personal contract hire, contract hire or balloon lease(e.g. 10000)
f_fee: a 'double' type variable for a VAT exclusive administration or document fee (e.g. 199.99)
Vehicle
The following values can be set to '0' but should be present in all {GET} requests:
v_l_price: a double type variable for the VAT inclusive sale price of the vehicle excluding options, delivery charges, registration fee or vehicle excise duty (e.g. 20000.00)
v_o_price: a double type variable for the VAT inclusive price of factory fitted options (e.g. 2000.00)
v_d_price: a double type variable for the VAT inclusive price of local dealer fitted options (e.g. 500.00)
v_dc_price: a double type variable for the VAT inclusive cost of delivery charges, number plates, etc (e.g. 750.00)
v_r_fee: a double type variable for the initial registration fee for new vans (e.g. 55.00)
v_ved1: a double type variable for the first year vehicle excise duty (e.g. 265.00)
v_otr: a double type variable for the total on-the-road price of the van (e.g. 20000.00)
Optional - finance dependent
v_mfv: an intger type variable for the minimum guaranteed future value of the vehicle at the specified finance term and contract miles (e.g. 10000) - applies to all finance with a deferral of the residual value, e.g. contract hire, contract purchase, etc
v_rv: an integer type variable for the VAT inclusive forecast residual value of the vehicle at the specified finance term and contract miles (e.g. 10000) - applies to all finance with a deferral of the residual value, e.g. contract hire, contract purchase, etc
v_ved2: a double type variable for the 2nd and subsequent year vehicle excise duty (e.g. 450.00) - applies where the 2nd and subsequent year VED is included in the monthly payments
Other
v_t_co2: an integer for the total CO2 output of the vehicle (including the CO2 outpt from options) in Grammes Per Kilometre (e.g. 110) where this affects the interest rate, VED or overhead (e.g. to compensate for capital allowance restrictions on vans with a higher CO2 output)
v_fuel: a string type variable for the CAP-HPI fuel type code for the vehicle (e.g. 'P', 'D', 'E', etc)
v_rde2: a string type variable for whether or not the diesel vehicles comply with the
RDE2 emissions requirements (e.g. 'Yes' or 'No')
v_type: a string type variable for the vehicle type - 'LCV'