eax protocol

E A X

Eservglobal / Amdocs eXtensions

EAX Protocol Specification Version 2.1.0q

eServGlobal/Amdocs EAX Protocol Specification V2.1.0q

Preface

Document purpose

This document forms the agreement for the eServGlobal/Amdocs Extensions (EAX) communications interface used between the Amdocs real-time convergent billing system and the eServGlobal IN service applications.

Scope of information The scope of this document includes protocols for connection handling, message structure and encoding, message types, message parameters, and permissible usage scenarios. It also covers operational scenarios for handling failure and recovery, or planned outages in a continuous operations environment.

Audience

This guide is the formal interface specification and hence is of interest to all parties with a need to understand the communication protocol used between the Amdocs real-time convergent billing system and eServGlobal IN service applications.

Prerequisites Assumed knowledge is basic concepts of IN systems, prepaid services, and OSA Charging operations.

Proprietary Information This document, including the information contained herein, is restricted, confidential and proprietary to eServGlobal Ltd and Amdocs It shall not be used or reproduced for any purpose except with the written consent of eServGlobal Ltd and Amdocs.

Document Approvals

Approved By (name) Signature Date

eServGlobal Technical Director

Amdocs Technical Director

6 December 2004 Copyright eServGlobal and Amdocs – 2004 of 43


Revision History

Version Revision date Description Updated by 2.0.9 02/09/02 Another update based on second Cyprus workshop. JXC 2.0.9b 09/10/02 Minor tweaks on initial AMDOCS feedback. JXC 2.0.9c 10/10/02 More AMDOCS input, and released eaxProtocol.h

(v209) JXC

2.0.9d 24/10/02 Shifted order of parameters in FFN response. JXC 2.0.9e 06/11/02 Added Subscriber Details Request. JXC 2.1.0a 27/11/02 Added GPRS and C2C support. JXC 2.1.0b 04/12/02 Updated with AMDOCS feedback. JXC 2.1.0c 05/11/02 Additional AMDOCS feedback. JXC 2.1.0d 06/11/02 More AMDOCS feedback. Header file proposed. JXC 2.1.0e 11/11/02 Add multiple balances for VR, plus bulk SU. JXC 2.1.0f 12/11/02 Additional clarification text. JXC 2.1.0g 06/01/03 Add MilliSeconds balance, BT invalid offer code

status, and SubscriberUpdate array support. JXC

2.1.0h 09/01/03 Removed milliseconds, added due to a misunderstanding.

JXC

2.1.0i 29/01/03 Added offerCode to voucher request, documented the secret get subscriber details response field.

JXC

2.1.0j 05/02/03 Added User IP Address to ARR and CHG requests, also PIN retries remaining to BT response. Added socket C notes, and indicated that SB request can be on any socket.

JXC

2.1.0m 28/07/04 Reformatted document and reviewed all content to bring it up to date and in line with current usage.

PW

2.1.0n 26/08/04 Allow SCP to connect to multiple FR servers and perform load-sharing of all requests Minor typo’s and corrections to ensure alignment with header file Wallet Balance is Balance Type == 7. Loyalty Points re-instated as Balance Type == 10. Change to Originating Cell ID and Terminating Cell ID fields – now called Originating Location Info and Terminating Location Info with format changes. Specify usage of Location Info fields Add Initial Activation to Subscriber Update

PW

2.1.0p 3/11/04 Change to Location Info for MTC Roaming cases where OriginatingLocationInfo will not be set as it is not available in the MTC trigger. Added some comments on BFT allowing an isolated EAX Charge request. Added some comments on primary server re-homing for the single connection policy EAX client. Removed some remaining Provider ID references.

PW

2.1.0q 3/11/04 BFT files to contain EAX Charge requests only. Support for EAX Charge retry count. Support for Connection quiesce indication.

PW

2.1.0r 10/05/06 Update session ID to be in the range of 230 Ids See CTS 25395

NL



Contents Preface.............................................................................................................................................2 Document Approvals........................................................................................................................2 Revision History ...............................................................................................................................3 1 Introduction ...............................................................................................................................7

1.1 Agreement .........................................................................................................................7 1.2 OSA considerations...........................................................................................................7 1.3 Components ......................................................................................................................8

2 Connection protocols ................................................................................................................9 2.1 Sockets and connections...................................................................................................9

2.1.1 Type of sockets ..............................................................................................................9 2.1.2 Connections ...................................................................................................................9 2.1.3 Socket addressing..........................................................................................................9

2.2 Connection procedure .....................................................................................................10 2.2.1 Single connection policy ..............................................................................................10 2.2.2 Multiple connection policy ............................................................................................11 2.2.3 Connection shutdown ..................................................................................................11 2.2.4 Server shutdown indication..........................................................................................11 2.2.5 Reconnection after shutdown ......................................................................................11

2.3 Billing Failure Treatment..................................................................................................11 2.4 BFT and other CDR generation.......................................................................................12

2.4.1 General CDR stream ...................................................................................................12 2.4.2 Specific BFT stream.....................................................................................................12

3 Message interactions ..............................................................................................................14 3.1 Message correlation ........................................................................................................14

3.1.1 Request/Response Pairs .............................................................................................14 3.1.2 Asynchronous processing............................................................................................14

3.2 Message timeout .............................................................................................................14 3.3 Message Header .............................................................................................................15

3.3.1 Protocol Version...........................................................................................................15 3.3.2 SCP ID .........................................................................................................................15 3.3.3 Session ID....................................................................................................................15 3.3.4 Message Type Identifiers.............................................................................................16

4 Message Scenarios & Interactions .........................................................................................17 4.1 Basic Subscriber Query...................................................................................................17

4.1.1 REQUEST: Subscriber Information Request (& Response)........................................17 4.2 Quota Based Reservation (Charge at End).....................................................................17

4.2.1 REQUEST: Authorize & Reserve Request (& Response)...........................................18 4.2.2 REQUEST: Charge Request (& Response) ................................................................18

4.3 Additional Subscriber Interaction Requests ....................................................................19 4.3.1 REQUEST: Subscriber Balances Request (& Response)...........................................19 4.3.2 REQUEST: Subscriber Numbers Request (& Response) ...........................................19 4.3.3 REQUEST: Subscriber Update Request (& Response) ..............................................20 4.3.4 REQUEST: Voucher Redeem Request (& Response) ................................................20 4.3.5 REQUEST: Subscriber Details Request (& Response)...............................................20 4.3.6 REQUEST: Balance Transfer Request (& Response).................................................20

5 Request Parameters ...............................................................................................................21 5.1 Common parameter values .............................................................................................21

5.1.1 Subscriber Key Types..................................................................................................21 5.1.2 Unit Types ....................................................................................................................21 5.1.3 Language Types ..........................................................................................................21 5.1.4 Balance Types .............................................................................................................21 5.1.5 Subscriber Update Action Types .................................................................................22 5.1.6 Subscriber Update Primary Key Types........................................................................22 5.1.7 Bearer Types................................................................................................................22

5.2 REQUEST: Subscriber Information Request (& Response) ...........................................23 5.2.1 Request Parameters ....................................................................................................23 5.2.2 Response Parameters .................................................................................................23



5.3 REQUEST: Authorize & Reserve Request (& Response)...............................................24 5.3.1 Request Parameters ....................................................................................................24 5.3.2 Response Parameters .................................................................................................26

5.4 REQUEST: Charge Request (& Response)....................................................................27 5.4.1 Request Parameters ....................................................................................................27 5.4.2 Response Parameters .................................................................................................28

5.5 REQUEST: Subscriber Balances Request (& Response)...............................................29 5.5.1 Request Parameters ....................................................................................................29 5.5.2 Response Parameters .................................................................................................29

5.6 REQUEST: Subscriber Numbers Request (& Response)...............................................30 5.6.1 Request Parameters ....................................................................................................30 5.6.2 Response Parameters .................................................................................................30

5.7 REQUEST: Subscriber Update Request (& Response)..................................................31 5.7.1 Request Parameters ....................................................................................................31 5.7.2 Response Parameters .................................................................................................32

