dxp-ux

(0 reviews)

Get-topupBalance

/topupBalance [GET]

This operation retrieves a list of TopupBalance resources.

This API is available for LCPR.

URL

http://[localhost]:[port]/dxp-ux/v1/{businessId}/topupBalance

URI PARAMS

name	type	description	required
businessId	string	Market: PR	Y

Headers

name	type	description	required
client_id	string	The client_id identifying the channel. Minimum characters: 5	Y
client_secret	string	Password associated with the client_id. Minimum characters: 5	Y
X-Correlation-ID	string	Identifier that correlates HTTP request between a client and server. Any identification model (UUDI, checksum, etc.) can be used, as long as it is a unique value to differentiate a transaction Minimum characters: 1	N
targetSystem	string	Expected target system: matrixx	Y
channelId	string	Channel to business Can be : APP	Y

Query Params

name	type	description	required
accountId	string	To list the topupBalance from a specific Subscription id of the line NOTE : accountId queryParamter will be deprecated from next change. Going forward this shall not be used.	M/O
partyAccount.id	string	To list the topupBalance of a specific Subscription id	M/O
partyAccount."@type"	string	Type of party account Y when partyAccount.id is passed example: "subscriptionRef"	M/O
logicalResource.id	string	To list the topupBalance of a specific MSISDN id
logicalResource."@type"	string	Type of logical resource Y when logicalResource.id is paased example: "MSISDN"	M/O
confirmationDate.gte	datetime	Start Date Time	N
confirmationDate.lte	endtime	End Date Time	N
limit	integer	Requested number of resources to be provided in response	N

NOTE: It is mandatory to pass one of the queryParams.

Possible response success

[ 200 ]

OK - list topupBalance request processed successfully, response body contains an entity corresponding to the requested resource.

List topupBalances by partyAccount.id

