1. REST Services Manager API for Billing and Revenue Management
  2. Tasks
  3. Prepay Balance Management
  4. Top-up Balances

Get Top-up Balances

get

/topupBalance

Gets top-up balances that match the query criteria.

Request

Query Parameters
  • Retrieves the top-up balance associated with the balance group POID.
    Example:
    0.0.0.1+-balance_group+71659
  • The list of comma-separated fields to return in the response.
    Example:
    isAutoTopup,paymentMethod
  • Retrieves the specified top-up POID.
    Example:
    0.0.0.1+-topup+285083
  • Whether the request is for an automatic top up.
    Example:
    true
  • The maximum number of results to return. For example, use limit=10 to return the first 10 results only.
    Example:
    10
  • Retrieves the top-up balance associated with the login ID or device ID.
    Example:
    964-20210827-041409-0-9169--146802944-mum-54
  • The number of periods to execute the recharge operation. If not included, the topup occurs every period.
    Example:
    2
  • The number of results to offset the response by. For example, use offset=10 to return results 10 and higher.
    Example:
    10
  • Retrieves the top-up balance associated with the account POID or account number.
    Example:
    0.0.0.1 /account 10966 0
  • Retrieves the top-up balance associated with the specified service ID.
    Example:
    0.0.0.1+-service-telco-gsm+67479
  • The periodicity for the recharge operation, such as monthly, weekly, or daily.
    Example:
    daily
  • The type of underlying balance type, such as data or voice.
    Example:
    data

There's no request body for this operation.

Back to Top

Response

Supported Media Types

200 Response

The top-up balances were retrieved successfully.
Headers
Body ()
Root Schema : schema
Type: array
Show Source
Nested Schema : Topup Balance
Type: object
Title: Topup Balance
A top-up.
Show Source
Nested Schema : Quantity
Type: object
The amount in a given unit.
Show Source
Nested Schema : Bucket Ref
Type: object
Title: Bucket Ref
A reference to a bucket.
Show Source
Nested Schema : ChannelRef
Type: object
A reference to a channel.
Show Source
Nested Schema : impactedBucket
Type: array
A reference to the bucket impacted by the request.
Show Source
Nested Schema : Logical Resource Ref
Type: object
Title: Logical Resource Ref
A reference to a logical resource.
Show Source
Nested Schema : Party Account Ref
Type: object
Title: Party Account Ref
A reference to a party account.
Show Source
Nested Schema : PaymentRef
Type: object
A payment received at order time.
Show Source
Nested Schema : PaymentMethodRef
Type: object
The PaymentMethod reference. A payment method defines a specific means of payment, such as direct debit.
Match All
The PaymentMethod reference. A payment method defines a specific means of payment, such as direct debit.
Show Source
Nested Schema : Product Ref
Type: object
Title: Product Ref
A reference to a product.
Show Source
Nested Schema : relatedParty
Type: array
Parties related to the top-up.
Show Source
Nested Schema : Related Topup Balance
Type: object
Title: Related Topup Balance
A relationship between balance top-ups that defines whether a balance is the parent or child of another.
Show Source
Nested Schema : Related Party
Type: object
Title: Related Party
A party related to another object.
Show Source
Nested Schema : ImpactedBucket
Type: object
A bucket impacted by a balance top-up, adjustment, transfer, or reservation.
Show Source
Nested Schema : item
Type: array
Minimum Number of Items: 1
The impacted bucket items.
Show Source
Nested Schema : ImpactedBucketItem
Type: object
An impact item that affects an ImpactedBucket object.
Show Source
Nested Schema : EntityRef
Match All
The entity reference schema to be use for all entityRef class.
Show Source
  • Extensible
    The Base Extensible schema for use in TMForum Open-APIs - When used for in a schema it means that the Entity described by the schema MUST be extended with the @type
  • Addressable
    The base schema for adressable entities.
  • EntityRef-allOf[2]
    The entity reference schema to be use for all entityRef class.