5.8 REQUEST: Voucher Redeem Request (& Response)....................................................33 5.8.1 Request Parameters ....................................................................................................33 5.8.2 Response Parameters .................................................................................................34

5.9 REQUEST: Subscriber Details Request (& Response) ..................................................35 5.9.1 Request Parameters ....................................................................................................35 5.9.2 Response Parameters .................................................................................................35

5.10 REQUEST: Balance Transfer Request (& Response).................................................36 5.10.1 Request Parameters ....................................................................................................36 5.10.2 Response Parameters .................................................................................................37

6 Appendix A: C-Language Bindings.........................................................................................38 6.1 Message Type Identifiers ................................................................................................38 6.2 Message Header File ......................................................................................................38

7 Appendix B: Request Number Validation ...............................................................................39 7.1 Authorize/Reserve Request Number...............................................................................39 7.2 Charge Request Number.................................................................................................40

8 Appendix C: Excelcom Parameter Notes ...............................................................................41 8.1 Required Fields................................................................................................................41

8.1.1 Authorize Reserve Request .........................................................................................41 8.1.2 Charge Request ...........................................................................................................41

8.2 Normalisation...................................................................................................................41 8.3 Location Info ....................................................................................................................41

8.3.1 Cell ID encoding...........................................................................................................41 8.3.2 Network element address encoding.............................................................................42

8.4 Call Plan Names..............................................................................................................42 8.5 Service Keys....................................................................................................................42 8.6 Subscriber Update...........................................................................................................42

8.6.1 Option 1: Language update .........................................................................................42 8.6.2 Option 2: F&F numbers update....................................................................................42 8.6.3 Option 3: PIN update ...................................................................................................42 8.6.4 Option 4: Initial Activation ............................................................................................43



1 Introduction

1.1 Agreement

Amdocs and eServGlobal offer a combined convergent billing (prepaid and postpaid) solution, which is comprised of the Amdocs real-time billing server and various eServGlobal IN service applications based on Advanced Call Services (ACS).

Amdocs is responsible for providing the back office billing functions, and the real-time pre-paid and/or postpaid billing function. eServGlobal is responsible for providing the IN service component for call control, SMS delivery and control, and USSD services.

There are three key interactions between the service and the billing/subscriber management functions:

• The IN service must request customer profile information in order to perform the correct functions.

• The IN service must request charging actions for the functions it provides.

• The IN service must request changes to the customer profile.

This document defines the messages and protocols that will be used to perform these interactions, and the overall connection management and fail-over functions that will be implemented.

This document forms an agreement between Amdocs and eServGlobal regarding how they will interact in order to provide an integrated joint product offering. In this sense, it forms an interface contract, which should outline the obligations of each party in any specific implementation.

1.2 OSA considerations

During initial discussions between Amdocs and eServGlobal, the suggested solution was that OSA/CORBA be used to form the interface between the billing and service components. However, a detailed investigation suggested that using this protocol might raise some problems, specifically:

• Functionality. The OSA specification does not support all of the required interactions.

• Latency. The CORBA architecture may add additional latency time, which could be a concern in some situations.

• Timeframe. The implementation of a full OSA/CORBA solution may increase the time-to-market, which could jeopardise some currently proposed joint projects.

In evaluating all these factors, it has been agreed by Amdocs and eServGlobal, that a non-OSA solution should be implemented initially.

The actual solution to be implemented will be a TCP/IP single streaming socket solution, using C-struct defined message content preceded by a fixed header.

It is planned to release an OSA/CORBA solution at a later date, which may be integrated into existing installations for customers who wish to migrate to a standards-based protocol.



1.3 Components

The following reference diagram provides a context diagram showing the use of the EAX protocol at Excelcom.

Billing

EAXServer

“A”

EAXServer

“B”

EAXServer

“C”

Billing

EAXServer

“A”

EAXServer

“B”

EAXServer

“C”

SCP

EAX Client

SCP

EAX Client

SCP

EAX Client

Voice USSD SMS Data

Network

Billing

EAXServer

“A”

EAXServer

“B”

EAXServer

“C”

LoadBalancing

PrimaryWith

Failover

OSA-likeChargingOperations

OSA-likeAccountOperations

ServiceControlPoint

RealTimeBilling

Figure 1: High level view of solution components

This document concerns the TCP/IP-based EAX interface, which is indicated between the AMDOCS Billing system and the SCP.



2 Connection protocols This section describes the nature of the connection(s) used by EAX. By convention when using EAX the eServGlobal side always acts as the client(s) by initiating connections to the Amdocs side that acts as server(s). This section includes the protocol for initial connection, and re-connection in the case of failure.

2.1 Sockets and connections

2.1.1 Type of sockets

Each EAX client will open a number of TCP/IP (IPv4) sockets.

• Socket A: Connects to the real-time billing servers for service charging operations.

• Socket B: Connects to the subscriber profile servers for low volume interactive subscriber enquiries and/or update

• Socket C: Connects to the real-time billing servers for selected high volume interactive subscriber enquiries and/or updates

In this manner the Amdocs system presents different server types for different types of message processing. The real-time prepaid server is implemented on one platform using a TimesTen database. The complete back-end customer database is implemented on a separate platform using an Oracle database and different technologies. These various server types are presented as the various socket types, designated as A, B, C, etc within this protocol description.

In order to avoid the need to proxy (or broker) all messages (with the associated performance impact) EAX makes use of these various sockets and distributes requests across the connected socket types according to the message type.

The message type table in a following section defines which message types can be sent on the various socket types.

2.1.2 Connections

For scalability, load-sharing, and redundancy each client may maintain multiple connections of each type of socket. A client may use a single connection for each socket type between each separate client/server pairing. However, multiple connections of the same type between the same client and server instance are permitted to allow for operational scenarios to deal with connection quiescence, failure, and recovery processing.

Each socket (type A, B, or C) can be used in full duplex communications to asynchronously send requests and receive responses for those requests.

2.1.3 Socket addressing

The client will maintain a list of multiple IP Address/Port pairs for each socket type. I.e. it will be configurable for the following parameters.

Parameter Value

Socket A - Destination 1 IP Address A1 (IP Name or Number + TCP/IP Port Number)

Socket A - Destination 2 IP Address A2 …

Socket A - Destination 3 IP Address A3 …

Socket B - Destination 1 IP Address B1 …



Socket C, etc. IP Address C1 … etc

Table 1 – Socket types to Server address configuration



2.2 Connection procedure

For each socket type, the EAX client may make use of either a single connection policy, or a multiple connection policy. The policy used depends upon the capabilities of the EAX client, and the particular configuration deployed by the system administrator.

Note that for connection purposes, socket A, socket B, etc. are treated entirely independently at all times. In fact, each socket could in theory be managed by a separate interface process, and may have a different policy applied.

At start-up, the configured connection policy and its accompanying procedure will be applied for all socket types independently.

2.2.1 Single connection policy

2.2.1.1 Normal connection

The following is the defined connection procedure for initial communications using the single connection policy.

The EAX client will always attempt to connect first to destination 1, also known as the primary server for this client instance.

If this fails, it will try destination 2, then destination 3, etc, until a connection is successfully made to a secondary server, or until all destinations have failed.

2.2.1.2 Steady state processing

During steady state processing each EAX client will attempt to maintain communication via a single connection of each socket type that is using the single connection policy.

However, if communications errors occur on any socket additional connections may be opened (as per the socket type to server address configuration table above) in an attempt to maintain communications and throughput.

2.2.1.3 Reconnection after communication failure

On connection failure, including socket write error, for a socket using the single connection policy, the normal connection procedure (as described above) will immediately be re-applied to that socket.

If at any time the entire connection procedure fails for a specific socket type, the interface will wait at least 10 seconds before attempting to reconnect. During that time, service requests will be treated according to the Billing Failure Treatment rules (originally defined in the SRS with Excelcom and with additional notes below).

