WMPay RESTful webservice Web Single Payment Germany Specification

WMPay RESTful webservice Web Single Payment Germany Specification

WMPay API WMPay RESTful webservice Web Single Payment Germany Specification API documentation whatever mobile GmbH Version 0.5

WMPay RESTful webservice Author: mige D_WebSingle_newWMPay_RESTful_webservice_API_V0.5.doc from 24.09.2013 Page 2 of 38 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 3.1. Requests from 3 rd 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 3.2. Requests from WMPay to 3 rd 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

WMPay RESTful webservice Author: mige D_WebSingle_newWMPay_RESTful_webservice_API_V0.5.doc from 24.09.2013 Page 3 of 38 1. WMPay REST Interface Documentation This document describes the communication between 3 rd 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 • 3 rd party – service provider – the organization that sells services/content and uses the WMPay web service directly. This document aims at the 3 rd party. • End customer – The end customer is a mobile phone user who wants to purchase the service/content offered by the 3 rd 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.

• serviceId – identifies the 3 rd 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 general functionality within WMPay. The 3 rd 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.

WMPay RESTful webservice Author: mige D_WebSingle_newWMPay_RESTful_webservice_API_V0.5.doc from 24.09.2013 Page 4 of 38 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 Web Single Payment is for payments initiated via the Web. The 3 rd 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 the responsibility of WMPay platform. From the point of view of the 3 rd party the interaction with the WMPay is the same in both cases.

WMPay RESTful webservice Author: mige D_WebSingle_newWMPay_RESTful_webservice_API_V0.5.doc from 24.09.2013 Page 5 of 38 2.1.1. Web Single Payment – successful flow - Operator sends TAN Explanation: Explanation: Explanation: Explanation: • the End customer wants to purchase service/content on the 3 rd party’s website using his mobile phone • the 3 rd party displays a webpage with a MSISDN input field • after the End customer submits his MSISDN, the 3 rd 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 • WMPay replies to the request and returns a unique transaction identifier as well as a status – the 3 rd party has to use this identifier in all follow up requests regarding this transaction • the 3 rd party displays a TAN entry page to the End customer • End customer enters the received TAN on the page and submits it • the 3 rd 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 • WMPay returns the result of the commitWebSingle request to the 3 rd party • the 3 rd party offers the purchased service/content to the End customer

WMPay RESTful webservice Author: mige D_WebSingle_newWMPay_RESTful_webservice_API_V0.5.doc from 24.09.2013 Page 6 of 38 2.1.2. Web Single Payment – successful flow – WM sends TAN Explanation: Explanation: Explanation: Explanation: • the End customer wants to purchase service/content on the 3 rd party’s website via his mobile phone • the 3rd party therefore displays a webpage with a MSISDN input field • after the End customer submits his MSISDN, the 3 rd 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 • WMPay replies to the request and returns a unique transaction identifier as well as a status – the 3 rd party has to use the identifier in all follow up requests regarding this transaction • the 3 rd party displays a TAN entry page to the End customer • End customer enters the received TAN on the page and submits it • the 3 rd 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 • WMPay returns the result of the commitWebSingle request to the 3 rd party • the 3 rd party delivers the purchased service/content to the End customer

WMPay RESTful webservice Author: mige D_WebSingle_newWMPay_RESTful_webservice_API_V0.5.doc from 24.09.2013 Page 7 of 38 2.1.3. Web Single Payment – authorization fails Explanation: Explanation: Explanation: Explanation: • the End customer wants to purchase service/content on the 3 rd party’s website via his mobile phone • the 3 rd party displays a webpage with a MSISDN input field • after the End customer submits his MSISDN, the 3 rd 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 • WMPay returns an error response to the 3 rd party – containing an WMPay error code as well as the Billing Interface’s error code • the 3 rd party displays an error page to the End customer with a specific error description

WMPay RESTful webservice Author: mige D_WebSingle_newWMPay_RESTful_webservice_API_V0.5.doc from 24.09.2013 Page 8 of 38 2.1.4. Web Single Payment – End customer cancels transaction Explanation: Explanation: Explanation: Explanation: • the End customer wants to purchase service/content on the 3 rd party’s website via his mobile phone • the 3 rd party displays a webpage with a MSISDN input field • after the End customer submits his MSISDN, the 3 rd 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 • WMPay replies to the request and returns a unique transaction identifier as well as a status – the 3 rd party has to use this identifier in all follow-up requests regarding this transaction • the 3 rd party displays a TAN entry page to the End customer • End customer cancels the payment at the TAN entry page • the 3 rd party calls cancelWebSingle at the WMPay interface • WMPay terminates the transaction at the Billing interface and in its own system • WMPay returns the status for the cancellation to the 3 rd party • the 3 rd party displays a cancel confirmation page to the End customer

