Refill a Prepaid Account

Service Operation (WS)

Definition

To refill the prepaid account of a subscriber account and to credit counters in a charging contract

Technical Data

Software Product and Version	SAP Convergent Charging 5.0
Technical Details	prepaidAccountRefill
Namespace	http://refilling.v1.ws.highdeal.com/
Proxy Instance in SAP CC System	Updater
Service Operation Version	1
Application Area	IS-CC
Direction	inbound
Mode	synchronous
Idempotency	true

Business Context and Use

This service operation is used to add some credit to the balance of a prepaid account in customer master data stored in SAP Convergent Charging. Then the credit can be used by the end customer to use and consume a service of the service provider. The refill types can vary from simple (only the balance of the prepaid account is credited) to complex refill when counters are also changed in the related charging contract.

The SAP CC system processes the refill logic and computes:

• The credit to add (including or not the remaining one) and its validity period
• Some gifts, loyalty points, and so on and do some checks (for capping purposes for instance)

This operation can also be used to reverse a previous refill or clear the balance of a prepaid account, using a negative amount in the refill logic.

Related Service Operations

You can use the following operation to identify prepaid accounts:

• Find the prepaid accounts related to one user technical identifier

You can use the following operations to perform actions on prepaid accounts:

• Create or change a prepaid account
• Cancel a prepaid account
• Change the state of a prepaid account

They are available in the Subscriber Account Management process component related to the Business Partner Management.

Features

This service operation enables you to refill (top up) the balance of a prepaid account managed and stored in SAP Convergent Charging.

You specify:

• The identifier of the prepaid account and its related subscriber account
• The refill price (amount and currency)
  • The amount includes paid taxes if you want to implement "pay-as-you-go" services (a prepaid mobile phone for example)
  • The amount does not include any tax if you want to implement cash advance services based on prepaid cards or gift cards
• A refill item that is a data record including data properties and an identifier
  • Usage identifier that is configured in the refill logic in a refill plan activated in the charging contract belonging to the subscriber. Several usage refills can be set in the refill logic to manage top up and reversal.
  • Named properties use to process the advanced refill logic configured in a refill plan; Some input properties may be expected in the output data (refill record) generated by SAP Convergent Charging during the refilling process.
• A unique refill operation identifier if SAP CC must provide an idempotent refill service.

Operation Response

The SAP CC system includes the USER_ALERT notifications in the operation responses.

Authorizations

To know the role that is expected in the user profile of the SAP CC user specified in your request messages, refer to the SAP CC Security Guide .

Error Handling

The SAP CC system may return an error classified into a category and an error stack detailing the issue and its cause.

Categories and Treatments to Implement

Consider the following error categories to design and implement the appropriate behavior of your connected application or system:

Error Category	Description	Error Handling
Already Exists	The data has to be created but another data already exists in the connected SAP CC system with the same type and the same identifier.	Applicable for this service operation: You implement the logging of this error to enable a system administrator or a consultant to investigate and resolve the issue. Data replication or data synchronization mechanisms may failed.
Does Not Exist	The data to be modified or deleted does not exist in the connected SAP CC system.	Applicable for this service operation: Next follows a non-exhaustive list of errors related to the Does Not Exist category: The subscriber account identifier does not exist in customer master data stored in SAP CC
Invalid	The request or the data is invalid.	Applicable for this service operation: Next follows a non-exhaustive list of errors related to the Invalid category: Refill item is not specified in the operation request Bad amount is specified, which includes no amount, an unknown currency, or no amount value Usage unique identifier is not specified Subscriber account identifier is not specified Prepaid account identifier is not specified
Incompatible Configuration	The configuration of the connected SAP CC system is not compatible with the data specified in the operation request and the scope of the request. Creating or correcting the prerequisite configuration data (master data, business data) has to be done in the SAP CC system with the Core Tool user interface or within your connected application or system.	Applicable for this service operation:
Prerequisite Missing	Another data mandatory for the operation is not available or is not compatible with the data specified in the operation request. Create a prerequisite for the data.	Applicable for this service operation: The prerequisite data is managed outside the SAP CC system. Next follows a non-exhaustive list of errors related to the Prerequisite Missing category: The specified prepaid account is not assigned to any contract item activating a refil plan at the specified date
Illegal State	The operation request is valid but was rejected because of the current state of the data in the connected SAP CC system which prevents the execution of the request. The current state of the complete system can be also the origin of the error.	Applicable for this service operation: The request will not succeed without a required manual correction or change in the SAP CC system. You implement error logging and manual retry mechanisms. Next follows a non-exhaustive list of errors related to the Illegal State category: A charging/refilling failure occurred in the SAP CC system
Temporary Illegal State	The valid request was rejected because of the temporarilly illegal state of the data in the connected SAP CC system. The data state may automatically change without any further notification. This is a subcategory of Illegal State category. The state of a data is temporarilly illegal but the operation request can be sent again after a waiting period. The current state of the complete system can be also the origin of the error.	Applicable for this service operation: You can implement an automated resend function.

Troubleshooting

Refer to the SAP CC Error Code Reference ( SAP Site ) for more information about a returned error code and the corrective actions necessary for troubleshooting your implementation project.

Message Types

Consult the structures of the message types related to this service operation :

• prepaidAccountRefillRequest
• prepaidAccountRefillResponse

Prerequisites

At least one subscriber account and one prepaid account included in this subscriber account must be created and relate to the end customer of the service provider.

The end customer has subscribed to a provider contract that activates a refill plan that is configured in the pricing catalog of the service provider.

Integration

You can use this operation to refill the prepaid account you may have previously identified (see the Find the prepaid accounts related to a user technical identifier operation).

This operation returns the notifications which have been generated by the refilling logic.

Constraints and Integrity Conditions

There is no specific constraint.

Notes on SAP CC Implementation

You must have installed and configured the SAP CC Core Server system.

Configuration

Consult the SAP CC Configuration and Implementation Guide to know the necessary configuration or Customizing of the SAP CC system.

Before implementing SAP Convergent Charging in your SAP system landscape, you must configure the systems and the data (master data, business data).

Additional Information

Consult the SAP CC Application Help for more information about the refilling process.

Consult the SAP CC Notification Reference for more information about the USER_ALERT notification.

Consult the SAP CC Logic Component Reference and the SAP CC Core Tool Primary Help for more information about the configuration of an alert triggering operator in the pricing logic.