NumberVerify (CAMARA)0.4.0

Number Verify (CAMARA) uses a three-legged OAuth flow. A three-legged OAuth process involves three parties: the end-user (or resource owner), the client (the third-party application), and the server (or authorization server):

1. Get an authorization code
2. Exchange the authorization code for an access token
3. Match the mobile number

For more information on OAuth, see OAuth 2.0 RFC 6749, section 4.1 (external website).

1. Make a request to Vodafone’s “/bc-authorize” endpoint.
2. Vodafone's API validates the client_id provided.
3. Vodafone obtains the mobile number of the user (of the application using the mobile network).
   This is achieved by the Vodafone returning a series of HTTP redirects that the application should follow.
4. Vodafone provides an authorization code back to the application.

Authorization request example

GET 'https://stagingref.eu3.api.vodafone.com/openIDConnectCIBA/v1/bc-authorize' \
    Content-Type: application/x-www-form-urlencoded \
    Accept: application/json \
    redirect_uri=https%3A%2F%2Fexample.com%2Fmc &client_id=asQIujGX4tD9eBMgeO8LnzyRnalkTGoG &scope=dpv:FraudPreventionAndDetection#number-verification:verify &response_type=code
    

Authorization response example

HTTP/1.1 302 Found
    Location: https://sp.example.com?code=SplxlOBeZQQYbYS6WxSbIA
    &state=af0ifjsldkj &correlation_id=42da5b19-457a-4d30-a5c4-038c62dccbb0
    

In order to use this API, you must exchange the authorization code for an access token.

The token is valid for 59 minutes and 59 seconds. It can be used for multiple requests.

The bearer tokens can only be used for a specific country. For example: If you generate a token for a UK mobile number (MSISDN), you cannot use it to query a German number.

If the request is valid, the API returns an access_token, along with expiry and scope information.
This access token can then be used in one or more requests, for as long as the token remains valid.

If the request is not valid, the APIs returns an error message.

To exchange the authorization code for an access token:

1. Make a “/token” request.
2. Validate the “id_token” within the response. This to ensure it was issued from the correct authorization server, the correct client_id, and in a timely manner.

Token request example

curl POST 'https://eu3.api.vodafone.com/openIDConnectCIBA/v1/token' 
    Authorization: Basic ZTcxNWE2OTYtYTY3OS00YmFhLTk3ODctYTU0ZmYlMTFhNmQ4OjdhMzM3OGI5LWZkMTQtNGNhYy1hZTc 3LTkwZGVmZmZkYWQ5Yg==
    code=w4tngz6O&state=1234&redirect_uri=https://sp.example.com &grant_type=authorization_code
    

Token response example

