OmniPort Integration API Requirements Specification

Transcription

1 OmniPort Integration API Requirements Specification FOR RETAILER USE ONLY Date Version 1.0

2 1. Contents 1. Introduction 2 2. General Overview Scope System Context 2 3. System Requirements Business Process OmniPort API Operations Authentication Initial State Create New Credit Check Required Fields Depending On Passed Employmentstatusid Responses Update Loan Application Status Update Customer Bank Details Check Loan Application Status Get Brokerage Finance Calculator Initial State Get List With Brokerage Finance Calculator Products Use Cases Functional Requirements Non-Functional Requirements Deployment 24 Omni Capital Retail Finance 1

3 1. Introduction This document includes information for developing an API for the purpose of integrating with the OmniPort platform. 2. General Overview The API provides an improvement in the integration process of OmniPort with external thirdparty applications. The main purpose of the API is to handle new loan application requests from the platforms that integrates it. Using the REST API approach more flexibility is given to the third-party platforms Scope The API should provide the following: Process third-party application requests based on the OmniPort platform credit policy and rules Store third-party application requests as OmniPort loan applications Return appropriate results to the third-party applications 2.2. System Context The API has the following functionalities: Authentication Process third-party application requests Store third-party application requests as OmniPort loan applications Return appropriate results Omni Capital Retail Finance 2

4 Figure 1 The above diagram (figure 1) shows the web system of OmniPort: Third-Party Applications All the applications and platforms that use the OmniPort Integration API Omni Capital Retail Finance 3

5 OmniPort Integration API An API which exposes services to the third-party applications, using a module for authentication. Internal Services A layer which exposes some of the business logic to the integration API. Business Logic The main business logic layer of the OmniPort application Third-Party Services (Experian, Post Code Anywhere) Services that are used by the business logic layer to process different type of request. OmniPort Database A database used by the Business logic layer to store data 3. System Requirements 3.1. Business Process This section includes a description of the business processes and the related business activities covered by the API. The below diagram shows the whole process. The customer accesses the OmniPort Integration API via third-party platforms. They need to authenticate to use the API functionalities. If authentication fails, an appropriate message is returned, containing more details about the failure. If authentication is successful third-party applications get an access token that is required for further requests. Using this token they can create a new loan application. At the end of the creating process third-party applications receive appropriate messages: Check preconditions failure message If the preconditions check is not passed. The returned message contains more details about the failure Final response This message is returned only the preconditions are passed. It contains details about the loan application (ID, status, further information). Omni Capital Retail Finance 4

6 Figure 2 Omni Capital Retail Finance 5

7 3.2. OmniPort API Operations This section describes the parameters that the API accepts and returns Authentication To access to API functionalities, integrated platforms should authenticate first. As result of successful authentication they get an access token, which allows them to access the API for a predefined period of time. Enpoint Url: /api/login Request Type: Post Request Body: username: string, password: string, grant_type: password (this field is not the password used for login) Note: The body must be send as x-www-form-encoded. Response: "access_token" : string, "token_type": "bearer", "expires_in": number, ".issued": date when the access token is issued ", ".expires": "date when the access token expires" Omni Capital Retail Finance 6

8 3.4. Initial State The idea of this state is to get the latest data from the OmniPort database that is going to be used in the necessary dropdowns. Enpoint Url: api/creditcheck/initialdata Headers: Authorization: Bearer access_token Request Type: Get Response: "RateCardProducs": [ "Key": "Rate card product id", "Value": "Rate card product name" ], "Titles": [ "Key": "Title id", "Value": "Title name" ], "Genders": [ "Key": "Gender id", "Value": "Gender name" ], "MaritalStatuses": [ "Key": "Marital status id", Omni Capital Retail Finance 7

9 "Value": "Marital status name" ], "ResidentialStatuses": [ "Key": "Residential status id", "Value": "Residential status name" ], "YearsAtAddress": [ "Key": "Years at address id", "Value": "Years at address name" ], "EmploymentStatuses": [ "Key": "Employment status id", "Value": "Employment status name" ], "YearsWithEmployer": [ "Key": "Years with employer id", "Value": "Years with employer name" ], "SourcesOfIncome": [ "Key": "Source of income id", "Value": "Source of income name" ] 3.5. Create New Credit Check This section explains the way that credit check is created. Omni Capital Retail Finance 8