WMPay RESTful webservice Author: mige D_WebSingle_newWMPay_RESTful_webservice_API_V0.5.doc from 24.09.2013 Page 9 of 38 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 The 3 rd 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.

Requests by the 3 rd 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 accepted or not. WMPay will deliver the final result of an asynchronous method by calling methods at the 3 rd party side. Therefore the 3 rd party has to offer a REST web service within its system to receive such callbacks.

Whether the communication is synchronous or asynchronous is determined by the existence of the responseURL parameter in the 3 rd party’s request. If the 3 rd party sets the responseURL parameter within a request, WMPay considers the communication as asynchronous and will send the final result of the method by calling this URL at the 3 rd party’s interface. The methods to be implemented by the 3rd party for asynchronous communication are defined in chapter 3.2 - Requests from WMPay to 3 rd 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).

3.1. Requests from 3 rd 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 Please note that, it is required that the 3 rd 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.

WMPay RESTful webservice Author: mige D_WebSingle_newWMPay_RESTful_webservice_API_V0.5.doc from 24.09.2013 Page 10 of 38 3.1.1.

Authorize Web Single Payment Path: Path: Path: Path: /authorizeWebSingle Method: Method: Method: Method: POST Description: Description: Description: 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: Request: Request: Request: Element Element Element Element Subelement Subelement Subelement Subelement Type Type Type Type Description Description Description Description Mandatory Mandatory Mandatory Mandatory msisdn Numeric The MSISDN of the end customer in international format, e.g.: 4917xxx Y serviceId Numeric The Identifier for the service configuration, which is stored in WMPay system.

