WMPay RESTful webservice Web Single Payment Germany Specification API documentation
←
→
Page content transcription
If your browser does not render page correctly, please read the page content below
WMPay API
WMPay RESTful webservice
Web Single Payment Germany Specification
API documentation
whatever mobile GmbH
Version 0.5WMPay RESTful webservice
Table of contents
1. WMPay REST Interface Documentation ............................................................... 3
1.1. Definition of terms .................................................................................................................... 3
2. Flow Definitions ......................................................................................................... 4
2.1. Web Single Payment ................................................................................................................. 4
2.1.1. Web Single Payment – successful flow - Operator sends TAN ............................ 5
2.1.2. Web Single Payment – successful flow – WM sends TAN ...................................... 6
2.1.3. Web Single Payment – authorization fails ................................................................... 7
2.1.4. Web Single Payment – End customer cancels transaction ................................... 8
3. Protocol of Transmission ......................................................................................... 9
rd
3.1. Requests from 3 party to WMPay....................................................................................... 9
3.1.1. Authorize Web Single Payment .................................................................................... 10
3.1.2. Commit Web Single Payment ........................................................................................ 17
3.1.3. Cancel Web Single Payment .......................................................................................... 22
rd
3.2. Requests from WMPay to 3 party (asynchronous communication) ..................... 27
3.2.1. Example Flow for asynchronous communication ................................................. 30
4. Appendix ................................................................................................................... 32
4.1. Hash codes for requests and responses ........................................................................... 32
4.1.1. authorizeWebSingle .......................................................................................................... 32
4.1.2. commitWebSingle .............................................................................................................. 33
4.1.3. cancelWebSingle ................................................................................................................ 33
4.2. Global status codes ................................................................................................................ 35
4.3. Network Codes (NWC) .......................................................................................................... 37
4.4. Network Provider .................................................................................................................... 37
4.5. Billing Interface........................................................................................................................ 37
5. Document History ................................................................................................... 38
Author: mige D_WebSingle_newWMPay_RESTful_webservice_API_V0.5.doc from 24.09.2013 Page 2 of 38WMPay RESTful webservice
1. WMPay REST Interface Documentation
rd
This document describes the communication between 3 parties and whatever mobile WMPay platform. The WMPay platform
allows billing of mobile phone users via WMPay’s RESTful web service. This web service is only available via https.
The old WMPay interface (simple http based protocol – WMPay Interface Documentation) is still valid, but it will be deprecated
shortly after this interface goes in production.
This interface will support all transaction types in the near future. At the moment it supports only Web Payment Single in
Germany.
1.1. Definition of terms
rd
• 3 party – service provider – the organization that sells services/content and uses the WMPay web service directly.
rd
This document aims at the 3 party.
• End customer – The end customer is a mobile phone user who wants to purchase the service/content offered by
rd
the 3 party.
• Operator – the mobile network operator or carrier.
• Provider – reseller of mobile network services. In contrast to the Operator, the Provider does not operate a mobile
network.
• Billing Interface – the actual interface for mobile payments which is provided by the Operator or the Provider.
• MSISDN – Mobile Subscriber – the abbreviation stands for “Mobile Subscriber Integrated Services Digital Network-
Number”, in other words: it is the telephone number to the SIM card in a mobile phone.
• TAN – Transaction Authentication Number – alphanumeric string consisting of 4 to 6 characters, which is sent via
SMS to the End customer for authentication purposes during the payment process.
rd
• serviceId – identifies the 3 party’s configuration in the WMPay platform. This configuration can be used to define
special parameters at the network operator interfaces (e.g. for special revenue shares) or to enable or disable some
rd
general functionality within WMPay. The 3 party can have several serviceIds, e.g. to map its own customers and
offered services/content to different settings.
• RESTful webservice – a common technology for offering web interfaces.
Author: mige D_WebSingle_newWMPay_RESTful_webservice_API_V0.5.doc from 24.09.2013 Page 3 of 38WMPay RESTful webservice
2. Flow Definitions
The following chapter describes the flows of various payment types in WMPay. This chapter should be read carefully. It
defines how requests and redirects are handled by the WMPay platform. This chapter is not fully defined by now. Additional
flows describing other transaction types will be added in the future.
2.1. Web Single Payment
rd
Web Single Payment is for payments initiated via the Web. The 3 party has the sole responsibility to deliver the purchased
service/content to the End customer in case of a successful payment. The following chapter shows all relevant flows when
using Web Single Payment.
The first two diagrams show the differences within a payment process at the WMPay platform’s side regarding who is
responsible to send the TAN to the End customer. In some cases TAN is sent by the Operator/Provider and in the others it is
rd
the responsibility of WMPay platform. From the point of view of the 3 party the interaction with the WMPay is the same in
both cases.
Author: mige D_WebSingle_newWMPay_RESTful_webservice_API_V0.5.doc from 24.09.2013 Page 4 of 38WMPay RESTful webservice
2.1.1. Web Single Payment – successful flow - Operator sends TAN
Explanation:
rd
• the End customer wants to purchase service/content on the 3 party’s website using his mobile phone
rd
• the 3 party displays a webpage with a MSISDN input field
rd
• after the End customer submits his MSISDN, the 3 party sends a request to WMPay (authorizeWebSingle)
• WMPay checks mandatory parameters and authorizes the End customer at the billing interface – the
operator/provider sends the TAN SMS to the End customer
rd
• WMPay replies to the request and returns a unique transaction identifier as well as a status – the 3 party has to use
this identifier in all follow up requests regarding this transaction
rd
• the 3 party displays a TAN entry page to the End customer
• End customer enters the received TAN on the page and submits it
rd
• the 3 party sends a commitWebSingle request to the WMPay interface containing the entered TAN
• WMPay sends the TAN to the billing interface where it gets validated
• After successful TAN validation WMPay sends a commit to the operator interface to finalize the payment
rd
• WMPay returns the result of the commitWebSingle request to the 3 party
rd
• the 3 party offers the purchased service/content to the End customer
Author: mige D_WebSingle_newWMPay_RESTful_webservice_API_V0.5.doc from 24.09.2013 Page 5 of 38WMPay RESTful webservice
2.1.2. Web Single Payment – successful flow – WM sends TAN
Explanation:
rd
• the End customer wants to purchase service/content on the 3 party’s website via his mobile phone
• the 3rd party therefore displays a webpage with a MSISDN input field
rd
• after the End customer submits his MSISDN, the 3 party sends a request to WMPay (authorizeWebSingle)
• WMPay checks mandatory parameters and tries to authorize the End customer at the Billing interface
• as soon as the End customer is authorized, WMPay will send a TAN SMS to the End customer
rd
• WMPay replies to the request and returns a unique transaction identifier as well as a status – the 3 party has to use
the identifier in all follow up requests regarding this transaction
rd
• the 3 party displays a TAN entry page to the End customer
• End customer enters the received TAN on the page and submits it
rd
• the 3 party sends a commitWebSingle request to the WMPay interface containing the entered TAN
• WMPay validates the TAN
• After successful TAN validation WMPay sends a commit request to the Billing interface to finalize the payment
rd
• WMPay returns the result of the commitWebSingle request to the 3 party
rd
• the 3 party delivers the purchased service/content to the End customer
Author: mige D_WebSingle_newWMPay_RESTful_webservice_API_V0.5.doc from 24.09.2013 Page 6 of 38WMPay RESTful webservice
2.1.3. Web Single Payment – authorization fails
Explanation:
rd
• the End customer wants to purchase service/content on the 3 party’s website via his mobile phone
rd
• the 3 party displays a webpage with a MSISDN input field
rd
• after the End customer submits his MSISDN, the 3 party sends a request to WMPay (authorizeWebSingle)
• WMPay checks mandatory parameters and tries to authorize the End customer at the Billing interface
• Billing interface denies authorization
rd
• WMPay returns an error response to the 3 party – containing an WMPay error code as well as the Billing Interface’s
error code
rd
• the 3 party displays an error page to the End customer with a specific error description
Author: mige D_WebSingle_newWMPay_RESTful_webservice_API_V0.5.doc from 24.09.2013 Page 7 of 38WMPay RESTful webservice
2.1.4. Web Single Payment – End customer cancels transaction
Explanation:
rd
• the End customer wants to purchase service/content on the 3 party’s website via his mobile phone
rd
• the 3 party displays a webpage with a MSISDN input field
rd
• after the End customer submits his MSISDN, the 3 party sends a request to WMPay (authorizeWebSingle)
• WMPay checks mandatory parameters and tries to authorize the End customer at the Billing interface
• if the Operator/Provider did not send a TAN, WMPay sends the TAN SMS to the End customer
rd
• WMPay replies to the request and returns a unique transaction identifier as well as a status – the 3 party has to use
this identifier in all follow-up requests regarding this transaction
rd
• the 3 party displays a TAN entry page to the End customer
• End customer cancels the payment at the TAN entry page
rd
• the 3 party calls cancelWebSingle at the WMPay interface
• WMPay terminates the transaction at the Billing interface and in its own system
rd
• WMPay returns the status for the cancellation to the 3 party
rd
• the 3 party displays a cancel confirmation page to the End customer
Author: mige D_WebSingle_newWMPay_RESTful_webservice_API_V0.5.doc from 24.09.2013 Page 8 of 38WMPay RESTful webservice
3. Protocol of Transmission
The methods using the RESTful web service are completely SSL-secured with HTTP Basic Authentication. The WMPay platform
requires that each REST web service call should be carried out using authentication credentials: a configured username and
password.
WMPay supports the following MIME types for transmission:
• application/xml
• application/json
rd
The 3 party may choose to implement one of the above MIME types within its interface. This API describes both MIME types
in several examples for better understanding.
rd
Requests by the 3 party must be UTF-8 encoded, and all responses by WMPay will be UTF-8 encoded as well.
The WMPay platform offers two ways of communication - synchronous or asynchronous. A synchronous method call at the
WMPay platform will not return until a final result from the Operator has been received (or a timeout has been reached). An
asynchronous method call will return immediately, but it will just provide a status indicating whether the request has been
rd
accepted or not. WMPay will deliver the final result of an asynchronous method by calling methods at the 3 party side.
rd
Therefore the 3 party has to offer a REST web service within its system to receive such callbacks. Whether the
rd
communication is synchronous or asynchronous is determined by the existence of the responseURL parameter in the 3
rd
party’s request. If the 3 party sets the responseURL parameter within a request, WMPay considers the communication as
rd
asynchronous and will send the final result of the method by calling this URL at the 3 party’s interface.
The methods to be implemented by the 3rd party for asynchronous communication are defined in chapter 3.2 - Requests
rd
from WMPay to 3 party (asynchronous communication). If there is any problem with creating such a service, please take a
look at the example code (coming with final version).
rd
3.1. Requests from 3 party to WMPay
The WMPay RESTful web service’s base URL will be provided upon request.
The environment for testing while development can be located at: http://dev.whatevermobile.com/wmpay-ng
rd
Please note that, it is required that the 3 party provides the IP addresses which will be used for communication with WMPay.
Access to WMPay will be allowed only when the connection is initiated from one of these addresses.
Author: mige D_WebSingle_newWMPay_RESTful_webservice_API_V0.5.doc from 24.09.2013 Page 9 of 38WMPay RESTful webservice
3.1.1. Authorize Web Single Payment
Path: /authorizeWebSingle
Method: POST
Description: Initiates a web single payment. The authorization is processed at the Operator’s/Provider’s payment
interface and a TAN is sent either by WMPay or by the Operator/Provider. Request and Response MIME
types may be “application/json” or “application/xml”. 3rd party needs to provide Basic Authentication
credentials with this method call.
Request:
Mandatory
Element Subelement Type Description
The MSISDN of the end customer in international format, e.g.:
msisdn Numeric Y
4917xxx
The Identifier for the service configuration, which is stored in
serviceId Numeric Y
WMPay system.
Alphanu The name of the product offered
name Y
meric
product
rd
Alphanu A short description of the product offered by 3 party for the
description Y
meric payment.
The gross price of the offered product. This should be in the
grossAmount Numeric smallest available currency denominator of the country, where the Y
price service/content is offered (e.g.: EUROCENT)
Alphanu The currency to be used for billing. At the moment, only
currency Y
meric EUROCENT is supported.
The text of the TAN SMS. This text is only used if WMPay sends the
TAN SMS to the End customer. If the Operator/Provider sends the
TAN this text will not be used.
There are different placeholders which have to be used within the
text and will be filled by WMPay:
Alphanu
text Placeholder Description Mandatory N
meric
tanSms {TAN} the generated TAN Y
{PRICE} the price in EURO, e.g.: EUR 1,99 Y
If the tanSms field is not set, a default TAN text may be sent by
WMPay.
The originator of the TAN SMS. It will be used, if WMPay sends TAN
Alphanu
originator SMS. Beware: for alphanumeric originators, you should not use N
meric
more than 8 characters!
Author: mige D_WebSingle_newWMPay_RESTful_webservice_API_V0.5.doc from 24.09.2013 Page 10 of 38WMPay RESTful webservice
Some operators send a notification SMS to the End customer after
successful billing, in this case this parameter will not be used. If
WMPay sends the final SMS notification, it will use this text.
There are different placeholders which can be used within this text
and will be filled by WMPay:
Alphanu
text Placeholder Description Mandatory N
meric
{PRICE} the price in EURO, that have been Y
confirmationSms
billed, e.g.: EUR 1,99
{PRODUCT} The name of the product, given by N
method call
If this confirmationSms parameter is not set, a default confirmation
text may be sent by WMPay.
The originator of the confirmation SMS, if the confirmation SMS is
Alphanu
originator sent by WMPay. Beware: for alphanumeric originators, you should N
meric
not use more than 8 characters!
This field can be used to identify the request or the transaction at
rd
the 3 party. It will be sent back by WMPay in the synchronous as
Alphanu
customerReference well as in the asynchronous response. For example, this field could N
meric rd
be used to add some kind of 3 party transaction ID. WMPay will
not check this field for uniqueness.
If a response URL is sent in the request, WMPay will work in an
asynchronous way. This means that WMPay will just check the
Alphanu
responseURL request parameters and if they are valid, it will accept the request N
meric
itself. But the final request result will be sent in a separate,
rd
asynchronous request to the 3 party (see chapter 3.2)
A hash code that is used by WMPay to check the integrity of the
rd
Alphanu request. This parameter is optional and will be used only if the 3
hash N
meric party’s account at WMPay is configured to use hashing. See chapter
4.1 on how to create a hash.
Identifies the cost centre to be used for all billings referencing this
rd
Alphanu transaction within WMPay’s billing system. This is useful if 3 party
costCentre rd N
meric has different cost centre settings and if 3 party wants to divide
the clearing between different cost centres.
Author: mige D_WebSingle_newWMPay_RESTful_webservice_API_V0.5.doc from 24.09.2013 Page 11 of 38WMPay RESTful webservice
Response:
Mandatory
Mandatory
Element Subelement Type Description
WMPay’s identifier of the payment process, if no error has
Alphanum rd
transactionId occurred. 3 party needs to specify this transaction ID in N
eric
follow-up requests (i.e. commit or cancel requests).
rd
If 3 party sent a customerReference in the request, WMPay
Alphanum
customerReference will include it in its response. This reference can be used by the N
eric rd
3 party internally for identification purposes.
code Numeric Result of the request. See chapter 4.2 for further information. Y
Contains detailed information clarifying the reasons for
rejecting the request. For example, in case when error code
Alphanum 207 - ANOTHER TRANSACTION PENDING is returned, this field
errorDetails N
status eric contains the ID of the pending transaction. In case when the
validation of the request failed, this field may contain the name
of the erroneous request field.
Alphanum If the authorization failed at the operator interface, the operator
operatorError N
eric error code will be returned within this field.
The network code of the operator, which has been identified
Alphanum for the authorization. This field may be empty if an error occurs
nwc N
eric or in case of asynchronous use of the interface. See chapter
operator 4.3 for detailed information on possible network codes.
Alphanum The name of the network operator identified for the billing
name N
eric process
The name of the network provider identified for the billing
Alphanum process. This field may not be transmitted in case when no
provider N
eric provider has been identified for billing process. See chapter 4.4
for any further information.
Alphanum The name of the billing interface which was used for the billing
billingInterface N
eric process.
A hash code that is used to check the integrity of the response.
rd
This parameter is optional and is used only in case when the 3
Alphanum
hash party account is configured to use hashing for requests and N
eric
responses. See chapter 4.1 for more details on how to create a
hash and how to check it in the response.
Author: mige D_WebSingle_newWMPay_RESTful_webservice_API_V0.5.doc from 24.09.2013 Page 12 of 38WMPay RESTful webservice
Possible HTTP status codes:
Status code Description
200 Request ok.
400 Bad Request. A malformed request has been sent. Request and MIME type has to be checked.
401 Authentication failed. UserId and/or password are or is invalid.
404 Not found. The requested resource has not been found; the request path should be checked.
405 Wrong request method. Please use POST instead
500 An internal server error has occurred. That’s an http status code which is generated by the application server
if an internal processing fails without being caught by the processor. If this error persists, please contact our
operations team.
Examples: MIME type application/xml
application/xml
Synchronous Request:
1 > POST http://localhost:8080/wmpay/authorizeWebSingle
1 > content-type: application/xml
1 > accept: application/xml
1 > authorization: Basic YWRtaW46Z2VoZWlt
1 > user-agent: Java/1.6.0_16
1 > host: localhost:8080
1 > connection: keep-alive
1 >
WM
Sie haben soeben {PRICE} für {PRODUCT} ausgegeben.
costcenter1
customerReference
491735857100
199
EUROCENT
Buy Test Dollars
Testproduct
5
WM
Bitte geben sie die TAN {TAN} jetzt zum Starten des Bezahlvorgangs in Höhe von
{PRICE} ein.
Author: mige D_WebSingle_newWMPay_RESTful_webservice_API_V0.5.doc from 24.09.2013 Page 13 of 38WMPay RESTful webservice
Response:
1 < 200
1 < Content-Type: application/xml
1 <
customerReference
DE-VODAFONE
26202
DE-VODAFONE
OK
0
xxxx-xxxx-xxxx-xxxx
Asynchronous Request:
1 > POST http://localhost:8080/wmpay/authorizeWebSingle
1 > content-type: application/xml
1 > accept: application/xml
1 > authorization: Basic YWRtaW46Z2VoZWlt
1 > user-agent: Java/1.6.0_16
1 > host: localhost:8080
1 > connection: keep-alive
1 >
WM
Sie haben soeben {PRICE} für {PRODUCT} ausgegeben.
costcenter1
customerReference
491735857100
199
EUROCENT
Buy Test Dollars
Testproduct
https://3rdparty.payment.com/notifyWebSingle
5
WM
Bitte geben sie die TAN {TAN} jetzt zum Starten des Bezahlvorgangs in Höhe von
{PRICE} ein.
Author: mige D_WebSingle_newWMPay_RESTful_webservice_API_V0.5.doc from 24.09.2013 Page 14 of 38WMPay RESTful webservice
Response:
1 < 200
1 < Content-Type: application/xml
1 <
customerReference
ACCEPTED
1
xxxx-xxxx-xxxx-xxxx
MIME type application/json
application/ json
Synchronous
Synchronous Request:
1 > POST http://localhost:8080/wmpay/authorizeWebSingle
1 > content-type: application/json
1 > accept: application/json
1 > authorization: Basic YWRtaW46Z2VoZWlt
1 > user-agent: Java/1.6.0_16
1 > host: localhost:8080
1 > connection: keep-alive
1 >
{
"confirmationSms":{"originator":"WM","text":"Sie haben soeben {PRICE} für {PRODUCT}
ausgegeben."},
"costCentre":"costcenter1",
"customerReference":"customerReference",
"msisdn":"491735857100",
"price":{"grossAmount":"199","currency":"EUROCENT"},
"product":{"description":"Buy Test Dollars","name":"Testproduct"},
"serviceId":"5",
"tanSms":{"originator":"WM","text":"Bitte geben sie die TAN {TAN} jetzt zum Starten des
Bezahlvorgangs in Höhe von {PRICE} ein."}
}
Response:
1 < 200
1 < Content-Type: application/json
1 <
{
"customerReference":"customerReference",
" operator ":{"nwc":"26202","name":"DE-VODAFONE"},
"status":{"errorDetails":"OK","code":"0"},
"billingInterface":"DE-VODAFONE",
"transactionId":"xxxx-xxxx-xxxx-xxxx"
}
Author: mige D_WebSingle_newWMPay_RESTful_webservice_API_V0.5.doc from 24.09.2013 Page 15 of 38WMPay RESTful webservice
Asynchronous Request:
1 > POST http://localhost:8080/wmpay/authorizeWebSingle
1 > content-type: application/json
1 > accept: application/json
1 > authorization: Basic YWRtaW46Z2VoZWlt
1 > user-agent: Java/1.6.0_16
1 > host: localhost:8080
1 > connection: keep-alive
1 >
{
"confirmationSms":{"originator":"WM","text":"Sie haben soeben {PRICE} für {PRODUCT}
ausgegeben."},
"costCentre":"costcenter1",
"customerReference":"customerReference",
"msisdn":"491735857100",
"price":{"grossAmount":"199","currency":"EUROCENT"},
"product":{"description":"Buy Test Dollars","name":"Testproduct"},
"responseURL":"https://3rdparty.payment.com/notifyWebSingle",
"serviceId":"5",
"tanSms":{"originator":"WM","text":"Bitte geben sie die TAN {TAN} jetzt zum Starten des
Bezahlvorgangs in Höhe von {PRICE} ein."}
}
Response:
1 < 200
1 < Content-Type: application/json
1 <
{
"customerReference":"customerReference",
"status":{"errorDetails":"ACCEPTED","code":"1"},
"transactionId":"xxxx-xxxx-xxxx-xxxx"
}
Author: mige D_WebSingle_newWMPay_RESTful_webservice_API_V0.5.doc from 24.09.2013 Page 16 of 38WMPay RESTful webservice
3.1.2. Commit Web Single Payment
Path: /commitWebSingle
Method: POST
rd
Description: Commits a web single payment transaction. 3 party has to provide the TAN submitted by the End
customer with this request for validation purposes. The TAN will be validated at the billing interface or at
WMPay (depending on who sent the TAN). After successful validation, the amount will be booked at the
billing interface. No further action is required and the transaction will be closed. Request and Response
MIME types may be “application/json” or “application/xml”. 3rd party needs to provide Basic Authentication
credentials with the method call.
Request:
Subelement
Mandatory
Element Type Description
Alphanu The WMPay transaction ID returned by the authorizeWebSingle (3.1.1)
transactionId Y
meric request.
Alphanu The TAN submitted by the End customer
tan Y
meric
A hash code that is used to check the integrity of the request. This parameter
rd
Alphanu is optional and is used only in case when the 3 party account is configured
hash N
meric to use hashing for requests and responses. See chapter 4.1 for more details
on how to create a hash and how to check it in the response.
If a response URL is sent in the request, WMPay will work asynchronously. It
Alphanu
responseURL accepts the request (if the parameters are valid) immediately, but sends the N
meric rd
final result in a separate asynchronous request to 3 party (see chapter 3.2)
Author: mige D_WebSingle_newWMPay_RESTful_webservice_API_V0.5.doc from 24.09.2013 Page 17 of 38WMPay RESTful webservice
Response:
Mandatory
Element Subelement Type Description
Alphanu WMPay’s unique transaction identifier.
transactionId Y
meric
rd
If 3 party sent a customerReference in authorize request, WMPay
Alphanu rd
customerReference will include it in its response. This reference can be used by the 3 N
meric
party internally for identification purposes.
code Numeric Result of the request. See chapter 4.2 for further information. Y
Contains detailed information clarifying the reasons for rejecting the
Alphanu
errorDetails request. In case the validation of the request failed this field may N
meric
status contain the name of the erroneous request field.
Alphanu If the transaction failed at the operator interface, the operator’s
operatorError N
meric error code will be returned directly within this field.
The network code of the operator, which has been identified for the
Alphanu authorization. This field may be empty if an error occurs or in case
nwc N
meric of asynchronous use of the interface. See chapter 4.3 for detailed
operator information on possible network codes.
Alphanu The name of the network operator identified for the billing process
name N
meric
The name of the network provider identified for the billing process.
Alphanu This field may not be transmitted in case when no provider has
provider N
meric been identified for billing process. See chapter 4.4 for any further
information.
Alphanu The name of the billing interface which was used for the billing
billingInterface N
meric process.
A hash code that is used to check the integrity of the response. This
rd
Alphanu parameter is optional and is used only in case if the 3 party
hash N
meric account is configured to use hashing. See chapter 4.1 on how to
create a hash and how to check it in the response.
Author: mige D_WebSingle_newWMPay_RESTful_webservice_API_V0.5.doc from 24.09.2013 Page 18 of 38WMPay RESTful webservice
Possible
Possibl e HTTP status codes:
Status code Description
200 Request ok.
400 Bad Request. A malformed request has been sent. Request and MIME type has to be checked.
401 Authentication failed. UserId and/or password are invalid.
404 Not found. The requested resource has not been found; the request path should be checked.
405 Wrong request method. Please use POST method instead.
500 An internal server error has occurred. That’s an http status code which is generated by the application server
if internal processing fails without being caught by the processor. If this error persists, please contact our
operations team.
Examples: MIME type application/xml
Synchronous Request:
1 > POST http://localhost:8080/wmpay/commitWebSingle
1 > content-type: application/xml
1 > accept: application/xml
1 > authorization: Basic YWRtaW46Z2VoZWlt
1 > user-agent: Java/1.6.0_16
1 > host: localhost:8080
1 > connection: keep-alive
1 >
d3e71ef6ce1987fc097b2a38e1d66752
1234
19ecd709-4952-43e7-813d-760e0dc50d8c
Response:
1 < 200
1 < Content-Type: application/xml
1 <
customerReference
ae30fdbe39858088a7a1754f6a4ac44b
0
OK
DE-VODAFONE
26202
DE-VODAFONE
19ecd709-4952-43e7-813d-760e0dc50d8c
Author: mige D_WebSingle_newWMPay_RESTful_webservice_API_V0.5.doc from 24.09.2013 Page 19 of 38WMPay RESTful webservice
Asynchronous Request:
1 > POST http://localhost:8080/wmpay/commitWebSingle
1 > content-type: application/xml
1 > accept: application/xml
1 > authorization: Basic YWRtaW46Z2VoZWlt
1 > user-agent: Java/1.6.0_16
1 > host: localhost:8080
1 > connection: keep-alive
1 >
b7e16ba255e0bb1af45457ce18e66470
https://3rdparty.payment.com/notifyWebSingle
1234
xxxx-xxxx-xxxx-xxxx
Response:
1 < 200
1 < Content-Type: application/xml
1 <
8fa32ba340fcf29e1b7c3e763476aafc
1
ACCEPTED
cust ref
DE-VODAFONE
26202
DE-VODAFONE
xxxx-xxxx-xxxx-xxxx
Author: mige D_WebSingle_newWMPay_RESTful_webservice_API_V0.5.doc from 24.09.2013 Page 20 of 38WMPay RESTful webservice
MIME type application/json
Synchronous Request:
1 > POST http://localhost:8080/wmpay/commitWebSingle
1 > content-type: application/json
1 > accept: application/json
1 > authorization: Basic YWRtaW46Z2VoZWlt
1 > user-agent: Java/1.6.0_16
1 > host: localhost:8080
1 > connection: keep-alive
1 >
{
"hash":"115e11f15b43c3eb0d92e7c1291979f8",
"tan":"1234",
"transactionId":"90ba6662-dc77-4813-a93e-4fc2efad64b5"
}
Response:
1 < 200
1 < Content-Type: application/json
1 <
{
"customerReference":"customerReference",
"hash":"de0da15cae0e4f196647a3affcecdd36",
"status":{"code":"0","errorDetails":"OK"},
" operator ":{"nwc":"26202","name":"DE-VODAFONE"},
"billingInterface":"DE-VODAFONE",
"transactionId":"90ba6662-dc77-4813-a93e-4fc2efad64b5"
}
Asynchronous Request:
1 > POST http://localhost:8080/wmpay/commitWebSingle
1 > content-type: application/json
1 > accept: application/json
1 > authorization: Basic YWRtaW46Z2VoZWlt
1 > user-agent: Java/1.6.0_16
1 > host: localhost:8080
1 > connection: keep-alive
1 >
{
"hash":"b7e16ba255e0bb1af45457ce18e66470",
"responseURL":"https://3rdparty.payment.com/notifyWebSingle",
"tan":"1234",
"transactionId":"xxxx-xxxx-xxxx-xxxx"
}
Response:
1 < 200
1 < Content-Type: application/json
1 <
{
"hash":"8fa32ba340fcf29e1b7c3e763476aafc",
"status":{"code":"1","errorDetails":"ACCEPTED"},
" operator ":{"nwc":"26202","name":"DE-VODAFONE"},
"billingInterface":"DE-VODAFONE", "transactionId":"xxxx-xxxx-xxxx-xxxx"
}
Author: mige D_WebSingle_newWMPay_RESTful_webservice_API_V0.5.doc from 24.09.2013 Page 21 of 38WMPay RESTful webservice
3.1.3. Cancel Web Single Payment
Path: /cancelWebSingle
Method:
Method: POST
Description: Cancels a web single payment transaction. This request is only possible after a successful
authorizeWebSingle request (3.1.1). Request and Response MIME types may be “application/json” or
“application/xml”. 3rd party needs to provide Basic Authentication credentials with the method call.
Request:
Subelement
Mandatory
Element Type Description
Alphanu The transaction ID returned by the authorizeWebSingle (3.1.1) request.
transactionId Y
meric
A hash code that is used to check the integrity of the request or response.
rd
Alphanu This parameter is optional and is used only if the 3 party’s account is
hash N
meric configured to use hashing for requests and responses. See chapter 4.1 on
how to create a hash and how to check it in the response.
If a response URL is sent in the request, WMPay will work asynchronously.
Alphanu
responseURL That means, it accepts the request itself but sends the final request result in a N
meric rd
separate request to 3 party’s interface (see chapter 3.2).
Author: mige D_WebSingle_newWMPay_RESTful_webservice_API_V0.5.doc from 24.09.2013 Page 22 of 38WMPay RESTful webservice
Response:
Mandatory
Element Subelement Type Description
Alphanu The unique WMPay transaction identifier.
transactionId Y
meric
rd
If 3 party sent a customerReference in the authorize request,
Alphanu
customerReference WMPay will include it in its response. This reference can be used by N
meric rd
the 3 party internally for identification purposes.
code Numeric Result of the request. See chapter 4.2 for further information. Y
Contains detailed information clarifying the reasons for rejecting the
Alphanu
errorDetails request. In case the validation of the request failed this field may N
status meric
contain the name of the erroneous request field.
Alphanu If a cancel request failed at operator interface, the operator’s result
operatorError N
meric code will be returned within this field.
The network code of the operator, which has been identified for the
Alphanu authorization. This field may be empty if an error occurs or in case
nwc N
meric of asynchronous use of the interface. See chapter 4.3 for detailed
operator information on possible network codes.
Alphanu The name of the network operator identified for the billing process
name N
meric
The name of the network provider identified for the billing process.
Alphanu This field may not be transmitted in case when no provider has
provider N
meric been identified for billing process. See chapter 4.4 for any further
information.
Alphanu The name of the billing interface which was used for the billing
billingInterface N
meric process.
A hash code that is used to check the integrity of the response. This
rd
Alphanu parameter is optional and is used only if the 3 party’s account is
hash N
meric configured to use hashing. See chapter 4.1 on how to create a hash
and how to check it in the response.
Author: mige D_WebSingle_newWMPay_RESTful_webservice_API_V0.5.doc from 24.09.2013 Page 23 of 38WMPay RESTful webservice
Possible HTTP status codes:
Status code Description
200 Request ok.
400 Bad Request. A malformed request has been sent. Request and MIME type has to be checked.
401 Authentication failed. UserId and/or password are invalid.
404 Not found. The requested resource has not been found; the request path should be checked.
405 Wrong request method. Please use POST method instead.
500 An internal server error has been occurred. That’s an http status code which is generated by the application
server, if internal processing fails without being caught by the processor. If this error persists, please contact
our operations team.
Examples: MIME type application/xml
Synchronous Request:
1 > POST http://localhost:8080/wmpay/cancelWebSingle
1 > content-type: application/xml
1 > accept: application/xml
1 > authorization: Basic YWRtaW46Z2VoZWlt
1 > user-agent: Java/1.6.0_16
1 > host: localhost:8080
1 > connection: keep-alive
1 >
1e1642edb93111c1d3f060cd63d45749
53f4d21e-91af-451b-ac61-6eb114a51966
Response:
1 < 200
1 < Content-Type: application/xml
1 <
customerReference
a5458dff73961ddff5ac83170220258c
0
OK
DE-VODAFONE
26202
DE-VODAFONE
53f4d21e-91af-451b-ac61-6eb114a51966
Author: mige D_WebSingle_newWMPay_RESTful_webservice_API_V0.5.doc from 24.09.2013 Page 24 of 38WMPay RESTful webservice
Asynchronous Request:
1 > POST http://localhost:8080/wmpay/cancelWebSingle
1 > content-type: application/xml
1 > accept: application/xml
1 > authorization: Basic YWRtaW46Z2VoZWlt
1 > user-agent: Java/1.6.0_16
1 > host: localhost:8080
1 > connection: keep-alive
1 >
802d7d9f8c938e67fb76d6bef374e267
https://3rdparty.payment.com/notifyWebSingle
xxxx-xxxx-xxxx-xxxx
Response:
1 < 200
1 < Content-Type: application/xml
1 <
8fa32ba340fcf29e1b7c3e763476aafc
1
ACCEPTED
xxxx-xxxx-xxxx-xxxx
MIME type application/json
Synchronous
Synchro nous Request:
1 > POST http://localhost:8080/wmpay/cancelWebSingle
1 > content-type: application/json
1 > accept: application/json
1 > authorization: Basic YWRtaW46Z2VoZWlt
1 > user-agent: Java/1.6.0_16
1 > host: localhost:8080
1 > connection: keep-alive
1 >
{
"hash":"7adfd90f785154426501bd639ee200ca",
"transactionId":"fab839dd-3551-430f-b3d4-7a9e14a895f6"
}
Response:
1 < 200
1 < Content-Type: application/json
1 <
{
"customerReference":"customerReference",
"hash":"0b9fa0a45e7bc695ba33d2dd5ee915986f97530284e72e8ff150e091b56ed6e6",
"status":{"code":"0","errorDetails":"OK"},
"transactionId":"fab839dd-3551-430f-b3d4-7a9e14a895f6"
}
Author: mige D_WebSingle_newWMPay_RESTful_webservice_API_V0.5.doc from 24.09.2013 Page 25 of 38WMPay RESTful webservice
Asynchronous Request:
1 > POST http://localhost:8080/wmpay/cancelWebSingle
1 > content-type: application/json
1 > accept: application/json
1 > authorization: Basic YWRtaW46Z2VoZWlt
1 > user-agent: Java/1.6.0_16
1 > host: localhost:8080
1 > connection: keep-alive
1 >
{
"hash":"802d7d9f8c938e67fb76d6bef374e267",
"responseURL":"https://3rdparty.payment.com/notifyWebSingle",
"transactionId":"xxxx-xxxx-xxxx-xxxx"
}
Response:
1 < 200
1 < Content-Type: application/json
1 <
{
"hash":"8fa32ba340fcf29e1b7c3e763476aafc",
"status":{"code":"1","errorDetails":"ACCEPTED"},
"transactionId":"xxxx-xxxx-xxxx-xxxx"
}
Author: mige D_WebSingle_newWMPay_RESTful_webservice_API_V0.5.doc from 24.09.2013 Page 26 of 38WMPay RESTful webservice
rd
3.2. Requests from WMPay to 3 party (asynchronous communication)
The API provides both synchronous and asynchronous communication. WM recommends that an asynchronous
rd
communication is used. Some synchronous method calls may take longer and the 3 party’s system may experience certain
rd
problems because of timeouts – for example, depending on its settings, the 3 party’s communication client may disconnect
rd
if there’s no response from the WMPay in a specific amount of time. However, 3 parties are free in deciding on whether they
should use synchronous or asynchronous way of communication.
rd
Whether the 3 party prefers synchronous or asynchronous way of communication is determined by the availability of the
rd
“responseURL” parameter in the 3 party’s request.
The first thing that the WMPay system does when a request is received is to validate it. If the request is invalid, the system
rd
responds (synchronously) to the 3 party with a corresponding status code and clarifying data. If the request is successfully
rd
validated, the WMPay system checks the “responseURL” parameter. If this parameter was set by the 3 party then WMPay
considers the communication as asynchronous and before any further processing of the request is done it responds
rd
(synchronously) to the 3 party that its request was validated and accepted (the status code is 1 - ACCEPTED). In case of
asynchronous communication after all internal processing of the request is completed by the WMPay system, the result will be
rd
sent to the response URL provided by the 3 party in the “responseURL” request parameter.
Author: mige D_WebSingle_newWMPay_RESTful_webservice_API_V0.5.doc from 24.09.2013 Page 27 of 38WMPay RESTful webservice
The following request will be sent to the URL if the request has been processed in the backend:
Path: defined by responseURL in the request formerly sent to WMPay
Method: POST
rd
Description: Sends the status of a fulfilled former request to 3 party for asynchronous communication protocol.
Request and Response MIME type is “application/json”. WMPay provides basic authentication to the 3rd
party, which has been used in the former request.
Request:
Mandatory
Element Subelement Type Description
Alphanum The unique WMPay transaction ID
transactionId Y
eric
rd
Alphanum The customerReference provided by the 3 party during the
customerReference N
eric initial request
code Numeric Result of the request. See chapter 4.2 for further information. Y
Contains detailed information clarifying the reasons for rejecting
Alphanum
errorDetails the request. In case the validation of the request failed this field N
status eric
may contain the name of the erroneous request field.
Alphanum This field contains the operator result if any operator interfaces
operatorError N
eric has been used during processing.
The network code of the operator, which has been identified for
Alphanum the authorization. This field may be empty if an error occurs or in
nwc N
eric case of asynchronous use of the interface. See chapter 4.3 for
operator detailed information on possible network codes.
Alphanum The name of the network operator identified for the billing
name N
eric process
The name of the network provider identified for the billing
Alphanum process. This field may not be transmitted in case when no
provider N
eric provider has been identified for billing process. See chapter 4.4
for any further information.
Alphanum The name of the billing interface which was used for the billing
billingInterface N
eric process.
A hash code that is used to check the integrity of this request.
rd
This parameter is optional and is used only if the 3 party
Alphanum
hash account is configured to use hashing for requests and responses. N
eric
See chapter 4.1 on how to create a hash and how to check it in
the response.
Response:
WMPay will only accept the HTTP status codes 200 (OK) and 204 (No Content) for the request response. If any other status
rd
code is returned by 3 party interface, WMPay will try to redeliver the request until the request timeout occurs. Any other
rd
status code will trigger an internal alerting: 3 party interface is not available.
Author: mige D_WebSingle_newWMPay_RESTful_webservice_API_V0.5.doc from 24.09.2013 Page 28 of 38WMPay RESTful webservice
Examples: Request (request has been processed successfully):
successfully):
1 > POST http://localhost:8080/wmpay/customer/notifyWebSingle
1 > content-type: application/json
1 > accept: application/json
1 > authorization: Basic YWRtaW46Z2VoZWlt
1 > user-agent: Java/1.6.0_16
1 > host: localhost:8080
1 > connection: keep-alive
1 > content-length: 194
1 >
{
"customerReference":"customerReference",
"operator":{ "name":"DE-VODAFONE", "nwc":"26202" },
"billingInterface" : "DE-VODAFONE",
"status":{"errorDetails":"OK","code":"0","operatorError":"0"},
"transactionId":"xxxx-xxxx-xxxx-xxxx"
}
Response:
1 < 200
1 < Content-Type: application/json
1 <
Request (request has not been processed successfully):
1 > POST http://localhost:8080/wmpay/customer/notifyWebSingle
1 > content-type: application/json
1 > accept: application/json
1 > authorization: Basic YWRtaW46Z2VoZWlt
1 > user-agent: Java/1.6.0_16
1 > host: localhost:8080
1 > connection: keep-alive
1 > content-length: 202
1 >
{
"customerReference":"customerReference",
"operator":{ "name":"DE-VODAFONE", "nwc":"26202" },
"billingInterface" : "DE-VODAFONE", "status":{"errorDetails":"NO
CREDIT","code":"10","operatorError":"8"},
"transactionId":"xxxx-xxxx-xxxx-xxxx"
}
Response:
1 < 200
1 < Content-Type: application/json
1 <
Author: mige D_WebSingle_newWMPay_RESTful_webservice_API_V0.5.doc from 24.09.2013 Page 29 of 38WMPay RESTful webservice
3.2.1. Example Flow for asynchronous communication
Explanation:
rd
• the End customer wants to purchase service/content on the 3 party’s website via his mobile phone and enters his
rd
MSISDN on 3 party’s web page
rd
• 3 party calls authorizeWebSingle with responseURL parameter set
• WMPay validates request parameters and creates a new transaction
• new transaction data and status “ACCEPTED” are returned by method call
rd
o 3 party now waits for asynchronous response
• WMPay authorizes the payment at the operator interface
• Operator sends the TAN SMS to the End customer and returns OK for authorization
rd
• WMPay calls the 3 party’s URL defined in the requestURL parameter of the initial call (Status: OK, appended:
transaction ID, etc.)
rd
• 3 party displays the TAN entry page to the End customer
rd
• End customer enters the received TAN at 3 party’s webpage
rd
• 3 party calls commitWebSingle to commit the transaction and provides a responseURL
• WMPay validates the parameters and returns status “ACCEPTED”
rd
o 3 party waits for final asynchronous method result
Author: mige D_WebSingle_newWMPay_RESTful_webservice_API_V0.5.doc from 24.09.2013 Page 30 of 38WMPay RESTful webservice
• WMPay validates the TAN at the operator interface
• WMPay sends the commit of transaction to the operator interface
• WMPay posts the final result to the response URL formerly submitted within the request call
rd
• 3 party delivers the purchased service/content to the End customer
Author: mige D_WebSingle_newWMPay_RESTful_webservice_API_V0.5.doc from 24.09.2013 Page 31 of 38WMPay RESTful webservice
4. Appendix
4.1. Hash codes for requests and responses
This appendix describes how to create a hash code for each request. Hash codes are used to verify the integrity of a request
rd
or response. Therefore, 3 party and WM share a secret key that is used for building the hash code. Request and response
verification is optional and will be only used if configured for 3rd party.
Hashing a request and verifying a response is pretty easy: all submitted request parameter values are concatenated in the
alphabetical order of the parameter names. Parameters, which are not used (not transmitted), have to be omitted. After the
concatenated string of parameter values has been built, the shared secret key has to be appended to it. Afterwards, an
MD5Hash of the resulting string is used as the hash code. Representation of the hash code is hexadecimal!
4.1.1. authorizeWebSingle
Request:
confirmationSms.originator + confirmationSms.text + costCenter + customerReference+ msisdn +
price.currency + price.grossAmount + product.description + product.name + responseURL + serviceId +
tanSms.originator + tanSms.text+ secret
Example: msisdn = 491735857100
serviceId = 5
product.name = Testproduct
product.description = Testing a product
price.grossAmount = 199
price.currency = EUROCENT
all other parameters are not set
Example Secret Key: secret
So, the String to be hashed is:
491735857100EUROCENT199Testing a productTestproduct5secret
The HEX hash code is:
dd56199e9e933d72fab3ec2df1d35276
Response:
billingInterface + customerReference + operator.name + operator.nwc + provider + status.code +
status.errorDetails + status.operatorError + transactionId + secret
Example: transactionId = xxxx-xxxx-xxxx-xxxx
status.code = 0
status.errorDetails = OK
billingInterface = DE-VODAFONE
operator.nwc = 26202
operator.name = DE-VODAFONE
Example Secret: secret
Author: mige D_WebSingle_newWMPay_RESTful_webservice_API_V0.5.doc from 24.09.2013 Page 32 of 38WMPay RESTful webservice
So, the String to be hashed is:
DE-VODAFONEDE-VODAFONE262020OKxxxx-xxxx-xxxx-xxxxsecret
The HEX hash code is:
767a53ab408e867857d534c0c326bfad
4.1.2. commitWebSingle
Request: responseURL + tan + transactionId + secret
Example: transactionId = xxxx-xxxx-xxxx-xxxx
tan = 4333
Example Secret: secret
So, the String to be hashed is:
4333xxxx-xxxx-xxxx-xxxxsecret
The HEX hash code is:
342eccbaf0a198f426b81eb5fd92011b
Response: billingInterface + customerReference + operator.name + operator.nwc + provider + status.code +
status.errorDetails + status.operatorError + transactionId + secret
transactionId = xxxx-xxxx-xxxx-xxxx
billingInterface = DE-MOBILCOM-DEBITEL
customerReference = CustomerReference
operator.name = DE-VODAFONE
operator.nwc = 26202
status.code = 0
status.errorDetails = OK
Example Secret: secret
So, the String to be hashed is:
DE-MOBILCOM-DEBITELCustomerReferenceDE-VODAFONE262020OKxxxx-xxxx-xxxx-xxxxsecret
The HEX hash code is:
9e7760cd9a78b4a57c131313da489bac
4.1.3. cancelWebSingle
Request: responseURL + transactionId + secret
Example: transactionId = xxxx-xxxx-xxxx-xxxx
Example Secret: secret
So, the String to be hashed is:
xxxx-xxxx-xxxx-xxxxsecret
The HEX hash code is:
4c031cf73c1451685a4ef941147ab2b3
Author: mige D_WebSingle_newWMPay_RESTful_webservice_API_V0.5.doc from 24.09.2013 Page 33 of 38WMPay RESTful webservice
Response: billingInterface + customerReference operator.name + operator.nwc + status.code + status.errorDetails +
status.operatorError + transactionId + secret
Example: transactionId = xxxx-xxxx-xxxx-xxxx
billingInterface = DE-EPLUS
customerReference = Some Reference
operator.name = DE-EPLUS
operator.nwc = 26203
status.code = 1
status.errorDetails = ACCEPTED
Example Secret: secret
So, the String to be hashed is:
DE-EPLUSSome ReferenceDE-EPLUS262041ACCEPTED1ACCEPTEDxxxx-xxxx-xxxx-xxxxsecret
The HEX hash code is:
74357daeb5eb00a4f72f5ffd35a246ab
Author: mige D_WebSingle_newWMPay_RESTful_webservice_API_V0.5.doc from 24.09.2013 Page 34 of 38WMPay RESTful webservice
4.2. Global status codes
The following status codes may be transmitted within any response to a request or within an asynchronous method call to
3rd party’s interface.
Status code Description
0 OK - request result is ok
rd
1 ACCEPTED – the method call has been accepted. 3 party receives a final request for the result of the
rd
method call. This status will be just returned, if the 3 party has set the parameter responseURL during its
request.
10 NO CREDIT – the end customer is (most likely) a prepaid user and has not enough credit on his prepaid card
11 BARRED – the end customer is barred for value added services
12 BLOCKED – the end customer is blocked by the operator for mobile payments
rd
13 WRONG TAN – the TAN delivered is wrong. 3 party may try again.
14 TAN ENTRY EXCEEDED – the TAN was wrong multiple times. The transaction has been closed and is finished.
15 TIMEOUT AT OPERATOR – the transaction has already timed out at the billing interface. Transaction will be
closed by WMPay itself.
16 OPERATOR CURRENTLY UNAVAILABLE – the operator’s/provider’s interface for billing / authorization
purposes is currently not available / reachable. Try again later.
17 MSISDN NOT BILLABLE – the MSISDN is not billable for any reason that cannot be matched to the above
error codes.
18 SPENDING CAP REACHED – the MSISDN has reached the maximum amount of payments in a specific
timeframe.
19 AGE VERIFICATION ERROR – the end customer is not allowed to use the specified category due to age
verification error at the operator.
20 ERROR AT OPERATOR – an error which cannot be mapped and was returned by the billing interface
rd
200 HASH MISMATCH – the hash for the request is not matching. This usually means, 3 party did not correctly
generate the hash of its request or uses a wrong secret.
201 PARAMETER WRONG OR MISSING – a parameter is wrong or missing. The errorDetails field should contain
the wrong parameter.
202 BLACKLISTED – the end customer is blacklisted in WMPay. This usually means that end customer called the
hotline and has been blocked for further payments at the platform.
203 TIMEOUT – timeout occurred while processing request. This means that request was accepted but not
completed in the timeframe given by method call.
204 NO ROUTING – the billing cannot be routed in the platform. There is no billing provider for the given
MSISDN.
205 BACKEND TEMPORARILY NOT AVAILABLE – the backend system is currently not available, e.g. due to
maintenance reasons. Try again later.
206 TRANSACTION NOT AVAILABLE – in case of commit or cancel, a transaction may not be available anymore,
e.g. for timeout reasons, so this status code is returned.
Author: mige D_WebSingle_newWMPay_RESTful_webservice_API_V0.5.doc from 24.09.2013 Page 35 of 38You can also read
