Direct Carrier Billing API: One-Time Payments

Q: Which inputs does each call to the DCB OneTime API need?

POST /adjustBalance: requires amount, bucket, usageType; headers transactionId, countryCode. Every call also needs Authorization: Bearer <access_token>. The API reference on this page shows each field's type and an example request.

Q: What does the DCB OneTime API return?

POST /adjustBalance returns HTTP 201 with id, href, status, amount, bucket, usageType. Responses are JSON.

Q: How do I authenticate with the DCB OneTime API?

Call POST https://api.ooredoo.com/tmf-api/oauth/v4/generateToken with client_id, client_secret in the headers. Send msisdn, charge, grant_type in the body. Use the client ID and secret of your app.. The response contains access_token, token_type, expires_in, consented_on, created_At, expired_At.. Send Authorization: Bearer <access_token> on each call until the token expires, then request a new one..

Q: Which errors can the DCB OneTime API return?

400: Bad Request. 401: Unauthorized. 403: Forbidden. 405: Method Not allowed. 409: Conflict. 422: Business Rule Exception. 500: Internal Server Error. On 401, request a new access token and retry.

TM Forum Open API

DCB OneTime API

Let customers pay with their mobile account

DCB is an online mobile payment method that allows users to make purchases directly charged to their mobile phone bill or prepaid sim card.

Digital content
In-app purchases
Online services

What you can do with this API

Charge a one-off purchase to the mobile account POST /adjustBalance

Inputs: channel, OTP, description, amount

Ready to test? Jump to the sample call and the API reference, where you can try every endpoint. Start testing

Read the full API overview

Direct Carrier Billing Details

What is Direct Carrier Billing?

Direct Carrier Billing is a type of online payment that allows consumers to charge the cost of a purchase to their phone bill. To put simply, it is a mechanism which enables consumers to make transactions while adding its charge to their mobile phone bills. The best part about this type of payment is that it is applicable not only to smart phone users but also all feature phone users.
The emergence of Direct Carrier Billing can be witnessed back at times when consumers opted for ringtone and wallpaper services on their feature phones. Unlike those days, DCB is now completely extensive in its usability and compatible to buy content on any digital platform. It allows users to purchase products and services across multiple channels, ranging from desktop computers, smartphones, smart TVs, to gaming consoles. Adding on to that, they can also buy a music streaming subscription on their device.

Consumers can often misinterpret DCB with different kinds of mobile payments such as Near-field communication (NFC) solutions and mobile wallets. One of the key differences between these traditional payment methods and DCB is DCB’s independence on banking infrastructure to complete a transaction. Making a payment through it is as simple as that of entering a phone number.
DCB is for sure a keeper for businesses that aim to attain traction and make consumers’ billing process a simple task. Along with the technical superiority that it has, it is lucrative for businesses as well as for consumers.

Easy to use

DCB is a payment mode designed to simplify the payment process. It does not require one to add lengthy details and sensitive information related to the payment. Ease of using is one of the most important traits that it offers to its consumers.

Easy Accessibility

Since DCB is a payment method which is directly linked to consumers’ mobile phone bill, it completely eliminates the need to sign in each time one makes a purchase. Besides that, it supports smartphones, tablets, and also feature phones making it widely usable and accessible.

Entrusted Payment Method

Consumers find it comparatively easy to trust this mode of payment as all their payments are processed through their telecom operators. Based on the length of the service used by consumers provided by their telecom operators, the consumer can trust them with their private details. Owing to the technological power of DCB, it has deployed a great deal of security system which ensures high-level payment security.

The use of mobile phones in the simplest of the tasks is prevalent, it can be attested that this number is to rise with the evolving telecom industry. More so, the total number of registered mobile money accounts in 2018 reached million, which showed a growth of 20% over the previous year.
These figures certainly attest the anticipated success of mobile money and hence a stronger future of a simple and easily accessible payment mode- Direct Carrier Billing. Considering the vastness of Direct Carrier Billing, it is certainly the key to escalated consumer satisfaction and experience.
Simplify payment procedure with Direct Carrier Billing today!

Benefits and Features

Deliver a truly digital order experience for you and your end customer
Reduced order management costs and manual order entry errors
Reduced time to order
Place and manage orders faster
Place and manage orders programmatically, saving time and money
Validate customers' address details and match to a single unique address key or create a new temporary key to facilitate delivery of service to the correct customer location
Check availability of appointment slots based on particular dates and book an engineer appointment.

Questions about the DCB OneTime API

What can I do with the DCB OneTime API?

DCB is an online mobile payment method that allows users to make purchases directly charged to their mobile phone bill or prepaid sim card.

Charge a one-off purchase to the mobile account (POST /adjustBalance)

Which inputs does each call to the DCB OneTime API need?

POST /adjustBalance: requires amount, bucket, usageType; headers transactionId, countryCode

Every call also needs Authorization: Bearer <access_token>. The API reference on this page shows each field's type and an example request.

What does the DCB OneTime API return?

POST /adjustBalance returns HTTP 201 with id, href, status, amount, bucket, usageType

Responses are JSON.

How do I authenticate with the DCB OneTime API?

Call POST https://api.ooredoo.com/tmf-api/oauth/v4/generateToken with client_id, client_secret in the headers. Send msisdn, charge, grant_type in the body. Use the client ID and secret of your app.
The response contains access_token, token_type, expires_in, consented_on, created_At, expired_At.
Send Authorization: Bearer <access_token> on each call until the token expires, then request a new one.

Which errors can the DCB OneTime API return?

400: Bad Request
401: Unauthorized
403: Forbidden
405: Method Not allowed
409: Conflict
422: Business Rule Exception
500: Internal Server Error

On 401, request a new access token and retry.

Where is the DCB OneTime API available?

DCB OneTime is available in Iraq, Algeria, Palestine, Qatar, Kuwait, Maldives, Oman and Tunisia.

Which standard does the DCB OneTime API follow?

It follows the TM Forum Open API standard used across the telecom industry. See our TM Forum certification page.

Sample call

From the published OpenAPI specification. Replace the placeholders with your app's credentials and real values.

1. Get an access token

curl -X POST https://api.ooredoo.com/tmf-api/oauth/v4/generateToken \
  -H "client_id: $CLIENT_ID" \
  -H "client_secret: $CLIENT_SECRET" \
  -H "scope: <scope>" \
  -H "transactionId: <transactionId>" \
  -d "msisdn=+974XXXXXXXX" \
  -d "charge=1" \
  -d "grant_type=client_credentials"

2. Call the API

curl -X POST https://api.ooredoo.com/tmf-api/prepayBalanceManagement/v4/adjustBalance \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "transactionId: <transactionId>" \
  -H "countryCode: <countryCode>" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": {
      "amount": 1,
      "units": "MVR"
    },
    "bucket": {
      "id": "<id>",
      "name": "New Subscription"
    },
    "usageType": "monetary"
  }'

API reference

Try any endpoint in the sandbox