Home Verify France - Mobile ID

2.0

• 2.0 (current)
• 1.0 (deprecated)
• 0.0 (deprecated)

The Customer Bill France API v2 gives you the last (more recent) Orange bill in PDF format for Orange customers authenticating on your service through the Orange Authentication API. It can typically be used as a proof od address. It is applicable to any mass-market Orange France customer, and includes SOSH customers.

You will need the end-user's consent in order to access his bill. A dedicated UI is provided with the Orange Authentication API.

Before starting

Our Customer Bill France API requires a 3-legged authentication with our OpenID Connect platform. Please follow the method described here, with customer_bill_last scope, in order to get an access token that will be granted to retrieve the end-user's bill.

Retrieve Orange customer's information

You need a valid access token to invoke the Customer Bill France API. This access token must be provided in the HTTP Authorization header:

curl -X GET \
    -H "Authorization: {authorization_header}" \
    -H "Accept: multipart/related" \
    https://api.orange.com/customerbill/fr/v2/last

As an example:

curl -X GET -H "Authorization: Bearer OFR_FJSyJ...Gms_a92e3fb8b16...0a75ef4" -H "Accept: multipart/related https://api.orange.com/customerbill/fr/v2/last

Note that you also need to accept the 'multipart/related" content type.

a/ If the transaction succeed

In the context of the Customer Bill France API v2, the customer_bill_last scope gives permissions to the following claims:

The 'CustomerBill' JSON object provides descriptive metadata of the Orange customer's bill. It is bound of the following attributes:

On success, the Customer Bill /last request returns a 200 OK HTTP status code with multipart data: a first JSON part containing requested claims about the end-user, and one or two PDF parts containing the mobile and/or internet bill.

HTTP/1.1 200 OK
Content-Type: multipart/related ;boundary="=_963c34cabe7ebdb48811182c420494f8"; type=application/json; 
start="<9d3238f13ad5ac908f7e5642bb32276b@orange.fr>"; start-info="<9d3238f13ad5ac908f7e5642bb32276b@orange.fr>, 
<1cf87722739cb13783f1824ef549b791@orange.fr>"
Content-Encoding: gzip
Transfer-Encoding: chunked
X-OAPI-Request-Id: OPOPECBALLRT01_CWDM2W5PI_RouterProxy-8-3319067_1

--=_963c34cabe7ebdb48811182c420494f8
Content-Type: application/json; charset=utf-8
Content-Transfer-Encoding: 8bit
Content-ID: <9d3238f13ad5ac908f7e5642bb32276b@orange.fr>

{
   "sub": "PBYJJF-200-DwltrLnXq+7jwTQEkOx9Z9jelg0t0NQrxWFasUgUgEs=",
   "customer_bills": [
      {
         "contract_type": "mobile",
         "file_id":"cid:3438f5ceb1f97bca26f500b2f703d17d@orange.fr",
         "creation_date":"2016-08-09"
      },
      {
         "contract_type": "internet",
         "file_id":"cid:1cf87722739cb13783f1824ef549b791@orange.fr",
         "creation_date":"2016-08-09"
      }
   ]
}
--=_963c34cabe7ebdb48811182c420494f8
Content-Type: application/pdf; charset=IBM850
Content-Transfer-Encoding: 8bit
Content-ID: <3438f5ceb1f97bca26f500b2f703d17d@orange.fr>
Content-Disposition: attachment; filename="FactureM.pdf"

%PDF-1.4
...
%%EOF

--=_963c34cabe7ebdb48811182c420494f8
Content-Type: application/pdf; charset=IBM850
Content-Transfer-Encoding: 8bit
Content-ID: <1cf87722739cb13783f1824ef549b791@orange.fr>
Content-Disposition: attachment; filename="FactureI.pdf"

%PDF-1.4
...
%%EOF

--=_963c34cabe7ebdb48811182c420494f8--

Absence of invoice

There are scenarios where some customers have no bill (new customer of less than a month, some cases of migration). For these customers, the absence of invoice is not considered as an abnormality. In application of the recommendations of Orange, the Customer Bill API sends back a code HTTP 200 and an empty customer_bills structure, that is hooks without anything inside: [].

HTTP/1.1 200 OK
Content-Type: multipart/related ;boundary="=_963c34cabe7ebdb48811182c420494f8"; type=application/json; 
start="<9d3238f13ad5ac908f7e5642bb32276b@orange.fr>"; start-info="<9d3238f13ad5ac908f7e5642bb32276b@orange.fr>"
Content-Encoding: gzip
Transfer-Encoding: chunked
X-OAPI-Request-Id: OPOPECBALLRT01_CWDM2W5PI_RouterProxy-8-3319068_1

--=_963c34cabe7ebdb48811182c420494f8
Content-Type: application/json; charset=utf-8
Content-Transfer-Encoding: 8bit
Content-ID: <9d3238f13ad5ac908f7e5642bb32276b@orange.fr>

{
   "sub": "PBYJJF-200-DwltrLnXq+7jwTQEkOx9Z9jelg0t0NQrxWFasUgUgEs=",
   "customer_bills": []
}
--=_963c34cabe7ebdb48811182c420494f8

b/ If the transaction failed

In case of error, the Customer Bill endpoint returns an error response (JSON format) with the following information:

• code (required): single ASCII error code
• message (required): short localized string that describes the error.
• description (optional): human-readable ASCII text providing additional information, used to assist the developer in understanding the error that occurred.

If the access_token is missing, a 401 Unauthorized HTTP status code is returned.

HTTP/1.1 401 Unauthorized
Content-Type: application/json; charset=utf-8

{
   "code": 40,
   "message": "Missing or invalid credentials",
   "description": "The requested service needs credentials, but the ones provided were invalid or missing."
}

If the access_token is expired, revoked or invalid, a 401 Unauthorized HTTP status code is returned. In that case, you'll have to renew the access token.

HTTP/1.1 401 Unauthorized
Content-Type: application/json; charset=utf-8

{
   "code": 41, 
   "message": "Invalid credentials", 
   "description": "access token resource OFR_FJSyJ...Gms_a92e3fb8b16...0a75ef4 not found"
}

If the user is not eligible to the service despite the check already done during user consent phase, a 403 Forbidden HTTP status code is returned with the following JSON response:

HTTP/1.1 403 Forbidden
Content-Type: application/json; charset=utf-8

{
   "code": 1590,
   "message": "User identifier is not eligible",
   "description": "User Id does not meet at least one eligibility criterion"
}

If the user doesn't exist, a 404 Not Found HTTP status code is returned with the following JSON response:

HTTP/1.1 404 Not Found
Content-Type: application/json; charset=utf-8

{
   "code": 1591,
   "message": "User identifier does not exist",
   "description": "User Id does not exist"
}

If the request , a 406 Not Acceptable HTTP status code is returned with the following JSON response:

HTTP/1.1 406 Not Acceptable
Content-Type: application/json; charset=utf-8

{
   "code": 62,
   "message": "Not acceptable",
   "description": "'multipart/related' must be accepted for the customer bill API."
}

See API Reference section for the exhaustive list of error codes.

We will always be there to support you if needed.