Nested Schema : Extensible
Type: object
The Base Extensible schema for use in TMForum Open-APIs - When used for in a schema it means that the Entity described by the schema MUST be extended with the @type
Show Source
Nested Schema : Addressable
Type: object
The base schema for adressable entities.
Show Source
Nested Schema : EntityRef-allOf[2]
Type: object
The entity reference schema to be use for all entityRef class.
Show Source

400 Response

The request isn't valid.
Body ()
Root Schema : Error
The operation used when an API throws an Error, typically with a HTTP error response-code (3xx, 4xx, 5xx).
Match All
The operation used when an API throws an Error, typically with a HTTP error response-code (3xx, 4xx, 5xx).
The operation used when an API throws an Error, typically with a HTTP error response-code (3xx, 4xx, 5xx).
Show Source
  • Extensible
    The Base Extensible schema for use in TMForum Open-APIs - When used for in a schema it means that the Entity described by the schema MUST be extended with the @type
  • Error-allOf[1]
Nested Schema : Extensible
Type: object
The Base Extensible schema for use in TMForum Open-APIs - When used for in a schema it means that the Entity described by the schema MUST be extended with the @type
Show Source
Nested Schema : Error-allOf[1]
Type: object
Show Source

401 Response

The client doesn't have the correct privileges.
Body ()
Root Schema : Error
The operation used when an API throws an Error, typically with a HTTP error response-code (3xx, 4xx, 5xx).
Match All
The operation used when an API throws an Error, typically with a HTTP error response-code (3xx, 4xx, 5xx).
The operation used when an API throws an Error, typically with a HTTP error response-code (3xx, 4xx, 5xx).
Show Source
  • Extensible
    The Base Extensible schema for use in TMForum Open-APIs - When used for in a schema it means that the Entity described by the schema MUST be extended with the @type
  • Error-allOf[1]
Nested Schema : Extensible
Type: object
The Base Extensible schema for use in TMForum Open-APIs - When used for in a schema it means that the Entity described by the schema MUST be extended with the @type
Show Source
Nested Schema : Error-allOf[1]
Type: object
Show Source

403 Response

The request wasn't authorized.
Body ()
Root Schema : Error
The operation used when an API throws an Error, typically with a HTTP error response-code (3xx, 4xx, 5xx).
Match All
The operation used when an API throws an Error, typically with a HTTP error response-code (3xx, 4xx, 5xx).
The operation used when an API throws an Error, typically with a HTTP error response-code (3xx, 4xx, 5xx).
Show Source
  • Extensible
    The Base Extensible schema for use in TMForum Open-APIs - When used for in a schema it means that the Entity described by the schema MUST be extended with the @type
  • Error-allOf[1]
Nested Schema : Extensible
Type: object
The Base Extensible schema for use in TMForum Open-APIs - When used for in a schema it means that the Entity described by the schema MUST be extended with the @type
Show Source
Nested Schema : Error-allOf[1]
Type: object
Show Source

404 Response

The requested resource couldn't be found.
Body ()
Root Schema : Error
The operation used when an API throws an Error, typically with a HTTP error response-code (3xx, 4xx, 5xx).
Match All
The operation used when an API throws an Error, typically with a HTTP error response-code (3xx, 4xx, 5xx).
The operation used when an API throws an Error, typically with a HTTP error response-code (3xx, 4xx, 5xx).
Show Source
  • Extensible
    The Base Extensible schema for use in TMForum Open-APIs - When used for in a schema it means that the Entity described by the schema MUST be extended with the @type
  • Error-allOf[1]
Nested Schema : Extensible
Type: object
The Base Extensible schema for use in TMForum Open-APIs - When used for in a schema it means that the Entity described by the schema MUST be extended with the @type
Show Source
Nested Schema : Error-allOf[1]
Type: object
Show Source

405 Response

This method is not allowed.
Body ()
Root Schema : Error
The operation used when an API throws an Error, typically with a HTTP error response-code (3xx, 4xx, 5xx).
Match All
The operation used when an API throws an Error, typically with a HTTP error response-code (3xx, 4xx, 5xx).
The operation used when an API throws an Error, typically with a HTTP error response-code (3xx, 4xx, 5xx).
Show Source
  • Extensible
    The Base Extensible schema for use in TMForum Open-APIs - When used for in a schema it means that the Entity described by the schema MUST be extended with the @type
  • Error-allOf[1]