[
    {
        "id": "IC40:1:52:3164",
        "requestedDate": "2022-09-06T09:27:24.919832Z",
        "channel": {
            "name": "IVR"
        },
        "validFor": {
            "endDateTime": "65535-12-31T23:59:59.999999Z",
            "startDateTime": "2022-08-29T06:29:41.000Z"
        },
        "partyAccount": {
            "id": "S-9077196",
            "@type": "subscriptionRef"
        },
        "bucket": {
            "id": 1
        },
        "product": [
            {
                "id": 0,
                "name": "RechargeOffer"
            }
        ],
        "amount": {
            "amount": -100.0,
            "units": "USD"
        },
        "impactedBucket": [
            {
                "amountAfter": -111.5,
                "name": "Total Amount",
                "item": [
                    {
                        "amount": 10.5,
                        "name": "STATE SALES TAX"
                    },
                    {
                        "amount": 1.0,
                        "name": "CITY SALES TAX"
                    }
                ]
            }
        ]
    },
    {
        "id": "IC30:1:52:3018",
        "requestedDate": "2022-09-05T11:59:55.535953Z",
        "channel": {
            "name": "sfdc-b2c"
        },
        "validFor": {
            "endDateTime": "65535-12-31T23:59:59.999999Z",
            "startDateTime": "2022-08-29T06:29:41.000Z"
        },
        "partyAccount": {
            "id": "S-9077196",
            "@type": "subscriptionRef"
        },
        "bucket": {
            "id": 1
        },
        "product": [
            {
                "id": 0,
                "name": "RechargeOffer"
            }
        ],
        "amount": {
            "amount": -100.0,
            "units": "USD"
        },
        "impactedBucket": [
            {
                "amountAfter": -111.5,
                "name": "Total Amount",
                "item": [
                    {
                        "amount": 10.5,
                        "name": "STATE SALES TAX"
                    },
                    {
                        "amount": 1.0,
                        "name": "CITY SALES TAX"
                    }
                ]
            }
        ]
    },
    {
        "id": "ICU0:1:52:1990",
        "requestedDate": "2022-08-29T06:41:30.084205Z",
        "reason": "Low balance",
        "validFor": {
            "endDateTime": "65535-12-31T23:59:59.999999Z",
            "startDateTime": "2022-08-29T06:29:41.000Z"
        },
        "partyAccount": {
            "id": "S-9077196",
            "@type": "subscriptionRef"
        },
        "bucket": {
            "id": 1
        },
        "amount": {
            "amount": -100.0,
            "units": "USD"
        },
        "impactedBucket": [
            {
                "amountAfter": -100.0,
                "name": "Total Amount",
                "item": [
                    {
                        "amount": 10.5,
                        "name": "STATE SALES TAX"
                    },
                    {
                        "amount": 1.0,
                        "name": "CITY SALES TAX"
                    }
                ]
            }
        ]
    },
    {
        "id": "ICU0:1:52:1988",
        "requestedDate": "2022-08-29T06:39:06.672519Z",
        "reason": "Low balance",
        "validFor": {
            "endDateTime": "65535-12-31T23:59:59.999999Z",
            "startDateTime": "2022-08-29T06:29:41.000Z"
        },
        "partyAccount": {
            "id": "S-9077196",
            "@type": "subscriptionRef"
        },
        "bucket": {
            "id": 1
        },
        "amount": {
            "amount": -100.0,
            "units": "USD"
        },
        "impactedBucket": [
            {
                "amountAfter": -100.0,
                "name": "Total Amount",
                "item": [
                    {
                        "amount": 10.5,
                        "name": "STATE SALES TAX"
                    },
                    {
                        "amount": 1.0,
                        "name": "CITY SALES TAX"
                    }
                ]
            }
        ]
    },
    {
        "id": "ICU0:1:52:1985",
        "requestedDate": "2022-08-29T06:35:50.033819Z",
        "channel": {
            "name": "sfdc-b2c"
        },
        "validFor": {
            "endDateTime": "65535-12-31T23:59:59.999999Z",
            "startDateTime": "2022-08-29T06:29:41.000Z"
        },
        "partyAccount": {
            "id": "S-9077196",
            "@type": "subscriptionRef"
        },
        "bucket": {
            "id": 1
        },
        "product": [
            {
                "id": 0,
                "name": "RechargeOffer"
            }
        ],
        "amount": {
            "amount": -100.0,
            "units": "USD"
        },
        "impactedBucket": [
            {
                "amountAfter": -111.5,
                "name": "Total Amount",
                "item": [
                    {
                        "amount": 10.5,
                        "name": "STATE SALES TAX"
                    },
                    {
                        "amount": 1.0,
                        "name": "CITY SALES TAX"
                    }
                ]
            }
        ]
    }
]

List topupBalances by logicalResource.id

