Generic PPS – PPS 4.3.2 / RTDC - Debit Credit Interface Part HTTP INTERFACE DESCRIPTION 3BL 45121 BAAA NSZZA Ed 04 Validated All rights reserved. Passing on or copying of this document, use and communication of its contents not permitted without written authorization

1/25

INTELLIGENT NETWORK

GENERIC PPS PPS 4.3.2 / RTDC - DEBIT CREDIT

INTERFACE PART

HTTP INTERFACE DESCRIPTION

Generic PPS – PPS 4.3.2 / RTDC - Debit Credit Interface Part HTTP INTERFACE DESCRIPTION 3BL 45121 BAAA NSZZA Ed 04 Validated All rights reserved. Passing on or copying of this document, use and communication of its contents not permitted without written authorization

2/25

PREFACE

This document describes the HTTP interfaces allowing an external entity to debit/credit a subscriber that is hosted on the SDP/DBRES of the PPS 4.3.2 service. In the PPS 4.3.2 deployment, pure prepaid accounts are held in SDP 1.4 whereas post-paid and regular prepaid accounts are held in DBRES 1.8.

HISTORY

Edition Date (yy-mm-dd)

Comments

Ed 04 05-10-27 Modification Type of the prices

Ed 03 05-06-29 Type of the prices was int instead of real

Ed 02 05-04-07 Update for FR VELin32219 (DBRES Currency Precision handling)

Ed 01 04-09-08 Creation of document

TRADEMARKS

None

Generic PPS – PPS 4.3.2 / RTDC - Debit Credit Interface Part HTTP INTERFACE DESCRIPTION 3BL 45121 BAAA NSZZA Ed 04 Validated All rights reserved. Passing on or copying of this document, use and communication of its contents not permitted without written authorization

3/25

CONVENTIONS

The table below shows the typing conventions used in this document. These conventions denote a special type of information.

Typing convention Information type

bold-face text • menu options

• dialog box fields

• commands

• buttons

• file names

italics • document titles

• document references

Generic PPS – PPS 4.3.2 / RTDC - Debit Credit Interface Part HTTP INTERFACE DESCRIPTION 3BL 45121 BAAA NSZZA Ed 04 Validated All rights reserved. Passing on or copying of this document, use and communication of its contents not permitted without written authorization

4/25

TABLE OF CONTENTS

1. INTRODUCTION ............................................................................................................ 7

2. NETWORK ENVIRONMENT............................................................................................ 9

3. INFORMATION FLOW.................................................................................................. 10

3.1 INTRODUCTION ............................................................................................................. 10 3.2 IMMEDIATE DEBIT........................................................................................................... 10 3.3 TWO-STEP DEBIT ............................................................................................................ 12 3.4 IMMEDIATE CREDIT ......................................................................................................... 14

4. EXTERNAL INTERFACES DESCRIPTION ........................................................................ 15

4.1 CONTENT PROVIDER REQUEST .......................................................................................... 15 4.2 CONTENT PROVIDER REPLY............................................................................................... 20

5. ANNEX A: VALUES FOR THE PARAMETER ‘RESULT’..................................................... 22

6. ANNEX B: DTD XML .....................................................................................................23

Generic PPS – PPS 4.3.2 / RTDC - Debit Credit Interface Part HTTP INTERFACE DESCRIPTION 3BL 45121 BAAA NSZZA Ed 04 Validated All rights reserved. Passing on or copying of this document, use and communication of its contents not permitted without written authorization

5/25

TABLE OF ILLUSTRATIONS

Figure 1: Immediate Debit Scenario – Fee Example when Debiting an Amount of Money................. 11 Figure 2: Immediate Debit Scenario – Example of a Debit on a Sub-account / Regular Prepaid or Post-

paid Case ............................................................................................................................ 11 Figure 3: Two-step Debit Scenario – One Example when Debiting an Amount of Money.................. 12 Figure 4: CP Aborts the Two-step Debit – Example of a Debit on a Sub-account / Regular Prepaid or

Post-paid Case ..................................................................................................................... 13 Figure 5: Credit Request - Post-paid/Regular Prepaid .................................................................... 14 Figure 6: Credit Request - Prepaid................................................................................................ 14

Generic PPS – PPS 4.3.2 / RTDC - Debit Credit Interface Part HTTP INTERFACE DESCRIPTION 3BL 45121 BAAA NSZZA Ed 04 Validated All rights reserved. Passing on or copying of this document, use and communication of its contents not permitted without written authorization