Nested Schema : Extensible
Type: object
The Base Extensible schema for use in TMForum Open-APIs - When used for in a schema it means that the Entity described by the schema MUST be extended with the @type
Show Source
Nested Schema : Error-allOf[1]
Type: object
Show Source

409 Response

The request could not be processed due to the conflict with the existing state of the resource.
Body ()
Root Schema : Error
The operation used when an API throws an Error, typically with a HTTP error response-code (3xx, 4xx, 5xx).
Match All
The operation used when an API throws an Error, typically with a HTTP error response-code (3xx, 4xx, 5xx).
The operation used when an API throws an Error, typically with a HTTP error response-code (3xx, 4xx, 5xx).
Show Source
  • Extensible
    The Base Extensible schema for use in TMForum Open-APIs - When used for in a schema it means that the Entity described by the schema MUST be extended with the @type
  • Error-allOf[1]
Nested Schema : Extensible
Type: object
The Base Extensible schema for use in TMForum Open-APIs - When used for in a schema it means that the Entity described by the schema MUST be extended with the @type
Show Source
Nested Schema : Error-allOf[1]
Type: object
Show Source

500 Response

The system encountered an internal error.
Body ()
Root Schema : Error
The operation used when an API throws an Error, typically with a HTTP error response-code (3xx, 4xx, 5xx).
Match All
The operation used when an API throws an Error, typically with a HTTP error response-code (3xx, 4xx, 5xx).
The operation used when an API throws an Error, typically with a HTTP error response-code (3xx, 4xx, 5xx).
Show Source
  • Extensible
    The Base Extensible schema for use in TMForum Open-APIs - When used for in a schema it means that the Entity described by the schema MUST be extended with the @type
  • Error-allOf[1]
Nested Schema : Extensible
Type: object
The Base Extensible schema for use in TMForum Open-APIs - When used for in a schema it means that the Entity described by the schema MUST be extended with the @type
Show Source
Nested Schema : Error-allOf[1]
Type: object
Show Source
Back to Top

Examples

The following example shows how to get top-up balances by submitting a GET request on the REST resource using cURL. For more information about cURL, see Use cURL.

The request uses query parameters to show two top-up balances for a specified account.

curl -X GET 'http://host:port/brm/prepayBalanceManagement/version/topupBalance?partyAccount.id=0.0.0.1+-account+6340627&limit=2'

Example of the Response Body

The following example shows the contents of the response body in JSON format.