After 10 seconds, the next request will initiate the normal connection procedure once more.

Note that a socket connection failure does not necessarily mean the loss of all outstanding requests on a socket. The BE server may not return responses on the re-connected socket for requests made on the failed socket – any request sent on one socket will be returned over the same socket only. However, requests made on socket category A will never be replied to on socket category B, and vice versa.

After the client loses the connection to its primary server, and successfully reconnects to a secondary server, it will periodically attempt to re-open the primary connection in an effort to re-home to the primary server and maintain a more predictable server load configuration. If it successfully reconnects to its primary server it will subsequently quiesce any secondary server connection and re-enter steady state on the primary.



2.2.2 Multiple connection policy

2.2.2.1 Normal connection

For the multiple connection policy the EAX client will attempt to connect to all configured destinations of a given socket type. These connections will be maintained as long as communication can be sustained through the connection.

Based on a load-sharing algorithm the EAX client may distribute requests over each of the various connections for a given socket type in turn.

2.2.2.2 Steady state processing

During steady state processing the EAX client maintains communication over all available connections of a given socket type.

If communications errors occur on any socket the connection may be closed and re-opened in an effort to regain communications. In addition, the EAX client may adjust the distribution of requests to provide effective load-sharing.

2.2.2.3 Reconnection after communication failure

On connection failure, including socket write error, for a socket using the multiple connection policy, an immediate retry is attempted.

If after an initial retry the connection procedure fails for a specific socket type, the interface will wait at least 10 seconds before attempting to reconnect. During that time the connection is removed from the load-sharing algorithm. As long as the remaining connections can sustain the increase in load no requests are lost.

If no connections of the appropriate type are available then each request is treated according to the Billing Failure Treatment rules (originally defined in the SRS with Excelcom and with additional notes below).

2.2.3 Connection shutdown

2.2.4 Server shutdown indication

For any connection the server side may indicate that an immediate shutdown of the connection is necessary, typically to support orderly shutdown of the entire server. An indication may be carried in the EAX header of any response returned from the server. When the client recognises this indicator is set it will stop sending any further requests on this connection, but will continue receiving responses until all outstanding requests on this connection have been responded to, or have timed out, or the connection is closed. Connection shutdown is then complete.

2.2.5 Reconnection after shutdown

Following server initiated shutdown, the usual immediate attempts to re-open the connection are suspended for a configurable period of time to allow the server to complete its orderly shutdown of all processes. After this interval however, the client will begin its usual periodic attempts to open the server so that reconnection occurs automatically once the server has been restarted.

2.3 Billing Failure Treatment

For some messages, there are Billing Failure Treatment (BFT) rules defined to the client. The message type table (Table 3 – Request/Response Types) indicates which messages may be subject to BFT rules, and which messages will automatically fail in the case of connection failure.

To further clarify the BFT behaviour, we apply BFT under three cases.

• If a client request cannot be sent to any server as there is no corresponding connection for the associated socket type (based on the request message type), then that single request



will have BFT applied. This will include the case where the client receives a “socket write” error or network error.

• If the client has lost communication to the associated socket type (based on the request message type) and cannot reconnect to any server address defined for that socket type, then all outstanding requests for that socket type will have BFT applied.

• If the client sends a request, and the response does not return within the timeout period, then that single request will have BFT applied.

The actual effect of applying BFT is described in more detail elsewhere, but a summary is provided here.

For those requests where BFT causes automatic failure, the service logic will normally translate this to a “temporary service failure” message to the subscriber. These types of automatic failures apply mainly to subscriber self-service transactions.

For those operations that involve a Charging Session, the BFT handling will be more sophisticated. In general, the BFT rules may grant a reservation with some limited number of units so that transient BFT impacts do not cause immediate loss of services. Based on the BFT rules, a subsequent debit for that Charging Session against the BFT granted reservation will be attempted, resulting in an isolated EAX Charge request being sent (even when no previous EAX Authorise and Reserve was successful). Only in the case that the EAX Charge is not successfully processed does the EAX client generate a BFT record in the BFT CDR file.

2.4 BFT and other CDR generation

For some messages, CDR generation will apply. There are two separate streams of CDRs that can be generated, one specifically for BFT records, and one generally for any/all EAX messages.

2.4.1 General CDR stream

CDR generation may apply to any subset of message types, based on configuration options. It refers to the capability of recording in a file each protocol data unit (PDU) of the selected message type that is requested to be sent over a server connection.

Under the configured circumstances, the EAX client will write the PDU into the CDR file in the exact same binary format that would be written to the TCP/IP socket – including the message header information. Within the file, each request PDU will be followed immediately by the corresponding response PDU that was returned by the server – meaning that each file contains a sequence of paired request/response PDUs.

The file name for a CDR file of Charge Requests which successfully managed to reach the BE during normal processing will have the following format:

<scphost>_EAX_success_<YYYYMMDDhhmmsss>.cdr

…where “scphost” is the machine host name returned by uname, excluding the domain portion, and where “YYYYMMDDhhmmsss” is the time of file creation to the resolution of deci-seconds, in GMT.

2.4.2 Specific BFT stream

CDR generation may be requested for BFT records. In this case, any Charging session that encounters BFT on the final EAX Charge request will cut a CDR in the BFT stream. Only the EAX Charge request, and not the (internally generated) response is logged. Note that if the sending of Charge requests is retried, only after all attempts have failed will a BFT record be logged.

The file name for a CDR file of BFT PDUs (i.e. Charge Requests) which failed to reach a BE server during normal processing will have the following format:

<scphost>_EAX_fail_<YYYYMMDDhhmmsss>.cdr



…where “scphost” and “YYYYMMDDhhmmsss” are as above for the general CDR stream.



3 Message interactions Once a socket connection is made, communication is via binary messages on that TCP/IP socket. This section defines the features of the messages that are common to all interactions.

3.1 Message correlation

3.1.1 Request/Response Pairs

All message communication will be via a single Request and single Response pair – with the exception of the NullOp messages used to check that a socket is still connected.

The EAX client will send a single request, which may be a request for information (e.g. subscriber data query), or a request for a function to be performed (e.g. reserve subscriber balance, debit balance, or update subscriber data, etc.) to an appropriate server.

The server will send one and only one Response to each Request. The Response must specify the same Session ID that was received in the original Request.

3.1.2 Asynchronous processing

Request/response processing is asynchronous.

Specifically:

• The client may send any number of subsequent requests (for a different Session ID) before receiving the response to an outstanding request.

• The server may respond to requests in an arbitrary order and not necessarily in the order in which the requests were sent and/or received.

3.2 Message timeout

Each request message is stamped with the request time. Either side may independently decide to perform a message timeout.

• The client may decide to no longer wait for a message response.

• The server may decide to not perform a message response, if it determines that its response is so delayed that it will not be of value to the client.

The message timeouts in either case are completely independent. The timers used by each side may or may not be the same. Different timeouts may be applied independently to different socket types and/or message types.

There is no explicit notification in any of these timeout scenarios; the message is simply discarded. If the server replies to a message after the client has abandoned waiting for a response, then the client will simply discard the unexpected response, possibly generating an application alarm.

In the case of a client side timeout the client will not resend the message except in case of Charge Request. In case of charge request, the client with resend the message with the retransmit indicator set to “true”.



3.3 Message Header

All requests and responses will be preceded with a fixed header, with the following elements.

Header Field Usage Protocol Version Agreed value. (Zero is shutdown indicator) Message Length Number of bytes in the message, excluding this header. Message Type The request type number, as shown in Table 3Time-Stamp The GMT epoch (seconds since 1970) at time of message send. Used for message

time-out. SCP ID A unique identifier for the requesting SCP, determined solely by the SCP. Used for

uniqueness only, not for identifying the originating SCP. Session ID A unique identifier for each outstanding request.

Table 2 – Message Header Fields

3.3.1 Protocol Version

This is the agreed level of the protocol. The client or server may refuse communication if there is a mismatch at this level.

3.3.1.1 Server shutdown indicator