6/25

REFERENCE DOCUMENTS

N° Reference Ed Title 1 3BL 45120 BAAA DTZZA 01 Generic PPS - PPS 4.3.2 / RTDC Functional Specifications

2 3BL 45011 EAAA DSZZA 01 Generic PPS - PPS 4.3.2 Pure Prepaid DBRES1.4 - General Design – Service Description

3 3BL 45180 BAAA DTZZA 01 Generic PPS - PPS 4.3.2 / DBRES 1.8 Functional Specifications

Generic PPS – PPS 4.3.2 / RTDC - Debit Credit Interface Part HTTP INTERFACE DESCRIPTION 3BL 45121 BAAA NSZZA Ed 04 Validated All rights reserved. Passing on or copying of this document, use and communication of its contents not permitted without written authorization

7/25

1. INTRODUCTION

The aim of this document is to describe the Debit-Credit HTTP interface that enables an external entity to perform following operations on users’ accounts identified by their MSISDN:

For prepaid users:

Debit an amount of money on the main account

Credit all the sub-accounts1 of the user and modify the activity and inactivity periods of the main account, the activity period of the promotional sub-account and the validity period of the refill bonus SMS.

Each amount is given in the unit of the targeted sub-account.

For post-paid and regular prepaid users:

Debit an amount associated with a content code. The determination of the targeted sub-account(s)2 follows the following logic:

Through RTDC service population, this content code refers to an operator service and, through the commercial offer subscribed by the user, this service is linked to a rating tree that enables the selection of the sub-account(s) to debit.

Credit all the sub-accounts of the user.

Each amount is given in the unit of the targeted sub-account.

Note that if the external entity does not know the type of user (prepaid or not), it can only debit an amount of money (and the RTDC service will use a default value (65535) of content code in case the user is post-paid or regular prepaid).

For debit transactions, two different scenarios may take place:

Immediate Debit: Charging is done at the reception of the request,

Two- Step Transaction: there is a first message to authorise the transaction and book the given amount in case of pure prepaid and regular prepaid accounts and a second message is sent when the transaction has been successfully completed. The subscriber’s account is charged at the reception of the confirmation request (second message). In case that the second message is not received, the booked amount (pure and regular prepaid) will be credited again to the account after a given timer. In all cases, the external entity has always the possibility to cancel the previous booking by sending an ABORT request.

1 The “sub-account” expression includes the main account, the promotional sub-account, the MMS sub-account, the data sub-account, the content sub-account and the refill bonus SMS counter. 2 The “sub-account” expression includes the balance, the general money sub-accounts (money1 and money2) and the specialised sub-accounts (time/voice, SMS, MMS, data, content).

Generic PPS – PPS 4.3.2 / RTDC - Debit Credit Interface Part HTTP INTERFACE DESCRIPTION 3BL 45121 BAAA NSZZA Ed 04 Validated All rights reserved. Passing on or copying of this document, use and communication of its contents not permitted without written authorization

8/25

Furthermore, for any transaction Call Detail Records (CDR) will be generated including information such as date and time, subscriber MSISDN, debited amount, identity of the external entity originating the request.

Generic PPS – PPS 4.3.2 / RTDC - Debit Credit Interface Part HTTP INTERFACE DESCRIPTION 3BL 45121 BAAA NSZZA Ed 04 Validated All rights reserved. Passing on or copying of this document, use and communication of its contents not permitted without written authorization

9/25

2. NETWORK ENVIRONMENT

The interface described in this document relies between the External Entity and the OSP where the prepaid, post-paid and regular prepaid accounts are held.

This interface may be used within the operator Intranet (between two network-nodes managed by the operator, as well as for a node lying outside in the Internet). For the later, this interface provides a secure transport by using https and digital certificates. However it must be pointed out that this security-layer will obviously decrease the overall solution performance.

Next figure depicts both possible configurations.

OSP

Debit / credit service

HTTP

(S) Interfa

ce

InternetCP

Operator IPnetwork

MMS-C

Firewall Firewall

Generic PPS – PPS 4.3.2 / RTDC - Debit Credit Interface Part HTTP INTERFACE DESCRIPTION 3BL 45121 BAAA NSZZA Ed 04 Validated All rights reserved. Passing on or copying of this document, use and communication of its contents not permitted without written authorization

10/25

3. INFORMATION FLOW

3.1 INTRODUCTION

This chapter aims at describing the message exchange for the different scenarios. The involved entities are:

CP Content Provider (or any other External Entity) using this HTTP interface

Debit/credit application (on OSP) responsible for managing the incoming requests and updating the account.

Hereafter you will find the message flow for different kinds of scenarios:

Immediate debit

Two-step debit

Two-step debit-abort,

Immediate credit

3.2 IMMEDIATE DEBIT

The CP asks for the immediate debit of an amount before/after (CP dependent) providing the content to the user. Once the OSP receives the CP request, the account will be updated, and the transaction will be acknowledged to the CP.

In case any parameter included in the CP request does not correspond to the expected parameters, the transaction will be rejected, and the CP will be informed of the error.

Generic PPS – PPS 4.3.2 / RTDC - Debit Credit Interface Part HTTP INTERFACE DESCRIPTION 3BL 45121 BAAA NSZZA Ed 04 Validated All rights reserved. Passing on or copying of this document, use and communication of its contents not permitted without written authorization

11/25

CP

CP REQUEST

CP REPLY

<cp_id, cp_transaction_id, op_transaction_id=“”,user_id, application= H’01’, action=H’00’, transaction_price, transaction_currency>

<result= H’00’, cp_transaction_id, cp_id>

HTTPHTTPOSP

OSP

Example 1Debit an amount of money Available for prepaid and postpaid

<cp_id, cp_transaction_id, op_transaction_id=“”, user_id, application= H’01’, action=H’00’, transaction_price, transaction_currency,debit_params:

dbt_ref1(subscriber_type)=0,dbt_ref2(content_code)

>

Example 2Debit an amount of money on a DBRES user (reg prepaid or post-paid)

CP

CP REQUEST

CP REPLY

<result= H’00’, cp_transaction_id, cp_id>

HTTPHTTPOSP

Figure 1: Immediate Debit Scenario – Fee Example when Debiting an Amount of Money

OSP

<cp_id, cp_transaction_id, op_transaction_id=“”, user_id, application= H’01’, action=H’00’, Debit_params:

dbt_ref1(subscriber_type)=0dbt_ref2(content_code),dbt_ref3(requested_units)

>

CP

CP REQUEST

CP REPLY

<result= H’00’, cp_transaction_id, cp_id>

HTTPHTTPOSP

Figure 2: Immediate Debit Scenario – Example of a Debit on a Sub-account / Regular Prepaid or Post-paid Case

Generic PPS – PPS 4.3.2 / RTDC - Debit Credit Interface Part HTTP INTERFACE DESCRIPTION 3BL 45121 BAAA NSZZA Ed 04 Validated All rights reserved. Passing on or copying of this document, use and communication of its contents not permitted without written authorization

12/25

3.3 TWO-STEP DEBIT

The CP sends a first message that is used to check the user is authorised to pursue the transaction. The CP uses the second message to confirm that the content has been delivered and SDP/DBRES updates the subscribers’ account. This second message is also acknowledged by the OSP.

CP

CP REQUEST

CP REPLY

<cp_id, cp_transaction_id, op_transaction_id=“”, user_id, application= H’01’, action=H’02’, transaction_price,transaction_currency>

<result= H’00’, cp_id, cp_transaction_id, op_transaction_id>

HTTPHTTP

CP REQUEST

CP REPLY

OSP

<result= H’00’, cp_id, cp_transaction_id>

<cp_id, cp_transaction_id, op_transaction_id, user_id,application= H’01’, action=H’04’, transaction_price,transaction_currency>

Figure 3: Two-step Debit Scenario – One Example when Debiting an Amount of Money

Hereafter you will find depicted the scenario where the CP aborts the transaction after having booked the credit.

Generic PPS – PPS 4.3.2 / RTDC - Debit Credit Interface Part HTTP INTERFACE DESCRIPTION 3BL 45121 BAAA NSZZA Ed 04 Validated All rights reserved. Passing on or copying of this document, use and communication of its contents not permitted without written authorization

13/25

CP

CP REQUEST

CP REPLY

<cp_id, cp_transaction_id, op_transaction_id=“”, user_id, application= H’01’, action=H’02’, debit_params:

dbt_ref1(subscriber type)=0,dbt_ref2(content code),dbt_ref3(requested unit) >

<result= H’00’, cp_id, cp_transaction_id, op_transaction_id>

HTTPHTTP

CP REQUEST

<cp_id, cp_transaction id, op_transaction_id, user_id, application=H’01’, action=H’99’>

CP REPLY