10 Enpoint Url: /api/creditcheck/create Headers: Authorization: Bearer access_token Content-Type: application/json Request Type: Post Request Body: "FinanceDetails": "RateCardProductId" : "Id", "DescriptionOfGoods" : "Sample description", "RetailersReference" : "ref", "Price" : "number in format ##.##", "Deposit": "number in format ##.##", "CustomerDetails" : "Customer " : " @domain.com", "TitleId" : "Id", "FirstName" : "first name", "MiddleName" : "middle name", "LastName" : "last name", "MaidenName" : "maiden name", "GenderId" : "gender id", "DateOfBirth" : "Date in format dd-mm-yyyy", "Telephone" : "telephone", "MobileNumber" : "mobile number", "MaritalStatusId" : "Id", "ResidentialStatusId" : "Id", "MonthlyRentAmount" : Number in format ##.##, "NumberOfDependants" : integer, "GoodsDeliveryAddressIsTheSameAsCurrentAddress" : "true or false", "CurrentAddress" : "PostCode" : "Postcode", Omni Capital Retail Finance 9

11 "Flat" : "flat", "HouseNumber": "house number", "HouseName": "house name", "Street" : "street", "City" : "city or town", "YearsAtAdressId" : "Id", "PreviousAddress1" : "PostCode" : "Postcode", "Flat" : "flat", "HouseNumber": "house number", "HouseName": "house name", "Street" : "street", "City" : "city or town", "YearsAtAdressId" : "Id", "PreviousAddress2" : ""PostCode" : "Postcode", "Flat" : "flat", "HouseNumber": "house number", "HouseName": "house name", "Street" : "street", "City" : "city or town", "YearsAtAdressId" : "Id", "GoodsDeliveryAddress" : "PostCode" : "Postcode", "Flat" : "flat", "HouseNumber": "house number", "HouseName": "house name", "Street" : "street", "City" : "city or town", "YearsAtAdressId" : "Id", "EmploymentDetails": "EmploymentStatusId": "Id", Omni Capital Retail Finance 10

12 "GrossAnnualIncome": Number in format ##.##, "MainOccupation": "Main occupation", "EmployerName": "Employer name", "YearsWithEmployerId": "Id", "BankDetails" : "AccountHolderName" : "Holder name", "BankAccountNumber" : "Account number", "BankSortCode" : "Sort code", "MarketingPreferences": "ReceiveInformationViaPost" : "true", "ReceiveInformationVia " : "false", "ReceiveInformationViaSMS" : "false", "ReceiveInformationViaPhone" : "true", "AgreePersonalDetailsToBeDisclosed" : "true", "AcceptAllTermsAndConditions":"true" Note: Based on different business cases not all of the field will be required. This JSON contains all possible fields that can be passed to the API. In the below section you can find different cases of when and what is required depending on the passed data. Omni Capital Retail Finance 11

13 3.6. Required Fields Depending On Passed Employmentstatusid Selected Required employment Example request data Properties status Retired GrossAnnualIncome "EmploymentDetails": "EmploymentStatusId": "9bde0258-3e34-4d72- ac7a-fa7a10d64438", "GrossAnnualIncome": " " Selfemployed GrossAnnualIncome "EmploymentDetails": "EmploymentStatusId": "59289f d0a- TypeOfBusiness BusinessName b2ae-4df33a70630d", "GrossAnnualIncome": " ", "TypeOfBusiness": "teste", YearsSelfEmployedId "BusinessName": "test", "YearsSelfEmployedId": "f8d673f1-2f19-4cadb045-b557388e9815" Notemployed GrossAnnualIncome "EmploymentDetails": "EmploymentStatusId": "e3d485e5-c3e2-41e0- SourceOfIncomeId b e2df2f26", "GrossAnnualIncome": " ", "SourceOfIncomeId": "000AA231-8DA B7AF-0E0D61928C32" Employed GrossAnnualIncome MainOccupation EmployerName YearsWithEmployerId "EmploymentDetails": "EmploymentStatusId": "c731a6c2-afee-417e- 8efc-78a fc", "GrossAnnualIncome": " ", "MainOccupation": "main occup", "EmployerName": "emp name", "YearsWithEmployerId": "f8d673f1-2f19-4cadb045-b557388e9815" Number format allowed: ##.## Date format allowed: dd-mm-yyyy Omni Capital Retail Finance 12

