roland schwarz march-3-2012 easypay interface …...easypay interface documentation.doc 5/34...

Easypay Interface Documentation.doc

1/34

From Roland Schwarz

Date March-3-2012

Subject Easypay Interface Documentation

Scope

Document-ID

Version

Status Released

Replaces version

Issue date

Valid from March-3-2012

Valid until

Document name Easypay Interface Documentation 1.5

Server location

Archiving

Checklist of changes

Version Date Changed by Comments/nature of the change

0.1 22.02.2011 A. Glisovic Initial Draft

1.0 31.03.2011 Roland Schwarz First version

1.1 12.04.2011 Roland Schwarz Update

1.2 12.05.2011 A. Glisovic Update

1.3 19.08.2011 Roland Schwarz Updated

1.4 07.12.2011 Roland Schwarz Update

1.5 03.03.2012 Roland Schwarz Removed deprecated REST Interface description

Release

Version Date Released by Comments

1.3 19.08.2011 Roland Schwarz Updated to cover Easypay release version 2.1 and

extended subscription management interface added

1.4 07.12.2011 Roland Schwarz Update global outside IP range for smartphones

Added staging REST URLs

1.5 03.03.2012 Roland Schwarz Removed deprecated REST Interface description


2/34

Index

Introduction .............................................................................................................................................................. 5

1.1 Overview ..........................................................................................................................................................................................5 1.2 Scope ..................................................................................................................................................................................................5 1.3 Target Readership, Requirements of the Reader ...........................................................................................................5 1.4 Terms and Abbreviations .........................................................................................................................................................5

1.4.1 Terms ........................................................................................................................................................................................5 1.4.2 Abbreviations ........................................................................................................................................................................6

1.5 Referenced Documents .............................................................................................................................................................7 1.6 Additional Documents...............................................................................................................................................................7 1.7 Other References ..........................................................................................................................................................................7 1.8 Contact Information ...................................................................................................................................................................7

1.8.1 For Technical Reasons .......................................................................................................................................................7 1.8.2 For Commercial Reasons: ................................................................................................................................................7

2 General ............................................................................................................................................................... 8

2.1 Payment modes ............................................................................................................................................................................8 2.1.1 One-phase...............................................................................................................................................................................8 2.1.2 Two-phase ..............................................................................................................................................................................8

2.2 Service Types ............................................................................................................................................................................... 10 2.2.1 Event ....................................................................................................................................................................................... 10 2.2.2 Subscription (Abo) ............................................................................................................................................................ 10

2.3 Flexible price charging ............................................................................................................................................................ 10 2.4 Detection of Access Device ................................................................................................................................................... 11

2.4.1 Common Mobile Phones............................................................................................................................................... 11 2.4.2 Smartphones ...................................................................................................................................................................... 11

2.5 Guideline for implementing Interfaces .......................................................................................................................... 11

3 Interface Description ....................................................................................................................................... 12

3.1 Checkout Service Interface ................................................................................................................................................... 12 3.1.1 Reserve Request (Checkout Service) Parameter ................................................................................................. 12 3.1.2 Checkout Service URL ..................................................................................................................................................... 13 3.1.3 Reserve Response Parameter ...................................................................................................................................... 14 JSON message examples .............................................................................................................................................................. 15

3.2 Subscription Management (signed SOAP) .................................................................................................................... 17 3.2.1 Request Example .............................................................................................................................................................. 18 3.2.2 Response Example ........................................................................................................................................................... 19 3.2.3 Request Example .............................................................................................................................................................. 21 3.2.4 Response Example ........................................................................................................................................................... 21

3.3 Parameter Definitions ............................................................................................................................................................ 22

4 Security ............................................................................................................................................................. 25

4.1 Secure Checkout Service (used in chapter 3.1) ........................................................................................................... 25 4.1.1 Message Authentication Code (MAC) ..................................................................................................................... 25 4.1.2 Using Base64 Encoding ................................................................................................................................................. 27

4.2 Sign SAOP Requests (used in chapter 3.2) !!! ............................................................................................................... 30 4.3 Creating a self signed Certificate....................................................................................................................................... 31


3/34

5 Error ID’s List .................................................................................................................................................... 33


4/34

Index of Figures

Figure 1: Detailed Purchase Flow from CP Point of View ...........................................................................................................9 Figure 2: Steps for authenticating requests to AWS ................................................................................................................. 26 Figure 3: Steps for signature generated by AWS ......................................................................................................................... 27

Index of Tables

Table 1: Flexible price charging use cases ...................................................................................................................................... 10 Table 2: Guideline for implementing interfaces .......................................................................................................................... 11 Table 3: Parameter for Reserve Request .......................................................................................................................................... 13 Table 4: Parameter from Reserve Response................................................................................................................................... 14 Table 5: Charging Enabler Subscriptions methods .................................................................................................................... 17 Table 6: Reserve Amount Charging methods ............................................................................................................................... 20 Table 7: EndUserIdentifier (SOAP parameter-name: endUserIdentifier) ......................................................................... 22 Table 8: Charging Information (SOAP Parameter Name: charge) ....................................................................................... 22 Table 9: code (Part of Charging Information, see Table 12: Charging Information (SOAP Parameter Name:

charge)) ........................................................................................................................................................................................................... 23 Table 10: Reference Code (SOAP Parameter Name: referenceCode) ................................................................................. 24 Table 11: Reservation Identifier (SOAP Parameter Name: ReservationIdentifier) ....................................................... 24 Table 12: List of Error IDs ........................................................................................................................................................................ 34


5/34

Introduction

1.1 Overview

Easypay is a simple and secure billing solution from Swisscom for any CP who wants to sell download,

streaming and browsing services on the (mobile) internet.

It offers the possibility to bill different event and subscription services to Swisscom customers (including

MVNOs) without the need for off-putting registration processes before making a purchase. Easypay is

accessible by mobile handsets/smartphones via mobile network and WLAN as well as by computers via

WLAN and LAN.

1.2 Scope

This manual describes the interfaces of Easypay and provides specific information regarding the following

topics:

Detailed parameter description Checkout Service see chapter 3.1

