Technical implementation
Once scoping is done, this quick guide will help you jump start the integration of our income verification use case on your platform.
Step 1: Get access
To start the process - first, you need access to the Mistho Dashboard to retrieve sandbox access. If you haven't got that yet, please get in touch with us at info[at]mistho.io and we will provide you an account.
Once signed up in the Dashboard, you can find the API keys for the sandbox under the API section and if needed you can create several sandbox keys. Once you have engaged into a commercial contract with Mistho, you will also find the keys to the production environment in the API section.
Step 2: Configure the Mistho APP
Once you have retrieved the sandbox keys, you need to create a configuration for the Mistho APP. In the dashboard under the Configuration section you are able to add, edit and delete as many different configurations you require. Each configuration will allow you to display different flows in various steps of your process flow. It is important to note that that you need to have at least one configuration to be able to call the Mistho APP.
The configuration page in the Dashboard will offer you following options:
- Name: Name your configuration.
- Display Name: Insert here the company / product name you want to display in the intro screen of the Mistho APP.
- ID: This value is automatically provided once created, you need to insert this value when you call the Mistho APP in order to relate to that config.
- Callback (Optional): Insert here the URL where you want to receive the data provided by our callback service.
- Redirection (Optional): Insert here the redirection URL, where you want your users routed once the flow is done. If you leave it empty, a "You can close this window now." text will be displayed. Recommended for the stand-alone flow. You can provider redirection URLs both for success and failed cases.
- Require Payslips: Here you can configure how many payslips you need for your operations. This value can be currently set between 1 and 6 months.
- Manual Upload: Decide wherever you want to offer manual upload to your end users, or not.
Step 3: Create a transaction
Mistho's income verification process revolves around transactions, meaning each time you would like to initiate a verification flow and showing the Mistho APP, a transaction has to be created beforehand. The Transaction will contain all necessary information linked to the verification process. Only when the transactions status switches to COMPLETED will you be able to receive the income data and only transactions with that status will be billed. You will be able to download the pay-stub file directly from the transaction response and if necessary you can still access it via dashboard in the transaction view. For the list of transaction status please refer to the API reference here.
So what are the pre-requisites to create a transaction? As mentioned above you need to have a sandbox access and a configuration. To be able to trace the transaction to the configuration, you are required to send the configuration ID in the body.
Note: In case you prefer to use your own identifier and not fully rely upon the transaction ID you will be provided once a transaction is created, you can put a "Ref_id" value in the body of the request, which will help you identify transactions based on your own identifier.
To start, here an example:
$http.post('https://api.mistho.io/api/v1/transactions', data).success(successCallback);
As described above, the input data:
{
"config_id" : "615adff7580c1c11140b913e"
"ref_id" : "xxxx", //optional
"extra_info" : {} //optional
}
The response of transaction creation as follows:
{
"transaction_id" : {{transaction_id}},
"mistho_url" : "https://app.mistho.io?transaction_id=" + {{transaction_id}}
}
In the response, as you can see, a link to the Mistho APP is provided for you to display anywhere you wish, which leads us to the next point.
Step 4: Display the Mistho APP (UI)
Once you have received the Link in the response, the transaction was successfully created and you are able to display it as you need. The UI can be integrated as an iframe, an overlay, a pop-up, etc. depending on your requirements.
All user information entered into the Mistho APP are encrypted and no credentials are stored. The user interface handles the complexity of multi-factor authentication and access control, thus enabling a smooth user experience.
As you can see the name and the number of payslips presented in the intro screen match with the configuration example above.
Step 5: Test the flow
Within the sandbox environment, you are able to test both the flow. Two sets of credentials will help you test a successful and a failed income verification.
| Success | Failed | |
|---|---|---|
| [email protected] | [email protected] | |
| Password | misthopass | misthopass |
For Universal Credit
| Success | |
|---|---|
| [email protected] | |
| Password | misthopass |
Testing the good flow and based on how to receive the response (via callback or you call our GET transaction endpoint), you will receive following response, with three payslips (as configured above):
{
"status": "COMPLETED",
"_id": "61642370f1ae39000405966f",
"client_id": "6140aeXXXXbe6b0004aXXXXX",
"created_at": "2021-10-11T11:43:44.118Z",
"updated_at": "2021-10-12T10:31:50.290Z",
"__v": 0,
"provider": "Sage HR",
"employee": {
"id": "1149700",
"name": "Bob Mistho",
"email": "[email protected]",
"address": 27, OLD GLOUCESTER STREET, LONDON, WC1N 3AX,
"tax_code": "1257L",
"ni_number": "AA123456C",
"annual_salary": "£40,000.00",
"start_date": "12/09/2016",
},
"employer": {
"name": "Mistho GmbH",
"address": "Charlottenstr. 4, 10969, Berlin",
},
"uk_payslips": [
{
"earnings": {
"basic_pay": "2,000.00",
"variable_earnings": [
{
"name": "Business Expenses",
"value": "90.00"
},
{
"name": "Basic Hours",
"value": "10.00"
}
],
"total_earnings": "£2,100.00"
},
"deductions": {
"tax_deductions": "192.40",
"social_security": "0.00",
"variable_deductions": [
{
"name": "Student Loan (Plan 1)",
"value": "31.00"
},
{
"name": "NEST AE",
"value": "31.00"
}
],
"total_deductions": "304.40"
},
"tax_year_to_date": {
"accumulative_gross_pay": "10,100.00",
"accumulative_taxable_pay": "553.60",
"accumulative_ni": "0.00",
"total_tax_paid": "0.00"
},
"summary": {
"payslip_month": "October",
"tax_period": "10",
"period": "10",
"payment_method": "BACS",
"payment_date": "01/11/2021",
"amount_paid": "£1,795.60",
"paystub_file": "...yOTY1fQ.CiVYfGADPaMWYuUyVXRl3y5eQRgerkjmJF-zHDknPbA"
}
},
{
"earnings": {
"basic_pay": "2,000.00",
"variable_earnings": [
{
"name": "Business Expenses",
"value": "90.00"
},
{
"name": "Basic Hours",
"value": "10.00"
}
],
"total_earnings": "£2,100.00"
},
"deductions": {
"tax_deductions": "192.40",
"social_security": "0.00",
"variable_deductions": [
{
"name": "Student Loan (Plan 1)",
"value": "31.00"
},
{
"name": "NEST AE",
"value": "31.00"
}
],
"total_deductions": "304.40"
},
"tax_year_to_date": {
"accumulative_gross_pay": "10,100.00",
"accumulative_taxable_pay": "553.60",
"accumulative_ni": "0.00",
"total_tax_paid": "0.00"
},
"summary": {
"payslip_month": "September",
"tax_period": "09",
"period": "09",
"payment_method": "BACS",
"payment_date": "01/10/2021",
"amount_paid": "£1,795.60",
"paystub_file": "...yOTY1fQ.CiVYfGADPaMWYuUyVXRl3y5eQRgerkjmJF-zHDknPbA"
}
},
{
"earnings": {
"basic_pay": "2,000.00",
"variable_earnings": [
{
"name": "Business Expenses",
"value": "90.00"
},
{
"name": "Basic Hours",
"value": "10.00"
}
],
"total_earnings": "£2,100.00"
},
"deductions": {
"tax_deductions": "192.40",
"social_security": "0.00",
"variable_deductions": [
{
"name": "Student Loan (Plan 1)",
"value": "31.00"
},
{
"name": "NEST AE",
"value": "31.00"
}
],
"total_deductions": "304.40"
},
"tax_year_to_date": {
"accumulative_gross_pay": "10,100.00",
"accumulative_taxable_pay": "553.60",
"accumulative_ni": "0.00",
"total_tax_paid": "0.00"
},
"summary": {
"payslip_month": "August",
"tax_period": "08",
"period": "08",
"payment_method": "BACS",
"payment_date": "01/09/2021",
"amount_paid": "£1,795.60",
"paystub_file": "...yOTY1fQ.CiVYfGADPaMWYuUyVXRl3y5eQRgerkjmJF-zHDknPbA"
}
}
],
"finished_at": "2021-10-12T10:31:50.290Z"
}
Downloading the payslip from the API response (update)
Till recently you were able to use the URL provided in the JSON response to download the payslip, but due to some security reasons this has been changed. In order to download the payslip now, you're required to do a GET request with the URL and include your API key in the request. An example could look like this: GET https://api.mistho.io/payslip123.pdf with the x-api-key in the header.
Finish the implementation
Whit this guideline you should have a good overview on when, where and how to integrate Mistho's Income Verification product.
In order to finish the implementation, please have a closer look on the following pages: