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
Easypay Interface Documentation.doc
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
Easypay Interface Documentation.doc
3/34
5 Error ID’s List .................................................................................................................................................... 33
Easypay Interface Documentation.doc
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
Easypay Interface Documentation.doc
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.
Easypay Interface Documentation.doc
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
Easypay Interface Documentation.doc
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
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
Easypay Interface Documentation.doc
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.
Easypay Interface Documentation.doc
9/34
Figure 1: Detailed Purchase Flow from CP Point of View
Easypay Interface Documentation.doc
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
Easypay Interface Documentation.doc
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
Easypay Interface Documentation.doc
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
For a purchase request the CP must
provide the billing Text for the
purchased service.
billingText must not contain any of the
following characters:
! " % & ' ( ) ; < > [ ] { } ,
Used for the reservation of the
subscription purchase.
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
Used for the reservation of the
subscription purchase
requestId Mandatory String Identification of the request. The
response will contain the same
identification.
roaming Mandatory Boolean:
true/false
For a purchase request the CP must
provide this flag indicating if the content
is allowed to be purchased abroad
Used for the reservation of the
subscription purchase.
serviceUrl Mandatory String CP URL redirected to with Reserve
Easypay Interface Documentation.doc
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>
Easypay Interface Documentation.doc
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
Easypay Interface Documentation.doc
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",
"contentPartnerId": "muster",
“requestId”: ”20100817113458123”,
"serviceUrl": "http://partner.service.url",
"serviceErrorUrl": "null",
“cancelUrl”: “null”
“amount”: “1.00”}
Easypay Interface Documentation.doc
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”
"contentPartnerId": "muster",
“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”
}
Easypay Interface Documentation.doc
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
Easypay Interface Documentation.doc
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>
Easypay Interface Documentation.doc
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
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
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>
Easypay Interface Documentation.doc
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
Easypay Interface Documentation.doc
21/34
3.2.3 Request Example
Host: localhost:8088
Content-Length: 887
SOAPAction: ""
User-Agent: Jakarta Commons-HttpClient/3.0.1
Content-Type: text/xml;charset=UTF-8
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
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>
<!--Optional:-->
<currency></currency>
<!--Optional:-->
<amount></amount>
<!--Optional:-->
<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
Content-Type: text/xml;charset=UTF-8
X-Powered-By: Servlet/2.5 (Winstone/0.9.10)
Server: Winstone Servlet Engine v0.9.10
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
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>
Easypay Interface Documentation.doc
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)
Easypay Interface Documentation.doc
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
Easypay Interface Documentation.doc
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
Easypay Interface Documentation.doc
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.
Easypay Interface Documentation.doc
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.
Easypay Interface Documentation.doc
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;.
Easypay Interface Documentation.doc
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
Easypay Interface Documentation.doc
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="
Easypay Interface Documentation.doc
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.
Easypay Interface Documentation.doc
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>
-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>
Extracting the certificate that needs to be sent to Swisscom Partner Integration:
3) keytool -export -alias <partnererID>
-keypass <your_keystore_password>
-file <certificate_name>.cer
-keystore <your_keystore>.jks
-storepass <your_keystore_password>
Finally you need to import the Swisscom public key, which you will receive from our Provider Support, into
your created keystore:
Easypay Interface Documentation.doc
32/34
4) keytool -import -alias stanton.server
-file stanton.server.cer
-keystore <your_keystore>.jks
-storepass <your_keystore_password>
The keystore can be examined using the following command:
keytool -list -v -keystore <your_keystore>.jks –storepass <your_keystore_password>
Easypay Interface Documentation.doc
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
Easypay Interface Documentation.doc
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
Top Related