TM Forum Open API

Prepay Balance Management API

Manage prepaid balances in real time

The Prepay Balance Management API is designed to handle prepaid subscriber accounts, ensuring seamless management of balances before service consumption.

  • Debits
  • Credits
  • Balance checks

What you can do with this API

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

Prepay Balance Management API

The Prepay Balance Management API is designed to handle prepaid subscriber accounts, ensuring seamless management of balances before service consumption. This API provides model definitions and various operations to support prepaid billing workflows, recharge mechanisms, and balance transfers.

Key Features & Capabilities

1. Prepaid Subscriber Account Management

  • Ensures subscribers maintain a sufficient balance before using services.
  • Manages account details, balance updates, and usage records efficiently.

2. Recharge & Top-Up Functionality

  • Supports multiple recharge channels, including credit card payments, vouchers, mobile wallets, and direct bank transfers.
  • Enables operators to configure automatic balance replenishment to prevent service interruptions.

3. Balance Transfer & Credit Sharing

  • Allows subscribers to transfer balance between different accounts or subscriptions.
  • Supports peer-to-peer balance sharing, enabling users to assist friends or family with prepaid credits.

4. Usage Tracking & Spend Control

  • Provides real-time balance inquiry to check available prepaid credits.
  • Supports spending limits and alerts, ensuring subscribers have control over their usage.

5. Integration with Billing & CRM Systems

  • Seamlessly connects with billing platforms, allowing prepaid balances to synchronize with service charges.
  • Integrates with CRM systems to provide personalized offers based on customer usage patterns.

6. Fraud Prevention & Security

  • Implements fraud detection mechanisms to prevent unauthorized balance transfers or recharge fraud.
  • Ensures secure authentication for balance transactions.

Use Cases of Prepay Balance Management API

  1. Mobile & Telecom Services – Allows prepaid mobile users to recharge and manage their accounts.
  2. Subscription-Based Platforms – Ensures prepaid customers can renew services seamlessly.
  3. Digital Wallet & Payment Systems – Enables users to maintain and transfer stored credit balances.
  4. Gift & Credit Sharing – Supports peer-to-peer balance sharing for prepaid services.
  5. Automated Balance Alerts & Replenishment – Notifies users of low balance and facilitates auto-recharges.

The Prepay Balance Management API plays a vital role in enabling flexible prepaid billing solutions, ensuring subscribers can efficiently manage their balances while preventing service disruptions.

Questions about the Prepay Balance Management API

What can I do with the Prepay Balance Management API?

The Prepay Balance Management API is designed to handle prepaid subscriber accounts, ensuring seamless management of balances before service consumption.

  • Debit or credit a prepaid balance (POST /adjustBalance)
  • Look up a debit by its ID (GET /adjustBalance/{debitId})
  • Look up a credit by its ID (GET /adjustBalance/{creditId})
Which inputs does each call to the Prepay Balance Management API need?
  • POST /adjustBalance: requires amount, bucket, logicalResource, usageType; headers transactionId, countryCode
  • GET /adjustBalance/{debitId}: requires debitId, adjustType, msisdn; headers transactionId, countryCode
  • GET /adjustBalance/{creditId}: requires creditId, adjustType, msisdn; 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 Prepay Balance Management API return?
  • POST /adjustBalance returns HTTP 201 with id, href, status, amount, bucket, usageType
  • GET /adjustBalance/{debitId} returns HTTP 200 with id, href, status, amount, bucket, usageType
  • GET /adjustBalance/{creditId} returns HTTP 200 with id, href, status, amount, bucket, usageType

Responses are JSON.

How do I authenticate with the Prepay Balance Management API?
  1. Call POST https://api.ooredoo.com/tmf-api/oauth/v4/token with client_id, client_secret in the headers. Send grant_type in the body. Use the client ID and secret of your app.
  2. The response contains access_token, token_type, expires_in, consented_on, created_At, expired_At.
  3. Send Authorization: Bearer <access_token> on each call until the token expires, then request a new one.
Which errors can the Prepay Balance Management API return?
  • 400: Bad Request
  • 401: Unauthorized
  • 403: Forbidden
  • 404: Not Found
  • 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 Prepay Balance Management API available?

Prepay Balance Management is available in Algeria, Tunisia, Qatar, Maldives, Palestine, Oman, Iraq and Kuwait.

Which standard does the Prepay Balance Management API follow?

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

Related APIs

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/token \
  -H "client_id: $CLIENT_ID" \
  -H "client_secret: $CLIENT_SECRET" \
  -H "scope: <scope>" \
  -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": "<units>"
    },
    "bucket": {
      "id": "<id>"
    },
    "logicalResource": [
      {
        "id": "<id>",
        "@type": "SUBSCRIBER_NUMBER"
      }
    ],
    "usageType": "monetary"
  }'

API reference

Try any endpoint in the sandbox