[
    {
        "@baseType": "TopupBalance",
        "@schemaLocation": null,
        "@type": "TopupBalance",
        "amount": {
            "amount": 2.0,
            "units": "USD",
            "@baseType": null,
            "@schemaLocation": null,
            "@type": null
        },
        "bucket": {
            "id": "0.0.0.1+-balance_group+6344211+840+0",
            "href": "http://host:port/brm/prepayBalanceManagement/v4/bucket/0.0.0.1+-balance_group+6344211+840+0",
            "name": null,
            "@baseType": "BucketRef",
            "@schemaLocation": null,
            "@type": "BucketRef",
            "@referredType": null
        },
        "channel": null,
        "confirmationDate": "2025-09-20T11:45:02+05:30",
        "description": null,
        "href": "http://host:port/brm/prepayBalanceManagement/v4/topupBalance/0.0.0.1+-topup+6448982",
        "id": "0.0.0.1+-topup+6448982",
        "impactedBucket": [
            {
                "@baseType": "ImpactedBucket",
                "@schemaLocation": null,
                "@type": "ImpactedBucket",
                "amountAfter": {
                    "amount": -2.0,
                    "units": "USD",
                    "@baseType": null,
                    "@schemaLocation": null,
                    "@type": null
                },
                "amountBefore": {
                    "amount": 0.0,
                    "units": "USD",
                    "@baseType": null,
                    "@schemaLocation": null,
                    "@type": null
                },
                "bucket": {
                    "id": "0.0.0.1+-balance_group+6344211+840+0",
                    "href": "http://host:port/brm/prepayBalanceManagement/v4/bucket/0.0.0.1+-balance_group+6344211+840+0",
                    "name": null,
                    "@baseType": "BucketRef",
                    "@schemaLocation": null,
                    "@type": "BucketRef",
                    "@referredType": null
                },
                "confirmationDate": null,
                "description": null,
                "item": [
                    {
                        "@baseType": "ImpactedBucketItem",
                        "@schemaLocation": null,
                        "@type": "ImpactedBucketItem",
                        "amount": {
                            "amount": 2.0,
                            "units": "USD",
                            "@baseType": null,
                            "@schemaLocation": null,
                            "@type": null
                        },
                        "description": null,
                        "itemType": null,
                        "name": null,
                        "reason": null
                    }
                ],
                "name": null,
                "requestedDate": null
            }
        ],
        "isAutoTopup": false,
        "logicalResource": {
            "@baseType": null,
            "@referredType": null,
            "@schemaLocation": null,
            "@type": null,
            "href": null,
            "id": null,
            "name": null,
            "value": ""
        },
        "numberOfPeriods": null,
        "partyAccount": {
            "id": "0.0.0.1+-account+6340627",
            "href": null,
            "description": null,
            "name": "Jane Mason",
            "status": "active",
            "@baseType": null,
            "@schemaLocation": null,
            "@type": "PartyAccountRef",
            "@referredType": null
        },
        "payment": {
            "id": "0.0.0.1+-item-payment+6450518",
            "href": "http://host:port/brm/payment/v4/payment/0.0.0.1+-item-payment+6450518",
            "name": "Billing Event Log",
            "amount": {
                "unit": "USD",
                "value": 2.0
            },
            "paymentDate": "2025-09-20T11:45:01+05:30",
            "@baseType": "Payment",
            "@schemaLocation": null,
            "@type": "Payment",
            "@referredType": null
        },
        "paymentMethod": {
            "id": "0.0.0.1+-payinfo-cc+6342675",
            "href": "http:/host:port/brm/paymentMethods/v1/paymentMethod/0.0.0.1+-payinfo-cc+6342675",
            "description": null,
            "isPreferred": true,
            "name": "PIN Payinfo Object",
            "status": null,
            "statusDate": null,
            "account": [
                {
                    "id": "0.0.0.1+-account+6340627",
                    "href": null,
                    "description": null,
                    "name": "Jane Mason",
                    "@baseType": null,
                    "@schemaLocation": null,
                    "@type": null,
                    "@referredType": null
                }
            ],
            "relatedParty": null,
            "validFor": null,
            "@baseType": null,
            "@schemaLocation": null,
            "@type": "tokenizedCard",
            "@referredType": null
        },
        "product": {
            "id": "0.0.0.1+-service-telco-gsm-telephony+6343955",
            "href": null,
            "name": "ServiceTelcoGsmTelephony",
            "@baseType": null,
            "@schemaLocation": null,
            "@type": "ProductRef",
            "@referredType": null
        },
        "reason": null,
        "recurringPeriod": null,
        "relatedParty": null,
        "relatedTopupBalance": null,
        "requestedDate": "2025-09-20T11:45:02+05:30",
        "requestor": null,
        "status": "CONFIRMED",
        "usageType": "monetary",
        "voucher": ""
    },
    {
        "@baseType": "TopupBalance",
        "@schemaLocation": null,
        "@type": "TopupBalance",
        "amount": {
            "amount": 20.0,
            "units": "USD",
            "@baseType": null,
            "@schemaLocation": null,
            "@type": null
        },
        "bucket": {
            "id": "0.0.0.1+-balance_group+4097444+840+0",
            "href": "http://host:port/brm/prepayBalanceManagement/v4/bucket/0.0.0.1+-balance_group+4097444+840+0",
            "name": null,
            "@baseType": "BucketRef",
            "@schemaLocation": null,
            "@type": "BucketRef",
            "@referredType": null
        },
        "channel": null,
        "confirmationDate": "2025-09-20T10:41:44+05:30",
        "description": null,
        "href": "http://host:port/brm/prepayBalanceManagement/v4/topupBalance/0.0.0.1+-topup+6442543",
        "id": "0.0.0.1+-topup+6442543",
        "impactedBucket": [
            {
                "@baseType": "ImpactedBucket",
                "@schemaLocation": null,
                "@type": "ImpactedBucket",
                "amountAfter": {
                    "amount": 643.0,
                    "units": "USD",
                    "@baseType": null,
                    "@schemaLocation": null,
                    "@type": null
                },
                "amountBefore": {
                    "amount": 663.0,
                    "units": "USD",
                    "@baseType": null,
                    "@schemaLocation": null,
                    "@type": null
                },
                "bucket": {
                    "id": "0.0.0.1+-balance_group+4097444+840+0",
                    "href": "http://host:port/brm/prepayBalanceManagement/v4/bucket/0.0.0.1+-balance_group+4097444+840+0",
                    "name": null,
                    "@baseType": "BucketRef",
                    "@schemaLocation": null,
                    "@type": "BucketRef",
                    "@referredType": null
                },
                "confirmationDate": null,
                "description": null,
                "item": [
                    {
                        "@baseType": "ImpactedBucketItem",
                        "@schemaLocation": null,
                        "@type": "ImpactedBucketItem",
                        "amount": {
                            "amount": 20.0,
                            "units": "USD",
                            "@baseType": null,
                            "@schemaLocation": null,
                            "@type": null
                        },
                        "description": null,
                        "itemType": null,
                        "name": null,
                        "reason": null
                    }
                ],
                "name": null,
                "requestedDate": null
            }
        ],
        "isAutoTopup": false,
        "logicalResource": {
            "@baseType": null,
            "@referredType": null,
            "@schemaLocation": null,
            "@type": null,
            "href": null,
            "id": null,
            "name": null,
            "value": "056-20250812-035011-1-20412--146856192-cagbu-phx-175"
        },
        "numberOfPeriods": null,
        "partyAccount": {
            "id": "0.0.0.1+-account+6340627",
            "href": null,
            "description": null,
            "name": "Jane Mason",
            "status": "active",
            "@baseType": null,
            "@schemaLocation": null,
            "@type": "PartyAccountRef",
            "@referredType": null
        },
        "payment": {
            "id": "0.0.0.1+-item-payment+6439471",
            "href": "http://host:port/brm/payment/v4/payment/0.0.0.1+-item-payment+6439471",
            "name": "Billing Event Log",
            "amount": {
                "unit": "USD",
                "value": 20.0
            },
            "paymentDate": "2025-09-20T10:41:43+05:30",
            "@baseType": "Payment",
            "@schemaLocation": null,
            "@type": "Payment",
            "@referredType": null
        },
        "paymentMethod": {
            "id": "0.0.0.1+-payinfo-cc+6306114",
            "href": "http://host:port/brm/paymentMethods/v1/paymentMethod/0.0.0.1+-payinfo-cc+6306114",
            "description": null,
            "isPreferred": false,
            "name": "PIN Payinfo Object",
            "status": null,
            "statusDate": null,
            "account": [
                {
                    "id": "0.0.0.1+-account+6340627",
                    "href": null,
                    "description": null,
                    "name": "Jane Mason",
                    "@baseType": null,
                    "@schemaLocation": null,
                    "@type": null,
                    "@referredType": null
                }
            ],
            "relatedParty": null,
            "validFor": null,
            "@baseType": null,
            "@schemaLocation": null,
            "@type": "tokenizedCard",
            "@referredType": null
        },
        "product": {
            "id": "0.0.0.1+-service-telco-gsm-sms+4099940",
            "href": null,
            "name": "ServiceTelcoGsmSms",
            "@baseType": null,
            "@schemaLocation": null,
            "@type": "ProductRef",
            "@referredType": null
        },
        "reason": null,
        "recurringPeriod": null,
        "relatedParty": null,
        "relatedTopupBalance": null,
        "requestedDate": "2025-09-20T10:41:44+05:30",
        "requestor": null,
        "status": "CONFIRMED",
        "usageType": "monetary",
        "voucher": ""
    }
]
Back to Top