Getting started

• Introduction
• API Scope
• Subscribe to the API
• API Authentication
• API Description
  • Summary of resources
  • Summary of methods and URL
  • Summary of request body parameters
  • Summary of response parameters
  • kyc match operation description
    • Request
    • Response
    • Fields description
  • Most frequent errors
• History of document

Introduction

The CAMARA KYC Match API offers a standardized way for service providers (SP) to compare their user information with the verified KYC records held by the user's operator. This process helps the SP confirm the accuracy of the information and deliver specific services to the user.

API Scope

The current API implementation is applicable for Live Trials with Orange Belgium (preselected list of MSISDN).

Subscribe to the API

You get the Authorization header credentials when you register your application on the Orange Developer Console.

API Authentication

HTTPS requests to the REST API are protected with CIBA 3-Legged OAuth.

In short, the API Invoker (e.g. Application Backend or Aggregator) before requesting KYC match, needs to request a Three-Legged Access Token from Orange Authorization Server. The process follows the OpenID Connect Client-Initiated Backchannel Authentication (CIBA) flow.

Step 1: request the OAuth authorization code from the user device

The API Invoker provides in the authorization request (/bc_authorize) a login_hint with a valid User identifier together with the application credentials (client_assertion & client_assertion_type) and indicates the Purpose for processing Personal Data. The Orange implementation follows the CAMARA scope definition. The scope must be set to: opendid dpv:<dpvValue> <technicalParameter>. dpv stands for Data Privacy Vocabulary.

Note on JWT usage via client assertion: client_assertion is a JWT used by a client to authenticate itself to an authorization server, while client_assertion_type specifies the type of assertion being used, typically indicating it is a JWT. Together, they facilitate secure client authentication in OAuth 2.0 and OpenID Connect protocols. API consumer as to define JWK keystore in settings tab of the application in Orange Developer

For current implementation, only FraudDetectionAndPrevention dpv value is managed, which means that to execute the KYC match process the scope in the bc-authorize must be set to openid dpv:FraudPreventionAndDetection kyc-match

Orange Authorization Server will check if the owner of the phone number did not opted-out to authorize access to this data. If this is not the case a response 200 is sent back with a authorization request identifier (auth_req_id). If the resource owner or OpenID Provider denied the request an error 403 Forbidden is sent back. Note: This is not yet available.

Request:

curl -X 'POST' \
  'https://api.orange.com/openidconnect/ciba/be/v1/bc-authorize' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'scope=openid%20dpv%3AFraudPreventionAndDetection%20kyc-match&login_hint=tel%3A%2B32493456721&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer&client_assertion=eyJraWQiOiJzYW...8jK9lM0nPqRstUvwXYZ'

          
          Copied 
        

Response:

200 
Content-Type: application/json

          
          Copied 
        

{
  "auth_req_id": "3f7b2e8a-9cde-4f3b-8b12-1a2b3c4d5e6f",
  "expires_in": 120,
  "interval": 2
}

          
          Copied 
        

Step 2: Request the OAuth access token

Once the client application gets the authorization code, the API Invoker polls the token endpoint by making an "HTTP POST" request by sending the grant_type (urn:openid:params:grant-type:ciba), auth_req_id (OperatorAuthReqId) and the the application credentials (client_assertion & client_assertion_type) parameters

If the transaction succeeds, in the POST response, the acccess_token is provided.

Request:

curl -X 'POST' \
  'https://api.orange.com/openidconnect/ciba/be/v1/token' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=urn%3Aopenid%3Aparams%3Agrant-type%3Aciba&auth_req_id=3f7b2e8a-9cde-...-1a2b3c4d5e6f&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer&client_assertion=eyJraWQiOiJzYW1wbGU...K9lM0nPqRstUvwXYZ'

          
          Copied 
        

Response:

200 
Content-Type: application/json

          
          Copied 
        