Detailed parameter description subscription management (SOAP) see chapter 3.3

Detailed information on security see chapter 4

A detailed conceptual overview is provided in Easypay Conceptual Overview [A].

1.3 Target Readership, Requirements of the Reader

This manual is primarily intended for technical staff from CPs.

It is assumed that the reader is familiar with the basics of mobile and internet terminology.

1.4 Terms and Abbreviations

1.4.1 Terms

MSISDN The telephone number e.g. 41 79 666 77 88.

Content Partner Content Partner offering one or more services using Easypay for charging. Also known

as ASP. Used abbreviation in this document is CP.

contentPartnerId The technical unique identifier of a CP (Merchant). This is assigned to CP once the

contract is signed. To be used as alias in certificate.

Event Service The term “Event Service” is used for a one off transaction. The complement of an

event service is a subscription service.

Subscription

Service

The term “Subscription Service” is used for a transaction which is normally time-

based. Subscription Services may be recurrent (i.e. periodically renewed). An often

used equivalent term to “Subscription Service” is “Abo”. The complement of a

subscription service is an event service.

Merchant A CP can act as an ASP and is able to handle different merchants.


6/34

Price Plan All service related definitions made in the pricing tool are compiled into a so called

price plan. Each merchant has its own price plan.

1.4.2 Abbreviations

APN Access Point Name

ASP Application Service Provider

CE Charging Enabler

CP Content Partner

GUID Globally Unique Identifier

HTTP(S) Hyper Text Transfer Protocol (Secure)

JDK Java Development Kit

JSON JavaScript Object Notation

MSISDN Mobile Subscriber ISDN number = mobile telephone number (e.g. 41 79 666 77 88)

MVNO Mobile Virtual Network Operator (e.g. Mbudget Mobile)

PP Price Plan

PT Pricing Tool

RTSP Real Time Streaming Protocol

SCS Swisscom Schweiz AG

SOAP Simple Object Access Protocol

URI Uniform Resource Identifier

URN Uniform Resource Name

URL Uniform Resource Locator

VAS Value Added Services

WAP Wireless Application Protocol

WSDL Web Service Description Language

XHTML eXtensible Hyper Text Markup Language

XML eXtensible Markup Language


7/34

1.5 Referenced Documents

[A] Easypay Conceptual Overview

1.6 Additional Documents

(Those documents are available upon request: Swisscom Contact Information , see chapter 1.8.1)

[doc1] MIB_Signing_Proxy

[doc2] MIB_additional_features_Manual

1.7 Other References

[1] The tel URI for Telephone Numbers RFC 3966, IETF http://www.ietf.org/rfc/rfc3966.txt

[2] Axis C++ http://ws.apache.org/axis/cpp/index.html

[3] java JDK http://java.sun.com/

[4] Web Service Security WSS4J http://ws.apache.org/wss4j/index.html

1.8 Contact Information

1.8.1 For Technical Reasons

During office hours: Partner Integration

SCS-CBU-MS-SDC-IIB-DES

+41-58 223 47 56, Renato Schneider

[email protected]

During non-office hours: MCS Olten

+41 800 5560 5560

1.8.2 For Commercial Reasons:

During office hours: Provider Support

SCS-CBU-MS-SDC-IIB-SO2

+41-800 848 900

[email protected]

http://www.ietf.org/rfc/rfc3966.txt

http://ws.apache.org/axis/cpp/index.html

http://java.sun.com/

http://ws.apache.org/wss4j/index.html

mailto:[email protected]


8/34

2 General

2.1 Payment modes

2.1.1 One-phase

Since Easypay version 2.1 the default charging mode is one-phase payment mode.

After successful customer authentication and authorization and pass through checkout page without

error, the charging will be effectuated immediately. Nevertheless the reservation transactionId is still

returned to partner application but does not need to be captured.

Please note: In case the partner application still calls capture by passing the reservation

transactionId, this call will be accepted and the response will behave as before, the partner is not

required to change his application.

2.1.2 Two-phase

Two-phase payment mode is normally used in case the service involves content delivery to customer’s

(mobile) device, such as games or ring tone downloads. Only in case of successful content delivery the

customer will be charged.

With the two-phase payment mode the charging process is split into two transactions.

On a purchase request, a reservation for the purchase will be issued first and a reservation transactionId

will be returned to the CP application after successful pass through checkout page (for backward

compatibility reasons this reservation transactionId is also returned to CP application in case of one-phase

payment mode). No charging is effectuated at this stage (in case of subscription service type there is no

active subscription yet).

After successful content delivery to customer device, the CP must commit the reservation transactionId by

calling “chargeReservation” operation to effectively charge the customer for his purchase (in case of

subscription service type, the subscription gets activated). If content delivery is not successful, the previous

reservation might me cancelled by calling release reservation operation. In order to capture or release the

purchase reservation use the signed SAOP web service described in chapter Fehler! Verweisquelle konnte

nicht gefunden werden..

Please note: Two-phase payment mode is available on explicit redirect to Easypay Checkout Service

(see chap 3.1.2) only and must contain the additional extra URL parameter: “capture=false” (see

chapter 3.1.2 (Optional two-phase charging mode requested)). It is not supported on implicit

redirect to checkout page through CE-Proxy.

The following figure shows the detailed purchase flow in case of two-phase payment mode. The flow is the

same for one-phase payment mode, except there is no capture request from CP and instead of charging

reservation the amount is charged on user’s accept purchase() immediately.


9/34

Figure 1: Detailed Purchase Flow from CP Point of View


10/34

2.2 Service Types

2.2.1 Event

In order to charge customer for event service type (default one-payment mode) does require implementing

chapter 3.1 Checkout Service interface only (see also chapter 4.1 Security concerning signing requests).

In case of two-phase charging mode will additionally require implementing chapter 3.2 signed SOAP

interface in order to capture or release purchase reservation transaction.

2.2.2 Subscription (Abo)

Subscription service type requires implementing the same interface as for event service type but

additionally the signed SOAP web service subscription management interface (chapter 3.2) in order to

retrieve active subscriptions and to cancel recurrent subscriptions.

Subscription service type can be recurrent (weekly and monthly only) or non-recurrent.

2.3 Flexible price charging

The price to be charged per service is defined in the price plan. Easypay allows overloading the price

dynamically on each Checkout redirect purchase request allowing a different price to be charged than the

one defined in the price plan. The price is always displayed to the checkout page and must be confirmed by

the customer. This flexible price must be within the allowed price ranges defined in [A].

The price (amount) must always be defined in the Checkout request parameter (see parameter details in

chapter 3.1.1). If the price defined in the Checkout request parameter is different from the price defined in

the price plan, it is considered as flexible price to be charged.

The following table shows the allowed cases for flexible price charging, if flexible price is used in not

allowed case, the price defined in the price plan will be used instead.

Event NonRecurrent

Subscription

Recurrent Subscription Trial Recurrent

Subscription

Allowed amount amount

Not allowed amount amount/ trialAmount

Table 1: Flexible price charging use cases


11/34

2.4 Detection of Access Device

2.4.1 Common Mobile Phones

Swisscom customers accessing a service with a common mobile phone can be identified as Swisscom

customer via WAP-Gateway (Proxy Mode) in case of presence of “via” http header allowing the customer to

be redirected to Easypay checkout service (http) directly to allow WAP purchase use case (without PIN

token authentication).

Important: In this case, please redirect to checkout URL using http (not https) in order to add the

msisdn to the http request headers. Otherwise the checkout page will behave like a WEB use case.

2.4.2 Smartphones

If the customer uses a smartphone which connects through mobile network (Non Proxy Mode, i.e. iPhone)

he can be identified as Swisscom customer by checking the remoteAddr being within global outside ranges

178.197.232.1-178.197.232.128 / 178.197.233.1-178.197.233.128 / 178.197.234.1-178.197.234.128

allowing the customer to be redirected to Easypay checkout service (https) directly to allow WAP purchase

use case (without PIN token authentication).

Important: In this case, please redirect to checkout URL using https. The checkout service will

detect the msisdn.

2.5 Guideline for implementing Interfaces

The following table gives an easy overview on which chapters need to be implemented depending on the

particular use case (e.g. if a CP wants to implement events to his customers, he needs only to implement

the interface according to chapter 3.1.

Usecase One-phase payment Two-phase payment

Events 3.1 (HTTP GET) 3.1 (HTTP GET)

3.2 (signed SOAP)

Subscriptions 3.1 (HTTP GET)

3.2 (signed SOAP)

3.1 (HTTP GET)

3.2 (signed SOAP)

Table 2: Guideline for implementing interfaces


12/34

3 Interface Description

3.1 Checkout Service Interface

Implementing this interface enables the CP application to call the Easypay checkout page

Please note: This gives the CP system the advantage to send more configuration parameters to

Easypay checkout page compared to the implicit call through CE Proxy.

Also this is the only supported way to still use two-phase payment charging mode by appending

corresponding optional parameter to Checkout URL (see chapter 3.1.2)

3.1.1 Reserve Request (Checkout Service) Parameter

The JSON checkoutRequestItem document has the following parameter

Please note: currently only JSON message format is supported; parameter name are case-

sensitive).

Parameter Required Type Description Further Information

adultContent Mandatory Boolean:

true/false

For a purchase request the CP must

provide this flag indicating the content

type:

Adult

Non Adult

Used for the reservation of the

subscription purchase.

Standard today is > 16.

billingText Mandatory String:

approx. 30

characters


provide the billing Text for the

purchased service.

billingText must not contain any of the

following characters:

! " % & ' ( ) ; < > [ ] { } ,



The billingText is displayed on the

checkout page, the notification sms,

in the customer center and on the

itemized bill.

contentPartnerId Mandatory String The ID assigned by Swisscom to each CP.

contentPartnerServiceId Mandatory String For a purchase request, the CP must

provide the contentPartnerServiceId


subscription purchase

requestId Mandatory String Identification of the request. The

response will contain the same

identification.

roaming Mandatory Boolean:

true/false


provide this flag indicating if the content

is allowed to be purchased abroad



serviceUrl Mandatory String CP URL redirected to with Reserve


13/34

Response parameters.

serviceErrorUrl Mandatory String CP URL redirected to in case of error

occurrence during customer

authorization and charging including

encoded error details as URL parameter.

If set as “null”, the error detail

parameter will be added and

redirected to serviceUrl.

cancelUrl Mandatory String CP URL redirected to if the customer hits

the cancel button on the Easypay

checkout page. Reason = cancellation

will be added encoded as parameter to

this URL.

If set as “null”, the cancellation

reason will be added and redirected

to serviceUrl.

transactionType Mandatory String Type of the Transaction:

Event

Recurrent

NonRecurrent

Trial

Only Week and Month durations may

be Recurrent.

amount Mandatory String The amount to be charged. Flexible price charging feature:

amount might be different to the

amount defined in price plan (not

supported for recurrent or trial

offers)

durationUnit Optional Integer The durationUnit may be:

Minute

Day

Week

Month

Mandatory in case of recurrent or

nonrecurrent subscription.

Only Week and Month may be

Recurrent.

Yearly subscriptions on request.

duration Optional Integer The duration of the authorized usage

normally is “1”.

Mandatory in case of recurrent or

nonrecurrent subscription.

currency Optional String The amount currency (Standard: CHF) Please note: This feature is not

supported yet.

trialAmount Optional String The trialAmount to be charged.

userLanguage Optional String The user language: de / fr / it

Table 3: Parameter for Reserve Request

3.1.2 Checkout Service URL

The parameters in Table 3 need to be in case sensitive JSON message format (see examples in chapter

3.1.3.1), base64 and URL encoded (see example in chapter 4.1.2.1) and sent together with base64/URL

encoded signature via HTTPS redirect to Easypay checkout service:

Production URL:

https://tpe.swisscom.ch/checkout/CheckoutPage.seam?signature=<base64/URL encoded

signature>&checkoutRequestItem=<base64/URL encoded checkoutRequestItem>


14/34

Staging URL:

https://tpe-staging.swisscom.ch/checkout/CheckoutPage.seam?signature=...

Optional two-phase charging mode requested:

The extra optional URL parameter must be added to the URL:

https://tpe.swisscom.ch/checkout/CheckoutPage.seam?signature=<base64/URL encoded

signature>&checkoutRequestItem=<base64/URL encoded checkoutRequestItem>&capture=false

3.1.3 Reserve Response Parameter

The Checkout response consists of encoded URL parameter added to the CP serviceUrl, serviceErrorUrl or

cancelUrl respectively. The following parameter will be added to the URL:

- requestId

- reservationId

- signature =<signed base64 encoded HMAC of the json document> (see chapter 4)

- checkoutResponseItem =<base64 encoded json document> (see chapter 4)

This base64 –encoded JSON checkoutResponseItem document has the following parameter:

Parameter Required Type Description Further Information

requestId Mandatory String Identification of the request. Can be

used to correlate the response to the

request.

Same as added to serviceUrl above.

reservationIdentifier Mandatory String Identifier of the successful reservation.

The reservationIdentifer is used for the

capture or the release in phase 2 of two-

phase purchase process.

Is present in successful reservation

Same as added to serviceUrl above.

userIdentification Optional Integer Today: MSISDN

Exception Optional String Is present in not successful reservation

Reason Optional String Is present in not successful reservation

ExceptionType Optional String Possible Values:

PolicyException

ServiceException

RemoteException

Is present in not successful reservation

Table 4: Parameter from Reserve Response


15/34

JSON message examples

3.1.3.1 Reserve Request

A) Event Offer

{"contentPartnerServiceId": "video1",

“transactionType”: ”Event”,

"adultContent": "false",

“roaming”: “false”,

"billingText": "Video download",

"contentPartnerId": "muster",

“requestId”:”20100817113458123”,

"serviceUrl": "http://partner.service.url",

"serviceErrorUrl": "null",

“cancelUrl”: “null”

“amount”: “1.00”}

B) Subscription Offer

{

"contentPartnerServiceId": "video1",

“transactionType”: ”Recurrent

“duration”: 1,

“durationUnit”: ”Month”,

"adultContent": "true",

“roaming”: “true”,

"billingText": "3 for 2 Music",


“requestId”: ”20100817113458123”,

"serviceUrl": "http://partner.service.url",

"serviceErrorUrl": "null",

“cancelUrl”: “null”

“amount”: “1.00”}

http://partner.service.url/

http://partner.service.url/


16/34

C) Trial Subscription Offer

{

"contentPartnerServiceId": "video2",

“transactionType”: ”Trial”

“duration”: 1,

“durationUnit”: ”Week”,

"adultContent": "false",

“roaming”: “true”

"billingText": "3 for 2 Music",

"amount": "2.00",

“trialAmount”: “0.00”


“requestId”: ”20100817113458123”,

"serviceUrl": "http://service.url",

"serviceErrorUrl": "http://service.error.url",

“cancelUrl”: “http://cancel.url”

}

Please note: A TRIAL can be subscribed only 1 single time per MSISDN. Hence the partner

application needs to track the MSISDN’s already has subscribed to TRIAL offer on given service.

Trying to subscribe twice for same MSISDN will result in error calling the Checkout Service.

3.1.3.2 Reserve Response

{

“requestId”: ”20100817113458123”,

“reservationIdentifier”: “123456”,

“userIdentification” :”41796667788”

}

http://service.url/

http://service.error.url/


17/34

3.2 Subscription Management (signed SOAP)

This interface offers methods to manage subscriptions. The interface is split into 2 parts described below.

Please note: For Parameter definitions refer to chapter 3.3

Part 1 ChargingEnablerSubscriptionsServicePort

(request or cancel (recurrent) active subscriptions)

WSDL location: https://tpe-staging.swisscom.ch/wsdl/charging_enabler_subscriptions_service.wsdl

Service URL Staging: https://tpe-staging.swisscom.ch/ws/ce/ChargingEnablerSubscriptionsServicePort

Service URL Production: https://tpe.swisscom.ch/ws/ce/ChargingEnablerSubscriptionsServicePort

Method Parameter Return Client Description

retrieveActiveSubscriptions endUserIdentifer

contentPartnerId

Subscripiton[] CE Proxy

CP portal

Retrieve active subscriptions

for a given MSISDN and CP

cancelRecurrentSubscription endUserIdentifier

contentPartnerId

subscriptionId

void CP portal Cancel a recurrent

subscription

(Only possible for recurrent

subscriptions)

retrieveActiveSubscriptionsByS

erviceId

endUserIdentifier

contentPartnerId

contentPartnerServiceId

Subscription CP portal Retrieve active subscription

of a subscriber which

contains the requested

service.

Table 5: Charging Enabler Subscriptions methods

https://tpe-staging.swisscom.ch/wsdl/charging_enabler_subscriptions_service.wsdl

https://tpe-staging.swisscom.ch/ws/ce/ChargingEnablerSubscriptionsServicePort

https://tpe.swisscom.ch/ws/ce/ChargingEnablerSubscriptionsServicePort


18/34

3.2.1 Request Example

Content-Length: 469

Host: localhost:8088

User-Agent: Jakarta Commons-HttpClient/3.0.1

SOAPAction: "urn:retrieveActiveSubscriptions"

Content-Type: text/xml;charset=UTF-8

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"

xmlns:int="http://www.swisscom.com/contentdelivery/payment/subscriptions/interf

ace">

<soapenv:Header/>

<soapenv:Body>

<int:retrieveActiveSubscriptions>

<int:endUserIdentifier>tel:+41-79-1234567</int:endUserIdentifier>

<int:contentPartnerId>muster</int:contentPartnerId>

</int:retrieveActiveSubscriptions>

</soapenv:Body>

</soapenv:Envelope>

http://schemas.xmlsoap.org/soap/envelope/

http://www.swisscom.com/contentdelivery/payment/subscriptions/interface



19/34

3.2.2 Response Example

HTTP/1.1 200 OK

Date: Thu, 20 Nov 2008 14:17:18 GMT

Server: Apache-Coyote/1.1

Transfer-Encoding: chunked


xmlns:xsd="http://www.w3.org/2001/XMLSchema"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

