Configuring Top-Ups

Integrating Top-Up Clients

ECE interfaces directly with top-up systems to manage balances. The top-up systems send the top-up amount to ECE, and then ECE updates the customer balance and sends the update to the BRM server.

ECE does not manage top-up authentication, authorization, or accounting operations.

For information about running sample programs that demonstrate how to use the ECE top-up API, see "ECE Sample Programs".

To configure top-up notifications, see "About ECE Notifications".

Detecting Duplicate Top-Up Requests

Duplicate top-up requests might occur within ECE as a result of node failures (for example, if an ECE server unexpectedly shuts down, ECE might internally resubmit a top-up request when restarted). To detect and eliminate these internal duplicate top-up requests, ECE maintains a top-up history cache.

Note:

Third-party top-up systems, such as voucher management systems, are expected to eliminate duplicate top-up requests coming from the network.

The ECE top-up history cache maintains a specified number of top-up message IDs for each customer. If the message ID of an incoming top-up request is already in the history, ECE considers the request to be a duplicate.

If ECE detects a duplicate top-up request, the following occurs:

ECE does not apply the top up
ECE includes the following in the top-up response message:
- The reason code DUPLICATE_REQUEST
- The current customer balance

If you do not retain a sufficient number of top-up request message IDs in your top-up history cache, ECE may not detect internal duplicate top-up requests. If ECE cannot detect an internal duplicate top-up request, the following occurs:

ECE applies the top-up balance to the customer balance as though it were a new request and sends the top-up balance to the BRM server.
The BRM server, which stores all top-up message IDs in the BRM database, detects the top-up request as a duplicate and does not apply the top up to the customer balance in the BRM database.
BRM adds the Error from BRM: ERR_DUPLICATE error to the BRM Gateway log file.

You must manually track such errors in the BRM Gateway log file and correct the customer balance in ECE because the ECE customer balance is no longer synchronized with the customer balance in the BRM database.

To configure the number of top-up request message IDs in your top-up history cache:

Access the ECE configuration MBeans in a JMX editor, such as JConsole. See "Accessing ECE Configuration MBeans".
Expand the ECE Configuration node.
Expand charging.externalTopUpConfig.
Expand Attributes.
Set the topUpHistoryCount attribute to the number of top-up request message IDs to store for each customer.

The default value is 3.

If you change the value of this attribute (for example, from 10 to 4) and the top-up history cache already contains 10 message IDs, ECE eliminates the message IDs of the oldest 6 top ups when the next top up arrives so that only the message IDs of the 4 most recent top-up requests are stored.

Using the Top-Up API

To validate top-up requests, clients call the submitUpdate API with ExternalTopupUpdateRequest.

Consider the following points for how the ECE top-up API validates top-up requests:

For a currency balance, validity should not be passed as part of the request; if it is passed, it fails with an error. The customer's balance is expected to have one valid currency balance item/bucket with infinite validity. If no balance item/bucket is present, a new one is created with infinite validity.
Validity extend (ValidityExtend) is only for noncurrency balances (given that currency balances do not have a validity).
Whenever validity must be set for a balance, both validity start and validity end must be sent as part of the request.

To create bucket with infinite validity, set both validityStart and validityEnd to -1.
If the request is to extend validity and the customer balance has multiple valid balance items/buckets, then an error response is sent.
If the request is to create a firstUsage bucket, then validity start and validity end should not be set in the request, except for the FirstUsageValidityUnit.ABSOLUTE mode.
ValidityExtend is not allowed on a first-usage bucket.
If both the validity and first-usage information (such as offset and unit) are specified as part of the request, then the top-up request fails with an error.
Top-ups from Third-party top-up systems are not allowed when ECE is in a short-lived phase of the rerating process called the CATCH_UP phase.

If top-up requests are sent during the CATCH_UP phase of rerating, ECE sends a response that includes the reason code for the failure. If that occurs, you can resend the top-up, and ECE will process it.
During testing, if a top-up request is sent to ECE with an event time that is earlier than the account creation time of the account to which the top-up applies, the balance is updated with the top-up in ECE but the balance is not updated in BRM. When you set event time stamps during testing, ensure the event time of the top-up request is later than the applicable account creation time.

For details about the top-up API, see the documentation for oracle.communication.brm.charging.brs and oracle.communication.brm.charging.messages.update in Elastic Charging Engine Java API Reference.