<result=H’00’, cp_id, cp_transaction_id>

OSP

Figure 4: CP Aborts the Two-step Debit – Example of a Debit on a Sub-account / Regular Prepaid or Post-paid Case

Generic PPS – PPS 4.3.2 / RTDC - Debit Credit Interface Part HTTP INTERFACE DESCRIPTION 3BL 45121 BAAA NSZZA Ed 04 Validated All rights reserved. Passing on or copying of this document, use and communication of its contents not permitted without written authorization

14/25

3.4 IMMEDIATE CREDIT

The CP asks for the credit of an account. Once the OSP receives the credit request, the account is updated, and the transaction will be acknowledged to the CP.

In case any parameter included in the CP request does not correspond to the expected parameters, the transaction will be rejected, and the CP will be informed of the error.

CP

CP REQUEST

CP REPLY

<cp_id, cp_transaction_id,user_id, application= H’01’, action=H’01’, transaction_price, transaction currency,Credit_params

crd_ref0(subscriber type)=0, crd_ref10( prepaid credit), crd_ref11(money_sub), crd_ref13(time_sub), crd_ref14(time bonus), crd_ref15(sms_su),crd_ref16(sms bonus), crd_ref17(mms_sub), crd_ref18(mms bonus), crd_ref19(data_sub),crd_ref20(data bonus), crd_ref21(content_sub),crd_ref22(content bonus)>

<result= H’00’, cp_id, cp_transaction_id>

HTTPHTTP

OSP

OSP

Figure 5: Credit Request - Post-paid/Regular Prepaid

CP

CP REQUEST

CP REPLY

<cp_id, cp_transaction_id,user_id, application= H’01’, action=H’01’, transaction_price, transaction currency,Credit_params:

crd_ref0(subscriber type)=1, crd_ref1(main activity), crd_ref2(main inactivity), crd_ref3(prom credit), crd_ref4(prom activity), crd_ref5(content credit), crd_ref6(data credit), crd_ref7(mms credit),crd_ref8(sms credit),crd_ref9(sms validity)>

<result= H’00’,cp_id, cp_transaction_id>

HTTPHTTP

OSP

OSP

Figure 6: Credit Request - Prepaid

Generic PPS – PPS 4.3.2 / RTDC - Debit Credit Interface Part HTTP INTERFACE DESCRIPTION 3BL 45121 BAAA NSZZA Ed 04 Validated All rights reserved. Passing on or copying of this document, use and communication of its contents not permitted without written authorization

15/25

4. EXTERNAL INTERFACES DESCRIPTION

4.1 CONTENT PROVIDER REQUEST

The CP sends this message. This message is used in all the scenarios described above. The parameter action is used to tell scenarios apart.

HTTP message type: Request

Request line: POST http(s)://www.in.fr/…/Si HTTP/1.1

Body: Next table lists the parameters expected in the form that will be sent in the enclosed entity.

Parameters Name M/O/C3 Format Value Comments

cp_id M Char string Max = 10 if credit 30 if debit

Used to identify the requesting entity in the CDR. (No checking is performed)

cp_tansaction_id M Char string Max = 30 CP Internal value.

op_transaction_id M Char string Max = 200

application M Unsigned int 1= Debit/Credit

action M Unsigned int 0=Immediate debit 1=Immediate credit 2=Two-step debit - book 4=Two-step debit - update 99=Two-step debit - abort

Describes the type of operation that the CP is sending to the OSP.

user_id M Number Max = 16 digits Only the MSISDN is supported in this interface

cp_timer O Unsigned int 0…65535 Used by the CP to specify the credit booked duration.

Otherwise default CP timer will be taken by the debit/credit service.

transaction_price O Real 0...MaxValue4 Amount to debit or credit on the user account

transaction_currency O Unsigned int 0…15 Value is always the default platform currency.

debit_params C Char string Max=100 Element withholding the debit parameters. The element is conditional, it should be present in case action is a type debit

credit_params C Char string Max=100 Element withholding the credit parameters. The element is conditional, it should be present in case action is 1

3 Mandatory/Optional/Conditional 4 MaxValue is 9999999.99 for SDP subscribers (pure prepaid). For DBRES subscribers (regular prepaid and postpaid), MaxValue depends on the Currency Precision (e.g. 99999.9999 if the precision is set to 4 digits.)

Generic PPS – PPS 4.3.2 / RTDC - Debit Credit Interface Part HTTP INTERFACE DESCRIPTION 3BL 45121 BAAA NSZZA Ed 04 Validated All rights reserved. Passing on or copying of this document, use and communication of its contents not permitted without written authorization

