Skip to end of metadata
Go to start of metadata

Introduction

Apstrata exposes a generic billing API that enables mobile and web application developers to seamlessly plug into the billing system of Telecom operators with whom Apstrata have signed a partnership.

Using the Apstrata billing API, mobile and web application developers can trigger the payment of goods directly from the mobile device (or the web page) of the application users, as long as these latter are subscribed to a line that belongs to the selected operator.

Billing models

Two main billing models are natively supported: "application" and "transaction"

The "application" model only requires the user to authorize the application once to pay on his behalf, by entering his credentials (those that authenticate him against the Telecom operator system, not against your application). After your user authorizes the application, you won't need to request for authorization every-time the application loads on the mobile device.

The "transaction" model implies the former (the user needs to authorize the application once) but also requires the user to approve every payment transaction by entering his credentials.

There also exist a derived version of the first billing model ("application") that is targeted to a specific category of developers known as "trusted partners". Entering the circle of "trusted partner" is actually a contractual matter that binds the developer to the Operator implementing the Billing API. Trusted partners can directly authorize an application on behalf of their users, replacing thus the two-steps authorization process triggered by "billing.requestAppAuthorization" with a one-step approval using "billing.trusted.registerApplication" (see usage scenario below).

When invoking the API by issuing HTTP calls, make sure to sign your request using your developer username and password (i.e. those used to register to the cloud developer web site).

Invoking the billing API

The billing API is directly accessible from your server-side scripts as a native object (the object has the name of the Telecom operator you will resort to for billing your users).

Another alternative is to invoke the billing functions that are exposed as first class functions in the corresponding SDKs.

You can also invoke the API using the RunScript API as you would do it for any other Apstrata server-side script. Read more about how to do this here.

Usage scenario

Step1: whatever billing model was selected, the application needs to verify that it has the user's authorization before proceeding to the payment procedure. The application can use the "billing.requestAppAuthorization" API on that purpose (or "billing.trusted.registerApplication" if the developer is a "trusted partner"). 

Step 2: if the user did not previously authorized the application, this latter has to invoke the "billing.requestAppAuthorization" API in order to trigger the authorization procedure. The API returns a result similar to the following:

"result": {
		"status": "success", 
		"authorizationUrl": "http://www.touch.com.lb/autoforms/view/authorization?token=ED26D8E7464B88D341D6DB11560F713B&authenticationkey=BILLING#&scriptName=billing.requestAppAuthorizationController"
	}

There are two important things to note here:

  • The authorizationUrl is the URL of the authorization pop-up hosted by the telecom operator. Your application should open this URL so the user can enter his credentials (the one provided to him by the telecom operator). Your application should keep this URL as long as the user did not authorize the application (so you can open it another time).
  • The above mentioned URL also contains parameters among which the "token" parameter. Your application should keep this value as it is authentication token of your user for this application

Step 3: As soon as the user submits his credentials through the authentication form, the billing API will try to authenticate him against the identity management service of the telecom operator. If the user is authenticated, the billing API authorizes the application and redirects the request to a callback url that has been initially provided by the developer to the telecom operator. Parameters informing you about the status of the procedure and that of the authorization are added to the callback URL, as shown in the following

http://your.callback.url?status=success&authorizationStatus=approved

Note that in case of failure, the value of "status" is set to "failure" and two other parameters are added to the URL: "errorCode" and "errorDetail"

Step 4: Now that the user has authorized the application, you can trigger the payment process every time he buys something from your application, by invoking the "billing.chargeCustomer" API. You will need to pass the authentication token received at step2 to the billing API identifies your user.

Note that if your billing model is "transaction", steps identical to steps 2 and 3 will be executed, in order to allow the user to charge the transaction this time.


  • No labels