<soapenv:Body wsu:Id="id-8317576" xmlns:wsu="http://docs.oasis-

open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">

<retrieveActiveSubscriptionsResponse

xmlns="http://www.swisscom.com/contentdelivery/payment/subscriptions/interf

ace">

<out>

<ns1:Subscription xsi:type="ns1:Subscription"

xmlns:ns1="http://www.swisscom.com/contentdelivery/payment/types/ext1">

<ns1:subscriptionId>111</ns1:subscriptionId>

<ns1:contentPartnerPackageId>testServiceA</ns1:contentPartnerPackageId

>

<ns1:contentPartnerServiceId>testServiceA</ns1:contentPartnerServiceId

>

<ns1:expireDate>2008-11-21T22:59:59.000Z</ns1:expireDate>

<ns1:purchaseDate>2008-11-01T14:04:25.000Z</ns1:purchaseDate>

<ns1:renewalDate>2008-11-19T23:10:02.000Z</ns1:renewalDate>

<ns1:offerId>testServiceA__X__package:testServiceA_TAX_3_8_999_999_999

_*_*_*_

false_false</ns1:offerId>

<ns1:isOfferRecurrent>true</ns1:isOfferRecurrent>

</ns1:Subscription>

<ns2:Subscription xsi:type="ns2:Subscription"

xmlns:ns2="http://www.swisscom.com/contentdelivery/payment/types/ext1">

<ns2:subscriptionId>112</ns2:subscriptionId>

<ns2:contentPartnerPackageId>testServiceB</ns2:contentPartnerPackageId

>

<ns2:contentPartnerServiceId>testServiceB</ns2:contentPartnerServiceId

>

<ns2:expireDate>2008-11-13T08:46:45.000Z</ns2:expireDate>

<ns2:purchaseDate>2008-11-13T08:46:45.000Z</ns2:purchaseDate>

<ns2:offerId>testServiceB__X__package:testServiceB_TAX_1_1_999_999_999

_*_*_*_

false_false</ns2:offerId>

<ns2:isOfferRecurrent>false</ns2:isOfferRecurrent>

</ns2:Subscription>

</out>

</retrieveActiveSubscriptionsResponse>

</soapenv:Body>

</soapenv:Envelope>

http://schemas.xmlsoap.org/soap/envelope/

http://www.w3.org/2001/XMLSchema

http://www.w3.org/2001/XMLSchema-instance

http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd

http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd



http://www.swisscom.com/contentdelivery/payment/types/ext1

http://www.swisscom.com/contentdelivery/payment/types/ext1


20/34

Part 2 ReserveAmountCharging

(confirm or release reserved purchase transaction in case of two phase payment mode see chapter 2.1.2)

WSDL location:

https://tpe-staging.swisscom.ch/wsdl/parlayx_payment_reserve_amount_charging_service_3_1.wsdl

Service URL Staging: https://tpe-staging.swisscom.ch/ws/ce/ReserveAmountCharging

Service URL Production: https://tpe.swisscom.ch/ws/ce/ReserveAmountCharging

Method Parameter Return Client Description

chargeReservation reservationIdentifier

charge

referenceCode

void CP portal confirm the reservation in

case of two phase payment

mode

releaseReservation reservationIdentifier void CP portal Release the reservation in

case of two phase payment

mode

Table 6: Reserve Amount Charging methods

https://tpe-staging.swisscom.ch/ws/ce/ReserveAmountCharging

https://tpe.swisscom.ch/ws/ce/ReserveAmountCharging

21/34

3.2.3 Request Example

Host: localhost:8088

Content-Length: 887

SOAPAction: ""

User-Agent: Jakarta Commons-HttpClient/3.0.1



xmlns:loc="http://www.csapi.org/schema/parlayx/payment/reserve_amount_charg

ing/v3_1/local">

<soapenv:Header/>

<soapenv:Body>

<loc:chargeReservation>

<loc:reservationIdentifier>1234</loc:reservationIdentifier>

<loc:charge>

<description>anything</description>



<currency></currency>



<amount></amount>



<code>urn:scm:easypay:contentPartnerId:WAP:ALL:testService1:

testService1:5:Minute:NonRecurrent</code>

</loc:charge>

<loc:referenceCode>urn:scm:easypay:contentPartnerId:f81d4fae-7dec-

11d0-a765-00a0c91e6bf6:NewsTV:News%2022-Nov-

2007:A123456789</loc:referenceCode>

</loc:chargeReservation>

</soapenv:Body>

</soapenv:Envelope>

3.2.4 Response Example

HTTP/1.1 200 OK

Date: Wed, 08 Apr 2009 08:55:20 GMT

Connection: Close


X-Powered-By: Servlet/2.5 (Winstone/0.9.10)

Server: Winstone Servlet Engine v0.9.10


xmlns:xsd="http://www.w3.org/2001/XMLSchema"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

<soapenv:Body wsu:Id="id-21721682" xmlns:wsu="http://docs.oasis-

open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">

<chargeReservationResponse

xmlns="http://www.csapi.org/schema/parlayx/payment/reserve_amount_charging/

v3_1/local"/>

</soapenv:Body>

</soapenv:Envelope>


22/34

3.3 Parameter Definitions

In this chapter the definition of the method parameters and their types are shown. This service follows the

tel-URI standard (RFC 3966) [1]. The “EndUserIdentifier” must use the “tel” scheme. This scheme supports

MSISDN and IMSI numbers.

Example of the syntax:

tel:+41-79-1234567” for a MSISDN or

tel:-;imsi=228011234567890” for a Swisscom IMSI

Enumeration value Description MSISDN User Identity via MSISDN.

IMSI User Identity via IMSI.

UUID User Identity via UUID as defined in ITU X.667

SESSIONID User Identity via Session ID as defined in W3C WD-session-id

Table 7: EndUserIdentifier (SOAP parameter-name: endUserIdentifier)

Please note that UUID and SESSIONID are not supported yet.

Element name Element type Optional Description description xsd:string No Description text used for information and billing text

currency xsd:string Yes Currency identifier as defined in ISO 4217.

Only set value if discrete price charging is enabled (see

chapter Fehler! Verweisquelle konnte nicht gefunden

werden.), otherwise leave empty