16/25

debit_params element:

Prepaid account

Ref 1: subscriber_type O Unsigned int 1 = pure prepaid Used to identify the subscriber account type.

Post-paid / regular-prepaid

Ref 1: subscriber_type M Unsigned int 0 = post-paid or regular prepaid

Used to identify the subscriber account type.

Ref 2: content_code C Unsigned int 1…65535 Identify the unit type to debit

Ref 3: requested_unit C Unsigned int >0 <=9999999

Quantity to debit

credit_params element:

Ref 0: subscriber_type M Unsigned int 0 = post-paid or regular prepaid

1 = pure prepaid

Used to identify the subscriber account type.

Prepaid account:

Ref 1: main_activity C Unsigned int >0 <=999

Number of activity days for Main account.

Ref 2: main_inactivity C Unsigned int >0 <=999

Number of inactivity days for Main account.

Ref 3: prom_credit O Real >0 <=9999999.99

Credit for promotional sub-account

Ref 4: prom_activity C Unsigned int >0 <=999

Number of validity days for promotional sub-account.

Ref 5: content_credit O Real >0 <=9999999.99

Credit for content sub-account

Ref 6: data_credit O Real >0 <=9999999.99 (if sub account in currency)

<=999999 (if sub account in Kbytes)

Credit for data sub-account (currency/volume)

Ref 7: mms_credit O Real >0 <=9999999.99 (if sub account in currency)

<=999999 (if sub account in unit)

Credit for mms sub-account (currency/unit)

Ref 8: sms_credit O Unsigned int >0 <=999

Credit for refill bonus sms (unit)

Ref 9: sms_validity O Unsigned int >0 <=999

Bonus sms validity days

Generic PPS – PPS 4.3.2 / RTDC - Debit Credit Interface Part HTTP INTERFACE DESCRIPTION 3BL 45121 BAAA NSZZA Ed 04 Validated All rights reserved. Passing on or copying of this document, use and communication of its contents not permitted without written authorization

17/25

Postpaid/Regular prepaid account: Ref 10: prepaid_credit O Real >0

<=MaxValue5 Credit on the money1 sub-account

Ref 11: money_sub O Real >0 <= MaxValue5

Credit on the money2 sub-account

Ref 13: time_sub O Unsigned int >0 <=99999

Credit on the time/voice sub-account

Ref 14: time_bonus O Unsigned int >0 <=99999

Credit the bonus on the time/voice sub-account

Ref 15: sms_sub O Unsigned int >0 <=99999

Credit on the sms sub-account

Ref 16: sms_bonus O Unsigned int >0 <=99999

Credit the bonus on the sms sub-account

Ref 17: mms_sub O Unsigned int >0 <=99999

Credit on the mms sub-account

Ref 18: mms_bonus O Unsigned int >0 <=99999

Credit the bonus on the mms sub-account

Ref 19: data_sub O Unsigned int >0 <=999999

Credit on the data sub-account

Ref 20: data_bonus O Unsigned int >0 <=999999

Credit the bonus on the data sub-account

Ref 21: content_sub O Real >0 <= MaxValue5

Credit on the content sub-account

Ref 22: content_bonus O Real >0 <= MaxValue5

Credit the bonus on the content sub-account

cp_id: It identifies the Content Provider or the external entity. It is case sensitive. Content Providers must refer to their operator to obtain a valid cp_id. The value of the field must be used in any request.

In case of the immediate credit request on a pure prepaid account, this value could be used to identify default account life cycle durations (cp_id identifies an instance of the bankrefill object) (refer to [1]),

cp_transaction_id: It is Content Provider specific, and it is not used by the RTDC. It is the Content Provider identifier of the transaction. This parameter will be added in each response from the RTDC to enable the CP to relate requests and responses. This field must contain only alphanumeric character,

op_transaction_id: It conveys the existing context at the RTDC side. For the first request it is set to null (empty element), and in the second request, it must be filled with the value of op_transaction_id get from the “content provider reply” sent to the first request,

5 MaxValue depends on the Digital Precision set in DBRES Service Retailer object. For instance, MaxValue=99999.9999 if the precision is set to 4 digits; but MaxValue is 999.999999 if currencies are handled on the platform with a 10-6 precision.

