EAX Protocol

EA X
Eservglobal / Amdocs eXtensions

EAX Protocol Specification
Version 2.1.0q

eServGlobal/Amdocs


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

Page 2 of 43

eServGlobal/Amdocs


V2.1.0q

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

PW

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
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.

PW

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.
2.1.0q

3/11/04

BFT files to contain EAX Charge requests only.

PW

Support for EAX Charge retry count.
Support for Connection quiesce indication.
2.1.0r

10/05/06

Update session ID to be in the range of 230 Ids

NL

See CTS 25395

6 December 2004


Page 3 of 43

eServGlobal/Amdocs

6 December 2004



V2.1.0q

Page 4 of 43

eServGlobal/Amdocs


V2.1.0q

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
6 December 2004


Page 5 of 43

eServGlobal/Amdocs


V2.1.0q

5.3
REQUEST: Authorize & Reserve Request (& Response)............................................... 24
5.4
REQUEST: Charge Request (& Response).................................................................... 27
5.5
REQUEST: Subscriber Balances Request (& Response)............................................... 29
5.6
REQUEST: Subscriber Numbers Request (& Response)............................................... 30
5.7
REQUEST: Subscriber Update Request (& Response).................................................. 31
5.8
REQUEST: Voucher Redeem Request (& Response).................................................... 33
5.9
REQUEST: Subscriber Details Request (& Response) .................................................. 35
5.10
REQUEST: Balance Transfer Request (& Response)................................................. 36
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

6 December 2004


Page 6 of 43

eServGlobal/Amdocs


1

Introduction

1.1

V2.1.0q

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 timeto-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 Cstruct 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.

6 December 2004


Page 7 of 43

eServGlobal/Amdocs

1.3


V2.1.0q

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

Billing
Billing
Billing
EAX
EAX
EAX
EAX
EAX
EAX
Server
EAX Server
EAX Server
EAX
Server
Server
Server
“A”
Server “B”
Server “C”
Server
“A”
“B”
“C”
“A”
“B”
“C”

Real
Time
Billing

OSA-like
Charging
Operations

Service
Control
Point

Primary
With
Failover

Load
Balancing

OSA-like
Account
Operations

EAX Client
EAX Client
EAX Client
SCP
SCP
SCP
Voice USSD SMS

Data

Network
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.

6 December 2004


Page 8 of 43

eServGlobal/Amdocs

2


V2.1.0q

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)


IP Address A2 …


IP Address A3 …

Socket B - Destination 1

IP Address B1 …


IP Address B2 …


IP Address B3 …

Socket C, etc.

IP Address C1 … etc

Table 1 – Socket types to Server address configuration

6 December 2004


Page 9 of 43

eServGlobal/Amdocs

2.2


V2.1.0q

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 rehome 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.

6 December 2004


Page 10 of 43

eServGlobal/Amdocs


2.2.2

Multiple connection policy

2.2.2.1

V2.1.0q

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.
•

6 December 2004

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


Page 11 of 43

eServGlobal/Amdocs


V2.1.0q

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

6 December 2004


Page 12 of 43

eServGlobal/Amdocs


V2.1.0q

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

6 December 2004


Page 13 of 43

eServGlobal/Amdocs

3


V2.1.0q

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:
•
•

3.2

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.

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”.

6 December 2004


Page 14 of 43

eServGlobal/Amdocs

3.3


V2.1.0q

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

Usage

Protocol Version
Message Length
Message Type
Time-Stamp

Agreed value. (Zero is shutdown indicator)
Number of bytes in the message, excluding this header.
The request type number, as shown in Table 3
The GMT epoch (seconds since 1970) at time of message send. Used for message
time-out.
A unique identifier for the requesting SCP, determined solely by the SCP. Used for
uniqueness only, not for identifying the originating SCP.
A unique identifier for each outstanding request.

SCP ID
Session ID

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.

6 December 2004


Page 15 of 43

eServGlobal/Amdocs

3.3.4