[
    {
        "id": "IC40:1:52:3164",
        "requestedDate": "2022-09-06T09:27:24.919832Z",
        "channel": {
            "name": "IVR"
        },
        "validFor": {
            "endDateTime": "65535-12-31T23:59:59.999999Z",
            "startDateTime": "2022-08-29T06:29:41.000Z"
        },
        "logicalResource": [
            {
                "id": "9077196",
                "@type": "msisdn"
            }
        ],
        "bucket": {
            "id": 1
        },
        "product": [
            {
                "id": 0,
                "name": "RechargeOffer"
            }
        ],
        "amount": {
            "amount": -100.0,
            "units": "USD"
        },
        "impactedBucket": [
            {
                "amountAfter": -111.5,
                "name": "Total Amount",
                "item": [
                    {
                        "amount": 10.5,
                        "name": "STATE SALES TAX"
                    },
                    {
                        "amount": 1.0,
                        "name": "CITY SALES TAX"
                    }
                ]
            }
        ]
    },
    {
        "id": "IC30:1:52:3018",
        "requestedDate": "2022-09-05T11:59:55.535953Z",
        "channel": {
            "name": "sfdc-b2c"
        },
        "validFor": {
            "endDateTime": "65535-12-31T23:59:59.999999Z",
            "startDateTime": "2022-08-29T06:29:41.000Z"
        },
        "logicalResource": [
            {
                "id": "9077196",
                "@type": "msisdn"
            }
        ],
        "bucket": {
            "id": 1
        },
        "product": [
            {
                "id": 0,
                "name": "RechargeOffer"
            }
        ],
        "amount": {
            "amount": -100.0,
            "units": "USD"
        },
        "impactedBucket": [
            {
                "amountAfter": -111.5,
                "name": "Total Amount",
                "item": [
                    {
                        "amount": 10.5,
                        "name": "STATE SALES TAX"
                    },
                    {
                        "amount": 1.0,
                        "name": "CITY SALES TAX"
                    }
                ]
            }
        ]
    },
    {
        "id": "ICU0:1:52:1990",
        "requestedDate": "2022-08-29T06:41:30.084205Z",
        "reason": "Low balance",
        "validFor": {
            "endDateTime": "65535-12-31T23:59:59.999999Z",
            "startDateTime": "2022-08-29T06:29:41.000Z"
        },
        "logicalResource": [
            {
                "id": "9077196",
                "@type": "msisdn"
            }
        ],
        "bucket": {
            "id": 1
        },
        "amount": {
            "amount": -100.0,
            "units": "USD"
        },
        "impactedBucket": [
            {
                "amountAfter": -100.0,
                "name": "Total Amount",
                "item": [
                    {
                        "amount": 10.5,
                        "name": "STATE SALES TAX"
                    },
                    {
                        "amount": 1.0,
                        "name": "CITY SALES TAX"
                    }
                ]
            }
        ]
    },
    {
        "id": "ICU0:1:52:1988",
        "requestedDate": "2022-08-29T06:39:06.672519Z",
        "reason": "Low balance",
        "validFor": {
            "endDateTime": "65535-12-31T23:59:59.999999Z",
            "startDateTime": "2022-08-29T06:29:41.000Z"
        },
        "logicalResource": [
            {
                "id": "9077196",
                "@type": "msisdn"
            }
        ],
        "bucket": {
            "id": 1
        },
        "amount": {
            "amount": -100.0,
            "units": "USD"
        },
        "impactedBucket": [
            {
                "amountAfter": -100.0,
                "name": "Total Amount",
                "item": [
                    {
                        "amount": 10.5,
                        "name": "STATE SALES TAX"
                    },
                    {
                        "amount": 1.0,
                        "name": "CITY SALES TAX"
                    }
                ]
            }
        ]
    },
    {
        "id": "ICU0:1:52:1985",
        "requestedDate": "2022-08-29T06:35:50.033819Z",
        "channel": {
            "name": "sfdc-b2c"
        },
        "validFor": {
            "endDateTime": "65535-12-31T23:59:59.999999Z",
            "startDateTime": "2022-08-29T06:29:41.000Z"
        },
        "logicalResource": [
            {
                "id": "9077196",
                "@type": "msisdn"
            }
        ],
        "bucket": {
            "id": 1
        },
        "product": [
            {
                "id": 0,
                "name": "RechargeOffer"
            }
        ],
        "amount": {
            "amount": -100.0,
            "units": "USD"
        },
        "impactedBucket": [
            {
                "amountAfter": -111.5,
                "name": "Total Amount",
                "item": [
                    {
                        "amount": 10.5,
                        "name": "STATE SALES TAX"
                    },
                    {
                        "amount": 1.0,
                        "name": "CITY SALES TAX"
                    }
                ]
            }
        ]
    }
]

Definitions

Each of the request parameters is detailed.