Generic PPS – PPS 4.3.2 / RTDC - Debit Credit Interface Part HTTP INTERFACE DESCRIPTION 3BL 45121 BAAA NSZZA Ed 04 Validated All rights reserved. Passing on or copying of this document, use and communication of its contents not permitted without written authorization

18/25

application: It specifies which application will be triggered on the OSP. For the debit/credit application, this field must be set to ‘1’.

action: It characterizes the kind of request. Valid values are listed above.

user_id: Identity of the subscriber. Only the MSISDN is supported by this interface.

cp_timer: It is an optional parameter that enables the CP to modify the timer value used by the platform in the two-step debit transactions. The timer is started at the reception of the first request, and if it expires, the transaction context is cleared and the booked amount is credited to the account. If this parameter is not filled, a default value that is configured by the service provider will be used.

transaction_price:

• for debit request for a pure prepaid user, the amount of money that will be charged or booked on the main account

In that case, it is mandatory for each debit request (action = 0, 2, 4, 99).

• for debit request for a regular prepaid or a post-paid user, the amount of money that will be charged or booked on the sub-account targeted by the content code given by the attribute (reference 2) of the debit_params element.

If debit_params element is not present (for example because the type of the subscriber is not known by the external entity), 65535 will be the default value of the content code if the user is identified as a DBRES user (regular prepaid or post-paid).

If transaction_price is set and the type of the user is known by the external entity and it is a DBRES user (regular prepaid or post-paid), it is recommended to send also the element debit_params with the attribute reference 1 (subscriber type) set to value 0 to avoid the system to search first if the user is a pure prepaid.

Note that transaction_price and attribute reference 3 (requested_unit) of the debit_params element are exclusive.

• for credit request, the amount of money that will be credited on the main account of the pure prepaid users or on the balance of the regular prepaid or post-paid users.

transaction_currency: Currency related to each parameter that corresponds to an amount of money (transaction_price, …). The single possible value is the default platform currency.

For a credit request, it is a mandatory parameter.

For a debit request, it is a mandatory parameter if transaction_price is present.

debit_params: element withholding the debit parameters (1- subscriber_type, 2- content_code, 3- requested_unit) . In case this element is not present, the request consists in a debit of an amount of money (transaction_price).

Generic PPS – PPS 4.3.2 / RTDC - Debit Credit Interface Part HTTP INTERFACE DESCRIPTION 3BL 45121 BAAA NSZZA Ed 04 Validated All rights reserved. Passing on or copying of this document, use and communication of its contents not permitted without written authorization

19/25

subscriber_type: It is an optional parameter stating whether the account is pure prepaid or not.

It is a mandatory parameter when attribute requested_unit is present and has to equal 0.

content_code: This parameter identifies the unit type to debit (i.e. SMS, MMS etc) (refer to §1 for the description of the content code and operator service relation).

It is a mandatory parameter when attribute requested_unit is present.

requested_unit: This parameter states the number of units of type content_code to debit.

credit_params: element withholding the credit parameters.

Dedicated to pure prepaid accounts:

main_activity: number of days for the update6 of the account activity duration. transaction_price has to be present when this parameter is sent.

If this parameter is not present, it is set to 0, except if the request credits at least the main account (transaction_price is present) and if no parameters of duration7 are defined; in that case, the default value is calculated comparing main amount to credit to five default intervals (refer to [1]).

main_inactivity: number of days for the update8 of the account inactivity duration. transaction_price has to be present when this parameter is sent.

If this parameter is not present, it is set to 0, except if the request credits at least the main account (transaction_price is present) and if no parameters of duration are defined; in that case, the default value is calculated comparing main amount to credit to five default intervals (refer to [1]).

prom_credit: amount of money to credit on the promotional sub-account.

prom_activity: number of days for the update9 of the promotional sub-account activity period.

prom_credit has to be present when this parameter is sent. It is set to 0 if not present in the request.

content_credit: amount of money to credit on the content sub-account.

data_credit: amount (money or Kbytes) to credit on the data sub-account.

mms_credit: amount (money or units) to credit on the mms sub-account.

sms_credit: number of sms to credit on the refill bonus sms counter.

sms_validity: number of days for the update of the bonus sms validity period. It is set to 0 if not present in the request.

Dedicated to regular prepaid accounts and postpaid accounts:

prepaid_credit: amount of money to credit on the money1 (rechargeable sub-account) sub-account

6 In cumulative or not cumulative mode, according to service configuration (refer to [2]) 7 Neither main activity, nor main inactivity, nor promotional activity, nor sms validity 8 In cumulative or not cumulative mode, according to service configuration (refer to [2]) 9 In cumulative or not cumulative mode, according to service configuration (refer to [2])