14 Guaranteed Application Results: Each below leads to different credit check status. For successful testing, the logged retailer user need to have the TestResultsProduct in his/her available products. This product must use the TestResultsCreditPolicty in order for the API to make decisions based on the different addresses. The test product can be applied to a retailer by an OCRF user. This product must be chosen when a new credit check is created. For accepted status use ocapital.test1@gmail.com as customer address. For referred status use ocapital.test2@gmail.com as customer address. For declined status use ocapital.test3@gmail.com as customer address Responses Invalid input fields "errors": "invalidfieldname": [ "Error message containing more details about the failure." ], " invalidfieldname2": [ "Error message containing more details about the failure." ] Create new loan application (Success) LoanApplicationId": "Id", "Status": "Status name", SignDocumentsUrl : url Create new loan application (Error on validation bank details /Experian/ ) LoanApplicationId : Id, Omni Capital Retail Finance 13

15 ErrorMessage : Error message from Experian 3.8. Update Loan Application Status Endpoint for updating the loan application status after the third-party application have received the loan application result. Third-party application can change the status to awaiting fulfilment or order fulfilled Enpoint Url: /api/creditcheck/updatestatus Headers: Authorization: Bearer access_token Content-Type: application/json Request Type: Post Request Body: LoanApplicationId: Guid, NewStatus: integer, New status options: Awaiting fulfilment : 1, Order fulfilled : 2 Response: The API returns an appropriate message containing the result of updating, or error message with more details about the failure. Successfully updated: Omni Capital Retail Finance 14

16 LoanApplicationId : Guid, LoanApplicationStatus: string Error occurred: ErrorMessage : Error message from Experian 3.9. Update Customer Bank Details Endpoint for updating the bank details of an existing customer, when invalid details were provided before. Enpoint Url: /api/creditcheck/updatecustomerbankdetails Headers: Authorization: Bearer access_token Content-Type: application/json Request Type: Post Request Body: "LoanApplicationId" : "Id", "BankDetails" : "AccountHolderName" : "string", "BankAccountNumber" : "string", "BankSortCode" : "string" Omni Capital Retail Finance 15

17 Responses: Invalid input fields "errors": "invalidfieldname": [ "Error message containing more details about the failure." ], " invalidfieldname2": [ "Error message containing more details about the failure." ] Success LoanApplicationId": "Id", "Status": "Status name", SignDocumentsUrl : url Error on validation bank details /Experian/ LoanApplicationId : Id, ErrorMessage : Error message from Experian Check Loan Application Status Endpoint for checking loan application status of loan application related to the retailer of the logged user through the API. Enpoint Url: /api/creditcheck/checkloanapplicationstatus Omni Capital Retail Finance 16

18 Headers: Authorization: Bearer access_token Content-Type: application/json Request Type: GET Request QueryString: "LoanApplicationId" : "Id" Responses: Invalid loan application id "LoanApplicationId": "4ac9648d-02e0-444c-b baa85425c", "ErrorMessage": "The loanapplicationid does not exist or you do not have permissions to check its status." Success "IsSigned": false, "Status": "Draft" Get Brokerage Finance Calculator Initial State This endpoint is intended to be used from brokerage users. The endpoint does not require authentication. Its purpose is to retrieve initial state for brokerage calculator. Enpoint Url: /api/financecalculator/brokerageinitialdata Headers: Omni Capital Retail Finance 17

19 Content-Type: application/json Request Type: POST Request Body: "brokerageapikey": "string" Responses: Invalid brokerage id "brokerageapikey": "4ac9648d-02e0-444c-b baa85425c", "ErrorMessage": "The provided brokerageapikey does not exist." Success "brokerageapikey": "a83579b4-aecd-4e38-b0dc-0b5117a45b15", "MinPrice": 100, "MaxPrice": 4100, "StepSizePrice": 50, "StepCountPrice": 81, "MiddleElementPrice": 2100, "MinTerm": 4, "MaxTerm": 40, "StepSizeTerm": 4, "StepCountTerm": 10, "MiddleElementTerm": 20 Omni Capital Retail Finance 18

