Get Top-up Balances
get
/topupBalance
Gets top-up balances that match the query criteria.
Request
Query Parameters
-
fields: string
The list of comma-separated fields to return in the response.Example:
isAutoTopup,paymentMethod -
limit: integer
The maximum number of results to return. For example, use limit=10 to return the first 10 results only.Example:
10 -
offset: integer
The number of results to offset the response by. For example, use offset=10 to return results 10 and higher.Example:
10
There's no request body for this operation.
Back to TopResponse
Supported Media Types
- application/json;charset=utf-8
200 Response
Success
Headers
-
X-Result-Count:
The number of items returned in the response body.
-
X-Total-Count:
The total number of items that matched the criteria.
Root Schema : schema
Type:
Show Source
array-
Array of:
object Topup Balance
Title:
Topup BalanceA top-up.
Nested Schema : Topup Balance
Type:
objectTitle:
Topup BalanceA top-up.
Show Source
-
@baseType: string
Title:
Base TypeThe object's superclass. -
@schemaLocation: string
(uri)
Title:
Schema LocationA URI to a JSON-Schema file that defines additional attributes and relationships. -
@type: string
Title:
TypeThe object's subclass. -
amount: object
Quantity
An amount in a given unit.
-
balanceTopup: object
Related Topup Balance
Title:
Related Topup BalanceA relationship between balance top-ups, that defines whether a balance is the parent or child of another. -
bucket: object
Bucket Ref
Title:
Bucket RefA reference to a bucket. -
channel: object
Channel Ref
Title:
Channel RefA reference to a channel. -
confirmationDate: string
(date-time)
Title:
Confirmation DateThe date the top-up was confirmed. -
description: string
Title:
DescriptionThe top-up's description. -
href: string
Title:
HrefThe top-up balance's href. -
id: string
Title:
IDThe top-up balance's ID. -
isAutoTopup: boolean
Title:
Is Auto TopupWhether the top-up is automatic (true) or not (false). -
logicalResource: array
logicalResource
Logical resources associated with the top-up.
-
numberOfPeriods: integer
Title:
Number of PeriodsThe number of billing periods for which an automatic top-up occurs. If this property is not specified, then the top-up will continue automatically indefinitely. -
partyAccount: object
Party Account Ref
Title:
Party Account RefA reference to a party account. -
paymentMethod: object
Payment Method Ref
Title:
Payment Method RefA payment method reference. -
product: array
product
Products associated with the top-up.
-
reason: string
Title:
ReasonThe reason for the top-up. -
recurringPeriod: string
Title:
Recurring Period TypeAllowed Values:[ "weekly", "fortnightly", "monthly" ]A type of recurring period. - relatedParty: array relatedParty
-
requestedDate: string
(date-time)
Title:
Requested DateThe date that the top-up request was made. -
requestor: object
Related Party
Title:
Related PartyA party related to another object. -
status(required): string
Title:
Action Status TypeAllowed Values:[ "created", "failed", "cancelled", "completed" ]The status of an action. -
usageType: string
Title:
Usage TypeAllowed Values:[ "monetary", "voice", "data", "sms", "other" ]The type of usage. For BRM REST Services Manager, only monetary and other are supported. -
validFor: object
Time Period
Title:
Time PeriodA period of time. You can specify only endDateTime or both endDateTime and startDateTime. -
voucher: string
Title:
VoucherThe voucher used for the top-up.
Nested Schema : Quantity
Type:
objectAn amount in a given unit.
Show Source
-
amount: number
(float)
Default Value:
1Numeric value in a given unit. -
units: string
Unit
Nested Schema : Related Topup Balance
Type:
objectTitle:
Related Topup BalanceA relationship between balance top-ups, that defines whether a balance is the parent or child of another.
Show Source
-
@baseType: string
Title:
Base TypeThe object's superclass. -
@referredType(required): string
Title:
Referred TypeThe object's type in the target system, if baseType and type need further disambiguation. -
@schemaLocation: string
(uri)
Title:
Schema LocationA URI to a JSON-Schema file that defines additional attributes and relationships. -
@type: string
Title:
TypeThe object's subclass. -
href: string
Title:
HrefThe balance's href. -
id(required): string
Title:
IDThe balance's ID. -
name: string
Title:
NameThe balance's name. -
role: string
Title:
RoleThe balance's role. For example, parent or child.
Nested Schema : Bucket Ref
Type:
objectTitle:
Bucket RefA reference to a bucket.
Show Source
-
@baseType: string
Title:
Base TypeThe object's superclass. -
@referredType: string
Title:
Referred TypeThe object's type in the target system, if baseType and type need further disambiguation. -
@schemaLocation: string
(uri)
Title:
Schema LocationA URI to a JSON-Schema file that defines additional attributes and relationships. -
@type: string
Title:
TypeThe object's subclass. -
href: string
Title:
Bucket HrefThe bucket's href. -
id(required): string
Title:
Bucket IDThe bucket's ID. -
name: string
Title:
Bucket NameThe bucket's name.
Nested Schema : Channel Ref
Type:
objectTitle:
Channel RefA reference to a channel.
Show Source
-
@baseType: string
Title:
Base TypeThe object's superclass. -
@referredType: string
Title:
Referred TypeThe object's type in the target system, if baseType and type need further disambiguation. -
@schemaLocation: string
(uri)
Title:
Schema LocationA URI to a JSON-Schema file that defines additional attributes and relationships. -
@type: string
Title:
TypeThe object's subclass. -
href: string
Title:
Channel HrefThe channel's href. -
id(required): string
Title:
Channel IDThe channel's ID. -
name: string
Title:
Channel NameThe channel's name.
Nested Schema : logicalResource
Type:
arrayLogical resources associated with the top-up.
Show Source
-
Array of:
object Logical Resource Ref
Title:
Logical Resource RefA reference to a logical resource.
Nested Schema : Party Account Ref
Type:
objectTitle:
Party Account RefA reference to a party account.
Show Source
-
@baseType: string
Title:
Base TypeThe object's superclass. -
@referredType: string
Title:
Referred TypeThe object's type in the target system, if baseType and type need further disambiguation. -
@schemaLocation: string
(uri)
Title:
Schema LocationA URI to a JSON-Schema file that defines additional attributes and relationships. -
@type: string
Title:
TypeThe object's subclass. -
description: string
Title:
DescriptionThe party account's description. -
href: string
Title:
HrefThe party account's href. -
id(required): string
Title:
Account IDThe party account's ID. -
name: string
Title:
NameThe party account's name. -
status: string
Title:
StatusThe overall status of the account. For example, due, paid, or in arrears.
Nested Schema : Payment Method Ref
Type:
objectTitle:
Payment Method RefA payment method reference.
Show Source
-
@baseType: string
Title:
Base TypeThe object's superclass. -
@referredType: string
Title:
Referred TypeThe object's type in the target system, if baseType and type need further disambiguation. -
@schemaLocation: string
(uri)
Title:
Schema LocationA URI to a JSON schema file that defines additional attributes and relationships. -
@type: string
Title:
TypeThe object's subclass. -
href: string
Title:
Payment Method HrefThe payment method's href. -
id(required): string
Title:
Payment Method IDThe payment method's ID. -
name: string
Title:
Payment Method NameThe payment method's name.
Nested Schema : product
Type:
arrayProducts associated with the top-up.
Show Source
-
Array of:
object Product Ref
Title:
Product RefA reference to a product.
Nested Schema : Related Party
Type:
objectTitle:
Related PartyA party related to another object.
Show Source
-
@baseType: string
Title:
Base TypeThe object's superclass. -
@referredType(required): string
Title:
Referred TypeThe object's type in the target system, if baseType and type need further disambiguation. -
@schemaLocation: string
(uri)
Title:
Schema LocationA URI to a JSON schema file that defines additional attributes and relationships. -
@type: string
Title:
TypeThe object's subclass. -
href: string
Title:
Related Party HrefThe related party's href. -
id(required): string
Title:
Related Party IDThe related party's ID. -
name(required): string
Title:
Related Party NameThe related party's name. -
role: string
Title:
Related Party RoleThe related party's role.
Nested Schema : Time Period
Type:
objectTitle:
Time PeriodA period of time. You can specify only endDateTime or both endDateTime and startDateTime.
Show Source
-
endDateTime: string
(date-time)
Title:
End Time PeriodThe end of the time period in IETC-RFC-3339 format. -
startDateTime: string
(date-time)
Title:
Start Time PeriodThe start of the time period in IETC-RFC-3339 format. If you specify this, you must also specify endDateTime.
Nested Schema : Logical Resource Ref
Type:
objectTitle:
Logical Resource RefA reference to a logical resource.
Show Source
-
@baseType: string
Title:
Base TypeThe object's superclass. -
@referredType: string
Title:
Referred TypeThe object's type in the target system, if baseType and type need further disambiguation. -
@schemaLocation: string
(uri)
Title:
Schema LocationA URI to a JSON-Schema file that defines additional attributes and relationships. -
@type: string
Title:
TypeThe object's subclass. -
href: string
Title:
HrefThe resource's href. -
id(required): string
Title:
IDThe resource's ID. -
name: string
Title:
NameThe resource's name.
Nested Schema : Product Ref
Type:
objectTitle:
Product RefA reference to a product.
Show Source
-
@baseType: string
Title:
Base TypeThe object's superclass. -
@referredType: string
Title:
Referred TypeThe object's type in the target system, if baseType and type need further disambiguation. -
@schemaLocation: string
(uri)
Title:
Schema LocationA URI to a JSON-Schema file that defines additional attributes and relationships. -
@type: string
Title:
TypeThe object's subclass. -
href: string
Title:
Product HrefThe product's href. -
id(required): string
Title:
Product IDThe product's ID. -
name: string
Title:
Product NameThe product's name.
400 Response
Bad Request
Root Schema : Error
Type:
objectTitle:
ErrorUsed when an API returns an error, typically with a HTTP error response-code such as 401 (Unauthorized) or 500 (Internal Server Error).
Show Source
-
@baseType: string
Title:
Base TypeThe object's superclass. -
@schemaLocation: string
(uri)
Title:
Schema LocationA URI to a JSON schema file that defines additional attributes and relationships. -
@type: string
Title:
TypeThe object's subclass. -
code(required): string
Title:
Error CodeAn application's error code, defined in the API or a common list. -
message: string
Title:
Error MessageMore details and corrective actions related to the error. -
reason(required): string
Title:
ReasonThe reason for the error. -
referenceError: string
(uri)
Title:
Reference ErrorA URI to documentation describing the error. -
status: string
Title:
Error StatusThe HTTP Error code extension
401 Response
Unauthorized
Root Schema : Error
Type:
objectTitle:
ErrorUsed when an API returns an error, typically with a HTTP error response-code such as 401 (Unauthorized) or 500 (Internal Server Error).
Show Source
-
@baseType: string
Title:
Base TypeThe object's superclass. -
@schemaLocation: string
(uri)
Title:
Schema LocationA URI to a JSON schema file that defines additional attributes and relationships. -
@type: string
Title:
TypeThe object's subclass. -
code(required): string
Title:
Error CodeAn application's error code, defined in the API or a common list. -
message: string
Title:
Error MessageMore details and corrective actions related to the error. -
reason(required): string
Title:
ReasonThe reason for the error. -
referenceError: string
(uri)
Title:
Reference ErrorA URI to documentation describing the error. -
status: string
Title:
Error StatusThe HTTP Error code extension
403 Response
Forbidden
Root Schema : Error
Type:
objectTitle:
ErrorUsed when an API returns an error, typically with a HTTP error response-code such as 401 (Unauthorized) or 500 (Internal Server Error).
Show Source
-
@baseType: string
Title:
Base TypeThe object's superclass. -
@schemaLocation: string
(uri)
Title:
Schema LocationA URI to a JSON schema file that defines additional attributes and relationships. -
@type: string
Title:
TypeThe object's subclass. -
code(required): string
Title:
Error CodeAn application's error code, defined in the API or a common list. -
message: string
Title:
Error MessageMore details and corrective actions related to the error. -
reason(required): string
Title:
ReasonThe reason for the error. -
referenceError: string
(uri)
Title:
Reference ErrorA URI to documentation describing the error. -
status: string
Title:
Error StatusThe HTTP Error code extension
404 Response
Not Found
Root Schema : Error
Type:
objectTitle:
ErrorUsed when an API returns an error, typically with a HTTP error response-code such as 401 (Unauthorized) or 500 (Internal Server Error).
Show Source
-
@baseType: string
Title:
Base TypeThe object's superclass. -
@schemaLocation: string
(uri)
Title:
Schema LocationA URI to a JSON schema file that defines additional attributes and relationships. -
@type: string
Title:
TypeThe object's subclass. -
code(required): string
Title:
Error CodeAn application's error code, defined in the API or a common list. -
message: string
Title:
Error MessageMore details and corrective actions related to the error. -
reason(required): string
Title:
ReasonThe reason for the error. -
referenceError: string
(uri)
Title:
Reference ErrorA URI to documentation describing the error. -
status: string
Title:
Error StatusThe HTTP Error code extension
405 Response
Method Not Allowed
Root Schema : Error
Type:
objectTitle:
ErrorUsed when an API returns an error, typically with a HTTP error response-code such as 401 (Unauthorized) or 500 (Internal Server Error).
Show Source
-
@baseType: string
Title:
Base TypeThe object's superclass. -
@schemaLocation: string
(uri)
Title:
Schema LocationA URI to a JSON schema file that defines additional attributes and relationships. -
@type: string
Title:
TypeThe object's subclass. -
code(required): string
Title:
Error CodeAn application's error code, defined in the API or a common list. -
message: string
Title:
Error MessageMore details and corrective actions related to the error. -
reason(required): string
Title:
ReasonThe reason for the error. -
referenceError: string
(uri)
Title:
Reference ErrorA URI to documentation describing the error. -
status: string
Title:
Error StatusThe HTTP Error code extension
409 Response
Conflict
Root Schema : Error
Type:
objectTitle:
ErrorUsed when an API returns an error, typically with a HTTP error response-code such as 401 (Unauthorized) or 500 (Internal Server Error).
Show Source
-
@baseType: string
Title:
Base TypeThe object's superclass. -
@schemaLocation: string
(uri)
Title:
Schema LocationA URI to a JSON schema file that defines additional attributes and relationships. -
@type: string
Title:
TypeThe object's subclass. -
code(required): string
Title:
Error CodeAn application's error code, defined in the API or a common list. -
message: string
Title:
Error MessageMore details and corrective actions related to the error. -
reason(required): string
Title:
ReasonThe reason for the error. -
referenceError: string
(uri)
Title:
Reference ErrorA URI to documentation describing the error. -
status: string
Title:
Error StatusThe HTTP Error code extension
500 Response
Internal Server Error
Root Schema : Error
Type:
objectTitle:
ErrorUsed when an API returns an error, typically with a HTTP error response-code such as 401 (Unauthorized) or 500 (Internal Server Error).
Show Source
-
@baseType: string
Title:
Base TypeThe object's superclass. -
@schemaLocation: string
(uri)
Title:
Schema LocationA URI to a JSON schema file that defines additional attributes and relationships. -
@type: string
Title:
TypeThe object's subclass. -
code(required): string
Title:
Error CodeAn application's error code, defined in the API or a common list. -
message: string
Title:
Error MessageMore details and corrective actions related to the error. -
reason(required): string
Title:
ReasonThe reason for the error. -
referenceError: string
(uri)
Title:
Reference ErrorA URI to documentation describing the error. -
status: string
Title:
Error StatusThe HTTP Error code extension
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": "Alice Rose",
"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": "aa aa",
"@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": "Alice Rose",
"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": "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+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": ""
}
]