Generic PPS – PPS 4.3.2 / RTDC - Debit Credit Interface Part HTTP INTERFACE DESCRIPTION 3BL 45121 BAAA NSZZA Ed 04 Validated All rights reserved. Passing on or copying of this document, use and communication of its contents not permitted without written authorization

20/25

money_sub: amount of money to credit on the money2 (all money sub-account) sub-account

time_sub: number of seconds to credit on the time sub-account

time_bonus: number of seconds to credit on the bonus counter of the time sub-account

sms_sub: number of sms to credit on the sms sub-account

sms_bonus: number of sms to credit on the bonus counter of the sms sub-account

mms_sub: number of mms to credit on the mms sub-account

mms_bonus: number of mms to credit on the bonus counter of the mms sub-account

data_sub: number of kbytes to credit on the data sub-account

data_bonus: number of kbytes to credit on the bonus counter of the data sub-account

content_sub: amount of money to credit on the content sub-account

content_bonus: amount of money to credit on the bonus counter of the content sub-account

4.2 CONTENT PROVIDER REPLY

This message is sent by the OSP to the Content Provider as the response to the request that has been sent previously. This message confirms the request done by the CP to update the subscriber’s account. Otherwise, if the account could not be updated, the result parameter will give the reason why it was not possible to perform the operation.

HTTP message type: Response

Status line: HTTP/1.1 200 OK

Entity Header Fields:

Content-type: text/xml

Content-length

Parameters: Next table lists the parameters expected in the answer.

Parameters Name M/O Format Value Comments

cp_id M Char string Max = 30 Same value present in the request

cp_transaction_id M Char string Max = 30 Same value present in the request

op_transaction_id O Char string Max = 200 Not sent if the transaction is closed with this message

result M Unsigned int Cf. Annex A

rejected_item O Char string Contains the parameter that caused the error.

cp_id: It contains the value received in the CP REQUEST message,

Generic PPS – PPS 4.3.2 / RTDC - Debit Credit Interface Part HTTP INTERFACE DESCRIPTION 3BL 45121 BAAA NSZZA Ed 04 Validated All rights reserved. Passing on or copying of this document, use and communication of its contents not permitted without written authorization

21/25

cp_transaction_id: It contains the value received in the CP REQUEST message,

op_transaction_id: It contains a reference of the context that is open at the debit/credit service. This reference must be used in the second CP request for two-step transaction scenarios. For one-step transactions, this parameter will not be present.

result: It gives the outcome of the received request. Refer to Annex A for a list of the possible values.

rejected_item: This optional parameter is present only if the result code equals 3, 4, 5, 6, or 8 (Refer to Annex A). In that case it contains the parameter (or set of parameters) that have been rejected by the debit/credit service.

If the value of ‘result’ is ‘4’, ‘5’, ‘6’, then the ‘rejected_item’ field format is:

<rejected_item>rejected_element_name=element_value</rejected_item>

Else if this value is ‘3’ or ‘8’, then the ‘rejected_item’ field format is:

<rejected_item><![CDATA[received_xml_document]]></rejected_item>

Generic PPS – PPS 4.3.2 / RTDC - Debit Credit Interface Part HTTP INTERFACE DESCRIPTION 3BL 45121 BAAA NSZZA Ed 04 Validated All rights reserved. Passing on or copying of this document, use and communication of its contents not permitted without written authorization

22/25

5. ANNEX A: VALUES FOR THE PARAMETER ‘RESULT’

Next table gives you the expected values that may be received at the parameter result and the appropriate comments.

Value Description Comments

0 OK

2 NOK_REJECT_DUE_TO_SERVICE Failure due to a service problem

3 NOK_MALFORMED_REQUEST Request structure is not valid

4 NOK_MALFORMATTED_PARAMETER A parameter does not respect the format restrictions

5 NOK_INVALID_PARAMETER A parameter has not been found in the database

6 NOK_UNEXPECTED_VALUE Failure due to an inconsistent parameter, this value is used if the debit/credit service detects that a fix parameter such as ‘cp_parameter_id’ has changed compared with previous request.

7 NOK_TIME_OUT The transaction has already been closed

8 NOK_MALFORMED_XML_PROLOG Received XML prolog does not equal waited prolog

9 NOK_XML_PARSE_ERROR Error during parser treatment

