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

WMPay RESTful webservice Author: mige D_WebSingle_newWMPay_RESTful_webservice_API_V0.5.doc from 24.09.2013 Page 31 of 38 • 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 • 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 32 of 38 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 or response. Therefore, 3 rd 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

WMPay RESTful webservice Author: mige D_WebSingle_newWMPay_RESTful_webservice_API_V0.5.doc from 24.09.2013 Page 33 of 38 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-xxxxs ecret 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

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

WMPay RESTful webservice Author: mige D_WebSingle_newWMPay_RESTful_webservice_API_V0.5.doc from 24.09.2013 Page 35 of 38 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 Status Status Status code code code code Description Description Description Description 0 OK - request result is ok 1 ACCEPTED – the method call has been accepted. 3 rd party receives a final request for the result of the method call. This status will be just returned, if the 3 rd 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 13 WRONG TAN – the TAN delivered is wrong. 3 rd 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 200 HASH MISMATCH – the hash for the request is not matching. This usually means, 3 rd 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.

WMPay RESTful webservice Author: mige D_WebSingle_newWMPay_RESTful_webservice_API_V0.5.doc from 24.09.2013 Page 36 of 38 207 ANOTHER TRANSACTION PENDING – another transaction is pending. Please cancel the pending transaction before starting another transaction. In the response the errorDetails field is filled with the ID of the pending transaction. 209 INVALID USERNAME OR PASSWORD – no customer account found for given credentials 210 INVALID REQUEST/REQUEST NOT ALLOWED – the request is syntactically incorrect or the request is not allowed for the current state of the transaction 300 INTERNAL ERROR – an internal error occurred while processing the request in the backend

WMPay RESTful webservice Author: mige D_WebSingle_newWMPay_RESTful_webservice_API_V0.5.doc from 24.09.2013 Page 37 of 38 4.3. Network Codes (NWC) The following network codes may be transmitted by the platform. The names of the network operators may change over time, but the network code for each operator is permanent and never changes. For implementation purposes, you should use the NWC to check the operator! NWC (returned in operator.nwc response field) Name (returned in operator.name response field) Name of operator 26201 DE-TELEKOM Germany - Telekom Deutschland 26202 DE-VODAFONE Germany - Vodafone D2 26203 DE-EPLUS Germany - e-plus 26207 DE-O2 Germany - o2 26217 DE-EPLUS Germany - e-plus 4.4.

Network Provider A network provider may be identified during the billing process. If this provider has its own billing interface, it will be probably used by WMPay for the billing process. If so, the name of the provider will be appended in the return field “provider”. At the moment, there’s only one provider with its own billing interface: • Mobilcom-Debitel (DE-MOBILCOM-DEBITEL) 4.5. Billing Interface The billing interface is identified during the billing process. It is the billing system (of the network Operator / Provider) against which the payment transaction is billed. The billing interface identified by WMPay N.G.

is returned within the WMPay N.G.‘s responses (with the exception of the synchronous response used to acknowledge that an asynchronous request was accepted/validated).

Billing Interface (returned in billingInterface response field) Name of network Operator / Provider DE-TELEKOM Germany - Telekom Deutschland DE-VODAFONE Germany - Vodafone D2 DE-EPLUS Germany - e-plus DE-O2 Germany - o2 DE-MOBILCOM-DEBITEL Germany - Mobilcom-Debitel

WMPay RESTful webservice Author: mige D_WebSingle_newWMPay_RESTful_webservice_API_V0.5.doc from 24.09.2013 Page 38 of 38 5. Document History Date Date Date Date Author Author Author Author Changes Changes Changes Changes Versio Versio Versio Version n n n 2012-12-12 MIGE Initial version of specification 0.1 2013-01-14 MIGE Some little changes in network codes and error codes.

Added provider information in network info. Added development environment URL. Removed customerReference from commit and cancel 0.2 2013-03-13 MIGE STVE merchantId element was removed from the Authorize Web Single Payment request.

timeout element was removed from all requests. The placeholders for the TAN and confirmation SMS were changed from numbers to keywords. Description sub-element of the status element of all types of requests was renamed to errorDetails and was made optional. Sub-element id of the Authorize Web Single Payment request’s element product was removed. Element customerId of Authorize Web Single Payment request was renamed to serviceId. 0.4 2013-09-23 ALDA HRMU STVE TOAV Replaced element networkInfo (containing nwc, operatorName and providerName) with two separate fields operator (containing nwc and name) and provider.

Added new field billingInterface to provide the actual interface which was used for requesting the payment. Adjusted samples accordingly. Added chapter 4.5 Billing Interface. Removed StatusCode 208. Some minor corrections in the text. The name of the document was changed. 0.5