{
  "access_token": "G5kXH2wHvUra0sHlDy1iTkDJgsgUO1bN",
  "token_type": "Bearer",
  "refresh_token": "4bwc0ESC_IAhflf-ACC_vjD_ltc11ne-8gFPfA2Kx16",
  "expires_in": 120,
  "id_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6...rGvsIIwk1uExynJIv_tgZGE0eZI7MtVb2UlCwDQrVlg"
}

          
          Copied 
        

Step 3: Access protected resources using OAuth access token

In order to call our API, the access_token is mandatory.

Specific documentation about KYC match resources is provided below.

Go up

API Description

This API is based on version 0.2 of the API kyc-match.

Summary of resources

This API has one resource match. This operation verifies matching of a number of attributes related to a customer identity against the verified data bound to their phone number in the Operator systems.

Summary of methods and URL

Summary of request body parameters

In bold parameters currently available in Orange Belgium KYC Match API:

Example of Body value:

{
    "phoneNumber": "+32495131517",
    "givenName": "Maeva",
    "familyName": "Huart",
    "locality": "Evere",
    "address": "Av. du Bourget 3 a, 1140 Evere",
    "postalCode": "1140",
    "country": "be",
    "email": "maeva.huart@orange.be",
    "birthdate": "1978-08-22"
}

          
          Copied 
        

Summary of response parameters

In bold parameters currently available in "KYC Match - CAMARA - Belgium - Client credentials" API

Note that the algorithm applies normalization rules regarding spaces, special characters, and case for comparison purposes.

kyc match operation description

Request

curl -X POST "https://api.orange.com/camara/obe/kyc-match/v0.2/match"
-H "Authorization: Bearer {your access token}"
-H "Cache-Control: no-cache"  
-H 'accept: application/json'
-H 'Content-Type: application/json'
-d  {
    "phoneNumber": "+32495131517",
    "givenName": "Maeva",
    "familyName": "Hurt",
    "address": "Av. du Bourget 3 a, 1140 Evere",
    "locality": "Evere",
    "email": "maeva.huart@orange.be"
}

          
          Copied 
        

Response

200 Match successful
Content-Type: application/json

          
          Copied 
        

{
    "giventNameMatch": "True",
    "familyNameMatch": "False",
    "familyNameMatchScore": 90,
    "addressMatch": "True",
    "localityMatch": "False",
    "localityMatchScore": 95,
    "emailMatch": "True"
}

          
          Copied 
        

Fields description

The response contains

• MatchResult attributes valued to true when user's information matches exactely with information held by the Operator, false when it doesn't match exactly or not_available when the MNO doesn't hold user's information.
• MatchScore, a numerical value that quantifies the similarity between two pieces of text based on the words they contain for some MatchResult attributes in case of value is equal to false.

Most frequent errors

If invalid or incomplete input are provided a 400 error is triggered.

HTTP/1.1 400 Error: bad Request
Content-Type: application/json
{
  "status": 400,
  "code": "INVALID_ARGUMENT",
  "message": "Client specified an invalid argument, request body or query param"
}

          
          Copied 
        

If missing, invalid, or expired credentials an error 401 is send back

HTTP/1.1 401 Error: Unauthorized
Content-Type: application/json
{
  "status": 401,
  "code": "UNAUTHENTICATED",
  "message": "Request not authenticated due to missing, invalid, or expired credentials."
}

          
          Copied 
        

If the service is not supported for the phone number, error code 422 is retrieved.

HTTP/1.1 422 Error: Unprocessable Content
Content-Type: application/json
{
  "status": 422,
  "code": "NOT_SUPPORTED",
  "message": "Service not supported for this phoneNumber"
}

          
          Copied 
        

If the service is not up and running, a 503 error is sent.

HTTP/1.1 503 Service unavailable
Content-Type: application/json
{
  "code": "UNAVAILABLE",
  "status": 503,
  "message": "Service unavailable"
}

          
          Copied 
        

Go up

History of document

Go up