V2.1.0q

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
0
1
2
3
4
5
6
7
8
9

Request/Response PDU type
Null Operation (Ignore)
Subscriber Information
Authorize & Reserve
Charge
Subscriber Balances
Subscriber Numbers
Subscriber Update
Voucher Redeem
Subscriber Details
Balance Transfer

Socket A
Yes
Yes
Yes
Yes
-

Socket B
Yes
Yes
Yes
Yes
Yes
Yes
Yes

Socket C
Yes
Yes
-

BFT?

CDR?

Apply rules
Apply rules
Apply rules
Fail
Fail
Fail
Fail
Fail
Fail

Per config
Per config
Per config
Per config
Per config
Per config
Per config
Per config
Per config
Per config

Table 3 – Message types and socket affinity

6 December 2004


Page 16 of 43

eServGlobal/Amdocs

4


V2.1.0q

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.

Network
Element

Prepaid
Server

SCP

Call Start Request

Subscriber Information Request

Session

...

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.

6 December 2004


Page 17 of 43

eServGlobal/Amdocs

4.2.1


V2.1.0q

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.

Network
Element

Prepaid
Server

SCP

Call Start Request

Call Start Response

Subscriber Information Response
Authorize&Reserve Reqest
Authorize&Reserve Response

Session
Authorize&Reserve Reqest
Authorize&Reserve Response
Call Termination Notification

Charge Request
Charge 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.

6 December 2004


Page 18 of 43

eServGlobal/Amdocs


V2.1.0q

