Paymentwithorange TV bill 1.0

Table of Contents

• Prerequisite authentication
• Base URL
• Resources
• Errors

Prerequisite authentication

Access to this API is secured by the OAuth 2.0 framework with the Client Credentials grant type, which means that you will have to present an OAuth 2.0 access_token whenever you want to request this API.

It's easy to negotiate this access_token: just send a request to the proper token negotiation endpoint, with a Basic Authentication header valued with your own client_id and client_secret.

For this API, the token negotiation endpoint is:

https://ope.apibackbone.orange.com/oauth/v3/token

A technical guide is available to learn how to negotiate and manage these access_token.

Important

• Please pay particular attention to properly handle authentication error responses in your application. See the section Errors
• The access_token default lifetime is 60 minutes.
• Header Accept: application/json is now required, when it’s omitted you will receive an error 406 error.

Base URL

The Base URL is the first part of the full invocation URL, just before the resource paths. Whenever you make requests on this API, you will need to prepend the following Base URL to the resource paths defined for this API.

If you request this API and encounter a 404 NOT FOUND HTTP error response, please check first that the Base URL is correct.

The Base URL for this API is:

https://ope.apibackbone.orange.com/pay-with-orange-tv-bill/v1

Resources

Description

WTV publishes APIs for Orange or trusted editors to handle payment on bill for Orange TV clients. APIs include single payment or periodic payment with tacit renewal.

APIs offers two mode to complete the payment :

• 1 STEP : the payment is completed with a simple request
• 2 STEP : the payment is completed with a 1st authorization request and a 2nd one to confirm or cancel the payment

Pre requisites

• The editor is responsible for the purchasing journey and customer authentication.
• The editor must be declared on the WTV platform which provides a merchant identifier. The merchant identifier must be sent in the header X-WTV-PARTNER-ID in every request.
• In the case of recurring payment, the catalog of offers is centralized on WTV and must be declared on the MSCA web application.
• The publisher must obtain a "presta code" from Orange for managing Orange invoice display.

Glossary

• transaction : single payment or subscription payment for a period
• subscription : periodic payment with tacit renewal
• offer : payment information model
• partner : Orange or trusted editor that is client of APIs

Use cases

• WTV APIs works in a partner flow where the client must be authenticated by Orange (through WT proxy for external partners). The application will present a payment form to the client to access a paid service. Once the client validate the payment, the partner can use WTV API to process the transaction. Access to WTV APIs is protected by OAuth2 authentication so the partner has to request an access token before using WTV APIs.
• The partner can choose to process the transaction in 2 differents modes : 1 step or 2 steps.
• The payment works with single payment or subscription to periodic payment with tacit renewal.
• Once the client is authenticated, the partner can check active subscriptions or handle subscription termination too.
• 
• Sequence for single payment in 1 step mode. The service returns a transaction object with an identifier and a confirmed status.
• 
• Sequence for subscription to a periodic payment in 1 step mode. The service returns a subscription object with an identifier and an active status.
• 
• Sequence for single payment in 2 steps mode. The creation service returns a transaction object with an identifier and an authorized status.
• The partner must send a confirmation request to complete the process. The step can be offline for the client and can be delayed up to 24 hours.
• 
• Sequence for subscription to a periodic payment in 2 steps mode. The creation service returns a subscription object with an identifier and an authorized status.
• The partner must send a confirmation request to complete the process. The step can be offline for the client and can be delayed up to 24 hours.
• 
• Sequence for single payment in 2 steps mode but finally cancelled by the partner.
• 
• Sequence for subscription to a periodic payment in 2 steps mode but finally cancelled by the partner.
• 

Errors

Important

Failure to code a proper management of the error responses in your application may affect its resilience. Access to the API may be revoked if your application generates too many mishandled errors.

Your application must parse the returned HTTP response to check if an error is returned instead of a 200 OK. Orange APIs use appropriate HTTP status codes to indicate any request processing error, providing detailed information about the underlying fault. This helps you provide better feedback to your users and implement failure recovery mechanism in your application.

For details on the main error codes, response format, tips and troubleshooting, see our Handling API errors guide. Here are the most common client errors encountered.

Errors 401

If you get a status code 401 with the error code 42 (such as below), then request a new access_token.

HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
  "code": 42,
  "message": "Expired credentials",
  "description": "The requested service needs credentials, and the ones provided were out-of-date."
}

Important

• Each access_token has a lifetime validity period (60 minutes by default). This validity period may change overtime to comply with security rules.
• Token requests are limited to 50 requests per minutes, when the rate limit is exceeded you will receive an error 429. Therefore, DON'T request an access_token each time you invoke the service API. DON'T hard-code a validity duration in your application. Instead, your application must parse the returned status code and error code to check if it needs to request a new access_token.

For other 401 errors: check that you provide the right Autorization header with the right Bearer.

API level Errors

In case of invalid request to the API, you will receive an error object in the body like the example below :

HTTP/1.1 400 Bad Request
{
  "code": 25,
  "message": "...."
}

Error can be identified with the field "code". Here is the list of possible error cases :

• 1001 : invalid request parameter
• 1002 : invalid request json format
• 1003 : access forbidden
• 1004 : technical error
• 1005 : operation failed
• 2001 : unknown credential
• 2002 : unknown partner identifier
• 2003 : unknown offer identifier
• 2004 : unknown transaction identifier
• 2005 : unknown subscription identifier
• 3001 : invalid transaction status
• 3002 : invalid subscription status
• 3003 : not debit transaction
• 3004 : max spending limit
• 3005 : multi subscription for same offer
• 3006 : insufficient balance error
• 3007 : invalid account status
• 3008 : duplicate partner reference identifier

Consult all generic errors.