During steady state processing, the server may at some point send one or more responses to the client with the Protocol Version set to 0 (zero) as an indication that it is shutting down. The client then suspends sending to the server to quiesce communications before closing the connection.

3.3.2 SCP ID

A unique SCP ID (integer) is configured on each SCP. It is guaranteed to be unique for the connecting machine.

3.3.3 Session ID

A Session ID (integer) that is unique per SCP ID is allocated for each outstanding message. Specifically, the following applies:

If a message with a given SCP ID/Session ID has been sent to the server, then no further messages with that SCP ID/Session ID will be sent to the server, unless one of the following has occurred:

• (Subsequent Message) The previous message has been responded to successfully, or…

• The message is re-transmitted to the Billing system, or…

• The SCP has been restarted, and the original Session ID is re-used, or…

• The entire range of Session ID (230 IDs) has been used.

For all requests except reservation/charge requests, the server does not need to be concerned with uniqueness of Session ID, because there is no context retained between requests.

The cases we need to examine are those that involve maintaining context, i.e. the reserve/charge requests. In this case, the Session ID becomes important, specifically when combined with the Number parameter, which is included in the message body for both of those messages.

This is discussed in more detail in later sections.



3.3.4 Message Type Identifiers

The following request/response types are supported. These values are the integer constants used in the message type field in PDUs from the client to the server, to indicate the type of request that is being made.

The same integer value must be populated in the corresponding return message from the server to the client, to indicate the corresponding response type.

In addition, this table details other message attributes that are specific to the indicated request/response type. These are described in the relevant sections elsewhere in this document.

ID Request/Response PDU type Socket A Socket B Socket C BFT? CDR? 0 Null Operation (Ignore) Yes Yes Yes - Per config 1 Subscriber Information Yes - - Apply rules Per config 2 Authorize & Reserve Yes - - Apply rules Per config 3 Charge Yes - - Apply rules Per config 4 Subscriber Balances - Yes Yes Fail Per config 5 Subscriber Numbers - Yes - Fail Per config 6 Subscriber Update - Yes - Fail Per config 7 Voucher Redeem - Yes - Fail Per config 8 Subscriber Details - Yes - Fail Per config 9 Balance Transfer - Yes - Fail Per config

Table 3 – Message types and socket affinity



4 Message Scenarios & Interactions This section defines the message scenarios that will be implemented at Excelcom where a scenario involves one or more client/server interactions.

In each case, every client/server interaction involves exactly one client Request, followed by exactly one corresponding server Response.

For each scenario, the valid messages, valid message sequences, and valid responses are identified.

4.1 Basic Subscriber Query

The Subscriber Information Request is used to return basic subscriber information, which is required to facilitate the initial service interaction, before a specific service function (e.g. initiate call) is made.

4.1.1 REQUEST: Subscriber Information Request (& Response)

This interaction may be performed at any time, for any subscriber identified by MSISDN. Typically, this is used at the start of a voice call setup, as indicated in the following diagram.

Session

SCP PrepaidServer

Subscriber Information RequestSubscriber Information Request

NetworkElement

Call Start Request

...

Figure 2 – Subscriber Information Event Flow

In practice this interaction will be used at the start of Mobile Originated and Mobile Terminated Calls (and also USSD Roaming Calls). However, the server should not restrict the use of this function in any way.

The Subscriber Information Request will succeed if and only if the Subscriber is known to the billing server. The success of a Subscriber Information Request does not imply any reservation, or any authorisation to perform any specific call function.

The IN service will use the Subscriber Information Response parameters to determine which service features to offer to the subscriber, and to determine how to offer those features. In most cases, the service feature selected by the subscriber is to perform a voice call. The IN service will then return to the pre-paid server to perform call authorisation and balance reservation.

4.2 Quota Based Reservation (Charge at End)

This scenario is the only charging model that will be supported with this version of the protocol. The key aspects of this interaction scenario are:

• The client service makes an initial Authorize/Reservation Request

• The client service may make one or more subsequent Authorize/Reservation Requests

• The client service makes a Charge Request at the end of the call

The initial and subsequent Reservation Requests typically will not perform an account debit. The final payment debit is usually performed only at the end of the call.

Specifically, the two requests used in this scenario are as follows.



4.2.1 REQUEST: Authorize & Reserve Request (& Response)

This transaction allocates quota units, rates/re-rates the allocated quota units and performs a balance authorization check. If request is authorized, the system creates/updates session information, reserving the quota amount and units, and returns an authorization response.

Allocated units may be voice call duration in seconds, or single action charges (i.e. SMS). The same message may also be applied to data volumes, e.g. GPRS Data Kb, although this is not within the scope of this protocol version.

The specific types of units that may be allocated, and the exact interpretation, are covered in a subsequent section.

If a server response is not received to an EAX Authorise and Reserve request then the client may apply BFT rules to determine a default quota allocation.

4.2.2 REQUEST: Charge Request (& Response)

This transaction is sent on session termination. It rates and charges the used units, it frees the balance reserved amount, and closes/deletes the session record

The following diagram indicates the use of these functions. The message flow shows the Subscriber Information Request from the previous section, and then proceeds to the reservation and charging interactions.

Session

SCP PrepaidServer

Subscriber Information RequestSubscriber Information Response

Charge RequestCharge Response

NetworkElement

Call Start Request

Call Start Response

Call Termination Notification

Authorize&Reserve ReqestAuthorize&Reserve Response

Authorize&Reserve ReqestAuthorize&Reserve Response

Figure 3 – Authorize & Reserve + Charging Event Flow

In time, the flow of messages is indicated as follows. This diagram indicates the general use of these operations, and does not form a requirement by itself.



AuthorizeRequest