Duration = Charged Duration (#5)
Reserved Duration (#4)
Quota Duration (#1)

Quota Duration (#2)

Quota Duration (#3)

Quota Duration (#4)

time
Authorize
Request
(Event #1)

Authorize
Request
(Event #2)

Authorize
Request
(Event #3)

Authorize
Request
(Event #4)

Charge
Request
(Event #5)

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.

6 December 2004


Page 19 of 43

eServGlobal/Amdocs


V2.1.0q

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).

6 December 2004


Page 20 of 43

eServGlobal/Amdocs

5


V2.1.0q

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
1

MSISDN
IMSI

Reserved for future use

Table 4: Subscriber Key values

5.1.2

Unit Types
Value

Description/Meaning

0

Not defined

1
2
3
4

Deci-seconds
Short Messages
USSD Messages
Bytes of Data

Notes
MO / MT Calls / GPRS sessions
MO / MT SMS

Table 5: Unit Type values

5.1.3

Language Types
Value

Description/Meaning

Notes

0
1
2

Not defined
English
Bahasa

System will take default

Table 6: Language Type values

5.1.4

Balance Types
Value

Description/Meaning

0
1
2
3
4
5
6
7
8
9
10

Not defined
Seconds
Short Messages
Not used
Not used
Rupiah
BFT
Wallet
Not used
Not used
Loyalty Points

Notes

Balance granted via Billing Failure Treatment
Separate wallet balance
Future

Table 7: Balance Type values

6 December 2004


Page 21 of 43

eServGlobal/Amdocs

5.1.5


V2.1.0q

Subscriber Update Action Types
Value

Description/Meaning

Notes

0
1
2
3
4

Not defined
Write
Delete
Overwrite
Clear

Add (insert or append) items
Delete or remove items
Replace all (items in a list, etc)
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

0
1

Not defined
F&F Numbers

2
3
4

Language
PIN
Initial Activation

Notes
•
Update Friends and Family numbers
Change preferred language
Change PIN
Starter pack activation for new SIM user

Table 9: Subscriber Update Primary Key Type values

5.1.7

Bearer Types
Value
0
1
2
3

Description/Meaning
Not defined
Voice
Data/Fax
Other

Notes

Table 10: Bearer Type values

6 December 2004


Page 22 of 43

eServGlobal/Amdocs

5.2


V2.1.0q

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

MSC Call ID
Subscriber Key
Key Type

Integer
Char Array
Integer

Future
Required
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.
If available.
Normalised key that identifies the subscriber.
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:
•

Required

Single Char

Required

Call Plan

Char Array

Required

Not Available (BE down, cannot handle)

•
Integer

Invalid Request (System Error)

•

Preferred
Language
Subscriber Status

Success

•

Unknown Service Key

•
Unknown Subscriber
Subscriber preferred language, from an agreed
enumeration (including not defined).
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.
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

6 December 2004


Page 23 of 43

eServGlobal/Amdocs

5.3


V2.1.0q

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, SMSMT or voice/data/fax calling, where data indicates a connection-based call over standard lines,
which is charged on duration only.

5.3.1

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

Parameter

Field Type

Usage

Description

Request Num
Service Key

Integer
Integer

Required
Required

MSC Call ID
Subscriber Key
Key Type
CNA

Integer
Char Array
Integer
Char Array

Future
Required
Required
Required

DNA

Char Array

Required

Original Dialled
Digits
Originating
Location Info

Char Array

Required

Sequence number of reservation. 1, 2, …
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.
If available.
The calling number, the originator of this call leg. In some
cases, this will be the MSISDN for billing. Normalised
form.
The dialled number, the terminator for this call leg. In
some cases, this will be the MSISDN for billing.
Normalised form.
The original dialled digits, from the IDP, before
normalisation. NoA is not used for this purpose.

Char Array

Optional

Terminating
Location Info

Char Array

Optional

Bearer Type

Integer

Required

The originating location information format depends on the
Service Key (refer Table 14: Standard parameter usage
for Authorise & Reserve and Charge requests)
The terminating location information format depends on
the Service Key (refer Table 14: Standard parameter
usage for Authorise & Reserve and Charge requests)
Indicates bearer type, one of:
•
•

Unit Type

Integer

Required

Request Retry
Count
Call Start Time

Integer

Future use

Date

Required

Alternate Unit Type

Integer

Optional

QoS
APN
User IP Address

Char Array
Char Array
Char Array

Optional
Optional
Optional

Voice
Data/Fax

•
Other (or not relevant)
An identifier indicating in the units of billable resource to
be charged.
Must be set to 0 for all A&R requests.
The GMT epoch (seconds since 1970) at time SCP
received the call (or SMS) initiate attempt.
An identifier indicating an alternate unit type which may be
accepted – or “Not Defined” if no alternate is applicable.
Negotiated QoS (GPRS only).
Access Point Name (GPRS only).
User end-point IP Address (GPRS only)

Table 13 – Authorize & Reserve Request Parameters

6 December 2004


Page 24 of 43

eServGlobal/Amdocs

5.3.1.1


V2.1.0q

Standard parameter usage for call cases

Description

Service
Key
Non-Roaming Voice Calls

sub Key
(MSISDN)

CNA

DNA

Originating
Location Info

Terminating
Location Info

MOC

Calling Number
(CNA)

Calling Number

Destination
Number

Originating Cell ID
(MPLN)

<null>

MTC

Destination
Number (DNA)

Calling Number

Destination
Number

<null>

Terminating Cell
ID (MPLN
network)

Mobile Originating Call
MOC
from (A) out-roaming
Roaming
XL sub
Mobile Terminating Call
MTC
to (B) out-roaming XL
Roaming
sub
USSD Roaming Voice Calls

Calling Number
(CNA)

Calling Number

Destination
Number

VLR ID
(FMPLN)

<null>

Destination
Number (DNA)

Calling Number

Destination
Number

<null>

VLR ID
(FMPLN)

USSD Call Back
USSD CB
Roaming from (A) outroaming XL sub
USSD Collect Call from USSD CC
(A) XL sub to (B) outRoaming
roaming XL sub
USSD Non-Roaming Voice Calls

Calling Number
(CNA)

Calling Number

Destination
Number

VLR ID
(MPLN or FMPLN)

<null>

Calling Number
(CNA)

Calling Number
(USSD B-party)

Destination
Number
(USSD A-party)

VLR ID
(MPLN or FMPLN)

<null>

USSD Collect Call from USSD CC
(A) XL sub to (B) nonroaming sub
Call Forwarding Voice Calls

Calling Number
(CNA)

Calling Number
(USSD B-party)

Destination
Number
(USSD A-party)

Originating Cell ID
(MPLN)

<null>

Call Forwarding from
(A) XL sub

MOC

Redirecting
Number
(Original DNA)

Calling Number
(Original CNA)

Destination
Number
(As Forwarded)

<null>

<null>

Mobile Originating SMS
from (A) non-roaming
XL sub
Mobile Terminating
SMS to (B) nonroaming XL sub
Roaming SMS

SMS-MO

Originating
Number (CNA)

Originating
Number

Destination
Number

<null>

SMS-MT

Destination
Number (DNA)

Originating
Number (Short
Code)

Destination
Number

Originating VMSC
ID
(MPLN)
<ASP name>
(future use)

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

SMS-MO

Originating
Number (CNA)

Originating
Number

Destination
Number

<null>*

SMS-MT

Destination
Number (DNA)

Originating
Number
(Short Code)

Destination
Number

Originating VMSC
ID
(FPLMN)
<ASP name>
(future use)

Mobile Originating Call
from (A) non-roaming
XL sub
Mobile Terminating Call
to (B) non-roaming XL
sub
Roaming Voice Calls

Non-Roaming SMS

<null>

<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

6 December 2004


Page 25 of 43

eServGlobal/Amdocs

5.3.2


V2.1.0q

Response Parameters
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:
•

Required

Pre Call Balance
Warning
Alternate Reserved
Units

Integer

Future

Integer

Optional.

Origin Prohibited (Future Option)

•

Integer

Feature Prohibited

•

Previous Balance

Insufficient Balance

•

Required

Unknown Provider

•

Integer

Unknown Subscriber

•

Balance Type

Unknown Service Key

•

Optional


•

Integer


•

Reserved Units

Success

•

Balance Expired

•
Bypass Number
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.
Indicates what type of balance was used, may be different
from the unit type reserved.
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.
Indicates if a pre-call balance warning announcement
should be played.
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

6 December 2004


Page 26 of 43

eServGlobal/Amdocs


5.4

REQUEST: Charge Request (& Response)

5.4.1

V2.1.0q

Request Parameters

Parameter

Field Type

Usage

Description

Request Num

Integer

Required

Service Key

Integer

Required

MSC Call ID
Subscriber Key
Key Type
CNA

Integer
Char Array
Integer
Char Array

Future
Required
Required
Required

DNA

Char Array

Required

Original Dialled
Digits
Originating
Location Info

Char Array

Required

This is 1 more than the last Authorize/Reserve Request
number, or 1 if there was no prior Authorize/Reserve.
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.
If available.
The calling number, the originator of this call leg. In some
cases, this will be the MSISDN for billing. Normalised
form.
The dialled number, the terminator for this call leg. In
some cases, this will be the MSISDN for billing.
Normalised form.
The original dialled digits, from the IDP, before
normalisation. NoA is not used for this purpose.

Char Array

Optional

Terminating
Location Info

Char Array

Optional

Bearer Type

Integer

Required

The originating location information format depends on the
Service Key (refer Table 14: Standard parameter usage
for Authorise & Reserve and Charge requests)
The terminating location information format depends on
the Service Key (refer Table 14: Standard parameter
usage for Authorise & Reserve and Charge requests)
Indicates bearer type, one of:
•
•

Unit Type

Integer

Required

Request Retry
count

Integer

Required

Call Start Time

Date

Required

Total Units
QoS
APN
Alternate Unit Type

Integer
Char Array
Char Array
Integer

Required
Optional
Optional
Optional

Alternate Total
Units
User IP Address

Integer

Optional

Char Array

Optional

Voice
Data/Fax

•
Other (or not relevant)
be charged.
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.
The GMT epoch (seconds since 1970) at time SCP
received the call (or SMS) initiate attempt.
The total number of units to be charged.
Negotiated QoS (GPRS only).
Access Point Name (GPRS only).
be charged, if there are two unit types to be charged – or
Not Defined otherwise.
The total number of units to be charged, if there are two
unit types to be charged – or 0 otherwise.
User end-point IP Address (GPRS only)

Table 16 – Charge Request Parameters

6 December 2004


Page 27 of 43

eServGlobal/Amdocs

5.4.2


V2.1.0q

Response Parameters

Parameter

Field Type

Usage

Description

Response Status

Integer

Required

One of:
•

Balance Type

Integer

Required

Session Charge
Remaining Balance

Integer
Integer

Required
Required

Success

•


•
An identifier indicating the type of balance that was
debited.
The amount that was charged for this call (of charge type).
Balance of the payment channel after the charge was
applied.

Table 17 – Charge Response Parameters

6 December 2004


Page 28 of 43

eServGlobal/Amdocs


5.5

REQUEST: Subscriber Balances Request (& Response)

5.5.1

V2.1.0q

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

Parameter

Field Type

Usage

Description

Service Key

Integer

Required

MSC Call ID
Subscriber Key
Key Type

Integer
Char Array
Integer

Future
Required
Required

document.
Note: For balances query, this will typically be a service
key that identifies a USSD or IVR account management
call.
If available.

Table 18 – Subscriber Balances Request Parameters

5.5.2

Response Parameters
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.

Parameter

Field Type

Usage

Description

Response Status

Integer

Required

One of:
•
•

Required

Date

Optional

Account
Termination
#1 Identifier
#1 Unit Type
#1 Value
#1 Active End
#1 Grace End
…
#10 Identifier
#10 Unit Type
#10 Value
#10 Active End
#10 Grace End

Date

Optional

Char Array
Integer
Integer
Date
Date
…
Char Array
Integer
Integer
Date
Date

Required
Required
Required
Optional
Optional
Optional
Optional
Optional
Optional
Optional


•
Integer


•

Number of
Balances
Account Expiry

Success

Unknown Service Key

•
Unknown Subscriber
The number of balances which the BE is returning to the
client. Must be >= 1.
The date at which the account did (or will) change from
state “A” to state “S”.
The date at which the account did (or will) change from
state “S” to state “T”.
The balance ID for the first balance.
The unit type of the first balance.
The balance value of the first balance.
End of the active period for the first balance.
End of the grace period for the first balance.
…
The balance ID for the tenth balance.
The unit type of the tenth balance.
The balance value of the tenth balance.
End of the active period for the tenth balance.
End of the grace period for the tenth balance.

Table 19 – Subscriber Balances Response Parameters

6 December 2004


Page 29 of 43

eServGlobal/Amdocs


5.6

REQUEST: Subscriber Numbers Request (& Response)

5.6.1

V2.1.0q

Request Parameters

Parameter

Field Type

Usage

Description

Service Key

Integer

Required

MSC Call ID
Subscriber Key
Key Type

Integer
Char Array
Integer

Future
Required
Required

document.
Note: For subscriber numbers query, this will typically be a
service key that identifies a USSD or IVR account
management call.
If available.

Table 20 – Subscriber Numbers Request Parameters

5.6.2

Response Parameters
subsequent parameters are not filled, and should be ignored. Up to ten F&F numbers may be
returned.

Parameter

Field Type

Response Status

Integer

Description
Required

One of:
•

Number of
Addresses
#1 F&F Number

Integer

Required

Char Array

Optional

…
#10 F&F Number

…
Char Array

…
Optional

Unknown Service Key

•
Optional


•

Integer


•

Number of Free
Changes Left

Success

•

Unknown Subscriber

•
Not Applicable (subscriber not F&F)
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.
The number of addresses which the BE is returning to the
client. May be zero.
The address value of the first address. Null string if not
present.
…
The address value of the tenth address. Null string if not
present.

Table 21 – Subscriber Numbers Response Parameters

6 December 2004


Page 30 of 43

eServGlobal/Amdocs


5.7

REQUEST: Subscriber Update Request (& Response)

5.7.1

V2.1.0q

Request Parameters

Parameter

Field Type

Description

Service Key

Integer

Required

MSC Call ID
Subscriber Key
Key Type
Update Type

Integer
Char Array
Integer
Integer

Future
Required
Required
Required

document.
Note: For subscriber update request, this will typically be a
management call.
If available.
Indicates either:
•
•

Integer

Required

Delete (i.e. Delete/Subtract)

•
Update Key

Write (i.e. Merge/Insert/Append)
Overwrite (i.e. Replace)

•
Clear (i.e. Purge/Empty)
The primary type of the data requested for update.
Indicates update type, one of:
•
•

Required

Secondary Key #1

Integer

Optional

New Value #1

Char Array

Optional

...
...
Secondary Key #10 Integer
New Value #10
Char Array

...
Optional
Optional

Change PIN

•
Integer

F&F number

•
Number Of Values

Language

Initial Activation

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
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.
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.
...
Tenth secondary key.
Tenth value to update.

Table 22 – Subscriber Update Request Parameters

6 December 2004


Page 31 of 43

eServGlobal/Amdocs

5.7.2


V2.1.0q

Response Parameters

Parameter

Field Type

Response Status

Integer

Description
Required

One of:
•

Success

•


•


•

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

6 December 2004


Page 32 of 43

eServGlobal/Amdocs


5.8

REQUEST: Voucher Redeem Request (& Response)

5.8.1

V2.1.0q

Request Parameters

Parameter

Field Type

Description

Service Key

Integer

Required

MSC Call ID
Subscriber Key
Key Type
Voucher Number
Voucher PIN

Integer
Char Array
Integer
Char Array
Char Array

Future
Required
Required
Required
Future

Offer Code

Integer

Optional

document.
Note: For voucher redeem request, this will typically be a
management call.
If available.
The number of the voucher requested for redeem.
Separate PIN number, if the voucher number and PIN are
distinct.
Specific customer requested offer code, or -1 if not
specified.

Table 24 – Voucher Redeem Request Parameters

6 December 2004


Page 33 of 43

eServGlobal/Amdocs

5.8.2


V2.1.0q

Response Parameters

Parameter

Field Type

Response Status

Integer

Description
Required

One of:
•

Integer

Required

Char Array
Integer
Integer
Integer
Date
Date
…
Char Array
Integer
Integer
Integer
Date
Date

Required
Required
Required
Future
Optional
Optional
Optional
Optional
Optional
Future
Optional
Optional

Voucher Already Redeemed

•

Num Updated
Balances
#1 Identifier
#1 Unit Type
#1 Change
#1 New Value
#1 Active End
#1 Grace End
…
#10 Identifier
#10 Unit Type
#10 Change
#10 New Value
#10 Active End
#10 Grace End

Voucher Expired

•

Future
Optional

Voucher Disabled

•

Integer
Integer

Voucher PIN Invalid

•

Face Value
Offer Code

Voucher Invalid

•

Future

Invalid Subscriber State

•

Integer

Unknown Subscriber

•

Face Value Units

Unknown Service Key

•

Optional


•

Integer


•

Retries Before
Blocked

Success

•

Wrong denomination (or Voucher Incompatible)

•
Subscriber Redeem Blocked
Number of retries left before account will be blocked from
redeeming. Specified if and only if (Response Status ==
Voucher Invalid).
Indicates the units for the face value of the voucher – e.g.
Rupiah.
Indicates the face value of the voucher, e.g. 100,000 Rp.
The offer code which this voucher invoked, or -1 if no offer
code applies.
How many balances were updated? Must be 1 .. 10.
Balance ID for the first updated target balance.
Unit type of the first updated target balance.
Change applied to first updated target balance.
New balance value of the first balance.
End of active period for the first balance.
End of grace period for the first balance.
…
Balance ID for the tenth updated target balance.
Unit type of the tenth updated target balance.
Change applied to tenth updated target balance.
New balance value of the tenth balance.

Table 25 – Voucher Redeem Response Parameters

6 December 2004


Page 34 of 43

eServGlobal/Amdocs

5.9


V2.1.0q

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.

5.9.1

Request Parameters

Parameter

Field Type

Usage

Description

Service Key

Integer

Required

MSC Call ID
Subscriber Key
Key Type

Integer
Char Array
Integer

Future
Required
Required

document.
If available.

Table 26 – Subscriber Details Request Parameters

5.9.2

Response Parameters

Parameter

Field Type

Usage

Description

Response Status

Integer

Required

One of:
•

Optional

Voucher Redeem
Blocked

Integer

Optional

Voucher Redeem
Retries

Integer

Optional


•
Integer


•

External Platform
Number

Success

•

Unknown Service Key

•
Unknown Subscriber
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.
Indicates if the subscriber is blocked for voucher redeem.
Set to non-zero if blocked, set to zero if not blocked, or
status unknown.
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

6 December 2004


Page 35 of 43

eServGlobal/Amdocs


5.10

REQUEST: Balance Transfer Request (& Response)

5.10.1

V2.1.0q

Request Parameters

Parameter

Field Type

Description

Service Key

Integer

Required

MSC Call ID
Subscriber Key
Key Type
Target Key

Integer
Char Array
Integer
Char Array

Future
Required
Required
Required

Target Key Type
Subscriber PIN
Offer Code

Integer
Char Array
Integer

Required
Required
Optional

Transfer Amount

Integer

Required

document.
Note: For balance transfer request, this will typically be a
management call.
If available.
Normalised key that identifies the requesting subscriber.
Target for balance transfer, may be same as subscriber
(e.g. Internal subscriber balance management).
Identifiers MSISDN or IMSI target key.
Authorisation code
Optional offer code associated with transfer, or -1 if no
offer code applies.
Requested amount of transfer.

Table 28 – Balance Transfer Request Parameters

6 December 2004


Page 36 of 43

eServGlobal/Amdocs

5.10.2


V2.1.0q

Response Parameters

Parameter

Field Type

Response Status

Integer

Description
Required

One of:
•

#10 New Value
#10 Active End
#10 Grace End
PIN Retries
Remaining

Integer
Date
Date
Integer

Future
Optional
Optional
Future

Recharge ID

Integer

Optional

Invalid Target Subscriber State

•

Optional
Optional
Optional

Unknown Target Subscriber

•

Required
Required
Required
Future
Optional
Optional

Subscriber PIN Invalid

•

Char Array
Integer
Integer
Integer
Date
Date
…
Char Array
Integer
Integer

Invalid Subscriber State

•

Required

Insufficient Subscriber Balance

•

Integer

Unauthorised Subscriber

•

Required

Unknown Subscriber

•

Integer

Unknown Service Key

•

Optional
Required


•

Char Array
Integer


•

Transaction Code
Subscriber Balance
Type
New Subscriber
Balance
Num Updated
Target Balances
#1 Identifier
#1 Unit Type
#1 Change
#1 New Value
#1 Active End
#1 Grace End
…
#10 Identifier
#10 Unit Type
#10 Change

Success

•

Wrong denomination (or Balances Incompatible)

•
Invalid Offer Code
Confirmation transaction code, may be empty.
Indicates what balance type of subscriber balance was
used for the source of the transfer.
Indicates the updated balance of the subscriber who was
the source of the transfer.
How many target balances were updated? Must be 1 ..
10.
Balance ID for the first updated target balance.
Unit type of the first updated target balance.
Change applied to first updated target balance.
New balance value of the first balance.
End of active period for the first balance.
End of grace period for the first balance.
…
Balance ID for the tenth updated target balance.
Unit type of the tenth updated target balance.
Change applied to tenth updated target balance.
New balance value of the tenth balance.
Number of PIN retries remaining, present IFF
Status == Subscriber PIN Invalid
Reciept number for transaction

Table 29 – Balance Transfer Response Parameters

6 December 2004


Page 37 of 43

eServGlobal/Amdocs

6


V2.1.0q

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:
•
•

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.

•

6.1

All integer values will be network byte order.

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

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

6 December 2004


Page 38 of 43

eServGlobal/Amdocs


V2.1.0q

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)
Reservation

Generate alarm.

M <= 0
The session is initiated.
Correct client behaviour.

M=1

Reservation
Request Num
1<M<N
Reservation
Request Num
1<M=N

(i.e. N >= 1)
Never valid.
Return invalidRequest.

Request Num

Reservation
Request Num

Previous Reservation

May occur if client is re-started.

Not valid in this protocol version.
Generate alarm.
Never valid.
Generate alarm.

Never valid.
Generate alarm.

Never valid.
Generate alarm.

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

Generate alarm.
Reservation
Request Num
1 < M = N+1
Reservation
Request Num
M > N+1

Never valid.
Generate alarm.

This is a subsequent reservation.
Never valid.
Generate alarm.

Table 30 – Handling of Authorize/Reserve Request Numbers

6 December 2004


Page 39 of 43

eServGlobal/Amdocs

7.2


V2.1.0q

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)
Charge Request
Num
M <= 0
Charge Request
Num

1<M<N
Charge Request
Num
1<M=N
Charge Request
Num
1 < M = N+1
Charge Request
Num
M > N+1

(i.e. N >= 1)
Never valid.
Generate alarm.
Generate alarm.

M=1
Charge Request
Num

Previous Reservation

Never valid.
Generate alarm.

Never valid.
Generate alarm.

Never valid.
Generate alarm.

Never valid.
Generate alarm.

Never valid.
Generate alarm.

This is a subsequent reservation.
Never valid.
Generate alarm.

Table 31 – Handling of Charge Request Numbers

6 December 2004


Page 40 of 43

eServGlobal/Amdocs

8


V2.1.0q

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.
•
•

8.1.2

Originating Cell ID – Required for MO calls originating within Excelcom network
Terminating Cell ID – Required for MT calls terminating within Excelcom network

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

8.2

Originating Cell ID – Required for MO calls originating within Excelcom network
Terminating Cell ID – Required for MT calls terminating within Excelcom network

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:
•
•

8.3.1

Cell ID format contains one or more “.” (period) characters
Network element address contains no “.” (period) characters

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

6 December 2004

Country Code (3 digits)


Page 41 of 43

eServGlobal/Amdocs


•

Network Code (2-3 digits)

•

Location Area Code (integer)

•

V2.1.0q

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.
•
•

8.5

“PREPAID” – Standard call flow.
“POSTPAID” – As for pre-paid, however low balance warning does not apply.

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
•
•

Update Type = Write or Overwrite

•

Number of Values = 1

•

Secondary Key #1 = 0

•

8.6.2

Primary Key = Language

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

Option 2: F&F numbers update
•
•

Update Type = Overwrite

•

Number of Values = 1 .. 10

•

Secondary Keys #1 - #10 = 0

•

8.6.3

Primary Key = F&F

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

Option 3: PIN update
•
•

Update Type = Overwrite

•
6 December 2004

Primary Key = PIN


Page 42 of 43

eServGlobal/Amdocs


•

New Values #1 = Existing PIN

•

8.6.4

Secondary Keys #1 - #2 = 0

•

V2.1.0q

New Values #2 = New PIN

Option 4: Initial Activation
•

Primary Key = Initial Activation

•

Update Type = Write

•


***END OF DOCUMENT***

6 December 2004


Page 43 of 43

EAX Protocol

Empfohlen

Empfohlen

Weitere ähnliche Inhalte

Ähnlich wie EAX Protocol

Ähnlich wie EAX Protocol (20)

Kürzlich hochgeladen

Kürzlich hochgeladen (20)

EAX Protocol