Align kyc-match with commonalities for meta spring25

[fernandopradocabrillo]

What type of PR is this?

Add one of the following kinds:

• correction
• enhancement/feature

What this PR does / why we need it:

This PR replaces outdated PR #115. Align error model and include required info.description sections according to latest Commonalities agreements (v0.5.0)

[ToshiWakayama-KDDI]

Hi @fernandopradocabrillo ,

Thanks very much for creating the PR. Even though this is for commonalities alignment, there are a lot included. Please allow me to take some time to confirm. I need to consult with my product team.

Many thanks,
Toshi

[ToshiWakayama-KDDI]

Hi @fernandopradocabrillo , @GillesInnov35 , all,

We/KDDI would like to keep the optional phoneNumber even when using a three-legged access token, as the KYC Match API has the optional phoneNumber input since its initial version and so KDDI has already provided API Consumers with this
function (optional phoneNumber). If the input phoneNumber is different from the phone number derived from the access token, 403 Invalid_token_context error is returned. This is for API Consumers (and End users) benefit and convenience. In addition to API Consumers (and End users) benefit and convenience, from backward compatibility perspective, we would like to keep this (the optional phoneNumber even when using a three-legged access token). The Mis-use discussion in Commonalities ended with inclusion of KYC Match as the exception, i.e. KYC Match could have the optional phoneNumber input if the sub-project wants to do so, and it is understood that the commonalities template could be customized by the sub project.

Concretely, the above proposal will affect 'Identifying the phoneNumber from the access token' part and 'Error handling' part of the KYC Match YAML proposal.

Is this proposal acceptable to all?

Best regards,
Toshi

[HuubAppelboom]

@ToshiWakayama-KDDI, all.

From KPN side, we have a different proposal than using an error code in case there is a phone number mismatch with the 3 legged authorization code flow. This proposal is much more in line how the results on other data points are returned in Match, and this is also more flexible towards API Consumers and friendly for end users.

The current implementation returns always an error in case an end user enters the wrong phone number , and as a result the verification results on the other data points are not returned.

This is problematic for those API Consumers which are mainly interested in the other data points, for example a name + address check, or a name + date date of birth check. Most of our customers in the Netherlands fall into this category, and for them the phone number is an extra nice to have data point, for example to prevent fraud, but not a must have. In case there is a mismatch, they would have to ask the end user again for the right number etc, or submit the API again without the phone number in the request body.

We think this kind of friction can be entirely avoided if the number verification result is returned in exactly the same way as the result of the other data points, so as a MatchResult which is true, false or not_available.

In case end user happens to have typed the wrong number or made a typing error, the API Consumer can still decide to use the verification results on the other data points, and decide themselves what to do with the phone number that the end user has entered. They can either completely disregard it, or store it as an unverified number in their customer database, or ask the end user again what the correct number is and verify the number again if that is necessary

This proposal is much more friendly towards API Consumers (they can decide what to do with the information), it is in line what we do with the other data points and with the regular Number Verification, and for API Providers that want to charge extra for the included phone number verification, and extra charge may also be much more easier to implement, because you can base the tariff entirely on the data attributes which are present in the request body of the response.

[ToshiWakayama-KDDI]

Hi @HuubAppelboom , all,

Thanks for your comment.

Please let me understand your comment clearly. So, your proposal is: to accept the optional 'phoneNumber' input even though the 3-legged authorization code flow is used, and to return true/false/not_available for 'phoneNumber' as it is one of the parameters/attributes. Is this correct understanding?

If yes, will the input phoneNumber be compared to the phone number derived from the access token, and not the phone number the MNO (API provider) has? (Maybe these two phone numbers are supposed to be the same, though.)

Thanks,
Toshi

[HuubAppelboom]

@ToshiWakayama-KDDI , all Yes, the proposal is to process the phonenumber information from the request body in case of a authorization code flow in exactly the same way as the other data attributes (like name, date of birth, etc).

The phone number associated with the access token in case of the authorization code flow is by definition always the number retrieved from the mobile network, and should always be treated as the correct number, againts which all verifications should be done. In the authorization flow the phone number in the request body is always the phone number the user has entered.

[GillesInnov35]