200 OK
    Server: VF
    Content-Type: application/json
    Content-Length: 165
    Cache-Control: no-store
    Pragma: no-cache.
    Content-Length: xx.
    Content-Type: application/json
    {
    "access_token": "OohPZluqx9NYtkTA3Ok6yfRmIECi", "token_type": "Bearer",
     "expires_in": 3599,
    "id_token": "eyJraWQiOiJhcGl4IiwidHlwIjoiSldUIiwiYWxnIjoiUlMyNTYifQ.eyJhdF9oYXNoIjoia0V3dzB SdF81dk8tZGo5UjFoY0dlQSIsInN1YiI6IjZmODVjM2EyLTRlY2EtNGM4Yy1hNDI4LWQ0NjNlNmIxNz NmNiIsImNyaWQiOiIyOTQ4NDUyNSIsImFtciI6WyJTTVNfVVJMX09LIl0sImlzcyI6Imh0dHBzOi8vY XBpc3RhZ2luZ3JlZi5kZXZlbG9wZXIudm9kYWZvbmUuY29tIiwibm9uY2UiOiIxMjM0NTY3OCIsImF1 ZCI6ImU3MTVhNjk2LWE2NzktNGJhYS05Nzg3LWE1NGZmZTExYTZkOCIsImFjciI6InVybjp2b2RhZm9 uZTpsb2E6YnJvbnplOnNtc3VybCIsImF6cCI6ImU3MTVhNjk2LWE2NzktNGJhYS05Nzg3LWE1NGZmZT ExYTZkOCIsImF1dGhfdGltZSI6IjE1NjUzNTI3MjAiLCJleHAiOjE1NjUzNTYzNjgsImlhdCI6MTU2N TM1Mjc2OCwianRpIjoiNGFlMTJlNzMtMDY4Yi00ZTUyLWJmMmMtOWUyNjdiNGQ3NDNmIn0.U3MO6FFr 3l0G6_TvmlbpGyxVPxZKCQyvB_1J5TFeA8Jlx7KhE1nf9LDVw22eX2X6- 1ogqKLGXl_4Q3ou0p_lMk2z8uFGulHB4Xv51qAMdLwA9XPfoW7j2fVaoRdjSDWQbNpurpyC0sHWsSJt -
    O4SP_All1_PTtv8MBlIPJyLpFsSU3cAnbQcXQ8NQ5FqNfAlgj11ejsxBOzr8UaT0wYMOCapz8V89FmQ 9F7fj- YpNoco4r8G_KSkjjbSWL4FdTbxTQ2iBNAKtoaTN2bmbVfUaADMJDDdTeLTJerpNbi4LVlqkvhKiSWzI UOBf_10FKt4KUffnx4AK_IAvS49nwwt5w"
    }
    

Decoding the id_token gives the following JWT header and payload:

{
      "kid": "apix",
      "typ": "JWT",
      "alg": "RS256"
    } {
    "at_hash": "kEww0Rt_5vO-dj9R1hcGeA",
    "sub": "6f85c3a2-4eca-4c8c-a428-d463e6b173f6", "amr": [
    "SEAM_OK" ],
    "iss": "https://stagingref.eu3.api.vodafone.com", "nonce": "12345678",
    "aud": "e715a696-a679-4baa-9787-a54ffe11a6d8", "acr": "2",
    "azp": "e715a696-a679-4baa-9787-a54ffe11a6d8", "auth_time": "1565352720",
    "exp": 1565356368,
    "iat": 1565352768,
    "jti": "4ae12e73-068b-4e52-bf2c-9e267b4d743f"
    }
    

1. Use the access token to make a request to the Vodafone API. To match the mobile number (MSISDN), you must provide a mobile number in the request.
2. Vodafone determines the result of the Number Verify transaction.
3. The result of the Number Verify transaction is stored before the response to the request is returned.
4. Vodafone sends the response.

Endpoint request example

This example is for mobile number “+447767787999”:

curl POST 'https://stagingref.eu3.api.vodafone.com/camara/number-verification/v0/'
    Authorization: Bearer LTRjZDMtNDUyYi1iNjk
    {
    "device-phone-number" : {
    "device_msisdn_hash" :
    "73e5578761e35869a6a97cc9a30d93f32c695c82aa4aa0e6cbdffadb52f5ac8c" },
    "correlation_id" : "TEST_CORRELATION_ID" }
    

Note: The attributes must be sent in hashed format: SHA-256 hash in hexadecimal format, lower-case. The mobile number must be prefixed with “+” and the country international dialling prefix.

Sample response

Below is an example response. In this situation, the mobile number provided did not match the number stored in the Vodafone database:

HTTP/1.1 200 OK.
    Date: Tue, 03 Oct 2023 09:37:43 GMT.
    Server: XXXXXXX
    Expires: Thu, 19 Nov 1981 08:52:00 GMT.
    Cache-Control: no-store, no-cache, must-revalidate, post-check=0, pre-check=0. Pragma: no-cache.
    Content-Length: xx.
    {
    "sub": "cd45a691-d311-4134-9a0c-2747e5110d22", "devicePhoneNumberVerified": true
    }
    

MSISDN for the Sandbox environment

The phone number is in a hashed format and present in the body of API.

"hashedPhoneNumber": "6dd5d20f257c1f3620662454064e3aa25ba9a6c7a4d1e99e965bbadd3a7e07d6"