Introduction

The Carrier Billing API provides programmable interface for developers and other users (capabilities consumers) to charge an amount on a mobile line. It can be easily integrated and allows end-users to buy digital content in an easy & secured way. The API provides management of a payment entity and its associated lifecycle.

Relevant terms and definitions

• Carrier Billing: An online payment process which allows users to make purchases by charging payments against Telco Operator Billing Systems, accordingly to the user's configuration in the Telco Operator. In a common usage in the industry, the payment is processed on current account balance or charged on next bill generated for this line.

• Payment: The process of paying for a (set of) good(s)/service(s).

• 1-STEP Payment: Payment process performed in one phase (i.e. one action), that involves all the Telco Operator Carrier Billing Systems checking and trigger the charging request against Billing Systems.

• 2-STEP Payment: Payment process performed in two phases (i.e. two actions). First action deals with payment preparation request to guarantee the reservation of the involved amount. Second action is an explicit confirmation or cancellation of the payment by the user. Any payment not confirmed/cancelled by a given user is discarded after some time in order to avoid inconsistency in the billing systems.

API Functionality

This API allows to third party clients to request the payment of a (set of) digital good(s)/service(s), as well as to retrieve information about a specific payment or a list of payments.

In the scope of version v0.3, only one-off payments are covered. Recurrent payments (a.k.a. payment subscriptions) are not covered so far.

The API provides several endpoints/operations:

• An endpoint to request a 1-STEP Payment, named createPayment.
• A set of endpoints to request a 2-STEP Payment:
  • One endpoint to setup the payment reservation, named preparePayment.
  • A couple of endpoints to confirm/cancel such payment reservation, named confirmPayment and cancelPayment respectively.
• A set of endpoints to retrieve information about a list of payments or a specific payment (identified by its specific paymentId), named retrievePayments and retrievePayment respectively.
• A callback endpoint where API Server can send notifications about a payment procedure, as defined within createPayment and preparePayment operations, towards the sink when provided by API client.

The usage of the API is based on Payment resource, which can be created (in 1-STEP or 2-STEP Payment process), confirmed/cancelled (for 2-STEP Payment process), and queried/retrieved (list of payments or a specific payment).

Before starting to use the API, the developer needs to know about the below specified details:

• Payment service endpoint: The URL pointing to the RESTful resource of the payment API. As 1-STEP and 2-STEP processes are managed, 2 separate tags One Step Payment and Two Step Payment have been defined to explicitly distinguish them in the API specification. A third tag Payment is defined for common operations in both processes (query/retrieve list of payments or a specific payment).
• 1-STEP & 2-STEP Payment:
  • 1-STEP Payment: The request intent is to charge an amount to the mobile line. When the server receives the request, it will check the user account associated with this line and, if nothing prevents it, the amount is charged and will be either bill in next invoice or removed from current line credit/balance.
  • 2-STEP Payment: The first call is to request a payment preparation, which implies an amount reservation. The amount is not charged and the server has to be ready to get a confirmation or a cancellation to perform the payment. Only when the confirmation is done, payment is charged. Depending on business rules of the Telco operator, a prepared payment could expire after a defined delay.
• Notification URL: Developers may provide a callback URL (sink param) on which status change notifications, regarding the payment, can be received from the Telco Operator. This is an optional parameter.

Following diagram shows the API resources operation sequencing:

Follow picture provides information about the payment state engine (state description & transition):

State transitions:

1-STEP Payment

If createPayment is a SYNC process:

• Response contains paymentId and paymentStatus=succeeded.
• In case of any error scenario paymentId is not created.

If createPayment is an ASYNC process:

• Response contains paymentId and paymentStatus=processing. After completion:
  • When payment is successfully completed then paymentStatus=succeeded.
  • When payment is not successfully performed then paymentStatus=denied.
• In case of any error scenario paymentId is not created.

2-STEP Payment

FIRST STEP

If preparePayment is a SYNC process:

• Case A - validationInfo is NOT provided in response.
  • Response contains paymentId and paymentStatus=reserved.
• Case B - validationInfo is provided in response.
  • Response contains paymentId and paymentStatus=pending_validation.
• In case of any error scenario paymentId is not created.

If preparePayment is an ASYNC process:

• Case A - validationInfo is NOT provided in response.
  • Response contains paymentId and paymentStatus=processing. After completion:
    • When payment preparation is successfully completed then paymentStatus=reserved.
    • When payment preparation is not successfully performed then paymentStatus=denied.
• Case B - validationInfo is provided in response.
  • Response contains paymentId and paymentStatus=processing. After completion:
    • When payment preparation is successfully completed then paymentStatus=pending_validation. [1]
    • When payment preparation is not successfully performed then paymentStatus=denied.
• In case of any error scenario paymentId is not created.

[OPTIONAL] VALIDATE STEP [1]

After validatePayment, paymentStatus=reserved OR denied, depending whether it was successful or not.

SECOND STEP

After confirmPayment, paymentStatus=succeeded OR denied, depending whether it was successful or not.

After cancelPayment, paymentStatus=cancelled.

Generic Clarification about optional parameters

Regarding optional parameters, they can be conditionally mandatory for a Telco Operator to implement them based on business scenarios or applicable regulations in a given market.

NOTE: Within a given market, in a multi Telco Operator ecosystem, the set of optional parameters to be implemented MUST be aligned among involved Telco Operators.

Authorization and authentication

The "Camara Security and Interoperability Profile" provides details on how a client requests an access token. Please refer to Identify and Consent Management (https://github.com/camaraproject/IdentityAndConsentManagement/) for the released version of the Profile.

Which specific authorization flows are to be used will be determined during onboarding process, happening between the API Client and the Telco Operator exposing the API, taking into account the declared purpose for accessing the API, while also being subject to the prevailing legal framework dictated by local legislation.

It is important to remark that in cases where personal user data is processed by the API, and users can exercise their rights through mechanisms such as opt-in and/or opt-out, the use of 3-legged access tokens becomes mandatory. This measure ensures that the API remains in strict compliance with user privacy preferences and regulatory obligations, upholding the principles of transparency and user-centric data control.

Further info and support

(FAQs will be added in a later version of the documentation)