10 NOK_NOT_ENOUGH_CREDIT Specific to debit:

For pure prepaid and regular prepaid, not enough credit on the account.

201 NOK_ACCOUNT_NOT_FOUND Account not found / Account profile (pure prepaid) not found

202-217

NOK_Account_status

The user account status isn’t valid.

For post-paid users and regular prepaid users, 209 means that the asked service is not found in the commercial offer subscribed by the user.

243 NOK_HIGH_DEBIT The debit amount is higher than the max. amount authorized per transaction for a pure prepaid user. This parameter is defined in the pure prepaid eaccount profile

253 No_More_Available_Credit

Specific to debit:

- For pure prepaid, possible in the case of a two parallel two steps debit.

- For controlled post-paid, possible when balance exceeds the maximum threshold.

- For regular prepaid, possible when the targeted sub-account/bundle and prepaid credit are emptied.

Else Nok_technical_problem Technical problem

Generic PPS – PPS 4.3.2 / RTDC - Debit Credit Interface Part HTTP INTERFACE DESCRIPTION 3BL 45121 BAAA NSZZA Ed 04 Validated All rights reserved. Passing on or copying of this document, use and communication of its contents not permitted without written authorization

23/25

6. ANNEX B: DTD XML

Here is the description of the DTD used by CP request and CP reply messages.

Content Provider Request Prologue

<?xml version="1.0"?>

<!DOCTYPE cp_request SYSTEM "cp_req_websvr.dtd">

Content Provider Request DTD

<!ELEMENT cp_request (cp_id, cp_transaction_id, op_transaction_id, application, action, user_id, cp_timer?, transaction_currency?, transaction_price?, debit_params?, credit_params?)>

<!ELEMENT cp_id (#PCDATA)>

<!ELEMENT cp_transaction_id (#PCDATA)>

<!ELEMENT op_transaction_id (#PCDATA)>

<!ELEMENT application (#PCDATA)>

<!ELEMENT action (#PCDATA)>

<!ELEMENT user_id (#PCDATA)>

<!ELEMENT cp_timer (#PCDATA)>

<!ELEMENT transaction_currency (#PCDATA)>

<!ELEMENT transaction_price (#PCDATA)>

<!ELEMENT debit_params (dbt_param+)>

<!ELEMENT credit_params (crd_param+)>

<!ELEMENT dbt_param (#PCDATA)>

<!ELEMENT crd_param (#PCDATA)>

<!ATTLIST dbt_param dbt_ref CDATA #REQUIRED>

<!ATTLIST crd_param crd_ref CDATA #REQUIRED>

Generic PPS – PPS 4.3.2 / RTDC - Debit Credit Interface Part HTTP INTERFACE DESCRIPTION 3BL 45121 BAAA NSZZA Ed 04 Validated All rights reserved. Passing on or copying of this document, use and communication of its contents not permitted without written authorization

24/25

Example:

<?xml version="1.0"?>

<!DOCTYPE cp_request SYSTEM "cp_req_websrv.dtd">

<cp_request>

<cp_id>TOPCPID1</cp_id>

<cp_transaction_id>direct_debit</cp_transaction_id>

<op_transaction_id></op_transaction_id>

<application>1</application>

<action>0</action> //immediate debit

<user_id>111111113</user_id>

<debit_params>

<dbt_param dbt_ref="1">0</dbt_param> //subscriber_type is 0 (postpaid)

<dbt_param dbt_ref="2">3</dbt_param> //content_code is 3

<dbt_param dbt_ref="3">10</dbt_param> //requested_unit is 10

</debit_params>

</cp_request>

Generic PPS – PPS 4.3.2 / RTDC - Debit Credit Interface Part HTTP INTERFACE DESCRIPTION 3BL 45121 BAAA NSZZA Ed 04 Validated All rights reserved. Passing on or copying of this document, use and communication of its contents not permitted without written authorization

25/25

Content Provider Reply Prologue

<?xml version="1.0"?>

<!DOCTYPE cp_request SYSTEM "cp_reply.dtd">

Content Provider Reply DTD

<!ELEMENT cp_reply (cp_id, cp_transaction_id, op_transaction_id?, result, rejected_item?> <!ELEMENT cp_id (#PCDATA)>

<!ELEMENT cp_transaction_id (#PCDATA)>

<!ELEMENT op_transaction_id (#PCDATA)>

<!ELEMENT result (#PCDATA)>

<!ELEMENT rejected_item (#PCDATA)>

END OF DOCUMENT