Document revision - 1.30
ID HUB (Service, System) - the described tool. An organized set of mechanisms for the Partner to assess the veracity of the Client's data. Verification may include personal data, image compatibility with a document or creditworthiness.
Client - the target user, the person using the service, authenticating one’s data.
Partner - a contractor, an entity integrating with ID HUB (website administrator/technical platform used by the Client)
Paywall - a view in the interface, where a list of available banks/payment channels via which the service can be provided is presented to the Client
Component - a component of the service that provides a verification mechanism within the scope specified for the Partner (e.g. name and surname verification based on bank account details)
Report / Daily report / Monthly report - a document sent to the Partner with data on the number of executed transactions in a specified time
Verification - a technological process consisting in the acceptance by the System of Client's data and providing the feedback specified by a given Component (e.g. photo verification of photographs, bank account details)
Verification result - a document produced by the Verification Component. It may contain a status or additional data. Its content is Component-specific.
ID HUB is a tool that allows a Partner to investigate the credibility of its Client or to retrieve Client's personal and Client-related data from external sources (documents, bank accounts, business databases).
Data verification and acquisition may be performed by different components, each with different characteristics.
The capabilities of the tool are:
ID HUB unifies all components into a single interface and standardizes how to navigate the Client through the process - regardless of what type of verification/data submission procedure the Partner requires its Clients to undergo.
The Client in the Partner's system performs actions that require verification of its identity. Partner sends to the System a request to create a new Verification. ID HUB, based on the Partner's account configuration, analyzes what kind of Verification should be performed. If the System has a Component, which has the ability to verify the parameters specified by the Partner, it contacts it and builds a unique URL address, to which Client should be redirected.
The URL address is returned to the Partner's system together with the identifier given to the new Verification. Partner's system redirects Client to the received address at the right moment. Client goes to the website in the Autopay domain or directly to the bank and follows the steps set by the selected Verification Component. After completing all the actions requested by the Component, Client is redirected back to the Partner's system. At this point, the verification result should already be available to the Partner's system.
The result of the completed verification is retrieved by Partner by sending a request to the address specified hereinafter. In response, the System will either return the calculated verification result or information that it is under preparation. To the result itself, individual components can attach additional data - so-called reports. Report content is specific to selected components.
It is possible for the System to actively notify the Partner about the prepared verification result. This is called PUSH. It requires the Partner's system to provide a URL, which will be called by the HUB, providing notification of the possibility of downloading the finished result.
Sequence diagram
Integration with the Verification System consists of the following steps:
TIP: There are many fields on the page, not all of which are required for the test. The values required in the form depend on the needs and order placed in the deployment card and the final configuration determined.
Preparation by the Partner of return addresses, the so-called "landing page" to which the Client should be redirected after leaving the system, where he should wait for the result of his verification.
Preparation of an address to handle notifications about a verification result ready to download. [OPTIONAL]
Prepare an address to handle change notifications in the list of active banks [OPTIONAL]
Partner may already be integrated with the service provided by Autopay - the Verification Transfer.
Connection to the ID HUB does not preclude the coexistence of the Verification Transfer as a parallel verification mechanism.
If, however, the Partner wishes that the Verification Transfer be covered up by a single interface according to the ID HUB concept and used as a component of a single service, it is unfortunately not possible to make a hassle-free migration and technical work on the Partner's application will be necessary.
The business configuration (methods of handling refunds, commission settlements, etc.) as well as part of the technological configuration (types of summaries returned by the verification transfer, reports, subsystems ran) will remain unchanged and will be moved to integration in the new model.
The start of verification, Client redirection and the way of receiving the final result will be different.
Two environments are prepared for the Partner's use: testing and production.
NOTE: When connecting to the Application at the above addresses, we recommend using TLS protocol in version at least 1.2. Support for lower versions will be discontinued soon.
The Partner can integrate with ID HUB using the following models: standard, standard with dedicated frontend, White Label.
TIP: The description of this model is analogous to the standard model. What differs is the frontend, the look of which can be personalized by the Partner.
TIP: The White Label model gives the Partner greater control over the Client's actions and minimizes the time of the Client's stay outside the Partner's domain (reduced to redirections through Autopay websites and staying in the bank).
In this manner of integration a new API method appears - BankList. Partner calls this method and in response receives a list of bank accesses configured for him.
Two types of accesses are available: 1PLN and AIS. Within 1PLN we additionally have division into the following accesses: PayByLink and Quick Transfer. At the integration stage, Partner is offered the choice of leaving the selection of banks and their respective components to Autopay, or to define a list of banks tailored to exact demand. The downloaded list of banks should be displayed to the Client in order to select the verification channel available to him.
It is Partner's responsibility to collect appropriate consents from the Client. The types of consents and their wording are agreed with the Autopay team before the integration commences.
When the Client chooses the bank in which he holds an account, we proceed to the initiation of verification using the method described in the main part of the documentation, plus the extra bank ID field. The Partner receives the Client's redirection address.
The Client, after getting to the view of his bank, authorizes Autopay systems to access his accounts or execute the transfer. Note, in the case of the AIS component and a history scan longer than 180 days, the Client may be redirected to the Autopay domain to perform additional SCA authorization.
The Client is redirected back, directly to the Partner's website with a temporary "jump" through the Autopay domain.
The report is downloaded in standard way, using the API - Result method.
This is a mode that does not perform any verification. It is used to retrieve Client data from external sources. The Partner then has the opportunity to verify the Client's data using its own method.
In download mode, the system redirects the Client to the selected component. There, the Client authorizes the Service's access to his data or enters it himself (Photo Verification).
The HUB takes the data available in the component and transmits it to the Partner in "raw" form or enhanced with additional reports (statistical, categorizing the types of transfers, etc.).
The data download mode is available in every component offered.
All verifications made by the system consist in comparing the data declared by the Client with the data received from the selected component.
The client data obtained from the components are complicated (in terms of lack of a standardized structure, unpredictable sequence of elements, variety of addresses, names and surnames); we do not guarantee a 100% correct data classification and consequently 100% correctness of the data comparison result.
To have the success rate of cutting and comparing data as high as possible, we use a number of instruments and algorithms to help with this.
The address data that the System components collect from their sources takes different formats.
Examples of data collected:
IZABELA ZIELIŃSKA Warszawska 39/14, 58-400 Kamienna Góra
KOWALSKI MARCIN ul. OSIEK 990, 63-920 OSIEK
WRÓBLEWSKI MARCIN JERZY CEYNOWY 136/15 77-100 BYTÓW
ORGANEK MARTA I ORGANEK WANDA NADWIŚLAŃSKA 82/4 03-349 WARSZAWA
GOSPODARSTWO ROLNE KAMIL MARECZEK BODZIEJOWICE 7B 42-446 IRZĄDZE
JĘDRZEJ NOREK JADWIGA JASKÓŁA-NOREK BRZEŹNICKA 1C32-700 BOCHNIA PL
NIKODEM ARLETA JANA III SOBIESKIEGO 2/6 21-500 BIAŁA PODLASKA
JANUSZ-STOLARCZYK JANINA KOSZARSKO 1 22-335 ŻÓŁKIEW KA
The data-cutting tool must recognize in lines like the above (and others) the following components:
The unpredictable and non-deterministic nature of data aggregated from external sources forces the System to resort to special techniques in order to divide lines into specific portions of data as close to ideal as possible.
These techniques include:
The adopted course of action may generate unexpected results (and, as a result, unsuccessful verification processes) for users with address data from outside Poland and first and last names from outside the PESEL database (similarly, when the input data includes the company name).
The Partner may observe unsatisfactory results of the cutting and verification of data when the component used takes data from a bank account that is jointly owned with another person. Such an account makes it impossible to uniquely identify the Client and the user of the System.
Despite making the utmost effort to ensure that the resulting data is correctly cut and classified, one should be prepared for the possibility that certain verifications are doomed to fail. This is due to the fact that ID HUB has no control over the quality of data received from external sources. This data is sometimes ridden with defects that prevent correct processing (for example, the first name, last name and address from the title of the transfer may be devoid of space characters, forming a cluster of words).
In the process of verifying Client data, a critical and crucial step is to compare the data declared by the Client with the data we obtained about him in the selected Component.
Data comparison paths
The system has more than a dozen predefined comparison modes. These modes determine which fields from the user's dataset are to be compared. The most common modes used are NAME_ONLY - comparing only first and last name, NAME_AND_ADDRESS_ONLY - comparing first name, last name and all address fields. Other modes were created for specific Partner requirements and are proposed after reviewing specific Partner requirements at the integration stage.
In the standard mode path, the mechanism performs data comparisons by normalizing all words: it ignores case and ignores the meaning of diacritical marks.
In this path, the Partner is given the opportunity to individually calibrate how the fields are compared. The list of fields considered for comparison as well as the comparison methodology can be profiled depending on the requirements. Possible comparison parameters include:
a. List of fields - for example: first name, last name, staircase number
b. Tolerance - determines whether the values of "Jan" and "Jan Piotr" in the comparison process is a positive, partially positive, or negative result
c. Sensitivity to character size
d. Sensitivity to the presence of diacritical marks
e. Processing of street prefixes - determines whether in the process of comparing street names we should clear the fields of prefixes like "ul.", "płk", "abp", etc.
f. Permissible word confusion - determined on the basis of the Levenstein distance for words with a fixed minimum length
g. Disabling conversion from text encoded numbers to numeric variables in such cases like house or flat numbers.
In the individual mode path, we provide the ability to detect fraud attempts. The mechanism tests whether, for a given account number, attempts have been made in the past (since the mechanism was enabled) to verify the data with a different set of parameters. If the check is positive, all subsequent verifications will automatically be set as negative.
The personal data verification mode consists in the verification of data declared by the Client against the data the System retrieves from, among others, banking systems.
The System verifies personal data using the following Components: AIS, 1PLN, PHOTO.
| Data | AIS | 1PLN | PHOTO |
|---|---|---|---|
| First name | ✔ | ✔ | ✔ |
| Last name | ✔ | ✔ | ✔ |
| Company name | ✔ | ✔ | ✖ |
| Street | ✔ | ✔ | ✔ |
| House number | ✔ | ✔ | ✔ |
| Staircase number | ✔ | ✔ | ✔ |
| Flat/suite/apartment number | ✔ | ✔ | ✔ |
| Postcode | ✔ | ✔ | ✔ |
| City | ✔ | ✔ | ✔ |
| Account number | ✔ | ✔ | ✖ |
| Identity document number | ✖ | ✖ | ✔ |
| Place of birth | ✖ | ✖ | ✔ |
| Identity document expiration dat | ✖ | ✖ | ✔ |
| PESEL number | ✖ | ✖ | ✔ |
The mode of company data verification in the 1PLN Component consists in verification of the company data declared by the Client with the data that the System collects from banking systems (after successful execution of a PLN transfer) or the Central Statistical Office.
The mode of verification of company data in the AIS Component involves providing either the Tax ID or REGON number in the initiation phase. In the process thus initiated, the user is redirected to the login page of his bank. After authorizing access, the Client returns to the Partner's system. At this time, the AIS component engine retrieves data from the Client's account and from the Central Statistical Office database. Data from the account are subjected to comparison with data from the CSO. The consistency of the acquired names and addresses, along with the fact that the account is correctly authorized, result in a positive verification result. Otherwise, a negative status is assigned.
Notes:
| Data type | 1PLN | AIS |
|---|---|---|
| Street | ✔ | ✔ |
| House number | ✔ | ✔ |
| Staircase number | ✔ | ✔ |
| Flat/suite/apartment number | ✔ | ✔ |
| Postcode | ✔ | ✔ |
| City | ✔ | ✔ |
| Account number | ✔ | ✖ |
| Company name | ✔ | ✔ |
| REGON number | ✔ | ✔ |
| NIP | ✔ | ✔ |
The component referred to as "AIS" is a subsystem of the ID HUB which operates on the basis of the analysis of the Client's bank account history.
The Client, after selecting his bank, either on the list of banks in the Partner's service or Autopay (depending on the mode of integration), is redirected to the login page for his account. There, the Client authenticates and authorizes the System to download the transaction history. The Client returns to the service where it started the process and there waits for the Component to finish retrieving and analyzing the data.
The AIS component, in addition to verifying Client data, has the ability to generate reports and summaries.
| Report | Description |
|---|---|
| Personal data | A report containing the following personal information: 1) First and last name 2) address |
| Aggregate financial data | A report containing a summary of the activity on the Client's account during a given period. Transactions are grouped according to the following rules: 1) Account number 2) Revenue/expenditure 3) Category of transaction (taxes, purchases, loans etc.) We total the transfer amounts in the cells designated by the above rules. In the report we include the date of the first transfer. |
| Raw data | A report containing a list of transactions from the Client's account in an agreed format (e.g. CSV, JSON). |
| Account data | List of bank accounts with detailed description, including: 1) Owner data 2) Bank account number and the type of account |
It is also possible to create reports for the Partner's individual needs. To run a new type of report, contact your Business Supervisor.
The reports generated by the AIS component are not an integral part of the object with the verification result. They are available at the URL that will be included in the verification result. The reason for separating the verification result from related reports is the size of data that the report can generate.
Access to the content of the reports requires authorization by the BasicAuth method. Login and password will be provided to the Partner in the implementation form or at the integration stage.
In the Example of a full report generated by the AIS component there is an example object with selected reports.
In the Example of a category tree for building an aggregate financial report there is an example list-tree of categories that is used in calculating the financial report.It is possible to individually design the category tree according to Partner's needs.
The 1PLN Component (Verification Transfer) is a Client verification mechanism in which the user transfers a set amount to Autopay's bank account.
After receiving the transfer, the Component checks if the information about the sender provided by the bank is consistent with the data received at the moment of initiating the verification. The calculated result is forwarded to the Partner, who takes further steps in the Client's business process.
Configuration personalization is available for the following extensions:
| Extension | Description |
|---|---|
| Predefined transfer title | Each transfer made by the Client will include in its title a fixed description, for example: "Confirmation of contract with XYZ" |
| Other transfer amount | By default, the user transfers the amount of PLN 1. However, it is possible to configure the component so that the user transfers a different, fixed amount. |
| Returning the data received in the transfer title | The object with the verification result will be accompanied by a structure with data containing details of the transfer executed by the Client: Returning the data received in the transfer title firstNameFromTransfer - first name lastNameFromTransfer - last name streetFromTransfer - street streetHouseNumberFromTransfer - house number streetFlatNumberFromTransfer - flat number streetStaircaseNumberFromTransfer - staircase number cityFromTransfer - street postCodeFromTransfer - postcode bankAccountNumberFromTransfer - account number unseparatedDataFromTransfer - data before classification companyNameFromTransfer - company name retrieved from CSO database during verification of transfer data (applies to company verification mode) |
A verification transfer performed at the Autopay Payment Gateway can be made with four methods.
Available payment channels:
Pay By Link - the transfer is carried out through a form generated in the electronic banking of the selected bank. The whole process closes in tens of seconds to a few minutes.
Quick transfer - the transfer is carried out similarly in the Pay By Link method, with the difference that the details for the transfer must be entered manually in their banking, based on the form presented in the Payment Gateway.
PSD2-PIS - a mechanism similar to the Pay By Link method, implemented using PSD2 banking interfaces.
Elixir - in situations where the above payment channels are permanently or temporarily unavailable, the transfer may be carried out using the classic Elixir transfer method. Verification processing time in this case may take up to two business days.
Verifications performed by the 1PLN component are verifications that may take longer. Factors influencing this time are the banking mechanisms that transfer money, along with the procedures that safeguard the process.
In special cases, the transfer processing time may take up to seven days (applies to weeks with consecutive holidays). For this reason, we set the expiration time for verification and waiting for the transfer to 7 days as standard. This parameter may be the cause of notifications about completed verification not arriving in the Partner's system for up to several days.
The PHOTO component is a mechanism in which the System obtains the Client's personal information directly from the Client's identity document (identity document). In addition to acquiring data from the document, the component also allows assessing the compatibility of the Client's biometric parameters at the device he is using with the image found on the presented identity document.
A Client can verify his identity using either a single mobile device or two devices - a desktop computer, where he completes the part of the process responsible for submitting data for verification, and a phone where the process of acquiring and submitting images takes place, after which he returns to the process completed on the computer.
| Extension | Description |
|---|---|
| OCR data | The report contains raw text data extracted from the identity document: idDocumentTypeFromOcr: "IDENTITY_CARD" idDocumentIssueCountryFromOcr: "POL" idDocumentIssueStateFromOcr: "" idDocumentExpiryDateFromOcr: "2021-06-30" idDocumentIssuingDateFromOcr: "2011-06-30" idDocumentNumberFromOcr: "ATX012345" peselFromOcr: "74121524371" genderFromOcr: "M streetFromOcr: "GOSPODY" streetHouseNumberFromOcr: "21" streetStircaseNumberFromOcr: "" streetFlaNumberFromOcr: "37" postCodeFromOcr: "80-344" cityFromOcr: "GDAŃSK" fullAddressFromOcr: "80-344 GDAŃSK GOSPODY 21/37" dateOfBirthFromOcr: "1974-12-15" placeOfBirthFromOcr: "ORNETA" firstNameFromOcr: "SZYMON" secondNameFromOcr: "JAN" thirdNameFromOcr: "PAWEŁ" maidenNameFromOcr: "ROGALIK" lastNameFromOcr: "ROGALIK" fullNameFromOcr: "SZYMON JAN PAWEŁ ROGALIK" |
| Status of the photo-verification process | These are three indicators: documentStatus - determines the processing status of the identity document bioStatus - determines the processing status of the biometric parameters overallStatus - determines the status of the entire process and compliance of the document with the biometric parameters The possible values that the statuses take are: VERIFIED - positive status NOT_PERFORMED - verification has not taken place at all SUSPICIOUS - verification has been performed and the result suggests a potential fraud attempt In case of problems with positive verification, the result includes “verificationProblems” parameter, where detailed verificators are listed, for example: “expiry_date” means that a document is expired. |
ID HUB compares data received from PHOTO component with data declared by the Client. The data to be verified should be in the input parameters (details are described in the Initiate method).
GET /api/bank/v1.1/list/{partnerUuid}
It is used to download a list of banks associated with a partner. The response contains a list of banks with information which components enable to carry out the subscribed service (verification/retrieval of transaction history) and the current availability status of the bank with the date of the last status change.
| ID | name | type | required | description |
|---|---|---|---|---|
| n/a | PartnerUuid | uuid | yes | Partner ID |
Output parameters
| ID | name | type | required | description |
|---|---|---|---|---|
| 5 | banks | map<Integer, Bank> | yes | List of banks related to Partner's profile. Map keys are bank identifiers. See table below for Bank object description. |
| 25 | status | Assumes the following values: OK, ERROR | no | |
| 30 | description | string | no | additional comment related to the action - information message if status=OK, error message if status=ERROR |
| ID | name | type | required | description |
|---|---|---|---|---|
| 5 | name | string | yes | Bank name |
| 10 | bic string | no | Bank BIC/SWIFT | code |
| 15 | iconUrl | string | no | URL to the bank's logo icon |
| 20 | additionalConsentsRequired | boolean | no | A flag indicating the need to display additional consents for the client (for the white label model). |
| 25 | component | string | yes | The name of the component to be selected in the process. In special cases, the client will be redirected to another component. E.g., in case of sudden unavailability of a pre-selected component during an ongoing process. |
Request: GET https://id-hub-accept.bm.pl/api/bank/v1.1/list/c455(...)6d89
Response:
{
"status": "OK",
"description": null,
"hash": null,
"banks": {
"1": {
"name": "Mbank",
"bic": "BREXPLPWMBK",
"iconUrl": "https://platnosci.bm.pl/pomoc/grafika/1800.png",
"additionalConsentsRequired": true,
"components": "AIS"
}
},
"24": {
"name": "Test Mock Bank",
"bic": "BMMOCKBANK",
"iconUrl": null,
"additionalConsentsRequired": true,
"components": "1PLN"
}
}
}
/api/verification/v1.0/initiate
It is used to initiate the verification process in the system. On the basis of the received input parameters and the project findings, the system selects the appropriate verification Component and prepares the address for redirecting the Client.
| name | type and scope of data | required | description |
|---|---|---|---|
| verificationId | string (~[a-zA-Z0-9-J{1,64}+$) | no | verification identifier given by the Partner |
| string (scope consistent with EmailValidator from Apache Commons ver. 1.6) | no - for 1PLN, PHOTO; yes - for AIS | email address | |
| type | enum: PERSONAL_VERIFICATION and COMPANY_VERIFICATION and DATA_HARVEST | yes | type of verification to be performed in the System |
| params | map<string, string> | yes | map of input parameters to be verified by a Component of a given type. The list of parameters is defined by the verification type (see "type” field). |
| PartnerUuid | uuid | yes | Partner's text identifier |
| bankId | integer (allowed values are keys of the map, returned by the BankList method) | no | id of the selected bank - required in the "White Label" model |
| component | enum: AIS, 1PLN, PHOTO | no | If there’s more components than one, a Partner may choose the component to be used. |
Parameter requirements are set individually in the process of creating an account, and depend on the scope of the verification and additional functionality to accompany the process (e.g., securing access to reports in PDF files with a password sent to a phone number).
| parameter | allowed values |
|---|---|
| firstName | ˄[\p{L}\s]{1,32}+$ |
| lastName | ˄[\p{L}-'.\s]{1,64}+$ |
| pesel | \d{11} |
| residenceAddressStreet | ˄[A-Za-z0-9ĘęÓ󥹌śŁłŻżŹźĆćŃń\s-.]{1,64}+$ |
| residenceAddressHouseNumber | ˄[A-Za-z0-9ĘęÓ󥹌śŁłŻżŹźĆćŃń\s-.A]{1,10}+$ |
| residenceAddressStaircaseNumber | ˄[A-Za-z0-9ĘęÓ󥹌śŁłŻżŹźĆćŃń\s-.A]{1,10}+$ |
| residenceAddressFlatNumber | ˄[A-Za-z0-9ĘęÓ󥹌śŁłŻżŹźĆćŃń\s-.A]{1,10}+$ |
| residenceAddressPostalCode | ˄[09 |
| residenceAddressCity | ˄[A-Za-z0-9ĘęÓ󥹌śŁłŻżŹźĆćŃń\s-.()]{1,64}+$ |
| phoneNumber | ˄((+ |
| bankAccountNumber | ˄([0 9]{26})$ |
| idDocumentType | IDENTITY_CARD |
| idDocumentExpiryDate | Date from the future in the YYYY-MM-DD format |
Parameter requirements are set individually in the process of creating an account, and depend on the scope of the verification and additional functionality to accompany the process (e.g., securing access to reports in PDF files with a password sent to a phone number).
| parameter | allowed values |
|---|---|
| companyName | ˄.{1,150}+$ |
| nip (Tax Identification Number) | ˄\d{10}$ |
| regon (REGON number) | ^(\d{9}|\d{14})$ |
| phoneNumber | ˄((+ |
| companyAddressStreet | ˄[A-Za-z0-9ĘęÓ󥹌śŁłŻżŹźĆćŃń\s-.]{1,64}+$ |
| companyAddressHouseNumber | ˄[A-Za-z0-9ĘęÓ󥹌śŁłŻżŹźĆćŃń\s-.A]{1,10}+$ |
| companyAddressStaircaseNumber | ˄[A-Za-z0-9ĘęÓ󥹌śŁłŻżŹźĆćŃń\s-.A]{1,10}+$ |
| companyAddressFlatNumber | ˄[A-Za-z0-9ĘęÓ󥹌śŁłŻżŹźĆćŃń\s-.A]{1,10}+$ |
| companyAddressPostalCode | ˄[09 |
| companyAddressCity | ˄[A-Za-z0-9ĘęÓ󥹌śŁłŻżŹźĆćŃń\s-.()]{1,64}+$ |
| bankAccountNumber | ˄([30 9 |
| parameter | allowed values |
|---|---|
| phoneNumber | ^((\+|00)?((?!00)\d{2}))?\d{9}$ |
The phoneNumber field is required when the Partner does not verify the email addresses of its users.
| name | type | required | description |
|---|---|---|---|
| redirectUrl | string | yes | The URL to which the Client should be redirected |
| orderUuid | uuid | yes | Verification identifier given by the System |
| status | enum | no | Response status. Assumes the following values: OK and ERROR |
| description | string | no | Additional commentary related to the action. Information message for status=OK, error message for status=ERROR |
Request:
{
"partnerUuid": "cc955e86-…65d2",
"type": "PERSONAL_VERIFICATION",
"email": "jan@example.com",
"params": {
"firstName": "Jan",
"lastName": "Niezbędny",
"residenceAddressStreet": "Ciemna",
"residenceAddressHouseNumber": "1",
"residenceAddressPostalCode": "89-999",
"residenceAddressCity": "Grodkowo",
"bankAccountNumber": "72249000052663617643733450"
}
}
Response:
{
"status": "OK",
"description": null,
"hash": null,
"redirectUrl": "https://id-hub-accept.bm.pl/api/verification/v1.0/start/U5F9VMY8WV",
"orderUuid": "2ed3575a-37a6-487a-a993-b753b6e4e607"
}
GET /api/verification/v1.0/start/<code>
The method is used to redirect the client to the verification Component in order to continue the identity verification process. The redirection should be done using the http GET method.
The only parameter of the method is the unique identifier given by the System in the initiate method.
The implementation of this method is not obligatory. The Partner's system can rely entirely on the address which appeared in the field "redirectUrl", response to the verification initiation request.
The start method is a one-time method. The client can be redirected to the component only once, after which the code is expired.
/api/verification/v2.0/result
The method is used to download the verification result. The response is a document with the verification status, information about the Component used and links to reports, if the selected Component had been configured to calculate and provide additional information about the client.
In each verification component, it is possible to opt out of verification. If the client explicitly chooses to do so, or abandons the process for a period of time specified in the configuration, the verification in the System receives ABANDONED status. In this case, the response from endpoint does not contain any additional data about the client and his details.
In DATA_HARVEST mode, the "result" response object field is understood differently. Only the PENDING value is significant here, which indicates that the data harvesting result is not yet ready. When the data is harvested successfully, the "result" field will have POSITIVE value and will mean that the report attached to the response object is downloadable.
| name | type | required | description |
|---|---|---|---|
| orderUuid | uuid | yes | Verification identifier |
| partnerUuid | uuid | yes | Partner identifier |
| name | type | required | description |
|---|---|---|---|
| result | enum | no | Verification status. Allowed values: ABANDONED - the client has abandoned and not completed the verification process; REJECTED_BY_USER - the client has openly opted out of further verification; POSITIVE - client data verified as consistent; NEGATIVE - client data is inconsistent |
| verificationId | string | no | Verification identifier given by the Partner |
| systemsUsed | enum | yes | Component Used. Allowed values: AIS; 1 PLN; PHOTO |
| resultDetails | map<string, string> | yes | The map of parameters received in the initiate method, in the |
| data | map<string, object> | tak | The map of objects with data declared by user on /initiate and data obtained from veryfing component (used to perform verification). |
| addons | map<string, string> | no | Map of additional parameters returned by the verification components. These may be, for example, addresses to the generated reports. Detailed lists of returned parameters can be found in the paragraphs describing the verification components. |
| status | enum | no | Response status. Allowed values: OK - verification is completed PENDING - verification is not yet completed and you should re-query in a few seconds; ERROR - verification error. The cause of the error could have been, for example, a lost connection to the Client's bank |
| description | string | no | Additional commentary related to the action. For status=OK information message. For status=ERROR error message |
Request:
{
"partnerUuid": "cc955e86-f78f-45fd-a6c8-615ae2be65d2",
"orderUuid": "2bc300b6-ec61-481f-a51f-114f662e9c63"
}
Response in AIS component:
{
"status": "OK",
"description": null,
"result": "NEGATIVE",
"verificationId": null,
"systemsUsed": [
"AIS"
],
"resultDetails": {
"firstName": "NEGATIVE",
"lastName": "NEGATIVE",
"residenceAddressPostalCode": "NEGATIVE",
"residenceAddressStreet": "NEGATIVE",
"residenceAddressHouseNumber": "NEGATIVE",
"bankAccountNumber": "POSITIVE",
"residenceAddressCity": "NEGATIVE"
},
"data": {
"provided": {
"firstName": "Nowak",
"lastName": "Jan",
"city": "Gdańsk",
"street": "Grunwladzka",
"bankAccountNumber": "(...)",
"postCode": "80-180",
"streetHouseNumber": "3"
},
"obtained": {
"city": "warszawa",
"street": "dobra",
"bankAccountNumber": [
"(...)"
],
"postCode": "01-100",
"individuals": [
{
"firstName": "tomek",
"lastName": "widelec"
}
],
"streetHouseNumber": "1"
}
},
"addons": {
"reportUrl": "https://id-hub.accept.bm.pl/ais/report/2f9a6e5d-5ac2-4b00-a3c6-cffb9380ae9a"
}
}
Response in 1PLN component:
{
"status": "OK",
"description": null,
"result": "POSITIVE",
"verificationId": null,
"systemsUsed": [
"1PLN"
],
"resultDetails": {
"firstName": "POSITIVE",
"lastName": "POSITIVE"
},
"data": {
"provided": {
"lastName": "NOWAK",
"firstName": "TERESA"
},
"obtained": {
"individuals": [
{
"firstName": "teresa",
"lastName": "nowak"
}
]
}
},
"addons": {
"streetHouseNumberFromTransfer": "6",
"firstNameFromTransfer": "teresa",
"lastNameFromTransfer": "nowak",
"streetFromTransfer": "długa",
"bankAccountNumberFromTransfer": "(...)",
"unseparatedDataFromTransfer": "Iwona Piesiewicz Teresa Nowak Długa 6 80-233 Gdańsk",
"cityFromTransfer": "gdańsk",
"postCodeFromTransfer": "80-233"
}
}
Response in PHOTO component:
{
"status": "OK",
"description": null,
"result": "NEGATIVE",
"verificationId": null,
"systemsUsed": [
"PHOTO"
],
"resultDetails": {
"firstName": "NEGATIVE",
"lastName": "NEGATIVE",
"idDocumentExpiryDate": "NEGATIVE",
"pesel": "NEGATIVE",
"idDocumentNumber": "NEGATIVE"
},
"data": {
"provided": {
"firstName": "Janina",
"lastName": "Miętka",
"phoneNumber": "123456789",
"idDocumentExpiryDate": "2030-01-01",
"pesel": "70060717411",
"idDocumentNumber": "USZ391914"
},
"obtained": {
"idDocumentExpiryDate": "2021-06-30",
"pesel": "84031221000",
"individuals": [
{
"firstName": "JAN",
"lastName": "PAJĄK"
}
],
"idDocumentNumber": "ATU111111"
}
},
"addons": {
"verificationProblems": "(...)",
"genderFromOcr": "M",
"idDocumentIssuingDateFromOcr": "2011-06-30",
"bioStatus": "NOT_PERFORMED",
"mode": "LIVENESS_PASSIVE",
"idDocumentNumberFromOcr": "ATU111111",
"idDocumentIssueCountryFromOcr": "POL",
"streetHouseNumberFromOcr": "15",
"maidenNameFromOcr": "PAJĄK",
"placeOfBirthFromOcr": "BYDGOSZCZ",
"documentStatus": "SUSPICIOUS",
"idDocumentTypeFromOcr": "IDENTITY_CARD",
"streetStaircaseNumberFromOcr": "a",
"dateOfBirthFromOcr": "1984-03-15",
"cityFromOcr": "gdańsk",
"fullAddressFromOcr": "80-344 GDAŃSK GOSPODY 15A M.143",
"streetFromOcr": "gospody",
"lastNameFromOcr": "PAJĄK",
"fullNameFromOcr": "JAN PAJĄK",
"postCodeFromOcr": "80-344",
"peselFromOcr": "84031221000",
"firstNameFromOcr": "JAN",
"streetFlatNumberFromOcr": "143",
"idDocumentExpiryDateFromOcr": "2021-06-30",
"overallStatus": "SUSPICIOUS"
}
}
GET /api/monitoring/health-check
The method is designed to test the network accessibility of the API. The answer to the demand should be the word: OK and http response code: 200. Any other code and any other answer means that there are problems with the operation of ID-HUB.
The system offers a mechanism for notifying changes in the list of banks. This is effected through notification/push to a specified address.
The address to which the system is to send notifications should be provided by the party integrating with the HUB.
The system sends an empty request (POST) and expects an empty http response with code 204.
By default, the HUB sends one notification and does not try to repeat it even if it has not received the http 204 response code. Repeating is an option that can be enabled on Partner's request.
The HUB can send a notification to the Partner's system, indicating that it is possible to download a ready verification result.
In order to use this functionality, which eliminates the need for cyclic queries about the verification result, the Partner must prepare an endpoint, which will handle the http POST request.
| name | type | required | description |
|---|---|---|---|
| orderUuid | uuid | yes | verification identifier |
| partnerUuid | uuid | yes | partner ID |
The response to such a request should be an empty response, with an http code of 200. Once it is received, the System considers the notification as delivered. Otherwise, it repeats the request with decreasing frequency until it receives the expected response.
NOTE: The list of fields notified to the Partner can be extended. Please include in the implementation the possibility of smooth appearance of new fields in the notification object.
Decreasing frequency means repeats in subsequent iterations, where each subsequent attempt takes place after a longer interval than the previous one. The intervals are calculated according to the Fibonacci sequence, as shown in the table below:
| Attempt repetition | Interval in minutes since previous attempt |
|---|---|
| 1 | 1 |
| 2 | 2 |
| 3 | 3 |
| 4 | 5 |
| 5 | 8 |
| 6 | 13 |
| … | t = (t-1) + (t-2) |
The Client completing the verification process at the HUB is redirected to the Partner's system to the specified return address.
There are two return addresses:
The return to partner's system is made to the addresses exactly as specified in the configuration in the implementation sheet.
Enriching the URL with a verification identifier
It is possible to enrich the URL with one of the following dynamic parameters:
| parameter | description |
|---|---|
| orderUuid | Verification identifier |
| verificationId | Verification identifier assigned by Partner during the verification initiation phase |
NOTE: We add only one of the above parameters to the return address, we do not combine them.
For some different reasons, the result of verification may be not satisfying.
There is a possibility to change the result manually. It's not enabled by default. To access this functionality a request must be sent to Autopay Service Desk. It shall be provided with list of logins which will be used by users changing results. In return Autopay will send confirmation of changing configuration of an account with passwords for given logins. Passwords are not stored in plain text and cannot be restored. After loosing it, they have to be regenerated by Service Desk.
{
"status": "OK",
(...)
"addons": {
"resultChangeUrl": "https://id-hub.bm.pl/v/:uuid1/:uuid2"
}
}
There is a field "resultChangeUrl" in "addons". It contains a unique URL assigned to verification.
When wrong verification result occurs, you have to use the URL from the field above, login to the site and change verification result to expected one.
The change of result may be performed only once and only from POSITIVE to NEGATIVE (and opposite).
After the change, new result notification is sent to the partner's notification URL.
{
"status": "OK",
(...)
"addons": {
"resultSetManually": true,
"resultSetManuallyAt": "2022-10-10 12:34:22",
"resultSetManuallyBy": "jkowalski"
}
}
In "addons" object there are new fields: "resultSetManually", "resultSetManuallyAt", "resultSetManuallyBy".
They carry information that the change was performed, when and by who.
The system offers the functionality of providing confirmations of completed 1PLN and AIS verifications.
The confirmation of the verification performed is a digitally signed .pdf document, which is sent by email to the email address set by the Partner (the address handled by the Partner; not the Client's address).
Generation of AIS confirmation is performed automatically, up to 24 hours after verification is completed, after reports are correctly downloaded using the /result method.
The 1 PLN verification confirmation is generated after the order is placed in the Scribe panel. An order can be placed at any time after verification.
By implementing transport objects into the System API, we suggest configuring the JSON serialization and deserialization tool in such a way that it tolerates the appearance of new fields or their absence. The development of verification components may result in the appearance of new reports or objects providing detailed client data. The basic answer to such a development is API versioning (visible in URLs), but we allow (without wanting to fragment the interface) for minor modifications without versioning entire paths.
We provide network security to our Partners by providing the service via HTTPS. Each endpoint or redirection will present itself with a network certificate issued for the domain: *.bm.pl. Apart from handling traffic via HTTPS, we have a default IP address filtering setting for requests incoming to the System’s API.
If these two methods of network security are not sufficient for the Partner, we allow to create a dedicated network tunnel, via which the Partner's application will be able to communicate with the System services. Establishing such tunnel requires separate arrangements and process, because it is not a solution available in the basic configuration.
It is also possible to control traffic between Partner’s systems and the HUB through the so-called "two-way SSL" mechanism. In this integration model, the Partner's system presents itself with a key signed by Autopay.
The implementation of this method of security, similarly to tunnel establishment, requires separate arrangements between the Partner and Autopay.
An ID-HUB running in AIS mode generates data reports that it sends to the Partner's system and to the verifying user. These reports may contain personal information such as name, address, transaction history from a bank account, etc. Critical to information security is the issue of delivering this information to the correct email address.
At the stage of integration with ID-HUB, the Partner should specify whether the email addresses it will provide at the time of initiation of verification are those confirmed by the user.
If so, ID-HUB will send email messages to the indicated addresses with a link to the site and a password for the reports.
If the Partner is not sure whether the addresses provided by the users are correct, the ID- HUB administrator shall set the appropriate mode in the configuration. As a result of setting it up, ID-HUB will require a phone number during verification initiation. Once the report is generated, the system will send an email to the unverified address and an SMS to the indicated number. In the body of the email will be a link to a website where the reports may be downloaded. The site will be secured with a password, the content of which the user will receive in an SMS.
When a user opens a view where he finds links to reports with his data, he will be able to download them for 20 minutes. After this time, the links will become inactive until the page is reloaded and password authorization made.
In addition to the security features in the transport layer, the System attempts to secure communication also in terms of the integrity of the transmitted data. For this purpose, a method of verifying the correctness of transmitted messages with the conventional name "HMAC" has been prepared.
It involves calculating a checksum from the request body using one of the supported functions:
The checksum calculating process involves a secret, Partner-specific key, which is passed on together with other integration parameters.
The Partner who in the integration process chooses the HMAC authentication method, is obliged to include two headers in each request performed by a method other than the GET method:
We recommend this way of authorizing requests for the following reasons:
A missing or incorrect value of the Hmac-Algorithm header results in response code 400.
A missing or incorrect value of the Hmac header results in response code 401.
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.util.Base64;
class Authenticator {
public static String calculateSignature(String algorithm, String secretKey, byte[] requestPayload) {
Mac mac = Mac.getInstance(algorithm);
mac.init(new SecretKeySpec(secretKey.getBytes(), algorithm));
mac.update(requestPayload);
byte[] signature = mac.doFinal();
return Base64.getEncoder().encodeToString(signature);
}
}
<?php
$code = hash_hmac('sha256', $requestPayload, $secretKey, true);
echo base64_encode($code);
?>
TIP: You can find examples in other programming languages at Joe Kampschmidt's blog.
NOTE: When implementing HMAC authorization, pay attention to invisible newline characters, which may lead to different results of calculated signatures on client and server end. The safest way to do this is to make sure that the serialized object being sent is free of these characters at all.
Authentication of http requests by means of BasicAuth mechanism is used in selected elements of the system, which the System wants to protect against accidental downloading of data by unauthorized users.
In the current version of the documentation and the system, the report download addresses in the AIS component have been secured using the BasicAuth method.
The login and password needed to build the header "Authorization" is given to the Partner at the moment of starting integration with the System, in the implementation sheet.
In the initial integration phase, in the test environment, we have the option to disable the data integrity control mechanism. We recommend using this configuration only in the test environment, in the initial integration phase.
Podziel się opinią