(Event #1)

Reserved Duration (#2)

AuthorizeRequest

(Event #2)

AuthorizeRequest

(Event #3)

Quota Duration (#2)Quota Duration (#1)

Duration = Charged Duration (#5)

ChargeRequest

(Event #5)

Quota Duration (#3) Quota Duration (#4)

AuthorizeRequest

(Event #4)

time

Reserved Durat ion (#1)

Reserved Duration (#3)Reserved Duration (#4)

Figure 4 – Authorize & Reserve + Charging Time Diagram

4.2.2.1 Isolated Charge and Retry support

It is possible for an EAX Charge request to arrive at the server without a previous EAX Authorise and Reserve to establish the Charging session. This is accepted by the server as an isolated charge and processed as a single request Charging session.

It is also possible for an EAX Charge request to be sent to the server more than once. This occurs when using a multiple connection policy where following the sending of the EAX Charge over one connection there is no response received by the client, or a communication error detected. The client may then retry sending the EAX Charge operation over another connection. On each attempt a retry count is incremented allowing the server to detect the duplicate requests and handle them appropriately. The server may respond to each EAX Charge request but only the first response received by the client on any connection will be used.

4.3 Additional Subscriber Interaction Requests

In addition to the basic subscriber query defined above there are some additional request messages which are required for the enhanced subscriber interaction functions.

All of the requests in this section may be used at any time for any known subscriber identified by MSISDN.

The use of these interaction messages does not necessarily imply that any reservation or other charging function has, or will be, performed. The success of this operation in no way guarantees that any subsequent charging function will be successful.

4.3.1 REQUEST: Subscriber Balances Request (& Response)

The Subscriber Balances Request returns a list of the subscriber payment channel balances, and their associated identifiers.

The identifiers are user allocated, and are arbitrary. Some identifiers may be pre-agreed to have specific interpretation. The use and interpretation of these identifiers and balances will be specific to the subscriber information service which is being implemented. These will be maintained in future versions of this document.

4.3.2 REQUEST: Subscriber Numbers Request (& Response)

The Subscriber Numbers Request returns a list of any special numbers associated with a subscriber identified by MSISDN.



Currently, the only accessible numbers are:

• Friends & Family Numbers

Future implementations may add additional options.

4.3.3 REQUEST: Subscriber Update Request (& Response)

The subscriber update request message is used to request an insert/update or delete a single parameter of a single subscriber identified by MSISDN.

Currently, the only accessible parameters are:

• Preferred Language

• Friends & Family Numbers

• PIN

• Initial Activation

Future implementations may add additional options.

4.3.4 REQUEST: Voucher Redeem Request (& Response)

This function is used to perform a voucher redemption request. The subscriber has been successfully identified, and the subscriber has provided us with a voucher number that appears superficially to be a valid voucher number (i.e. length is in acceptable range).

The IN service provides the voucher details to the pre-paid platform, to be passed to the replenishment function. The response indicates if the voucher has been successfully redeemed. In the case of failure, the nature of the failure is indicated.

4.3.5 REQUEST: Subscriber Details Request (& Response)

This function is used to fetch additional subscriber information which is not available through the real-time AMDOCS billing system. This request is intended to provide additional subscriber profile information which can be used to enhance IVR interaction.

4.3.6 REQUEST: Balance Transfer Request (& Response)

This function is used to request the transfer of funds within a subscriber's balance portfolio, or to an alternate recipient subscriber (consumer to consumer).



5 Request Parameters This section defines the parameters for all messages that are supported in this version of the protocol.

5.1 Common parameter values

This section defines various common parameters an d allowed values.

5.1.1 Subscriber Key Types Value Description/Meaning Notes 0 MSISDN 1 IMSI Reserved for future use

Table 4: Subscriber Key values

5.1.2 Unit Types Value Description/Meaning Notes 0 Not defined 1 Deci-seconds MO / MT Calls / GPRS sessions 2 Short Messages MO / MT SMS 3 USSD Messages Reserved for future use 4 Bytes of Data Reserved for future use

Table 5: Unit Type values

5.1.3 Language Types Value Description/Meaning Notes 0 Not defined System will take default 1 English 2 Bahasa

Table 6: Language Type values

5.1.4 Balance Types Value Description/Meaning Notes 0 Not defined 1 Seconds 2 Short Messages 3 Not used Reserved for future use 4 Not used Reserved for future use 5 Rupiah 6 BFT Balance granted via Billing Failure Treatment 7 Wallet Separate wallet balance 8 Not used Reserved for future use 9 Not used Reserved for future use 10 Loyalty Points Future

Table 7: Balance Type values



5.1.5 Subscriber Update Action Types Value Description/Meaning Notes 0 Not defined 1 Write Add (insert or append) items 2 Delete Delete or remove items 3 Overwrite Replace all (items in a list, etc) 4 Clear Delete all (items in a list, etc)

Table 8: Subscriber Update Action Type values

5.1.6 Subscriber Update Primary Key Types Value Description/Meaning Notes 0 Not defined 1 F&F Numbers • Update Friends and Family numbers 2 Language Change preferred language 3 PIN Change PIN 4 Initial Activation Starter pack activation for new SIM user

Table 9: Subscriber Update Primary Key Type values

5.1.7 Bearer Types Value Description/Meaning Notes 0 Not defined 1 Voice 2 Data/Fax 3 Other

Table 10: Bearer Type values



5.2 REQUEST: Subscriber Information Request (& Response)

This message is used to request basic subscriber information, typically at the start of a voice call.

5.2.1 Request Parameters

The following parameters are specified in the request.

Parameter Field Type Usage Description Service Key Integer Required A value which identifies the service being executed, MOC,

MTC, SMS-MO, SMS-MT, USSD-ROAMING. The actual values used will be agreed outside the scope of this document.

MSC Call ID Integer Future If available. Subscriber Key Char Array Required Normalised key that identifies the subscriber. Key Type Integer Required Identifiers MSISDN or IMSI subscriber key.

Table 11 – Subscriber Information Request Parameters

5.2.2 Response Parameters

The following parameters are specified in the response. If the response is not Success, then the subsequent parameters are not filled, and should be ignored.

Parameter Field Type Usage Description Response Status Integer Required One of:

• Success • Invalid Request (System Error) • Not Available (BE down, cannot handle) • Unknown Service Key • Unknown Subscriber

Preferred Language

Integer Required Subscriber preferred language, from an agreed enumeration (including not defined).

Subscriber Status Single Char Required One of ‘A’, ‘S’, ‘T’ – indicating the current subscriber status (Active, Suspended, Terminated). Note: “S” indicates a subscriber whose balances are all in grace period. Typically, this subscriber can receive, but not initiate calls. “T” indicates a terminated subscriber, who can access no regular calling functions.

Call Plan Char Array Required Name of the call plan to execute. This defines the service features that are offered to the subscriber. The valid options are “PREPAID” or “POSTPAID”.

Table 12 – Subscriber Information Response Parameters



5.3 REQUEST: Authorize & Reserve Request (& Response)

This message is used to request authorization and balance reservation in order to proceed with a chargeable service function. In this protocol version, this chargeable service is SMS-MO, SMS-MT or voice/data/fax calling, where data indicates a connection-based call over standard lines, which is charged on duration only.


This message is used for reserving SMS and connected call resources. Parameters are:

Parameter Field Type Usage Description Request Num Integer Required Sequence number of reservation. 1, 2, … Service Key Integer Required A value which identifies the service being executed, MOC,

MTC, SMS-MO, SMS-MT, USSD Roaming (Call Back) USSD Collect Call, USSD Collect Call – Roaming. The actual values used will be agreed outside the scope of this document.

MSC Call ID Integer Future If available. Subscriber Key Char Array Required Normalised key that identifies the subscriber. Key Type Integer Required Identifiers MSISDN or IMSI subscriber key. CNA Char Array Required The calling number, the originator of this call leg. In some

cases, this will be the MSISDN for billing. Normalised form.

DNA Char Array Required The dialled number, the terminator for this call leg. In some cases, this will be the MSISDN for billing. Normalised form.

Original Dialled Digits

Char Array Required The original dialled digits, from the IDP, before normalisation. NoA is not used for this purpose.

Originating Location Info

Char Array Optional The originating location information format depends on the Service Key (refer Table 14: Standard parameter usage for Authorise & Reserve and Charge requests)

Terminating Location Info

Char Array Optional The terminating location information format depends on the Service Key (refer Table 14: Standard parameter usage for Authorise & Reserve and Charge requests)

Bearer Type Integer Required Indicates bearer type, one of: • Voice • Data/Fax • Other (or not relevant)

Unit Type Integer Required An identifier indicating in the units of billable resource to be charged.

Request Retry Count

Integer Future use Must be set to 0 for all A&R requests.

Call Start Time Date Required The GMT epoch (seconds since 1970) at time SCP received the call (or SMS) initiate attempt.

Alternate Unit Type Integer Optional An identifier indicating an alternate unit type which may be accepted – or “Not Defined” if no alternate is applicable.

QoS Char Array Optional Negotiated QoS (GPRS only). APN Char Array Optional Access Point Name (GPRS only). User IP Address Char Array Optional User end-point IP Address (GPRS only)

Table 13 – Authorize & Reserve Request Parameters



5.3.1.1 Standard parameter usage for call cases Description Service

Key sub Key

(MSISDN) CNA DNA Originating

Location Info Terminating

Location Info Non-Roaming Voice Calls Mobile Originating Call from (A) non-roaming XL sub

MOC Calling Number (CNA)

Calling Number Destination Number

Originating Cell ID (MPLN)

<null>

Mobile Terminating Call to (B) non-roaming XL sub

MTC Destination Number (DNA)


<null>

Terminating Cell ID (MPLN network)

Roaming Voice Calls Mobile Originating Call from (A) out-roaming XL sub

MOC Roaming

Calling Number (CNA)


VLR ID (FMPLN)

<null>

Mobile Terminating Call to (B) out-roaming XL sub

MTC Roaming

Destination Number (DNA)


<null>

VLR ID (FMPLN)

USSD Roaming Voice Calls USSD Call Back Roaming from (A) out-roaming XL sub

USSD CB Calling Number (CNA)


VLR ID (MPLN or FMPLN)

<null>

USSD Collect Call from (A) XL sub to (B) out-roaming XL sub

USSD CC Roaming

Calling Number (CNA)

Calling Number (USSD B-party)

Destination Number

(USSD A-party)

VLR ID (MPLN or FMPLN)

<null>

USSD Non-Roaming Voice Calls USSD Collect Call from (A) XL sub to (B) non-roaming sub

USSD CC Calling Number (CNA)

Calling Number (USSD B-party)

Destination Number

(USSD A-party)

Originating Cell ID (MPLN)

<null>

Call Forwarding Voice Calls Call Forwarding from (A) XL sub

MOC Redirecting Number

(Original DNA)

Calling Number (Original CNA)

Destination Number

(As Forwarded)

<null> <null>

Non-Roaming SMS Mobile Originating SMS from (A) non-roaming XL sub

SMS-MO Originating Number (CNA)

Originating Number

Destination Number

Originating VMSC ID

(MPLN)

<null>

Mobile Terminating SMS to (B) non-roaming XL sub

SMS-MT Destination Number (DNA)

Originating Number (Short

Code)

Destination Number

<ASP name> (future use)

<null>

Roaming SMS Mobile Originating SMS from (A) out-roaming XL sub

SMS-MO Originating Number (CNA)

Originating Number

Destination Number

Originating VMSC ID

(FPLMN)

<null>*

Mobile Terminating SMS to (B) out-roaming XL sub

SMS-MT Destination Number (DNA)

Originating Number

(Short Code)

Destination Number

<ASP name> (future use)

<null>*

* If the VLR ID information is not available for roaming SMS-MT then the incoming SMS message can not be charged.

Table 14: Standard parameter usage for Authorise & Reserve and Charge requests




If the response is not Success, then the subsequent parameters are not filled, and should be ignored.


• Success • Invalid Request (System Error) • Not Available (BE down, cannot handle) • Unknown Service Key • Unknown Subscriber • Unknown Provider • Insufficient Balance • Feature Prohibited • Origin Prohibited (Future Option) • Balance Expired • Bypass Number

Reserved Units Integer Optional Number of units reserved. This is > 0 if the primary unit type was reserved. This will contain 0 if the alternate unit type was reserved.

Balance Type Integer Required Indicates what type of balance was used, may be different from the unit type reserved.

Previous Balance Integer Required Balance of the payment channel before this reservation is made. This is computed before these reserved units were deducted, but incorporates deductions for prior reservations.

Pre Call Balance Warning

Integer Future Indicates if a pre-call balance warning announcement should be played.

Alternate Reserved Units

Integer Optional. If the alternate unit type was used, then this field will contain the reserved units rather than the “Reserved Units Field”. Otherwise this field will contain 0. Only one of “Reserved Units” or “Alternate Reserved Units” may be non-zero.

Table 15 – Authorize & Reserve Response Parameters



5.4 REQUEST: Charge Request (& Response)



Parameter Field Type Usage Description Request Num Integer Required This is 1 more than the last Authorize/Reserve Request

number, or 1 if there was no prior Authorize/Reserve. Service Key Integer Required A value which identifies the service being executed, MOC,

MTC, SMS-MO, SMS-MT, USSD Roaming (Call Back) USSD Collect Call, USSD Collect Call – Roaming. The actual values used will be agreed outside the scope of this document.

MSC Call ID Integer Future If available. Subscriber Key Char Array Required Normalised key that identifies the subscriber. Key Type Integer Required Identifiers MSISDN or IMSI subscriber key. CNA Char Array Required The calling number, the originator of this call leg. In some

cases, this will be the MSISDN for billing. Normalised form.

DNA Char Array Required The dialled number, the terminator for this call leg. In some cases, this will be the MSISDN for billing. Normalised form.

Original Dialled Digits

Char Array Required The original dialled digits, from the IDP, before normalisation. NoA is not used for this purpose.

Originating Location Info

Char Array Optional The originating location information format depends on the Service Key (refer Table 14: Standard parameter usage for Authorise & Reserve and Charge requests)

Terminating Location Info

Char Array Optional The terminating location information format depends on the Service Key (refer Table 14: Standard parameter usage for Authorise & Reserve and Charge requests)

Bearer Type Integer Required Indicates bearer type, one of: • Voice • Data/Fax • Other (or not relevant)

Unit Type Integer Required An identifier indicating in the units of billable resource to be charged.

Request Retry count

Integer Required Set to 0 on first EAX Charge request sent for this Charging session. If an EAX Charge response is not received a retry of sending the EAX Charge request may take place on another connection and this value will be incremented for each subsequent send undertaken.

Call Start Time Date Required The GMT epoch (seconds since 1970) at time SCP received the call (or SMS) initiate attempt.

Total Units Integer Required The total number of units to be charged. QoS Char Array Optional Negotiated QoS (GPRS only). APN Char Array Optional Access Point Name (GPRS only). Alternate Unit Type Integer Optional An identifier indicating in the units of billable resource to

be charged, if there are two unit types to be charged – or Not Defined otherwise.

Alternate Total Units

Integer Optional The total number of units to be charged, if there are two unit types to be charged – or 0 otherwise.

User IP Address Char Array Optional User end-point IP Address (GPRS only)

Table 16 – Charge Request Parameters






• Success • Invalid Request (System Error) • Not Available (BE down, cannot handle)

Balance Type Integer Required An identifier indicating the type of balance that was debited.

Session Charge Integer Required The amount that was charged for this call (of charge type). Remaining Balance Integer Required Balance of the payment channel after the charge was

applied.

Table 17 – Charge Response Parameters



5.5 REQUEST: Subscriber Balances Request (& Response)


The following parameters are specified in the request. Note that this operation also returns subscriber date information.


MTC, SMS-MO, SMS-MT, USSD-ROAMING. The actual values used will be agreed outside the scope of this document. Note: For balances query, this will typically be a service key that identifies a USSD or IVR account management call.


Table 18 – Subscriber Balances Request Parameters


The following parameters are specified in the response. If the response is not Success, then the subsequent parameters are not filled, and should be ignored. Up to ten balances may be returned.

Note: All times are Unix epoch time, 0 if N/A.



Number of Balances

Integer Required The number of balances which the BE is returning to the client. Must be >= 1.

Account Expiry Date Optional The date at which the account did (or will) change from state “A” to state “S”.

Account Termination

Date Optional The date at which the account did (or will) change from state “S” to state “T”.

#1 Identifier Char Array Required The balance ID for the first balance. #1 Unit Type Integer Required The unit type of the first balance. #1 Value Integer Required The balance value of the first balance. #1 Active End Date Optional End of the active period for the first balance. #1 Grace End Date Optional End of the grace period for the first balance. … … … #10 Identifier Char Array Optional The balance ID for the tenth balance. #10 Unit Type Integer Optional The unit type of the tenth balance. #10 Value Integer Optional The balance value of the tenth balance. #10 Active End Date Optional End of the active period for the tenth balance. #10 Grace End Date Optional End of the grace period for the tenth balance.

Table 19 – Subscriber Balances Response Parameters



5.6 REQUEST: Subscriber Numbers Request (& Response)




MTC, SMS-MO, SMS-MT, USSD-ROAMING. The actual values used will be agreed outside the scope of this document. Note: For subscriber numbers query, this will typically be a service key that identifies a USSD or IVR account management call.


Table 20 – Subscriber Numbers Request Parameters


The following parameters are specified in the response. If the response is not Success, then the subsequent parameters are not filled, and should be ignored. Up to ten F&F numbers may be returned.

Parameter Field Type Description Response Status Integer Required One of:

• Success • Invalid Request (System Error) • Not Available (BE down, cannot handle) • Unknown Service Key • Unknown Subscriber • Not Applicable (subscriber not F&F)

Number of Free Changes Left

Integer Optional How many F&F number changes the subscriber may make free of charge. Possibly 0. Value of -1 means that the feature is not supported.

Number of Addresses

Integer Required The number of addresses which the BE is returning to the client. May be zero.

#1 F&F Number Char Array Optional The address value of the first address. Null string if not present.

… … … … #10 F&F Number Char Array Optional The address value of the tenth address. Null string if not

present.

Table 21 – Subscriber Numbers Response Parameters



5.7 REQUEST: Subscriber Update Request (& Response)



Parameter Field Type Description Service Key Integer Required A value which identifies the service being executed, MOC,

MTC, SMS-MO, SMS-MT, USSD-ROAMING. The actual values used will be agreed outside the scope of this document. Note: For subscriber update request, this will typically be a service key that identifies a USSD or IVR account management call.

MSC Call ID Integer Future If available. Subscriber Key Char Array Required Normalised key that identifies the subscriber. Key Type Integer Required Identifiers MSISDN or IMSI subscriber key. Update Type Integer Required Indicates either:

• Write (i.e. Merge/Insert/Append) • Delete (i.e. Delete/Subtract) • Overwrite (i.e. Replace) • Clear (i.e. Purge/Empty)

Update Key Integer Required The primary type of the data requested for update. Indicates update type, one of:

• Language • F&F number • Change PIN • Initial Activation

Number Of Values Integer Required Number of values to update, range 0..10. Not all values may be usable in all contexts. E.g. for language update, this value must be == 1. Value of 0 is valid only with Update Type == Clear. For PIN change transaction, number of values will be 2: item #1 will contain existing PIN and item #2 will contain new PIN

Secondary Key #1 Integer Optional Optional extended information about the first field to be updated, e.g. if this is a F&F number, then which F&F number is to be updated.

New Value #1 Char Array Optional First value to update. If the update type requires a string value, then this field is used to contain the new value for update. Ignored for delete. Integers are converted to using “%d” or equivalent.

... ... ... ... Secondary Key #10 Integer Optional Tenth secondary key. New Value #10 Char Array Optional Tenth value to update.

Table 22 – Subscriber Update Request Parameters






• Success • Invalid Request (System Error) • Not Available (BE down, cannot handle) • Unknown Service Key • Unknown Subscriber • Invalid Update Type • Invalid Update Key • Invalid Secondary Key • Invalid Value(s) • Change Not Permitted

Table 23 – Subscriber Update Response Parameters



5.8 REQUEST: Voucher Redeem Request (& Response)




MTC, SMS-MO, SMS-MT, USSD-ROAMING. The actual values used will be agreed outside the scope of this document. Note: For voucher redeem request, this will typically be a service key that identifies a USSD or IVR account management call.

MSC Call ID Integer Future If available. Subscriber Key Char Array Required Normalised key that identifies the subscriber. Key Type Integer Required Identifiers MSISDN or IMSI subscriber key. Voucher Number Char Array Required The number of the voucher requested for redeem. Voucher PIN Char Array Future Separate PIN number, if the voucher number and PIN are

distinct. Offer Code Integer Optional Specific customer requested offer code, or -1 if not

specified.

Table 24 – Voucher Redeem Request Parameters






• Success • Invalid Request (System Error) • Not Available (BE down, cannot handle) • Unknown Service Key • Unknown Subscriber • Invalid Subscriber State • Voucher Invalid • Voucher PIN Invalid • Voucher Disabled • Voucher Expired • Voucher Already Redeemed • Wrong denomination (or Voucher Incompatible) • Subscriber Redeem Blocked

Retries Before Blocked

Integer Optional Number of retries left before account will be blocked from redeeming. Specified if and only if (Response Status == Voucher Invalid).

Face Value Units Integer Future Indicates the units for the face value of the voucher – e.g. Rupiah.

Face Value Integer Future Indicates the face value of the voucher, e.g. 100,000 Rp. Offer Code Integer Optional The offer code which this voucher invoked, or -1 if no offer

code applies. Num Updated Balances

Integer Required How many balances were updated? Must be 1 .. 10.

#1 Identifier Char Array Required Balance ID for the first updated target balance. #1 Unit Type Integer Required Unit type of the first updated target balance. #1 Change Integer Required Change applied to first updated target balance. #1 New Value Integer Future New balance value of the first balance. #1 Active End Date Optional End of active period for the first balance. #1 Grace End Date Optional End of grace period for the first balance. … … … #10 Identifier Char Array Optional Balance ID for the tenth updated target balance. #10 Unit Type Integer Optional Unit type of the tenth updated target balance. #10 Change Integer Optional Change applied to tenth updated target balance. #10 New Value Integer Future New balance value of the tenth balance. #10 Active End Date Optional End of the active period for the tenth balance. #10 Grace End Date Optional End of the grace period for the tenth balance.

Table 25 – Voucher Redeem Response Parameters



5.9 REQUEST: Subscriber Details Request (& Response)

This message is used to request enhanced subscriber profile information, typically during the course of an IVR interaction, where these parameters are used to profile additional control over the interaction behavior.




MTC, SMS-MO, SMS-MT, USSD-ROAMING. The actual values used will be agreed outside the scope of this document.


Table 26 – Subscriber Details Request Parameters





External Platform Number

Integer Optional If the subscriber belongs to an external IN system, e.g. a Siemens legacy IN, then this indicates the platform number.If the subscriber is a local AMDOCS subscriber, then the value “0” is returned.

Voucher Redeem Blocked

Integer Optional Indicates if the subscriber is blocked for voucher redeem. Set to non-zero if blocked, set to zero if not blocked, or status unknown.

Voucher Redeem Retries

Integer Optional Indicates the number of retries permitted before the subscriber will be blocked for voucher redeem. Value > 0 if this value is known. Value = 0 if the subscriber is already blocked. Value of -1 means that the feature is not supported.

Table 27 – Subscriber Details Response Parameters



5.10 REQUEST: Balance Transfer Request (& Response)




MTC, SMS-MO, SMS-MT, USSD-ROAMING. The actual values used will be agreed outside the scope of this document. Note: For balance transfer request, this will typically be a service key that identifies a USSD or IVR account management call.

MSC Call ID Integer Future If available. Subscriber Key Char Array Required Normalised key that identifies the requesting subscriber. Key Type Integer Required Identifiers MSISDN or IMSI subscriber key. Target Key Char Array Required Target for balance transfer, may be same as subscriber

(e.g. Internal subscriber balance management). Target Key Type Integer Required Identifiers MSISDN or IMSI target key. Subscriber PIN Char Array Required Authorisation code Offer Code Integer Optional Optional offer code associated with transfer, or -1 if no

offer code applies. Transfer Amount Integer Required Requested amount of transfer.

Table 28 – Balance Transfer Request Parameters






• Success • Invalid Request (System Error) • Not Available (BE down, cannot handle) • Unknown Service Key • Unknown Subscriber • Unauthorised Subscriber • Insufficient Subscriber Balance • Invalid Subscriber State • Subscriber PIN Invalid • Unknown Target Subscriber • Invalid Target Subscriber State • Wrong denomination (or Balances Incompatible) • Invalid Offer Code

Transaction Code Char Array Optional Confirmation transaction code, may be empty. Subscriber Balance Type

Integer Required Indicates what balance type of subscriber balance was used for the source of the transfer.

New Subscriber Balance

Integer Required Indicates the updated balance of the subscriber who was the source of the transfer.

Num Updated Target Balances

Integer Required How many target balances were updated? Must be 1 .. 10.

#1 Identifier Char Array Required Balance ID for the first updated target balance. #1 Unit Type Integer Required Unit type of the first updated target balance. #1 Change Integer Required Change applied to first updated target balance. #1 New Value Integer Future New balance value of the first balance. #1 Active End Date Optional End of active period for the first balance. #1 Grace End Date Optional End of grace period for the first balance. … … … #10 Identifier Char Array Optional Balance ID for the tenth updated target balance. #10 Unit Type Integer Optional Unit type of the tenth updated target balance. #10 Change Integer Optional Change applied to tenth updated target balance. #10 New Value Integer Future New balance value of the tenth balance. #10 Active End Date Optional End of the active period for the tenth balance. #10 Grace End Date Optional End of the grace period for the tenth balance. PIN Retries Remaining

Integer Future Number of PIN retries remaining, present IFF Status == Subscriber PIN Invalid

Recharge ID Integer Optional Reciept number for transaction

Table 29 – Balance Transfer Response Parameters



6 Appendix A: C-Language Bindings This section defines the C-Language constant and structure definitions that provide the reference implementation of the messages defined in the previous sections.

The on-the-wire format is determined by the following rules:

• All integer values will be network byte order.

• Character arrays that are less than the indicated field length will be null terminated.

• Trailing spaces are not significant, unless indicated otherwise.

• All 32 bit integers will be aligned to 4-byte boundaries.

• All 16 bit integers will be aligned to 2-byte boundaries.

• All character arrays will be aligned to 4-byte boundaries.

• Single characters will not be aligned.

• All dates are in 4-byte Unix epoch time, or 0 if not defined.

6.1 Message Type Identifiers

The following definitions define the message types used for the request/response. The message type for the response matches the message type for the request.

/*

******************************************************************************

* Message Request/Response type constants.

******************************************************************************

*/

typedef enum {

eaxMessageTypeNullOp = 0,

eaxMessageTypeSubscriberInformation,

eaxMessageTypeAuthorizeReserve,

eaxMessageTypeCharge,

eaxMessageTypeSubscriberBalances,

eaxMessageTypeSubscriberNumbers,

eaxMessageTypeSubscriberUpdate,

eaxMessageTypeVoucherRedeem,

eaxMessageTypeSubscriberDetails,

eaxMessageTypeBalanceTransfer

} eaxMessageType_t;

6.2 Message Header File

The associated header file “eaxProtocol.h” defines the remainder of the structures and constants used in a “C” language reference implementation of the protocol.

This header file is available as a separate attachment. To ensure that you have the correct version of the header file, check for the following line.

/* Current protocol version, as defined in protocol spec 2.1.0j */

#define EAX_CURRENT_PROTOCOL 210



7 Appendix B: Request Number Validation

7.1 Authorize/Reserve Request Number

The first reservation/charge on a session ID will be made with request number 1. Subsequent reservation/charge requests will increment the request number. When a charge request is received, the session context is cleared, and that session is available for re-use.

Assume that “N” is the request number last received reservation for this session ID. The following table indicates the possible cases that may occur when an authorize/reservation request is received for a session ID. In many cases, an alarm log should be generated for follow-up, since an application error is indicated.

No Previous Reservation

(i.e. N = 0)

Previous Reservation

(i.e. N >= 1) Reservation

Request Num

M <= 0

Never valid.

Return invalidRequest.

Generate alarm.

Reservation Request Num

The session is initiated. Correct client behaviour.

May occur if client is re-started.

Not valid in this protocol version. Return invalidRequest. Generate alarm.

M = 1


1 < M < N

Never valid. Return invalidRequest. Generate alarm.



1 < M = N


This indicates a repeat of a subsequent reservation (e.g. client resend after timeout).

Not valid in this protocol version. Return invalidRequest. Generate alarm.


1 < M = N+1


This is a subsequent reservation.

Correct client behaviour.


M > N+1

Never valid.

Return invalidRequest.

Generate alarm.

Table 30 – Handling of Authorize/Reserve Request Numbers



7.2 Charge Request Number

The following table indicates the possible scenarios for request number on Charge Request. Note again that under this protocol version, it is not valid to send a Charge Request for a Session ID without a preceding Authorize/Reserve Request.

Note also that all Authorize/Reserve Requests will (under normal circumstances) be succeeded by a Charge Request. If the subscriber hangs up during the call set-up procedure, then the corresponding Charge Request will have a zero length call duration.

No Previous Reservation

(i.e. N = 0)

Previous Reservation

(i.e. N >= 1) Charge Request Num

M <= 0

Never valid. Return invalidRequest.

Generate alarm.

Charge Request Num

M = 1

Not valid in this protocol version. Return invalidRequest.

Generate alarm.

Charge Request Num

1 < M < N



Charge Request Num

1 < M = N



Charge Request Num

1 < M = N+1


This is a subsequent reservation.

Correct client behaviour.

Charge Request Num

M > N+1

Never valid. Return invalidRequest.

Generate alarm.

Table 31 – Handling of Charge Request Numbers



8 Appendix C: Excelcom Parameter Notes This protocol is not specific to any particular project, however the Excelcom project will be the first installation site for this joint protocol. Hence, the following notes related to the Excelcom project are provided here for reference. They do not form a part of the base project definition.

8.1 Required Fields

The following fields are marked as optional in the core document. However, in the Excelcom implementation, the following subset of optional fields will in fact be required in all or some cases, as noted.

8.1.1 Authorize Reserve Request

The following AR request parameter notes apply for the Excelcom project.

• Originating Cell ID – Required for MO calls originating within Excelcom network

• Terminating Cell ID – Required for MT calls terminating within Excelcom network

8.1.2 Charge Request

The following CH request parameter notes apply for the Excelcom project.

• Originating Cell ID – Required for MO calls originating within Excelcom network

• Terminating Cell ID – Required for MT calls terminating within Excelcom network

8.2 Normalisation

Note that the following fields will be sent in normalized form when they are specified:

• Subscriber Key (Key Type = MSISDN)

• Calling Number Address (CNA)

• Destination Number Address (DNA)

The Original Dialed Digits field will always be specified in the exact same form that it was received from the network. The NoA for the Original Dialed Digits will not be passed.

8.3 Location Info

The Location Info fields in EAX will contain either:

• Cell ID, or

• Network element address such as the VLR ID, VMSC, etc.

The type of Location Info present in a message depends upon the value of the Service Key as defined in the EAX Authorise and Reserve, and the EAX Charge requests.

If the Location Info is processed in the absence of the Service Key then these two field types can be differentiated as follows:

• Cell ID format contains one or more “.” (period) characters

• Network element address contains no “.” (period) characters

8.3.1 Cell ID encoding

The CAMEL Cell-Id value consists of four separate fields, which may be of variable length.

• Country Code (3 digits)



• Network Code (2-3 digits)

• Location Area Code (integer)

• Cell Identity (optional, integer)

The protocol field is a text field, which consists of these values with a “.” separator. If the cell identity is present, the EAX protocol encoding for these values will be in the form:

<country>.<network>.<location>.<cell>

…and if the cell identity is not present, it will be in the form: <country>.<network>.<location>

8.3.2 Network element address encoding

The Network element address is in the international E.164 numbering plan format.

8.4 Call Plan Names

The only two valid call plan names to be returned from a Subscriber Information Request are as follows.

• “PREPAID” – Standard call flow.

• “POSTPAID” – As for pre-paid, however low balance warning does not apply.

8.5 Service Keys

The actual service keys to be used for the Excelcom project will be agreed in conjunction with Excelcom, eSG, AMDOCS, and Siemens. They are specified in the Excelcom SRS.

8.6 Subscriber Update

For subscriber updates on the Excelcom project, the following options are supported:

8.6.1 Option 1: Language update

• Primary Key = Language

• Update Type = Write or Overwrite

• Number of Values = 1

• Secondary Key #1 = 0

• New Value #1 = “1” (English) or “2” (Bahasa)

8.6.2 Option 2: F&F numbers update

• Primary Key = F&F

• Update Type = Overwrite

• Number of Values = 1 .. 10

• Secondary Keys #1 - #10 = 0

• New Values #1 - #10 = “<Normalized F&F Number #1 - #10>”

8.6.3 Option 3: PIN update

• Primary Key = PIN

• Update Type = Overwrite




• Secondary Keys #1 - #2 = 0

• New Values #1 = Existing PIN

• New Values #2 = New PIN

8.6.4 Option 4: Initial Activation

• Primary Key = Initial Activation

• Update Type = Write


* * * E N D O F D O C U M E N T * * *


eax protocol

Technology

amdocs 2004v2

initial amdocs feedback

0d061102more amdocs

9c101002more amdocs

document approvals

qpreface document

0m280704reformatted

eax charge requests