name	type	description	required
description	string	Represents a detailed description of a recharge operation requested over a bucket (defined by a specific product or reference to a product (i.e.: a commercial id such as an msisidn) and a service type)	N
id	string	Unique Identifier for the resource	Y
href	string	A reference to the resource	N
confirmationDate	datetime	Date when the deduction was confirmed in the server	Y
description	string	Description of the recharge operation	Y
isAutoTopup	boolean	Indicates if the topup requested is an autotopup (to be processed periodically)	N
numberOfPeriods	integer	For autotopup indicates the number of occurrences of the period the recharge operation must be executed. If not included then no limit is set to stop the executionof the topup every period	N
reason	string	Text describing the reason for the action/task	N
requestedDate	datetime	Date when the deduction request was received in the server	Y
voucher	string	Identifier for a voucher when the topup can be performed by this means	N
amount	Quantity	An amount in a given unit	Y
amount.amount	number	Numeric value in a given unit	Y
amount.unit	string	Unit	Y
balanceTopup	object	Related Entity reference. A related balance topup defines a relationship via a role to another balance topup. Used in the PrepayBalanceManagement API to track child topups that are related to the parent (initiating balance topup resource). PrepayBalanceManagement defines the child role	N
balanceTopup.id	string	unique identifier	N
balanceTopup.href	string	Hyperlink reference	N
balanceTopup.name	string	Name of the related entity.	N
balanceTopup.role	string	Role played by the TopupBalance. In the PrepayBalanceManagement API this is parent or child	N
balanceTopup.@baseType	string	When sub-classing, this defines the super-class	N
balanceTopup.@schemaLocation	string	A URI to a JSON-Schema file that defines additional attributes and relationships	N
balanceTopup.@type	string	When sub-classing, this defines the sub-class Extensible name	N
balanceTopup.@referredType	string	The actual type of the target instance when needed for disambiguation.	N
bucket	object	link to the resource that holds bucket information	N
bucket.id	string	unique identifier	N
bucket.href	string	Hyperlink reference	N
bucket.name	string	Name of the related entity.	N
bucket.@baseType	string	When sub-classing, this defines the super-class	N
bucket.@schemaLocation	string	A URI to a JSON-Schema file that defines additional attributes and relationships	N
bucket.@type	string	When sub-classing, this defines the sub-class Extensible name	N
bucket.@referredType	string	The actual type of the target instance when needed for disambiguation.	N
channel	object	The channel to which the resource reference to. e.g. channel for selling product offerings, channel for opening a trouble ticket etc..	N
channel.id	string	unique identifier	N
channel.href	string	Hyperlink reference	N
channel.name	string	Name of the channel.	N
channel.@baseType	string	When sub-classing, this defines the super-class	N
channel.@schemaLocation	string	A URI to a JSON-Schema file that defines additional attributes and relationships	N
channel.@type	string	When sub-classing, this defines the sub-class Extensible name	N
channel.@referredType	string	The actual type of the target instance when needed for disambiguation.	N
logicalResource	array	reference to the LogicalResource eg MSISDN	N
logicalResource.id	string	unique identifier	N
logicalResource.href	string	Hyperlink reference
logicalResource.name	string	Name of the related entity.	N
logicalResource.@baseType	string	When sub-classing, this defines the super-class	N
logicalResource.@schemaLocation	string	A URI to a JSON-Schema file that defines additional attributes and relationships	N
logicalResource.@type	string	When sub-classing, this defines the sub-class Extensible name	N
logicalResource.@referredType	string	The actual type of the target instance when needed for disambiguation.	N
partyAccount	object	PartyAccount reference. A party account is an arrangement that a party has with an enterprise that	N
partyAccount.id	string	Unique identifier of the party account	N
partyAccount.href	string	Reference of the party account	N
partyAccount.description	string	Detailed description of the party account	N
partyAccount.name	string	Name of the party account	N
partyAccount.status	string	The condition of the account, such as due, paid, in arrears.	N
partyAccount.@baseType	string	When sub-classing, this defines the super-class	N
partyAccount.@schemaLocation	string	A URI to a JSON-Schema file that defines additional attributes and relationships	N
partyAccount.@type	string	When sub-classing, this defines the sub-class entity name	N
partyAccount.@referredType	string	The actual type of the target instance when needed for disambiguation.	N
paymentMethod	object	PaymentMethod reference. A payment method defines a specific mean of payment (e.g direct debit).	N
paymentMethod.id	string	unique identifier	N
paymentMethod.href	string	Hyperlink reference	N
paymentMethod.name	string	Name of the related entity.	N
paymentMethod.@baseType	string	When sub-classing, this defines the super-class	N
paymentMethod.@schemaLocation	string	A URI to a JSON-Schema file that defines additional attributes and relationships	N
paymentMethod.@type	string	When sub-classing, this defines the sub-class Extensible name	N
paymentMethod.@referredType	string	The actual type of the target instance when needed for disambiguation.	N
product	array	A reference to the Product associated with this bucket.	N
product.id	string	unique identifier	N
product.href	string	Hyperlink reference	N
product.name	string	Name of the related entity.	N
product.@baseType	string	When sub-classing, this defines the super-class	N
product.@schemaLocation	string	A URI to a JSON-Schema file that defines additional attributes and relationships	N
product.@type	string	When sub-classing, this defines the sub-class Extensible name	N
product.@referredType	string	The actual type of the target instance when needed for disambiguation.	N
recurringPeriod	string	Valid values for this type. enum: - weekly - fortnightly - monthly	N
relatedParty	array	Used to provide information about any other entity with relation to the operation	N
relatedParty.id	string	Unique identifier of a related entity.	N
relatedParty.href	string	Reference of the related entity.	N
relatedParty.name	string	Name of the related entity.	N
relatedParty.role	string	Role played by the related party	N
relatedParty.@baseType	string	When sub-classing, this defines the super-class	N
relatedParty.@schemaLocation	string	A URI to a JSON-Schema file that defines additional attributes and relationships	N
relatedParty.@type	string	When sub-classing, this defines the sub-class entity name	N
relatedParty.@referredType	string	The actual type of the target instance when needed for disambiguation.	N
requestor	object	Related Entity reference. A related party defines party or party role linked to a specific entity.	N
requestor.id	string	Unique identifier of a related entity.	N
requestor.href	string	Reference of the related entity.	N
requestor.name	string	Name of the related entity.	N
requestor.role	string	Role played by the related party	N
requestor.@baseType	string	When sub-classing, this defines the super-class	N
requestor.@schemaLocation	string	A URI to a JSON-Schema file that defines additional attributes and relationships	N
requestor.@type	string	When sub-classing, this defines the sub-class entity name	N
relatedParty.@referredType	string	The actual type of the target instance when needed for disambiguation.	N
status	string	Valid values for the Action Status Type	Y
usageType	string	Valid values for the usage type are	N
validFor	object	A period of time, either as a deadline (endDateTime only) a startDateTime only, or both	N
validFor.startDateTime	datetime	Start of the time period, using IETC-RFC-3339 format. If you define a start, you must also define an end	N
validFor.endDateTime	datetime	End of the time period, using IETC-RFC-3339 format	N
@baseType	string	When sub-classing, this defines the super-class	N
@schemaLocation	string	A URI to a JSON-Schema file that defines additional attributes and relationships	N
@type	string	When sub-classing, this defines the sub-class entity name	N
payment	object	PaymentMethod reference. A payment method defines a specific mean of payment (e.g direct debit).	Y
payment.id	string	unique identifier	Y
payment.href	string	Hyperlink reference	N
payment.name	string	Name of the related entity.	N
payment.@baseType	string	When sub-classing, this defines the super-class	N
payment.@schemaLocation	string	A URI to a JSON-Schema file that defines additional attributes and relationships	N
payment.@type	string	When sub-classing, this defines the sub-class Extensible name	Y
payment.@referredType	string	The actual type of the target instance when needed for disambiguation.	N
impactedBucket	array	A resource that references other buckets that have been impacted by the action of TopupBalance	N
impactedBucket.amountAfter	number	Indicates the amount on the impacted bucket after the action has completed.	N
impactedBucket.name	string	Friendly name to identify the bucket	N
impactedBucket.item	array	A resource used by the ImpactedBucket resource to capture the impact of an ImpactedBucket	N
impactedBucket.item.amount	number	Indicate the amount on the bucket	N
impactedBucket.item.name	string	This represents the transaction activity. e.g. topup, bonus, additional bonus, tax, fees, and so on	N

Possible Error Scenarios: :

IF WE ARE NOT PASSING QUERYPARAMS

{
    "errors": [
        {
            "code": 400,
            "message": "VALIDATION:BLANK_STRING",
            "description": "Either of accountId | partyAccount.id | logicalResource.id is expected"
        }
    ]
}

IF WE ARE PASSING INVALID ACCOUNTID IN QUERYPARAMS

[
    {
        "errors": [
            {
                "code": 404,
                "message": "MATRIXX:RETRIEVE_TOPUPBALANCE",
                "description": "11 | Subscriber not found (ExternalId=S-9012)"
            }
        ]
    }
]

INVALID URL

{
    "errors": [
        {
            "code": 405,
            "message": "APIKIT:METHOD_NOT_ALLOWED",
            "description": "HTTP Method get not allowed for : /{businessId}"
        }
    ]
}