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

Create a Top-up Balance

post

/topupBalance

Creates a top-up balance.

Request

There are no request parameters for this operation.

Supported Media Types
Request Body - application/json;charset=utf-8 ()
Root Schema : Topup Balance Create
Type: object
Title: Topup Balance Create
A top-up, used in TopupBalance create requests.
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 buckets 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
Back to Top

Response

Supported Media Types

201 Response

The top-up balance was created successfully.
Body ()
Root 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

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

Example 1: Create a One-time Noncurrency Top-up Balance

The following examples shows how to create a one-time noncurrency top-up balance by submitting a POST request on the REST resource using cURL. For more information about cURL, see Use cURL.

The -d option specifies the file to attach as the request body. 

curl -X POST 'http://host:port/brm/prepayBalanceManagement/version/topupBalance' -d @topupBalanceCreate.json

Example of Request Body for a One-time Noncurrency Top-up Balance

The following is an example of the contents of the topupBalanceCreate.json file sent as the request body to create a one-time noncurrency top-up balance. 

{   
   "amount": {
      "amount": "11",
      "units": "Free Minutes"
   },
   "bucket": {
      "id" : "0.0.0.1+-balance_group+6336883+100002+8"
   }
}

Example of Response Body for a One-time Noncurrency Top-up Balance

The following is an example of the response body in JSON format.

