Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update endpoint description to reflect all use cases #138

Merged
merged 2 commits into from
Sep 2, 2024
Merged

Update endpoint description to reflect all use cases #138

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
ccf594f
improve endpoint description
fernandopradocabrillo Aug 20, 2024
59152f5
Update kyc-match.yaml
ToshiWakayama-KDDI Aug 30, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 13 additions & 0 deletions code/API_definitions/kyc-match.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,8 @@ info:

* To prevent fraud, wrong or imprecise information, and/or facilitate the onboarding of a mobile phone user to a 3rd party service.

The API supports a multi-level hierarchy of property validation. In addition to the initial verification of the `phoneNumber`, an additional `idDocument` validation may occur based on different Operator requirements. This means that, in those cases, if the value of `idDocument` is not provided or it does not match the one bound to the specific phone number in the Operator systems, the operation will return an error.

The following figure is the generic high-level flows of this API.

<img width="848" alt="KYC_Match_flow" src="https://raw.githubusercontent.com/camaraproject/KnowYourCustomer/main/documentation/API_documentation/assets/kyc-match_flow.png">
Expand Down Expand Up @@ -70,7 +72,18 @@ paths:
tags:
- Match
summary: Matching a customer identity by checking a set of attributes related against the account data bound to their phone number.
description: |-
Verify matching of a number of attributes related to a customer identity against the verified data bound to their phone number in the Operator systems. Regardless of whether the `phoneNumber` is explicitly stated in the request body, at least one of the other fields must be provided, otherwise a `HTTP 400 - KNOW_YOUR_CUSTOMER.INVALID_PARAM_COMBINATION` error will be returned.

In order to proceed with the match check, some Operators may have the requirement to perform an additional level of validation based on the `idDocument` property. This means that, in those cases, the `idDocument` is required and the provided value needs to match the one stored in the Operator system associated with the indicated `phoneNumber`. This validation will be done before proceeding with the match check of the rest of the properties. The following two rules apply only in the cases where the Operator have the requirement to validate the `idDocument`:
- If no `idDocument` is provided, then a `HTTP 403 - KNOW_YOUR_CUSTOMER.ID_DOCUMENT_REQUIRED` error will be returned.
- If the provided `idDocument` does not match the one stored in the Operator systems, then a `HTTP 403 - KNOW_YOUR_CUSTOMER.ID_DOCUMENT_MISMATCH` error will be returned.
- There is a corner case where the Operator requires the `idDocument` to perform the match validation for the rest of the properties, but it also needs to be able to perform the validation only for the `idDocument` itself. In this case, if only the `idDocument` is provided along with the phoneNumber (either in the request body or extracted from the access token) then the match will be performed as with any other attribute and the response will contain the result of the match operation.

The API will return the result of the matching process for each requested attribute. This means that the response will **only** contain the attributes for which validation has been requested. Possible values are:
- **true**: the attribute provided matches with the one in the Operator systems.
- **false**: the attribute provided does not match with the one in the Operator systems.
- **not_available**: the attribute is not available to validate.
operationId: KYC_Match

security:
Expand Down