20 3.12. Get List With Brokerage Finance Calculator Products This endpoint is intended to be used from brokerage users. The endpoint does not require authentication. Its purpose is to retrieve list with finance products based on provided term and price. Enpoint Url: /api/financecalculator/brokerage Headers: Content-Type: application/json Request Type: POST Request Body: "brokerageapikey": "string", "term": "int", "price": " number in format ##.##" Responses: Invalid brokerage api key "brokerageapikey": "4ac9648d-02e0-444c-b baa85425c", "ErrorMessage": "The provided brokerageapikey does not exist." Omni Capital Retail Finance 19

21 Success "SelectedProductCode": "ONIB ", "Products": [ "Id": " ONIB ", "APR": 1.27, "MonthlyCost": , "TotalRepayment": , "Term": 8, "InterestRate": 10.00, "Id": " ONIB ", "APR": 1.19, "MonthlyCost": 83.78, "TotalRepayment": , "Term": 12, "InterestRate": 10.00, "Id": " ONIB ", "APR": 1.14, "MonthlyCost": 62.94, "TotalRepayment": , "Term": 16, "InterestRate": 10.00, "Id": " ONIB ", "APR": 1.12, "MonthlyCost": 50.43, "TotalRepayment": , "Term": 20, "InterestRate": 10.00, Omni Capital Retail Finance 20

22 ] "Id": " ONIB ", "APR": 1.1, "MonthlyCost": 42.1, "TotalRepayment": , "Term": 24, "InterestRate": Use Cases ID: Name: Actors: Preconditions: UC01 Login Third-Party applications n/a Step Actor Description Main Flow 1 Third-Party Post valid and password to the API application 2 API Validate the credentials 3 API Check if the third-party application is allowed to use the API 4 API Return an access token for further requests Alternative Flow 1 Third-Party Post valid and password to the API application 2 API Validate the credentials 3 API Check if the third-party application is allowed to use the API 4 API Return appropriate message saying that this third-party application is not allowed to use API Omni Capital Retail Finance 21

23 ID: Name: Actors: Preconditions: UC02 Create a credit check Customer Need to be authenticated to create a credit check Step Actor Description Main Flow 1 Customer Fill correct and necessary data to apply for a credit check 2 Customer Submit the data 3 API Validate the data 4 API Create a credit check 5 API Return response Alternative Flow 1 Customer Fill incorrect or unnecessary data to apply for a credit check 2 Customer Submit the data 3 API Validate the data 4 API Return appropriate message (invalid data) ID: Name: Actors: Preconditions: UC03 Update credit check status Third-Party applications Need to be authenticated to update a credit check status Step Actor Description Main Flow 1 Third-party application Submit the credit check and the new status that should be applied 2 API Validate the credit check and the status 3 API Update the credit check 4 API Return a message for successful update Alternative Flow 1 Third-party application Submit the credit check and the new status that should be applied Omni Capital Retail Finance 22

24 2 API Validate the credit check and the status 3 API The data is invalid or the credit check cannot be updated to this status 4 API Return appropriate message containing more details about the failure Functional Requirements ID: Name: Description: F01 Login The retailers should login before use API functionalities ID: Name: Description: F02 Launch loan application The API should create a new loan application when valid data is passed to it. ID: Name: Description: F03 Check loan application status The API should return the status of a loan application when valid data is passed to it. ID: Name: Description: F04 Update credit check status The API should update a credit check status when valid credit check and status are passed to it. Omni Capital Retail Finance 23

25 3.15. Non-Functional Requirements ID: Name: Description: NF01 User Authentication and Authorization Each user should identify himself in front of the system with User Name and User Password. In addition to that there should be control on the access for the different users. ID: Name: Description: NF02 Response time The API response time should be up to 15 seconds per request. ID: Name: Description: NF03 Security The communication to the API should use HTTPS 4. Deployment The OmniPort Integration API is part of the same solution as the OmniPort platform is. The API is deployed on the same machine where the OmniPort platform is. The platform and the API use IIS as a server for hosting. Omni Capital Retail Finance 24

26 For Retailer Use Only Tel: , Option 2 Retailer Support Enquiries for Omni Capital Retail Finance: retailersupport@ocrf.co.uk Omni Capital Retail Finance Oak House, Reeds Crescent, Watford, Herts WD24 4QP Omni Capital Retail Finance is authorised and regulated by the Financial Conduct Authority, Firm Reference Number: Omni Capital Retail Finance is a member of the Finance and Leasing Association (FLA) Omni Capital Retail Finance 25