amount xsd:decimal Yes Amount to be charged.

Only set value if discrete price charging is enabled (see

chapter Fehler! Verweisquelle konnte nicht gefunden

werden.), otherwise leave empty

code xsd:string No Charging code, referencing a contract under which the

charge is applied, see syntax in next table

Table 8: Charging Information (SOAP Parameter Name: charge)


23/34

Part name Part type Optional Description Example urn xsd:string No The identifier of URI urn

serviceProvider xsd:string No The service provider for charging

service

scm

enabler xsd:string No The enabler for the provided

services

easypay

conentPartnerId xsd:string No The partner ID as defined by

Swisscom

ContentPartnerId

accessChannel xsd:string No The access channel of the

request. WEB, WAP, SMS, MMS,

POS

WAP

userGroup xsd:string

(UserGroup

enumeration)

No Use “ALL” by default. ALL

serviceId xsd:string Yes The service Id as defined by the

pricing tool.

SERVICE_1

packageId xsd:string Yes The package Id as defined by

pricing tool for the package that

is purchased. It must contain the

service identified by the serviceId.

The packageId may be empty if

the serviceId is set and the

related package has been bought

by the end customer in a previous

transaction and is still valid.

SERVICE_1

duration xsd:int Yes The duration of the subscription

identified by the packageId. For

events no duration.

1

durationTimeUnit xsd:string

(TimeMetrics

Enumeration)

Yes The unit of duration of the

subscription identified by the

packageId. For events there is no

durationTimeUnit.

Month

recurrent xsd:string

(Recurrency

Enumeration)

Yes The recurrency flag of the

subscription

Recurrent,

NonRecurrent,

Event

restrictions xsd:string

(0..unbounded)

Yes Optional restrictions: MinAge16,

MinAge18, NonRoaming (Service

is not allowed in roaming

conditions), colons.

MinAge16,

MinAge18,

NonRoaming


24/34

Table 9: code (Part of Charging Information, see Table 12: Charging Information (SOAP Parameter Name: charge))

All part names must be separated by colons.

Part name Part type Optional Description Example urn xsd:string No The identifier of the URI urn

serviceProvider xsd:string No The service provider for charging

service.

scm

enabler xsd:string No The enabler for the provided

services.

easypay

contentPartnerId xsd:string No The partner ID as defined by the

service provider.

ContentPartnerId

GUID xsd:string No A unique UID in the namespace of

the partner.

f81d4fae-7dec-11d0-

a765-00a0c91e6bf6

contentCategory xsd:string Yes The content category for the

content to be delivered.

NewsTV

contentItem xsd:string Yes The content item delivered to the

subscriber. No colons and

whitespace characters allowed.

String must be HTML escaped.

News%2022-Nov-2007

assetId xsd:string Yes The asset ID of the content. A123456789

Table 10: Reference Code (SOAP Parameter Name: referenceCode)

All part names must be separated by colons. So the examples of above table results in the

following URI:

“urn:scm:easypay:ContentPartnerId:f81d4fae-7dec-11d0-a765-00a0c91e6bf6:NewsTV:

News%2022-Nov-2007:A123456789”

The URIs are case sensitive.

Part name Part type Optional Description Example reservationIdentifier xsd:string No The subscription

reservationIdentifier

1234

Table 11: Reservation Identifier (SOAP Parameter Name: ReservationIdentifier)

The “reservationIdentifier” is the return value of the Checkout Response discussed in chapter 3.1.3


25/34

4 Security

4.1 Secure Checkout Service (used in chapter 3.1)

Two threats are of special interest here:

1. The user could manipulate the price

2. The user could pretend to the CP a successful charge reservation

For fighting both threats a standard Message Authentication Code is passed as a parameter.

Swisscom and the CP share a secret key. The CP creates this Message Authentication Code and passes it

with the offer data to protect the price. Swisscom creates a Message Authentication Code (MAC) and

passes it with the “Purchase Proof” to protect the transaction token.

HMAC SHA-1 is the cryptographic method used. This method is supported by libraries for all popular

programming languages.

The shared secret key is sent to the CP once the integration to Easypay is started. This secret key will be sent

to CP by Swisscom Partner Integration. The secret key has to be stored in the CP configuration and must

not be shared with any other party.

4.1.1 Message Authentication Code (MAC)

This chapter contains examples and further information on Message Authentication Code (MAC). Very

similar automatism of securing messages can be found on amazon.com developer page:

http://docs.amazonwebservices.com/AmazonS3/latest/dev/