{
   "@baseType": "TopupBalance",
   "@schemaLocation": null,
   "@type": "TopupBalance",
   "amount": {
      "amount": 11.0,
      "units": "Free Minutes",
      "@baseType": null,
      "@schemaLocation": null,
      "@type": null
   },
   "bucket": {
      "id": "0.0.0.1+-balance_group+6336883+100002+8",
      "href": "http://host:port/brm/prepayBalanceManagement/v4/bucket/0.0.0.1+-balance_group+6336883+100002+8",
      "name": null,
      "@baseType": "BucketRef",
      "@schemaLocation": null,
      "@type": "BucketRef",
      "@referredType": null
   },
   "channel": null,
   "confirmationDate": "2025-09-30T02:45:11+05:30",
   "description": null,
   "href": "http://host:port/brm/prepayBalanceManagement/v4/topupBalance/0.0.0.1+-topup+6535618",
   "id": "0.0.0.1+-topup+6535618",
   "impactedBucket": [
      {
         "@baseType": "ImpactedBucket",
         "@schemaLocation": null,
         "@type": "ImpactedBucket",
         "amountAfter": {
            "amount": -23.0,
            "units": "Free Minutes",
            "@baseType": null,
            "@schemaLocation": null,
            "@type": null
         },
         "amountBefore": {
            "amount": -12.0,
            "units": "Free Minutes",
            "@baseType": null,
            "@schemaLocation": null,
            "@type": null
         },
         "bucket": {
            "id": "0.0.0.1+-balance_group+6336883+100002+8",
            "href": "http://host:port/brm/prepayBalanceManagement/v4/bucket/0.0.0.1+-balance_group+6336883+100002+8",
            "name": null,
            "@baseType": "BucketRef",
            "@schemaLocation": null,
            "@type": "BucketRef",
            "@referredType": null
         },
         "confirmationDate": null,
         "description": null,
         "item": [
            {
               "@baseType": "ImpactedBucketItem",
               "@schemaLocation": null,
               "@type": "ImpactedBucketItem",
               "amount": {
                  "amount": 11.0,
                  "units": "Free Minutes",
                  "@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+6338675",
      "href": null,
      "description": null,
      "name": "Tom Smith",
      "status": "active",
      "@baseType": null,
      "@schemaLocation": null,
      "@type": "PartyAccountRef",
      "@referredType": null
   },
   "payment": null,
   "paymentMethod": {
      "id": "0.0.0.1+-payinfo-cc+6337651",
      "href": "http://host:port/brm/paymentMethods/v1/paymentMethod/0.0.0.1+-payinfo-cc+6337651",
      "description": null,
      "isPreferred": true,
      "name": "PIN Payinfo Object",
      "status": null,
      "statusDate": null,
      "account": [
         {
            "id": "0.0.0.1+-account+6338675",
            "href": null,
            "description": null,
            "name": "Tom Smith",
            "@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+6337523",
      "href": null,
      "name": "ServiceTelcoGsmSms",
      "@baseType": null,
      "@schemaLocation": null,
      "@type": "ProductRef",
      "@referredType": null
   },
   "reason": null,
   "recurringPeriod": null,
   "relatedParty": null,
   "relatedTopupBalance": null,
   "requestedDate": "2025-09-30T02:45:11+05:30",
   "requestor": null,
   "status": "CONFIRMED",
   "usageType": "other",
   "voucher": ""
}

Example 2: Create a Recurring Currency Top-up Balance

The following examples shows how to create a currency top-up balance by submitting a POST request on the REST resource using cURL. For more information about cURL, see Use cURL.

The -d option specifies the file to attach as the request body. 

curl -X POST 'http://host:port/brm/prepayBalanceManagement/version/topupBalance' -d @topupBalanceCreate.json

Example of Request Body for a Recurring Currency Top-up Balance

The following is an example of the contents of the topupBalanceCreate.json file sent as the request body to create a recurring currency top-up balance. 

{
   "amount":{
      "amount":"2",
      "units":"USD"
   },
   "recurringPeriod" : "daily",
   "isAutoTopup" : "true",
   "numberOfPeriods" : "2",
   "partyAccount":{
      "id" : "0.0.0.1+-account+6340627"
   }
}

Example of Response Body for a Recurring Currency Top-up Balance

The following is an example 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+6336883+840+0",
      "href": "http://host:port/brm/prepayBalanceManagement/v4/bucket/0.0.0.1+-balance_group+6336883+840+0",
      "name": null,
      "@baseType": "BucketRef",
      "@schemaLocation": null,
      "@type": "BucketRef",
      "@referredType": null
   },
   "channel": null,
   "confirmationDate": "2025-09-30T03:06:42+05:30",
   "description": null,
   "href": "http://host:port/brm/prepayBalanceManagement/v4/topupBalance/0.0.0.1+-topup+6528179",
   "id": "0.0.0.1+-topup+6528179",
   "impactedBucket": [
      {
         "@baseType": "ImpactedBucket",
         "@schemaLocation": null,
         "@type": "ImpactedBucket",
         "amountAfter": {
            "amount": 299.0,
            "units": "USD",
            "@baseType": null,
            "@schemaLocation": null,
            "@type": null
         },
         "amountBefore": {
            "amount": 301.0,
            "units": "USD",
            "@baseType": null,
            "@schemaLocation": null,
            "@type": null
         },
         "bucket": {
            "id": "0.0.0.1+-balance_group+6336883+840+0",
            "href": "http://host:port/brm/prepayBalanceManagement/v4/bucket/0.0.0.1+-balance_group+6336883+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": true,
   "logicalResource": {
      "@baseType": null,
      "@referredType": null,
      "@schemaLocation": null,
      "@type": null,
      "href": null,
      "id": null,
      "name": null,
      "value": ""
   },
   "numberOfPeriods": 2,
   "partyAccount": {
      "id": "0.0.0.1+-account+6340627",
      "href": null,
      "description": null,
      "name": "Alice Rose",
      "status": "active",
      "@baseType": null,
      "@schemaLocation": null,
      "@type": "PartyAccountRef",
      "@referredType": null
   },
   "payment": {
      "id": "0.0.0.1+-item-payment+6526899",
      "href": "http://host:port/brm/payment/v4/payment/0.0.0.1+-item-payment+6526899",
      "name": "Billing Event Log",
      "amount": {
         "unit": "USD",
         "value": 2.0
      },
      "paymentDate": "2025-09-30T03:06:43+05:30",
      "@baseType": "Payment",
      "@schemaLocation": null,
      "@type": "Payment",
      "@referredType": null
   },
   "paymentMethod": {
      "id": "0.0.0.1+-payinfo-cc+6337651",
      "href": "http://host:port/brm/paymentMethods/v1/paymentMethod/0.0.0.1+-payinfo-cc+6337651",
      "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": "Alice Rose",
            "@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+6337523",
      "href": null,
      "name": "ServiceTelcoGsmSms",
      "@baseType": null,
      "@schemaLocation": null,
      "@type": "ProductRef",
      "@referredType": null
   },
   "reason": null,
   "recurringPeriod": "1 Day",
   "relatedParty": null,
   "relatedTopupBalance": null,
   "requestedDate": "2025-09-30T03:06:42+05:30",
   "requestor": null,
   "status": "CONFIRMED",
   "usageType": "monetary",
   "voucher": ""
}
Back to Top