Y product name Alphanu meric The name of the product offered Y description Alphanu meric A short description of the product offered by 3 rd party for the payment. Y price grossAmount Numeric The gross price of the offered product. This should be in the smallest available currency denominator of the country, where the service/content is offered (e.g.: EUROCENT) Y currency Alphanu meric The currency to be used for billing. At the moment, only EUROCENT is supported. Y tanSms text Alphanu meric 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 have have have to be used within the text and will be filled by WMPay: Placeholder Placeholder Placeholder Placeholder Description Description Description Description Mandatory Mandatory Mandatory Mandatory {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. N originator Alphanu meric The originator of the TAN SMS. It will be used, if WMPay sends TAN SMS. Beware: for alphanumeric originators, you should not use more than 8 characters!

N

WMPay RESTful webservice Author: mige D_WebSingle_newWMPay_RESTful_webservice_API_V0.5.doc from 24.09.2013 Page 11 of 38 confirmationSms text Alphanu meric 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: Placeholder Placeholder Placeholder Placeholder Description Description Description Description Mandatory Mandatory Mandatory Mandatory {PRICE} the price in EURO, that have been billed, e.g.: EUR 1,99 Y {PRODUCT} The name of the product, given by method call N If this confirmationSms parameter is not set, a default confirmation text may be sent by WMPay.

N originator Alphanu meric The originator of the confirmation SMS, if the confirmation SMS is sent by WMPay. Beware: for alphanumeric originators, you should not use more than 8 characters! N customerReference Alphanu meric This field can be used to identify the request or the transaction at the 3 rd party. It will be sent back by WMPay in the synchronous as well as in the asynchronous response. For example, this field could be used to add some kind of 3 rd party transaction ID. WMPay will not check this field for uniqueness. N responseURL Alphanu meric If a response URL is sent in the request, WMPay will work in an asynchronous way.

This means that WMPay will just check the request parameters and if they are valid, it will accept the request itself. But the final request result will be sent in a separate, asynchronous request to the 3 rd party (see chapter 3.2) N hash Alphanu meric A hash code that is used by WMPay to check the integrity of the request. This parameter is optional and will be used only if the 3 rd party’s account at WMPay is configured to use hashing. See chapter 4.1 on how to create a hash.

N costCentre Alphanu meric Identifies the cost centre to be used for all billings referencing this transaction within WMPay’s billing system. This is useful if 3 rd party has different cost centre settings and if 3 rd party wants to divide the clearing between different cost centres. N

WMPay RESTful webservice Author: mige D_WebSingle_newWMPay_RESTful_webservice_API_V0.5.doc from 24.09.2013 Page 12 of 38 Response: Response: Response: Response: Element Element Element Element Subelement Subelement Subelement Subelement Type Type Type Type Description Description Description Description Mandat Mandat Mandat Mandatory ory ory ory transactionId Alphanum eric WMPay’s identifier of the payment process, if no error has occurred.

3 rd party needs to specify this transaction ID in follow-up requests (i.e. commit or cancel requests). N customerReference Alphanum eric If 3 rd party sent a customerReference in the request, WMPay will include it in its response. This reference can be used by the 3 rd party internally for identification purposes. N status code Numeric Result of the request. See chapter 4.2 for further information. Y errorDetails Alphanum eric Contains detailed information clarifying the reasons for rejecting the request. For example, in case when error code 207 - ANOTHER TRANSACTION PENDING is returned, this field 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.

N operatorError Alphanum eric If the authorization failed at the operator interface, the operator error code will be returned within this field. N operator nwc Alphanum eric The network code of the operator, which has been identified for the authorization. This field may be empty if an error occurs or in case of asynchronous use of the interface. See chapter 4.3 for detailed information on possible network codes. N name Alphanum eric The name of the network operator identified for the billing process N provider Alphanum eric The name of the network provider identified for the billing process.

This field may not be transmitted in case when no provider has been identified for billing process. See chapter 4.4 for any further information.

N billingInterface Alphanum eric The name of the billing interface which was used for the billing process. N hash Alphanum eric A hash code that is used to check the integrity of the response. This parameter is optional and is used only in case when the 3 rd party account is configured 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. N

WMPay RESTful webservice Author: mige D_WebSingle_newWMPay_RESTful_webservice_API_V0.5.doc from 24.09.2013 Page 13 of 38 Possible HTTP status codes: Possible HTTP status codes: Possible HTTP status codes: Possible HTTP status codes: Examples: Examples: Examples: Examples: MIME type ap MIME type ap MIME type ap MIME type application/xml plication/xml plication/xml plication/xml Synchronous Request: Synchronous Request: Synchronous Request: 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.

Status Status Status Status code code code code Description Description Description 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.

WMPay RESTful webservice Author: mige D_WebSingle_newWMPay_RESTful_webservice_API_V0.5.doc from 24.09.2013 Page 14 of 38 Response: Response: Response: Response: 1 < 200 1 < Content-Type: application/xml 1 < customerReference DE-VODAFONE 26202 DE-VODAFONE OK xxxx-xxxx-xxxx-xxxx Asynchronous Request: Asynchronous Request: Asynchronous Request: 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.

WMPay RESTful webservice Author: mige D_WebSingle_newWMPay_RESTful_webservice_API_V0.5.doc from 24.09.2013 Page 15 of 38 Response: Response: Response: Response: 1 < 200 1 < Content-Type: application/xml 1 < customerReference ACCEPTED 1 xxxx-xxxx-xxxx-xxxx MIME type application/ MIME type application/ MIME type application/ MIME type application/json json json json Synchron Synchron Synchron Synchronous ous ous ous Request: Request: Request: 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: Response: Response: 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" }

WMPay RESTful webservice Author: mige D_WebSingle_newWMPay_RESTful_webservice_API_V0.5.doc from 24.09.2013 Page 16 of 38 Asynchronous Request: Asynchronous Request: Asynchronous Request: 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: Response: Response: Response: 1 < 200 1 < Content-Type: application/json 1 < { "customerReference":"customerReference", "status":{"errorDetails":"ACCEPTED","code":"1"}, "transactionId":"xxxx-xxxx-xxxx-xxxx" }

WMPay RESTful webservice Author: mige D_WebSingle_newWMPay_RESTful_webservice_API_V0.5.doc from 24.09.2013 Page 17 of 38 3.1.2. Commit Web Single Payment Path: Path: Path: Path: /commitWebSingle Method: Method: Method: Method: POST Description: Description: Description: Description: Commits a web single payment transaction. 3 rd 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: Request: Request: Request: Element Element Element Element Subelement Subelement Subelement Subelement Type Type Type Type Description Description Description Description Mandatory Mandatory Mandatory Mandatory transactionId Alphanu meric The WMPay transaction ID returned by the authorizeWebSingle (3.1.1) request.

Y tan Alphanu meric The TAN submitted by the End customer Y hash Alphanu meric A hash code that is used to check the integrity of the request. This parameter is optional and is used only in case when the 3 rd party account is configured 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. N responseURL Alphanu meric If a response URL is sent in the request, WMPay will work asynchronously. It accepts the request (if the parameters are valid) immediately, but sends the final result in a separate asynchronous request to 3 rd party (see chapter 3.2) N

WMPay RESTful webservice Author: mige D_WebSingle_newWMPay_RESTful_webservice_API_V0.5.doc from 24.09.2013 Page 18 of 38 Response: Response: Response: Response: Element Element Element Element Subelement Subelement Subelement Subelement Type Type Type Type Description Description Description Description Mandatory Mandatory Mandatory Mandatory transactionId Alphanu meric WMPay’s unique transaction identifier. Y customerReference Alphanu meric If 3 rd party sent a customerReference in authorize request, WMPay will include it in its response. This reference can be used by the 3 rd party internally for identification purposes.

N status code Numeric Result of the request. See chapter 4.2 for further information. Y errorDetails Alphanu meric Contains detailed information clarifying the reasons for rejecting the request. In case the validation of the request failed this field may contain the name of the erroneous request field. N operatorError Alphanu meric If the transaction failed at the operator interface, the operator’s error code will be returned directly within this field. N operator nwc Alphanu meric The network code of the operator, which has been identified for the authorization. This field may be empty if an error occurs or in case of asynchronous use of the interface.

See chapter 4.3 for detailed information on possible network codes.

N name Alphanu meric The name of the network operator identified for the billing process N provider Alphanu meric The name of the network provider identified for the billing process. This field may not be transmitted in case when no provider has been identified for billing process. See chapter 4.4 for any further information. N billingInterface Alphanu meric The name of the billing interface which was used for the billing process. N hash Alphanu meric A hash code that is used to check the integrity of the response. This parameter is optional and is used only in case if the 3 rd party account is configured to use hashing.

See chapter 4.1 on how to create a hash and how to check it in the response. N

WMPay RESTful webservice Author: mige D_WebSingle_newWMPay_RESTful_webservice_API_V0.5.doc from 24.09.2013 Page 19 of 38 Possibl Possibl Possibl Possible HTTP status codes: e HTTP status codes: e HTTP status codes: e HTTP status codes: Examples: Examples: Examples: Examples: MIME type application/xml MIME type application/xml MIME type application/xml MIME type application/xml Synchronous Request: Synchronous Request: Synchronous Request: 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: Response: Response: Response: 1 < 200 1 < Content-Type: application/xml 1 < customerReference ae30fdbe39858088a7a1754f6a4ac44b OK DE-VODAFONE 26202 DE-VODAFONE 19ecd709-4952-43e7-813d-760e0dc50d8c Status Status Status Status code code code code Description Description Description 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.

WMPay RESTful webservice Author: mige D_WebSingle_newWMPay_RESTful_webservice_API_V0.5.doc from 24.09.2013 Page 20 of 38 Asynchronous Request: Asynchronous Request: Asynchronous Request: 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: Response: Response: Response: 1 < 200 1 < Content-Type: application/xml 1 < 8fa32ba340fcf29e1b7c3e763476aafc 1 ACCEPTED cust ref DE-VODAFONE 26202 DE-VODAFONE xxxx-xxxx-xxxx-xxxx

WMPay RESTful webservice Author: mige D_WebSingle_newWMPay_RESTful_webservice_API_V0.5.doc from 24.09.2013 Page 21 of 38 MIME type application/json MIME type application/json MIME type application/json MIME type application/json Synchronous Request: Synchronous Request: Synchronous Request: 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: Response: Response: 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: Asynchronous Request: Asynchronous Request: 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: Response: Response: 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" }

WMPay RESTful webservice Author: mige D_WebSingle_newWMPay_RESTful_webservice_API_V0.5.doc from 24.09.2013 Page 22 of 38 3.1.3. Cancel Web Single Payment Path: Path: Path: Path: /cancelWebSingle Meth Meth Meth Method: od: od: od: POST Description: Description: Description: 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: Request: Request: Request: Element Element Element Element Subelement Subelement Subelement Subelement Type Type Type Type Description Description Description Description Mandatory Mandatory Mandatory Mandatory transactionId Alphanu meric The transaction ID returned by the authorizeWebSingle (3.1.1) request.

Y hash Alphanu meric A hash code that is used to check the integrity of the request or response. This parameter is optional and is used only if the 3 rd party’s account is 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. N responseURL Alphanu meric If a response URL is sent in the request, WMPay will work asynchronously. That means, it accepts the request itself but sends the final request result in a separate request to 3 rd party’s interface (see chapter 3.2). N

WMPay RESTful webservice Author: mige D_WebSingle_newWMPay_RESTful_webservice_API_V0.5.doc from 24.09.2013 Page 23 of 38 Response: Response: Response: Response: Element Element Element Element Subelement Subelement Subelement Subelement Type Type Type Type Description Description Description Description Mandatory Mandatory Mandatory Mandatory transactionId Alphanu meric The unique WMPay transaction identifier. Y customerReference Alphanu meric If 3 rd party sent a customerReference in the authorize request, WMPay will include it in its response. This reference can be used by the 3 rd party internally for identification purposes.

N status code Numeric Result of the request. See chapter 4.2 for further information. Y errorDetails Alphanu meric Contains detailed information clarifying the reasons for rejecting the request. In case the validation of the request failed this field may contain the name of the erroneous request field. N operatorError Alphanu meric If a cancel request failed at operator interface, the operator’s result code will be returned within this field.

N operator nwc Alphanu meric The network code of the operator, which has been identified for the authorization. This field may be empty if an error occurs or in case of asynchronous use of the interface. See chapter 4.3 for detailed information on possible network codes. N name Alphanu meric The name of the network operator identified for the billing process N provider Alphanu meric The name of the network provider identified for the billing process. This field may not be transmitted in case when no provider has been identified for billing process. See chapter 4.4 for any further information.

N billingInterface Alphanu meric The name of the billing interface which was used for the billing process.

N hash Alphanu meric A hash code that is used to check the integrity of the response. This parameter is optional and is used only if the 3 rd party’s account is configured to use hashing. See chapter 4.1 on how to create a hash and how to check it in the response. N

WMPay RESTful webservice Author: mige D_WebSingle_newWMPay_RESTful_webservice_API_V0.5.doc from 24.09.2013 Page 24 of 38 Possible HTTP status codes: Possible HTTP status codes: Possible HTTP status codes: Possible HTTP status codes: Examples: Examples: Examples: Examples: MIME type application/xml MIME type application/xml MIME type application/xml MIME type application/xml Synchronous Request: Synchronous Request: Synchronous Request: 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: Response: Response: Response: 1 < 200 1 < Content-Type: application/xml 1 < customerReference a5458dff73961ddff5ac83170220258c OK DE-VODAFONE 26202 DE-VODAFONE 53f4d21e-91af-451b-ac61-6eb114a51966 Status Status Status Status code code code code Description Description Description 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.

WMPay RESTful webservice Author: mige D_WebSingle_newWMPay_RESTful_webservice_API_V0.5.doc from 24.09.2013 Page 25 of 38 Asynchronous Request: Asynchronous Request: Asynchronous Request: 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: Response: Response: Response: 1 < 200 1 < Content-Type: application/xml 1 < 8fa32ba340fcf29e1b7c3e763476aafc 1 ACCEPTED xxxx-xxxx-xxxx-xxxx MIME type application/json MIME type application/json MIME type application/json MIME type application/json Synchro Synchro Synchro Synchronous Request: nous Request: nous Request: 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: Response: Response: Response: 1 < 200 1 < Content-Type: application/json 1 < { "customerReference":"customerReference", "hash":"0b9fa0a45e7bc695ba33d2dd5ee915986f97530284e72e8ff150e091b56ed6e6", "status":{"code":"0","errorDetails":"OK"}, "transactionId":"fab839dd-3551-430f-b3d4-7a9e14a895f6" }

WMPay RESTful webservice Author: mige D_WebSingle_newWMPay_RESTful_webservice_API_V0.5.doc from 24.09.2013 Page 26 of 38 Asynchronous Request: Asynchronous Request: Asynchronous Request: 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: Response: Response: Response: 1 < 200 1 < Content-Type: application/json 1 < { "hash":"8fa32ba340fcf29e1b7c3e763476aafc", "status":{"code":"1","errorDetails":"ACCEPTED"}, "transactionId":"xxxx-xxxx-xxxx-xxxx" }

WMPay RESTful webservice Author: mige D_WebSingle_newWMPay_RESTful_webservice_API_V0.5.doc from 24.09.2013 Page 27 of 38 3.2. Requests from WMPay to 3 rd party (asynchronous communication) The API provides both synchronous and asynchronous communication. WM recommends that an asynchronous communication is used. Some synchronous method calls may take longer and the 3 rd party’s system may experience certain problems because of timeouts – for example, depending on its settings, the 3 rd party’s communication client may disconnect if there’s no response from the WMPay in a specific amount of time.

However, 3 rd parties are free in deciding on whether they should use synchronous or asynchronous way of communication. Whether the 3 rd party prefers synchronous or asynchronous way of communication is determined by the availability of the “responseURL” parameter in the 3 rd 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 responds (synchronously) to the 3 rd party with a corresponding status code and clarifying data. If the request is successfully validated, the WMPay system checks the “responseURL” parameter.

If this parameter was set by the 3 rd party then WMPay considers the communication as asynchronous and before any further processing of the request is done it responds (synchronously) to the 3 rd 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 sent to the response URL provided by the 3 rd party in the “responseURL” request parameter.

WMPay RESTful webservice Author: mige D_WebSingle_newWMPay_RESTful_webservice_API_V0.5.doc from 24.09.2013 Page 28 of 38 The following request will be sent to the URL if the request has been processed in the backend: Path: Path: Path: Path: defined by responseURL in the request formerly sent to WMPay Method: Method: Method: Method: POST Description: Description: Description: Description: Sends the status of a fulfilled former request to 3 rd 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: Request: Request: Request: Response: Response: Response: Response: WMPay will only accept the HTTP status codes 200 (OK) and 204 (No Content) for the request response. If any other status code is returned by 3 rd party interface, WMPay will try to redeliver the request until the request timeout occurs. Any other status code will trigger an internal alerting: 3 rd party interface is not available. Element Element Element Element Subelement Subelement Subelement Subelement Type Type Type Type Description Description Description Description Mandatory Mandatory Mandatory Mandatory transactionId Alphanum eric The unique WMPay transaction ID Y customerReference Alphanum eric The customerReference provided by the 3 rd party during the initial request N status code Numeric Result of the request.

See chapter 4.2 for further information. Y errorDetails Alphanum eric Contains detailed information clarifying the reasons for rejecting the request. In case the validation of the request failed this field may contain the name of the erroneous request field. N operatorError Alphanum eric This field contains the operator result if any operator interfaces has been used during processing.

N operator nwc Alphanum eric The network code of the operator, which has been identified for the authorization. This field may be empty if an error occurs or in case of asynchronous use of the interface. See chapter 4.3 for detailed information on possible network codes. N name Alphanum eric The name of the network operator identified for the billing process N provider Alphanum eric The name of the network provider identified for the billing process. This field may not be transmitted in case when no provider has been identified for billing process. See chapter 4.4 for any further information.

N billingInterface Alphanum eric The name of the billing interface which was used for the billing process.

N hash Alphanum eric A hash code that is used to check the integrity of this request. This parameter is optional and is used only if the 3 rd party account is 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. N

WMPay RESTful webservice Author: mige D_WebSingle_newWMPay_RESTful_webservice_API_V0.5.doc from 24.09.2013 Page 29 of 38 Examples: Examples: Examples: Examples: Request Request Request Request (request has been processed successfully) (request has been processed successfully) (request has been processed successfully) (request has 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: 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: Response: Response: Response: 1 < 200 1 < Content-Type: application/json 1 < Request (request has Request (request has Request (request has Request (request has not not not not been processed successfully): been processed successfully): been processed successfully): 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: Response: Response: Response: 1 < 200 1 < Content-Type: application/json 1

WMPay RESTful webservice Author: mige D_WebSingle_newWMPay_RESTful_webservice_API_V0.5.doc from 24.09.2013 Page 30 of 38 3.2.1. Example Flow for asynchronous communication Explanation: Explanation: Explanation: Explanation: • the End customer wants to purchase service/content on the 3 rd party’s website via his mobile phone and enters his MSISDN on 3 rd party’s web page • 3 rd 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 o 3 rd 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 • WMPay calls the 3 rd party’s URL defined in the requestURL parameter of the initial call (Status: OK, appended: transaction ID, etc.) • 3 rd party displays the TAN entry page to the End customer • End customer enters the received TAN at 3 rd party’s webpage • 3 rd party calls commitWebSingle to commit the transaction and provides a responseURL • WMPay validates the parameters and returns status “ACCEPTED” o 3 rd party waits for final asynchronous method result