The following illustration has been copied from above link to show how it works. This AWS (in this case

from Amazon) is similar to the one from Easypay (except with Easypay only the Secret Access Key is used.

The Access Key ID mentioned in the pictures below corresponds to the “contentPartnerId” (see chapter

1.4.1):

Below the general steps for authenticating requests to AWS is described. It is assumed that the CP has

already created an AWS account and received an Access Key ID as well as a Secret Access Key.

http://docs.amazonwebservices.com/AmazonS3/latest/dev/


26/34

Figure 2: Steps for authenticating requests to AWS

1. Construct a request to AWS.

2. Calculate a keyed-hash message authentication code (HMAC) signature using your Secret Access

Key.

3. Include the signature and your Access Key ID in the request, and then send the request to AWS.

AWS performs the next three steps.


27/34

Figure 3: Steps for signature generated by AWS

4. AWS uses the Access Key ID to look up your Secret Access Key.

5. AWS generates a signature from the request data and the Secret Access Key using the same

algorithm used to calculate the signature the CP sent in the request.

6. If the signature generated by AWS matches the one you sent in the request, the request is

considered authentic. If the comparison fails, the request is discarded and AWS returns an error

response.

4.1.2 Using Base64 Encoding

HMAC request signatures must be Base64 encoded. Base64 encoding converts the signature into a simple

ASCII string that can be attached to the request. Two characters, plus (+) and forward slash (/), cannot be

used directly and must be encoded if used in a URI. For example, if the authentication code includes a plus

(+) sign, encode it as %2B; in the request. Encode a forward slash as %2F;.


28/34

4.1.2.1 Example

This sample has been created using java and library from apache commons-codec version 1.4

Assuming the CP secret key is:

/QHccpbYHDXNRYXjsP/oNtKbS6o7+Zr643mmV39qg

Assuming the CP “contentPartnerId” is:

muster

Assuming the JSON message to be signed would be:

{\"contentPartnerServiceId\": \"video1\", \"transactionType\": \"Event\", \"adultContent\": \"false\",

\"roaming\": \"false\", \"billingText\": \"Video download\", \"contentPartnerId\": \"muster\",

\"requestId\":\"20100817113458123\", \"serviceUrl\": \"http://service.url\", \"serviceErrorUrl\":

\"null \", \"cancelUrl\": \"null\"}

The resulting (base64URLSafe) signature is: _V44CXtzTgtfAK-lfu-F5822B5U

The resulting (base64) checkoutRequestItem is: eyJjb250ZW50UGFydG5lclNlcnZpY2VJZCI6ICJ2aWRlbzEiLCAidHJhbnNhY3Rpb25UeXB

lIjogIkV2ZW50IiwgImFkdWx0Q29udGVudCI6ICJmYWxzZSIsICJyb2FtaW5nIjogImZhbH

NlIiwgImJpbGxpbmdUZXh0IjogIlZpZGVvIGRvd25sb2FkIiwgImNvbnRlbnRQYXJ0bmVyS

WQiOiAibXVzdGVyIiwgInJlcXVlc3RJZCI6IjIwMTAwODE3MTEzNDU4MTIzIiwgInNlcnZp

Y2VVcmwiOiAiaHR0cDovL3NlcnZpY2UudXJsIiwgInNlcnZpY2VFcnJvclVybCI6ICJudWx

sICIsICJjYW5jZWxVcmwiOiAibnVsbCJ9

This needs to be URL encoded now:

_V44CXtzTgtfAK-lfu-F5822B5U

eyJjb250ZW50UGFydG5lclNlcnZpY2VJZCI6ICJ2aWRlbzEiLCAidHJhbnNhY3Rpb

25UeXBlIjogIkV2ZW50IiwgImFkdWx0Q29udGVudCI6ICJmYWxzZSIsICJyb2FtaW

5nIjogImZhbHNlIiwgImJpbGxpbmdUZXh0IjogIlZpZGVvIGRvd25sb2FkIiwgImN

vbnRlbnRQYXJ0bmVySWQiOiAibXVzdGVyIiwgInJlcXVlc3RJZCI6IjIwMTAwODE3

MTEzNDU4MTIzIiwgInNlcnZpY2VVcmwiOiAiaHR0cDovL3NlcnZpY2UudXJsIiwgI

nNlcnZpY2VFcnJvclVybCI6ICJudWxsICIsICJjYW5jZWxVcmwiOiAibnVsbCJ9


29/34

4.1.2.2 Coding Example

Below you’ll find an example of a signing process for the Amazon Storage Cloud:

import sys

import chilkat

# This example uses sample data from:

# http://docs.amazonwebservices.com/AmazonS3/2006-03-

01/RESTAuthentication.html

strToSign = "GET" + "\n" + "\n" + "\n" + "Tue, 27 Mar 2007 19:36:42 +0000" +

"\n" + "/johnsmith/photos/puppy.jpg"

crypt = chilkat.CkCrypt2()

success = crypt.UnlockComponent("Anything for 30-day trial.")

if (success != True):

# Unlock Failed.

print crypt.lastErrorText()

sys.exit()

# We want SHA1 for the HMAC hash algorithm:

crypt.put_HashAlgorithm("sha1")

AWSAccessKeyId = "0PN5J17HBGZHT7JJ3X82"

AWSSecretAccessKey = "uV3F3YluFJax1cknvbcGwgjvx4QpvB+leU8dUj2o"

# Set the HMAC secret key:

crypt.SetHmacKeyString(AWSSecretAccessKey)

# By setting the charset = "utf-8", the string will be converted

# to utf-8 (internal to the Chilkat component) prior to signing:

crypt.put_Charset("utf-8")

# Indicate that Base64 output is desired:

crypt.put_EncodingMode("base64")

signature = crypt.hmacStringENC(strToSign)

print crypt.lastErrorText()

# Display the signature as part of the HTTP Authorization header:

print "Authorization: AWS " + AWSAccessKeyId\

+ ":" + signature

print "Expected: AWS 0PN5J17HBGZHT7JJ3X82:xXjDGYUmKxnwqr5KXNPGldn5LbA="

http://www.chilkatsoft.com/refdoc/pythonCkCrypt2Ref.html


30/34

For JAVA the following code could be used to get URL safe signature (using apache commons-codec library

version 1.4):

import org.apache.commons.codec.binary.Base64

import javax.crypto.Mac

import javax.crypto.spec.SecretKeySpec

public static String getSignature(final String source, final String key) {

if (key == null) {

throw new IllegalArgumentException("key cannot be null");

}

Mac mac = null;

try {

mac = Mac.getInstance("HmacSHA1");

mac.init(new SecretKeySpec(key.getBytes(),"HmacSHA1"));

} catch (Exception e) {

throw new RuntimeException(e);

}

final byte[] result = mac.doFinal(source.getBytes());

final String signature = new String(Base64.encodeBase64URLSafe(result));

return signature;

}

4.2 Sign SAOP Requests (used in chapter 3.2)

The SOAP communication over the CE Service web service interface is done over HTTPS. Each request must

be signed using WSS4J [4]. The key store for this has to be generated by the CP and the public key

certificate must be provided to Swisscom Provider Support. If needed, Swisscom can also generate a key

store for the CP. If the CP already has a certificate issued by signing authority, this can be used for Easypay

integration, in this case the public key certificate must be provided to Swisscom Provider Support when

applying for contract.


31/34

The Swisscom server certificate (stanton.server.cer) delivered by Swisscom (PartnerIntegration)

must be included in the CP keystore.

4.3 Creating a self signed Certificate

The following java tool delivered with JDK in “JDK/bin/keytool.exe” can be used to create a keystore that

will be used for signing the webservice SOAP messages:

The “contentPartnerId” will be provided by Partner Integration of Swisscom (please replace all

brackets)

The password for “–keypass” and “–storepass” must be the same.

How to proceed (please replace all squared brackets with your values) :

1) keytool -genkey -alias <partnererID>

-keypass <your_keystore_password>

-dname "cn=<partnererID>, O=<your_company>, C=ch"

-keyalg "RSA"

-keysize 2048

-validity 730

-keystore <your_keystore>.jks

-storepass <your_keystore_password>

2) keytool -selfcert -alias <partnererID>