hi @HuubAppelboom, you've confirmed that in your proposition

the input phoneNumber be compared to the phone number derived from the access token

I'm wondering why the phoneNumber attributes (if provided in the request body) should be managed differently from the others parameters if the objectives of the API is to check and compare provided attributes with those held by the MNO.

Gilles

[HuubAppelboom]

hi @HuubAppelboom, you've confirmed that in your proposition

the input phoneNumber be compared to the phone number derived from the access token

I'm wondering why the phoneNumber attributes (if provided in the request body) should be managed differently from the others parameters if the objectives of the API is to check and compare provided attributes with those held by the MNO.

Gilles

@GillesInnov35 Hi Gilles,

No, I think you misunderstand it. The idea is that we process all the data attributes that are provided in the request body in the same way, including the phone number attribute. All these data attributes are presumably the data the end user has provided to the API consumer. All these attributes are compared to what the MNO holds (based on the phone number associated with the Access Token, because that is in the authorization code flow always correct).

[ToshiWakayama-KDDI]

Thanks, @huub. We/KDDI are happy with Huub KPN's proposal and support the proposal to have 'phoneNumber' one of the optional parameters and to return 'phoneNumberMatch' result (true/false/not_available).

Probably four changes will be needed as overviewed below:

1. API General Description
The following points to be added:

• 'phoneNumber' can be input as an optional parameter even when the three-legged access flow is used.
• The phone number is derived from the access token, and it is used for identifier of the subscription contract to check.
• Together with other parameters, 'phoneNumber' will be checked with that of MNO's, and the match result of 'phoneNumber' will be returned.

2. Identifying the phoneNumber from the access token

• In the two-legged access flow case, 'phoneNumber' must be provided. (no change)
• In the three-legged access flow case, the 'phoneNumber' can be input as on optional parameter, but the phone number of the device is derived from the access token and it is used for the key identifier of the subscription.

3. Error handling

• 422 MISSING_IDENTIFIER is still valid. (no change)
• 422 UNNECESSARY_IDENTIFIER is not valid for KYC Match and to be removed.

To note, when the phone number derived from the access token and the input 'phoneNumber' are different, API will return 'false', not an error.

4. API definition

• Add 'phoneNumber' in the request example for 3-legged access token.
• Add 'phoneNumberMatch' parameter definition, and add it in the response example.
• Add 'phoneNumberMatch' definition

Please point out anything missing or wrong, as the above is based on my quick thoughts.

Thanks,
Toshi

[HuubAppelboom]

Thanks, @huub. We/KDDI are happy with Huub KPN's proposal and support the proposal to have 'phoneNumber' one of the optional parameters and to return 'phoneNumberMatch' result (true/false/not_available).

Probably four changes will be needed as overviewed below:

1. API General Description The following points to be added:

• 'phoneNumber' can be input as an optional parameter even when the three-legged access flow is used.
• The phone number is derived from the access token, and it is used for identifier of the subscription contract to check.
• Together with other parameters, 'phoneNumber' will be checked with that of MNO's, and the match result of 'phoneNumber' will be returned.

2. Identifying the phoneNumber from the access token

• In the two-legged access flow case, 'phoneNumber' must be provided. (no change)
• In the three-legged access flow case, the 'phoneNumber' can be input as on optional parameter, but the phone number of the device is derived from the access token and it is used for the key identifier of the subscription.

3. Error handling

• 422 MISSING_IDENTIFIER is still valid. (no change)
• 422 UNNECESSARY_IDENTIFIER is not valid for KYC Match and to be removed.

To note, when the phone number derived from the access token and the input 'phoneNumber' are different, API will return 'false', not an error.

4. API definition

• Add 'phoneNumber' in the request example for 3-legged access token.
• Add 'phoneNumberMatch' parameter definition, and add it in the response example.
• Add 'phoneNumberMatch' definition

Please point out anything missing or wrong, as the above is based on my quick thoughts.

Thanks, Toshi

@ToshiWakayama-KDDI Hi Toshi, to me it looks ok.
Just one question though. Should we mention that it is only relevant for the Authorization Code flow (and not for CIBA, which is also a 3 legged flow) ?