-dname "cn=<partnererID>, O=<your_company>, C=ch"

-keyalg "RSA"

-keysize 2048

-validity 730



Extracting the certificate that needs to be sent to Swisscom Partner Integration:

3) keytool -export -alias <partnererID>


-file <certificate_name>.cer



Finally you need to import the Swisscom public key, which you will receive from our Provider Support, into

your created keystore:


32/34

4) keytool -import -alias stanton.server

-file stanton.server.cer



The keystore can be examined using the following command:

keytool -list -v -keystore <your_keystore>.jks –storepass <your_keystore_password>


33/34

5 Error ID’s List

The following error ID’s were defined for system and business exceptions on CE Service:

Error ID Description Severity

SVC0002 Invalid input value for CE Service interface (invalid method parameter) ERROR

SVC0007 Invalid charging information ERROR

SVC1001 Some system- or server side problem takes place FATAL

SVC1002 Some system- or server side problem takes place. Temporary error: typically another system

which is used by CE Service is temporary not reachable

ERROR

SVC1003 Mandatory user identifier in header is missing in request. This is probably due to a WAP

Gateway error (only in CE Proxy)

ERROR

SVC1004 Error retrieving attributes for Third Parties. Could be a database connection error FATAL

SVC1005 Needed resource not found (required parameter missing in method call) ERROR

SVC1006 Error while requesting user information from subsystem. Retry after delay possible ERROR

SVC1007 Error while writing price plan or catalog file to system ERROR

SVC1008 Error while requesting user information from subsystem. Retry after delay possible ERROR

POL1001 CP is not authorized to use the requested function POLICY VIOLATION

POL1002 Credit check failed. The end customer has not sufficient credit to purchase the service POLICY VIOLATION

POL1003 The end customer is not authorized to purchase a service because of his age POLICY VIOLATION

POL1004 The end customer is not authorized to purchase service because he is banned or not allowed

to watch premium content

POLICY VIOLATION

POL1005 Bearer is not supported. The end customer is not authorized to use service because the

bearer is not supported

POLICY VIOLATION

POL1006 Roaming not supported. The end customer is not authorized to use service because he is

roaming at the time

POLICY VIOLATION

POL1007 Handset blocked. The end customer is not authorized to use service because his handset is

not supported

POLICY VIOLATION

POL1008 Telco not supported. The end customer is not authorized to use service because he is not a

Swisscom customer

POLICY VIOLATION

POL1010 CP service not available. The requested service is not available POLICY VIOLATION

POL1011 The requested offer is not available POLICY VIOLATION

POL1012 Unknown CP URL. The requested URL is not valid. POLICY VIOLATION

POL1013 The purchase transaction has not been committed or released due to timeout or other

reason

POLICY VIOLATION

POL1014 The subscription cannot be cancelled. Either the subscription does not exist, is not recurrent

or has already been cancelled

POLICY VIOLATION

POL1015 The end customer is blocked for premium services POLICY VIOLATION

POL1016 The end customer is blocked for adult content POLICY VIOLATION


34/34

POL1017 Direct request to proxy leads to endless loop and is therefore forbidden POLICY VIOLATION

POL1018 Unexpected business error POLICY VIOLATION

POL1019 Missing offerId in request. (CE Proxy policy violation) POLICY VIOLATION

POL1020 Missing billing text in request. (CE Proxy policy violation) POLICY VIOLATION

POL1021 Missing CP service id in request. (CE Proxy policy violation) POLICY VIOLATION

POL1022 Missing CP id in request. (CE Proxy policy violation) POLICY VIOLATION

POL1023 Missing MSISDN in request. (CE Proxy policy violation) POLICY VIOLATION

POL1024 Missing subscriptionId in request. POLICY VIOLATION

POL1025 Missing transactionId in request POLICY VIOLATION

POL1026 The package does not support two phase payment POLICY VIOLATION

POL1027 The subscription already exists. POLICY VIOLATION

POL1028 Easypay authorization does not succeed: End customer is not authorized to subscribe/use

particular service. The reason is not enough credit on customer's account (Payment failed).

POLICY VIOLATION

POL1029 The requested package is not found POLICY VIOLATION

POL1030 The requested price point is not found POLICY VIOLATION

POL1031 Price plan XML files cannot be parsed. Either invalid or not complete POLICY VIOLATION

POL1032 The mandatory parameter URL is blank. POLICY VIOLATION

POL1033 The mandatory parameter URL does not represent a valid URL POLICY VIOLATION

POL1034 The Top Stop amount has been reached. The end customer has reached the highest monthly

purchase amount possible

POLICY VIOLATION

POL1035 The VAS spending limit has been reached POLICY VIOLATION

POL1036 Fraud detection. The transmitted CP id does not match the certificate CP id POLICY VIOLATION

POL1037 The requested service s not found POLICY VIOLATION

POL1038 The requested subscriber is not found POLICY VIOLATION

POL1039 The subscription for the requested service is not found. To use the service the end customer

has to purchase at least one package containing the service

POLICY VIOLATION

POL1040 The barring state has been reached. The end customer cannot purchase anymore POLICY VIOLATION

POL1041 Reservation identifier expired. Redo reservation POLICY VIOLATION

POL1044 The CP is not allowed to use discrete price charging POLICY VIOLATION

POL1045 No valid price range for discrete amount existing, the amount might be to large POLICY VIOLATION

POL1048 Invalid transactioType in request POLICY VIOLATION

POL1049 Invalid duration in request POLICY VIOLATION

POL1050 Invalid durationUnit in request POLICY VIOLATION

POL1051 Missing adultContent flag in request POLICY VIOLATION

Table 12: List of Error IDs