Gateway Wap en v7

Gateway Wap Spain
v.7
Elaborated by Resonance Tech, R&D Department
Gateway Wap Spain
1. REVISION HISTORY ................................................................................................................................... 2

2. INTRODUCTION .......................................................................................................................................... 3
3. OPERATOR QUERY ................................................................................................................................... 4
4. USER IDENTIFICATION .............................................................................................................................. 6
4.1. MOVISTAR ...................................................................................................................................... 11
5. SUBSCRIPTION STATUS QUERY ........................................................................................................... 13
6. WAP SUBSCRIPTION - URL METHOD .................................................................................................... 19
7. WIFI SUBSCRIPTION ................................................................................................................................ 24
7.1. WIFI SUBSCRIPTION: CONFIRMATION BY PIN - CHECKPIN .................................................... 24
7.2. WIFI SUBSCRIPTION: ACCEPTANCE OF OPERATOR CARRIED CARD - REDIRECT ............ 29
8. CANCELLATION PROCESS .................................................................................................................... 35
9. WAP SINGLE PAYMENT - URL METHOD ............................................................................................... 37
10. WIFI SINGLE PAYMENT ......................................................................................................................... 42
10.1. WIFI SINGLE PAYMENT: CONFIRMATION BY PIN-CHECKPIN ............................................... 42
10.2. WIFI SINGLE PAYMENT: ACCEPTANCE OF OPERATOR PAYMENT CARD - REDIRECT
.......................................................................................................................................................... 46
11. SINGLE PAYMENT STATUS QUERY .................................................................................................... 50
12. REFUND .................................................................................................................................................. 53
13. NOTIFICATIONS ..................................................................................................................................... 56
14. ERROR CODE LIST ................................................................................................................................ 72
Page 1
Gateway Wap Spain
1. Revision History
Revi Changes from previous release Date

sion
1 New document. 2018/04/03
2 Section 7. It has to be used input parameter "operator" in the call to the WiFi 2019/02/28
webSubscribe subscription method.
3 New examples of notifications and new error code UNKNOWN_ERROR have 2019/06/28
been respectively included in sections 12. Notifications and 13. Error Code List.
4 Section 10. WiFi Single Payment. 2019/08/01
Section 11. Error Code List. The description for error code
CAPPING_LIMIT_REACHED is included.
Page 2
Gateway Wap Spain
2. Introduction
The Resonance Tech platform offers the client an API through which they can implement a platform for
payments and subscriptions, and offer premium services charged to the user's mobile line. This API
consists of Wap payment and subscription methods, WiFi subscription, and methods of control and
management of payments and subscriptions.
The methods belonging to the Wap flow and automatic user identification will be available only when the
user browses with their mobile terminal through the operator’s data network.
The WiFi flow, however, allows charges and subscriptions to be made when the user is browsing from a
different device, such as a personal computer or tablet (provided they are not browsing through a SIM
card with 3G enabled).
Finally, the methods of management and control of payments and subscriptions offer a set of queries
and notifications through which the client knows at all times what is happening with each payment or
subscription taking place in their system.
Page 3
Gateway Wap Spain
3. Operator Query
By this method the client can find out which operator the user is browsing with from their terminal, based
on the IP address. If the client obtains an operator supported by the platform as a result of this query,
they can start a Wap payment or subscription flow.
This method is only useful if the user is browsing through their data connection and using the operator
data APN. If they are browsing with their terminal’s WiFi connection, the call will fail and the client will
have to start the WiFi payment/subscription flow.
The URL of the operator query method is http://passwap.com/gw/lookup. A GET call with the following
parameters must be made:
api_key: service identification hash.
ip: IP from which the user is browsing.
Example call:
http://passwap.com/gw/lookup?
api_key=11310430628cec77317f1aec7a88a54b&
ip=88.214.165.117
Response OK:
<?xml version="1.0" encoding="ISO-8859-1" ?>
Page 4
Gateway Wap Spain
<lookup>
<status>OK</status>
<operator>vodafone</operator>
</lookup>
Unresolved response:
<lookup>
<status>ERROR</status>
<code>UNKNOWN_OPERATOR</code>
<reason>Unknown operator</reason>
</lookup>
Page 5
Gateway Wap Spain
4. User Identification
By this method the client can check the MSISDN of a user when they are browsing from their mobile
device and using the operator data APN. Once the user has been identified, the client can check the
status of the subscription in order to offer the user either the contracted services or the subscription.
The identification process chart is as follows:
The description of the identification process is as follows:
1. The user requests access to the client’s Wap subscription portal.
2. To identify the user, the client must request a user identification URL. The URL of the method for
obtaining an identification URL is http://passwap.com/gw/identifyUrl. A GET call with the following
parameters must be made:
Page 6
Gateway Wap Spain
return_url: Return URL to which the user will be redirected once identification has been processed.
This URL is provided by the client. This parameter must be url_encoded.
Example of the call the client must make to get the identification URL:
http://passwap.com/gw/identifyUrl?
return_url=http%3A%2F%2Fcliente.com%2Fidentify_back
3. A user identification URL is returned.
Example response to a correct request:
<identifyUrl>
<status>OK</status>
<url><![CDATA[http://passwap.com/gw/identify/bf02b27c-ea76-450d-8673-8fa2d3598650?qs=14
289136801759]]></url>
</identifyUrl>
Page 7
Gateway Wap Spain
Example response to an erroneous request:
<identifyUrl>
<code>VALIDATION_ERROR</code>
<reason>Invalid or return_url not found</reason>
</identifyUrl>
4. The client has obtained the identification URL and redirects the user to that URL.
5. The user accesses the identification URL from their terminal.
6. Once the user has been identified, they are redirected to the client’s return URL, indicated by the client
in step 2 (return_url). This return URL has been enriched by adding the following parameters:
status: Indicates the status of identification. Possible values: "OK", "ERROR"
operator: Indicates the user operator. Possible values: “movistar”, “vodafone”, “yoigo”, “orange”. This
parameter is added only if it has been possible to determine the operator.
token: String hash with which the client can obtain the user's MSISDN.
error_type: Error code in case of identification failure (see list of errors).
Page 8
Gateway Wap Spain
Example of URL to which the user is sent once their identification has been attempted, but the process
has not concluded satisfactorily:
http://cliente.com/identify_back?
status=ERROR&
error_type=UNKNOWN_OPERATOR
Example of URL to which the user is sent once their identification has been attempted satisfactorily:
http://cliente.com/identify_back?
status=OK&
operator=movistar&
token=C04628C17DC94DC09E1A3AC642CE9920
7. On the page to which they have been sent after identification, the user asks the client for the
parameters added by the Resonance Tech platform.
8. With the token obtained, the client must make a call to the checkIdentifyUser method to complete the
identification process and obtain the user MSISDN.
Page 9
Gateway Wap Spain
The URL of the method is http://passwap.com/gw/checkIdentifyUser, with the following parameters:
token: identification hash received.
Example call:
http://passwap.com/gw/checkIdentifyUser?
token=C04628C17DC94DC09E1A3AC642CE9920
9. Response to the call. The response to the call is an XML with the following format:
<checkIdentifyUser>
<status>OK</status>
<operator>yoigo</operator>
<msisdn>nnnnnnnnn</msisdn>
</checkIdentifyUser>
Page 10
Gateway Wap Spain
In which:
status: Indicates the status of identification. Possible values: “OK”, “ERROR”
operator: Indicates the user operator. Possible values: “movistar”, “vodafone”, “yoigo”, “orange”. Only
if it has been possible to identify the operator.
msisdn: The user’s MSISDN, without international code. Sometimes it is possible that instead of the
MSISDN an alphanumeric string will be returned. This is a unique alphanumeric identifier. If this
identifier is returned, it can also be used in the subscription status query method.
code: Error code in case of identification failure (see list of errors).
Example of erroneous identification:
<checkIdentifyUser>
<code>INVALID_TOKEN</code>
</checkIdentifyUser>
4.1. Movistar
This operator modified the way of identify users. This operator will only provide the MSISDN if the end
user have a subscription active on the service that is trying to acces. If the end user dont have any
subscription active passwap will return the following error:
Page 11
Gateway Wap Spain
status=ERROR&error_type=IDENTIFICATION_ERROR
Page 12
Gateway Wap Spain
5. Subscription Status Query
The client can check the status of a subscription or whether a user has an active subscription. They can
make the query based on the unique subscription identifier (sid) which is provided when a subscription is
made, or based on the user MSISDN. In the latter case, the status of the last subscription made in that
service is returned.
The subscription query method URL is http://passwap.com/gw/checkSubscription, with the following

parameters:
api_key: Service identification hash.
sid: Unique subscription identifier (*1)
msisdn: user MSISDN (*1)
(*1) Only one of the two parameters is required.
Example call with subscription identifier:
http://passwap.com/gw/checkSubscription
sid=C04628C17DC94DC09E1A3AC642CE9920
Page 13
Gateway Wap Spain
Example call with user MSISDN:
http://passwap.com/gw/checkSubscription?
msisdn=nnnnnnnnn
An XML with the subscription information is returned.
In case of error with the following structure:
<checkSubscription>
<code>SUBSCRIPTION_NOT_FOUND</code>
<reason>Subscription not found</reason>
</checkSubscription>
In which:
Page 14
Gateway Wap Spain
status: Call status.
code: Error code. (See table of errors)
reason: Brief description of error.
If the subscription is found an XML with the following structure is returned:
<checkSubscription>
<status>OK</status>
<subscription>
<sid>557CC7DDC4534877B6D9F97C7D68AF62</sid>
<status>OK</status>
<msisdn>nnnnnnnnn</msisdn>
<metadata><![CDATA[23ce185134]]></metadata>
<startDate>2013-09-05 13:04:32</startDate>
<endDate></endDate>
<lastBillingStatus>OK</lastBillingStatus>
<lastBillingDate>2013-09-05 13:04:34</lastBillingDate>
</subscription>
Page 15
Gateway Wap Spain
In which:
sid: Unique subscription identifier
status: Subscription status. Possible values: “OK” (current subscription), “DELETED” (cancelled
subscription)
msisdn: user MSISDN
metadata: Client’s own data, provided by the client when creating the subscription
startDate: Subscription start date
endDate: subscription cancellation date
lastBillingStatus: Status of last payment processed. Possible values: “OK”, “ERROR”
lastBillingDate: Date of last payment processed.
The above example is for a current subscription whose last payment was processed correctly.
Example of the status of a subscription with last payment failed:
<checkSubscription>
Page 16
Gateway Wap Spain
<status>OK</status>
<subscription>
<sid>BC1E0B4B31F54800994D334D889D11A2</sid>
<status>OK</status>
<msisdn>667790520</msisdn>
<metadata><![CDATA[5c04925674]]></metadata>
<endDate></endDate>
<lastBillingStatus>ERROR</lastBillingStatus>
</subscription>
Example of a cancelled subscription:
<checkSubscription>
<status>OK</status>
<subscription>
Page 17
Gateway Wap Spain
<sid>C96112F8723545F6B534D846359C13A5</sid>
<status>DELETED</status>
<metadata><![CDATA[e4a6222cdb]]></metadata>
<endDate>2013-09-05 10:19:33</endDate>
<lastBillingStatus>ERROR</lastBillingStatus>
</subscription>
Page 18
Gateway Wap Spain
6. Wap Subscription - URL method
The URL subscription method enables the client to obtain a URL to which they can redirect the user to
make a subscription attempt. Subscription by this method is only available when the user is browsing
from their mobile device and using the operator data APN. When this occurs, an attempt will be made to
subscribe the user, who will then be sent to the client’s return URL.
The flowchart of subscription by the URL method is as follows:
The description of the subscription process is as follows:
1. The user accesses the client’s service home page. They accept the terms and want to subscribe.
2. The client then requests a subscription URL by the subscribeUrl method.
Page 19
Gateway Wap Spain
The URL of the method is http://passwap.com/gw/subscribeUrl, with the following parameters:
api_key: Service identification hash
return_url: Client return URL, to which the user will be redirected once they have completed the
subscription process. It must be url_encoded.
metadata: Free field for client use. This field can be used, for example, for storing data relating to the
user, subscription, etc. Maximum length: 512 characters.
card_id: Operator carrier card customization identifier. With this ID the client can select which carrier
card they want to show if the operator so requires.
Example call to the subscribe Url method:
http://passwap.com/gw/subscribeUrl?
return_url=http%3A%2F%2Fcliente.com%2Fsubscribe_back&
operator=vodafone&
metadata=dd45850574&
card_id=modelo1
3. Response to the subscribeUrl call.
The answer is an XML with the URL to which the client must send the user. The XML will have the
following structure:
Page 20
Gateway Wap Spain
<subscribeUrl>
<status>OK</status>
<url><![CDATA[http://passwap.com/gw/subscribe?request_id=267b0ca3-69f6-4976-8168-1f09f0
3ba205&api_key=33083c57ee6cec83c3bf9dcf77bed37a&tool=pagosvodafone]]></url>
</subscribeUrl>
In which:
status: Status of the subscription button request. Possible values: “OK”, “ERROR”
url: Contains the URL to which the client must send the user.
Example of an erroneous call:
<subscribeUrl>
<code>UNKNOWN_SERVICE</code>
<reason>Unknown service</reason>
</subscribeUrl>
Page 21
Gateway Wap Spain
4. The client sends the user to the <url> received.
5. The user browses to the subscription URL.
6. The user accepts the operator’s confirmation page (if any) and is redirected to the client return URL,
indicated by the client in step 2 (return_url).
After attempting the subscription of the user, the latter is redirected to the client return URL, to which the
following parameters have been added:
status: Indicates the subscription status. Possible values: “OK”, “ERROR”
error_type: Error code in case of subscription failure (see list of errors).
If the subscription has been successfully completed, the platform proceeds to make the first payment for
the first cycle of the subscription.
Example of successful subscription:
http://cliente.com/subscribe_back?
status=OK&
Page 22
Gateway Wap Spain
Example of failed subscription:
status=ERROR&
error_type=ALREADY_SUBSCRIBED
7. The user requests the client return URL page, with the parameters added by the Resonance Tech
platform. At this time, the client may want to make a call to the subscription status query method to
validate the integrity of data received and check the status of down payment if any.
8. The client responds to the user with the welcome page.
Page 23
Gateway Wap Spain
7. WIFI Subscription
The WiFi subscription method allows users to subscribe via Web browsing. Depending on the service
offered and the user operator, subscription is completed by a confirmation flow with a PIN code, by a
flow of acceptance of a carrier card of the operator, or by a redirect plus pin confirmation. When to use
one flow type or another will be indicated in the response to the WiFi subscription method call, which is
common to all flows.
7.1. WiFi SUBSCRIPTION: CONFIRMATION

BY PIN - CHECKPIN
The flow for WiFi subscription by PIN confirmation is as follows:
The subscription process for the flow based on PIN confirmation is described below:
1. The user accesses the client service home page.
2. The client makes a call to the WiFi webSubscribe subscription method.
Page 24
Gateway Wap Spain
The URL is http://passwap.com/gw/webSubscribe, with the following parameters:
operator: User operator (orange, yoigo, vodafone or movistar)
return_url: Client return URL. In the PIN confirmation process this parameter has no effect. However
if you do not know in advance which method will be used, it is mandatory to add a return URL.
msisdn: The user’s phone number without international code.
Example call to the webSubscribe API:
http://passwap.com/gw/webSubscribe?api_key=dbdcd7e60c919512f18f58d8eba531c1&operator=orang
e&msisdn=667790520&return_url=http%3A%2F%2Fcliente.com%2Fsubscribe_back&
metadata=dd45850574&card_id=modelo1
3. Response to the webSubscribe call.
The response is an xml indicating which subscription flow to follow and providing additional information.
For PIN confirmation, the additional information is a URL. An SMS will be sent to the user with a PIN
code. The user must enter this PIN in the client website, and the client must confirm the validity of the
Page 25
Gateway Wap Spain
PIN against the URL returned in the call to the webSubscribe API.
The xml of the response to the call will have the following structure:
<webSubscribe>
<status>OK</status>
<url><![CDATA[http://passwap.com/gw/webSubscribeCheckPin/orange/33083c57ee6cec83c3bf
9dcf77bed37a/c7034b4a-c8ce-4aee-a152-0ec76a08e0be]]></url>
<method>CHECKPIN</method>
<operator>orange</operator>
</webSubscribe>
In which:
status: Status of the subscription request. Possible values: “OK”, “ERROR”
method: Contains the method that the client must follow to complete the subscription. In this case
"CHECKPIN"
operator: User operator
url: URL against which the client has to check the PIN received by the user by adding the parameter
“pin” to it.
Page 26
Gateway Wap Spain
<webSubscribe>
<reason>Invalid msisdn</reason>
</webSubscribe>
4. In the PIN confirmation method, the client serves the user an acceptance page where they must enter
the PIN received in their terminal.
5. The PIN is sent to the user’s terminal.
6. The user enters the PIN on the client website.
7. The client makes a call to the URL returned in step 3 with a single parameter: the PIN that the user
has entered. Example call to this URL:
http://passwap.com/gw/webSubscribeCheckPin/orange/33083c57ee6cec83c3bf9dcf77bed37a/c7034
Page 27
Gateway Wap Spain
b4a-c8ce-4aee-a152-0ec76a08e0be?pin=xxxx
At this time, if the PIN is correct, an attempt is made to process the subscription.
8. Response to the call. The result of the operation will be returned in the call itself in an XML with the
following fields:
status: Subscription status. Possible values: “OK”, “ERROR”
sid: The ID of the subscription, if successful..
<webSubscribeCheckPin>
<status>OK</status>
<sid>D34905D1FCB246E18A7426550B2CEA50</sid>
</webSubscribeCheckPin>
At this point the client may choose to make a call to the subscription status query API for more
information.
Page 28
Gateway Wap Spain
<webSubscribeCheckPin>
<code>WRONG_PIN</code>
<reason>Wrong pin code provided</reason>
</webSubscribeCheckPin>
9. The client serves the user the welcome page or error information page as appropriate.
7.2. WiFi SUBSCRIPTION: ACCEPTANCE OF

OPERATOR CARRIED CARD - REDIRECT
The flow for WiFi subscription by acceptance of operator carrier card is as follows:
Page 29
Gateway Wap Spain
The subscription process for flow based on acceptance of the operator carrier card is described below:
2. The client makes a call to the WiFi webSubscribe subscription method.
The URL is http://passwap.com/gw/webSubscribe, with the following parameters:
operator: User operator (orange, yoigo, vodafone or movistar)
subscription process. It must be url_encoded.
Page 30
Gateway Wap Spain
Example call to the webSubscribe API:
http://passwap.com/gw/webSubscribe?api_key=dbdcd7e60c919512f18f58d8eba531c1&operator=movist
ar&msisdn=667790520&
return_url=http%3A%2F%2Fcliente.com%2Fsubscribe_back&metadata=dd45850574&card_id=modelo1
3. Response to the webSubscribe call.
The response is an XML indicating which subscription flow to follow and a URL. For the flow with
authentication by operator carrier card, a URL will be returned, where the client should redirect the user.
In this case, the XML will have the following structure:
<webSubscribe>
<status>OK</status>
<url><![CDATA[https://pagos.movistar.es/pegui/purchase.action?callback_url=http%3A%2F%
2Fpasswap.com%2Fgw%2Fcashlog%2Fsubscribe_ok&error_callback_url=http%3A%2F%2Fpa
sswap.com%2Fgw%2Fcashlog%2Fsubscribe_ko&price=0.12&name_merchant=Suscripci%C3
%B3n&sub_frequency=W&sub_start_date=2014-09-05&request_id=noqbuoQccUzKkvJmKiLU
BA%3D%3D&currency=EUR&subscription=Y&merchant_website_url=&country=es&user_id=
%2B34638137441&user_id_type=MSISDN&telco_code=movistar]]></url>
<method>REDIRECT</method>
Page 31
Gateway Wap Spain
<operator>movistar</operator>
</webSubscribe>
In which:
status: Status of the subscription request. Possible values: “OK”, “ERROR”
method: Contains the method that the client must follow to complete the subscription. In this case
"REDIRECT"
operator: User operator
url: URL to which the client should redirect the user to complete the authorization.
<webSubscribe>
<reason>Invalid msisdn</reason>
</webSubscribe>
Page 32
Gateway Wap Spain
4. In the method of confirmation by operator carrier card, the client should redirect the user to the URL
returned, which corresponds to the operator carrier card, where the user must follow the instructions to
complete the subscription.
5. The user requests the operator carrier card and accepts the subscription.
6. The user is redirected to the client return URL, indicated by the client in step 2 (return_url).
After attempting the subscription of the user, the latter is redirected to the client return URL, to which the
following parameters have been added:
status: Indicates the subscription status. Possible values: “OK”, “ERROR”
error_type: Error code in case of subscription failure (see list of errors).
If the subscription has been successfully completed, the platform proceeds to make the first payment for
the first cycle of the subscription.
status=OK&
Page 33
Gateway Wap Spain
status=ERROR&
platform. At this time, the client may want to make a call to the subscription status query method to
validate the integrity of the data received and check the status of down payment.
Page 34
Gateway Wap Spain
8. Cancellation Process
Cancellation is deferred. At the time the API is called, the cancellation sms is sent and the cancellation is
processed in the operator, but the subscription status query API still responds that the subscription is
active until the period of the last payment ends.
The cancellation method URL is http://passwap.com/gw/cancelSubscription, with the following

parameters:
api_key:Service identification hash.
sid: Unique subscription identifier (*1)
Example request:
http://passwap.com/gw/cancelSubscription?
The response is an XML with the status of the request. Example response to a correctly processed
cancellation request:
Page 35
Gateway Wap Spain
<cancelSubscription>
<status>OK</status>
</cancelSubscription>
In case of error, the XML will have the following structure:
<cancelSubscription>
<code>ALREADY_UNSUBSCRIBED</code>
<reason>Already unsubscribed</reason>
</cancelSubscription>
In which:
Page 36
Gateway Wap Spain
9. Wap Single Payment - URL method
The URL single payment method allows the client to get a URL to which they can redirect the user to
make a single payment attempt. When this occurs, the user will be sent to the client return URL.
The URL single payment flowchart is as follows:
The description of the single payment process is as follows:
2. The client requests a payment URL through the payUrl API.
Page 37
Gateway Wap Spain
The URL is http://passwap.com/gw/payUrl, with the following parameters:
return_url: Client return URL, to which the user will be redirected once they complete the payment
process. It must be url_encoded.
metadata: Free field for client use. Este dato puede usarse por ejemplo para propagar datos relativos
al usuario, al pago, etc. Maximum length: 512 characters.
Example call to the payUrl API:
http://passwap.com/gw/payUrl?
api_key=33083c57ee6cec83c3bf9dcf77bed37a&
return_url=http%3A%2F%2Fcliente.com%2Fpay_back&
operator=vodafone&
metadata=dd45850574&
card_id=modelo2
3. Response to the payUrl call.
Page 38
Gateway Wap Spain
The response is an XML with the URL which the client must include on their page. The XML will have the
following structure:
<payUrl>
<status>OK</status>
<url><![CDATA[http://passwap.com/gw/pay?request_id=b0dbc56e-b0d1-4813-a694-48b107710
97&api_key=33083c57ee6cec83c3bf9dcf77bed37a&tool=pagosvodafone]]></url>
</payUrl>
In which:
status: Status of the payment URL request. Possible values: “OK”, “ERROR”
url: Contains the URL which the client must include on their page before serving it to the user.
<payUrl>
Page 39
Gateway Wap Spain
</payUrl>
4. The client serves the user an acceptance page containing the terms of the payment service. This page
will have the URL returned in point 3 embedded in it.
5. The user accepts the page and clicks on the payment button.
6. The user accepts the operator’s confirmation page (if any) and is redirected to the client return URL,
indicated by the client in step 2 (return_url).
After attempting payment, the user is redirected to the client return URL, to which the following
parameters have been added:
status: Indicates the status of payment. Possible values: “OK”, “ERROR”
pid: Unique payment identifier.
error_type: Error code in case of payment failure. (See list of errors)
Example of return of successful payment:
http://cliente.com/pay_back?
Page 40
Gateway Wap Spain
status=OK&
pid=C04628C17DC94DC09E1A3AC642CE9920
Example of return of failed payment:
http://cliente.com/pay_back?
status=ERROR&
error_type=BLACKLIST
platform. At this time, the client may want to make a call to the single payment query method to validate
the integrity of the data received.
Page 41
Gateway Wap Spain
10. WiFi Single Payment
The WiFi single payment method allows users perform a single purchase while surfing via Web
browsing. Depending on the service offered and the user operator, the single payment is completed by a
confirmation flow with a PIN code or by a REDIRECT confirmation flow by the acceptance of a carrier
card. When to use one flow type or the other will be indicated in the response of the WiFi single payment
method call, which is common to both flows.
The method url is http://passwap.com/gw/webPay, with the following parameters:
return_url: Client return URL. In the PIN confirmation process this parameter has no effect. However if
you do not know in advance which method will be used, it is mandatory to add a return URL.
metadata: Optional free field for client use. This field can be used, for example, for storing data relating
to the user, the single purchase, etc. Maximum length: 512 characters.
The WiFi single payment method by url, allows client to obtain a url to which redirect user to attempt a
single payment. When the single purchase is accomplished, the user will be sent to the client return url
set in the call.
10.1. WiFi Single Payment: Confirmation by
Page 42
Gateway Wap Spain
pin-CHECKPIN
The CHECKPIN WiFi single payment flowchart is as follows:
The description of the CHECKPIN WiFi single payment process is as follows:
2. The client requests a payment URL through the WiFi single payment API method webPay.
The url is http://passwap.com/gw/webPay, with the following paramenters:
return_url: Client return URL. In the PIN confirmation process this parameter has no effect. However
if you do not know in advance which method will be used, it is mandatory to add a return URL.
metadata: Optional free field for client use. This field can be used, for example, for storing data
relating to the user, the single purchase, etc. Maximum length: 512 characters.
Page 43
Gateway Wap Spain
Example call to the webPay API method:
http://passwap.com
/gw/webPay?api_key=dd67bebfdb52ffbed8b8f1fbb7396055&return_url=http://www.google.com&msis
dn=638137441
3. Response to the webPay API call.
The response is an xml indicating which subscription flow to follow and providing additional
information. For PIN confirmation, the additional information is a URL. An SMS will be sent to the user
with a PIN code. The user must enter this PIN in the client website, and the client must confirm the
validity of the PIN against the URL returned in the call to the webSubscribe API.
The xml of the response to the call will have the following structure:
<webPay>
<status>OK</status>
<url>http://passwap.com/gw/webPayCheckPin/movistar/dd67bebfdb52ffbed8b8f1fbb7396055/03b90f
98-020c-a389-29f1-00005d4026aa</url>
<method>CHECKPIN</method>
<operator>movistar</operator>
</webPay>
In which:
status: Status of the single payment request. Possible values: “OK”, “ERROR”.
url: URL against which the client has to check the PIN received by the user by adding the parameter
“pin” to it.
Page 44
Gateway Wap Spain
method: Contains the method that the client must follow to complete the single payment. In this case
"CHECKPIN".
operator: User's operator.
Example of an erroneous call response:
<webPay>
<code>UNKNOWN_OPERATOR</code>
<reason>Unknown operator</reason>
</webPay>
4. In the PIN confirmation method, the client serves the user an acceptance page where they must
enter the PIN received in their terminal. .
5. The PIN is sent to the user’s terminal.
6. The user enters the PIN on the client website.
7. The client makes a call to the URL returned in step 3 with a single parameter: the PIN that the user
has entered. Example call to this URL:
http://passwap.com/gw/webPayCheckPin/movistar/dd67bebfdb52ffbed8b8f1fbb7396055/03b90f98-02
0c-a389-29f1-00005d4026aa?pin=xxxx
At this time, if the PIN is correct, an attempt is made to process the payment.
8. Response to the call. The result of the operation will be returned in the call itself in an XML with the
following field:
status: The payment status. Possible values “OK” or “ERROR”.
pid: The payment id, if successful.
Page 45
Gateway Wap Spain
Example of successful payment:
<webPayCheckPin>
<status>OK</status>
<pid>01916e68010ca545699800005d402782</pid>
</webPayCheckPin>
At this point, the client may choose to make a call to the payment status query API for more
information.
Example of failed payment:
<webPayCheckPin>
</webPayCheckPin>
9. The client serves the user the welcome page or error information page as appropriate.
10.2. WiFi Single Payment: Acceptance of

operator payment card - REDIRECT
The flowchart for WiFi single payment by acceptance of operator payment card with redirect is as
follows:
Page 46
Gateway Wap Spain
The WiFi single payment process for the flow based on acceptance of the operator payment card is
described below:
2. The client makes a call to the WiFi webPay method.
The url is http://passwap.com/gw/webPay, with the following parameters:
api_key: Service identification Hash.
single payment process. It must be url_encoded.
msisdn: The user's phone number without international code.
metadata: Optional free field for client use. This field can be used, for example, for storing data
relating to the user, the single purchase, etc. Maximum length: 512 characters.
card_id: Operator carrier card customization identifier. With this ID the client can select which
carrier card they want to show if the operator so requires.
Example call to the webPay API call:
http://passwap.com/gw/webPay?api_key=a1ec98867d86b09d7c7aea5ba67d2cdc&return_url=http://www
Page 47
Gateway Wap Spain
.google.de&msisdn=635646879
3. Response to the webPay call.
The response is an XML indicating which single payment flow to follow and a URL. For the flow with
acceptance of operator carrier card, a URL will be returned, where the client should redirect the user. In
this case, the XML will have the following structure:
<webPay>
<status>OK</status>
<url>https://enabler.dvbs.com/session/cardm/web/627ebfc6-1990-4416-82bc-506c954708e5/00cfa954-
e819-ab8c-eac1-00005d405c6b</url>
<method>REDIRECT</method>
<operator>orange</operator>
</webPay>
In which:
status: Status of the single payment request. Possible values: “OK” or “ERROR”.
method: Contains the method that the client must follow to complete the single payment. In this
case "REDIRECT".
operator: User's operator.
url: URL to which the client should redirect the user to complete the single payment.
<webPay>
</webPay>
4. In the method of confirmation by operator carrier card, the client should redirect the user to the URL
returned, which corresponds to the operator carrier card, where the user must follow the instructions to
complete the single payment.
5. The user requests the operator carrier card and accepts the single payment.
Page 48
Gateway Wap Spain
6. The user is redirected to the client return URL, indicated by the client in step 2 (return_url).
After attempting the single payment, the user is redirected to the client return URL, to which the following
parameters have been added:
status: Indicates the subscription status. Possible values: “OK” or “ERROR”.
error_type: Error code in case of payment failure (see list of errors).
platform. At this time, the client may want to make a call to the single payment status query method to
validate the integrity of the data received and check the status of the payment.
Page 49
Gateway Wap Spain
11. Single Payment Status Query
The client can check the status of a single payment. The query should be made based on the unique
payment identifier (pid) provided when a single payment is made. In case of a successful request,
additional payment information will be returned.
The payment query method URL is http://passwap.com/gw/checkPayment, with the following

parameters:
pid: Unique payment identifier
Example call:
http://passwap.com/gw/checkPayment?
api_key=33083c57ee6cec83c3bf9dcf77bed37a&
pid=c99122e348a641deaa5b9f0d106b65da
An XML is returned with the payment information:
<checkPayment>
Page 50
Gateway Wap Spain
<status>OK</status>
<payment>
<pid>c99122e348a641deaa5b9f0d106b65da</pid>
<price>0.01</price>
<date>2014-09-05 11:04:59</date>
</payment>
</checkPayment>
In which:
msisdn: user MSISDN
price: Payment price
date: Payment date
In case of error, an XML is returned with the following structure:
Page 51
Gateway Wap Spain
<payment>
</payment>
In which:
Page 52
Gateway Wap Spain
12. Refund
The Refund method allows client to pay back a subscription renewal or a single payment purchase to the
end user. Note that in order to refund a single payment purchase, the client should provide two
parameters that identify the single purchase but in case to refund a subscription renewal payment the
client should provide three parameters to identify a particular payment transaction.
The Refund query method URL is http://passwap.com/gw/refund
With the following parameters in case of single payment purchase:
pid: Unique payment identifier
And with the following parameter in case of a subscription renewal payment:
sid: Unique subscription identifier.
Example call to the Refund API for a single payment purchase:
http://passwap.com/gw/refund?
api_key=6183aa6582a2aaa8ee6be1eebf579652&
Page 53
Gateway Wap Spain
pid=0570632c-0119-ac89-5054-00005aa69f66
Example call to the Refund API for a subscription renewal payment:
http://passwap.com/gw/refund?
api_key=6183aa6582a2aaa8ee6be1eebf579652&
pid=0570632c-0119-ac89-5054-00005aa69f66
sid=0502a56c010ca490797a00005aa69f65
In case of success, an XML is returned with the following structure:
<refund>
<status>OK</status>
</refund>
In case of error, an XML is returned with the following structure:
<refund>
<code>PAYMENT_NOT_FOUND</code>
<reason>Payment not found</reason>
</refund>
Page 54
Gateway Wap Spain
In case of error due to the payment has already been refunded, the returned XML is as follows:
<refund>
<reason>Payment already refunded</reason>
</refund>
Page 55
Gateway Wap Spain
13. Notifications
The Resonance Tech platform has a notification system whereby the client is informed of events relating
to subscriptions and attempted subscriptions. When registering the service, the client must provide a
URL on which Resonance Tech will report all the events that take place. Notifications are via GET to the
notification URL provided by the client, to which the relevant parameters are added.
The types of notification are as follows:
SUBSCRIPTION_OK: A subscription has been registered in the system.
SUBSCRIPTION_ERROR: There has been a failed subscription attempt.
BILLING_OK: A charge has been issued for an active subscription.
BILLING_ERROR: There has been an attempt to charge an active subscription, but it has failed.
UNSUBSCRIPTION_REQUEST: The subscription cancellation has been requested but it will not take
effect until the renewal period is expired.
UNSUBSCRIPTION: A subscription cancellation has been processed.
BILLING_REFUND: A refund has been successfully processed in the system.
Parameters added to the client notification URL.
Not all parameters are available in all types of notifications. The list of parameters is as follows:
sid: Unique subscription identifier. (All except SUBSCRIPTION_ERROR and BILLING_REFUND for
single payment purchase)
Page 56
Gateway Wap Spain
pid: Unique payment identifier. (BILLING_OK and BILLING_REFUND)
metadata: Client’s own data, provided by the client when creating the subscription. (All)
msisdn: The user MSISDN. (All except SUBSCRIPTION_ERROR)
price: Price of subscription (without VAT) (All except SUBSCRIPTION_ERROR)
date: Date of event. (All )
operator: User operator. (All )
api_key: Service identification hash. (All )
type: Type of notification. (All )
error_type: Error code. (See list of errors) (SUBSCRIPTION_ERROR, BILLING_ERROR and

UNSUBSCRIPTION)
error_code: Main error code, from the operator (if available)
error_description: Brief description of error, from the operator (if available)
fail_code: Detailed error code, from the operator (if available)
Error Type List
Type Description
API_CANCEL Content provider requested the subscription
Termination
OPERATOR_ERROR User terminated the subscription calling
Operator CC
LIFECYCLE Subscription terminated by platform due lifecycle
BLACKLIST Subscription terminated because user is on
blacklist
NOT_ACTIVE The subscription is not active on operator
database
Page 57
Gateway Wap Spain
Example notifications:
Subscription OK Vodafone:
http://cliente.com/call_back?
sid=19CED68DE29943938497E9DC6942D3BC&
metadata=2421fcb126&
msisdn=nnnnnnnnn&
price=0.10&
date=2013-09-10+13%3A57%3A56&
operator=vodafone&
type=SUBSCRIPTION_OK
Subscription KO Vodafone (the user pressed Cancel):
metadata=a3c65c2974&
date=2013-09-10+13%3A22%3A16&
operator=vodafone&
Page 58
Gateway Wap Spain
error_code=E-CUSTCANC&
error_description=Compra+cancelada+por+el+usuario&
type=SUBSCRIPTION_ERROR&
error_type=USER_CANCEL
Subscription KO Yoigo (the user pressed Cancel):
metadata=58ae749f25&
date=2013-09-10+17%3A54%3A41&
operator=yoigo&
api_key=dbdcd7e60c919512f18f58d8eba531c1&
error_code=0&
error_description=Success%7CAborted+by+consumer&
fail_code=0&
Subscription KO MoviStar (the user pressed Cancel):
Page 59
Gateway Wap Spain
metadata=daca41214b&
date=2013-09-12+11%3A09%3A59&
operator=movistar&
api_key=8db51b5c7832d74a77216be96ec86c39&
error_code=ERR_0127&
error_description=Operation+aborted+by+user.+Redirect+now&
Subscription KO Orange (the user pressed Cancel):
MainController::__construct REQUEST /gw/subscribeBack/orange?
request_id=03fde0c8-030c-a480-5fe2-00005b28e240&
result=ERROR&
error_code=CANCELLED_BY_USER&
message=Subscription+cancelled+by+user&
session_id=0014350c-0219-aba3-6233-00005b28e242
Subscription KO, user already subscribed:
Page 60
Gateway Wap Spain
metadata=362e80d4df&
date=2013-09-10+15%3A58%3A51&
operator=vodafone&
Limit of active subscriptions in Vodafone:
metadata=6aca97005c&
date=2013-09-10+16%3A30%3A02&
operator=vodafone&
error_code=E-MAX-USER-TRANS-EXC&
error_description=Se+ha+superado+el+maximo+de+suscripciones+activas+para+el+cliente&
error_type=OPERATOR_ERROR
Billing OK in Vodafone:
Page 61
Gateway Wap Spain
sid=929A902735C744039B1234A2F25BC2D4&
metadata=3a066bda8c&
msisdn=nnnnnnnnn&
price=0.10&
date=2013-09-10+15%3A56%3A00&
operator=vodafone&
type=BILLING_OK
Billing KO vodafone
sid=929A902735C744039B1234A2F25BC2D4&
msisdn=nnnnnnnnn&
price=0.10&
date=2013-09-10+16%3A01%3A54&
operator=vodafone&
Page 62
Gateway Wap Spain
error_code=E-MAN-PER-CAPT&
error_description=La+suscripcion+ya+ha+sido+cobrada+una+vez+para+el+periodo+en+curso&
type=BILLING_ERROR&
error_type=GENERIC_ERROR
Billing KO yoigo
sid=3DF6FE959E7046A281639F0DFFCE9D46&
metadata=2e65f2f2fd&
msisdn=nnnnnnnnn&
price=0.01&
date=2013-09-10+17%3A58%3A42&
operator=yoigo&
error_code=10&
error_description=The+service+provider+charging+frequency+is+exceeded&
fail_code=0&
type=BILLING_ERROR&
Page 63
Gateway Wap Spain
Cancellation via API:
http://serviciocliente.com/orange/notifications?
type=UNSUBSCRIPTION_REQUEST&
error_type=API_CANCEL&
operator=orange&
date=2018-02-26+10%3A08%3A08&
api_key=1431d25a1ba8f576b0d24423d0140d1b&
sid=059cf7ac010ca5c83e9000005a925d4a&
msisdn=nnnnnnnnn&
metadata=34651592705&
price=2.06&
error_description=Unsubscription+via+API en pycola.jmeservicios.com:6374;PASSWAP_notificaciones
_h_<servicio>.com
Cancellation via API:
sid=F010DBD4D8E54E20BDEAC54528FF5F7D&
metadata=08419be897&
msisdn=nnnnnnnnn&
Page 64
Gateway Wap Spain
price=0.10&
date=2013-09-10+15%3A52%3A48&
operator=vodafone&
type=UNSUBSCRIPTION&
error_type=API_CANCEL
Vodafone cancellation due to final error in billing:
sid=929A902735C744039B1234A2F25BC2D4&
msisdn=nnnnnnnnn&
price=0.10&
date=2013-09-10+16%3A09%3A30&
operator=vodafone&
error_code=E-CUSTFRAUD&
error_description=Error+procedente+de+la+plataforma+de+cobro+de+VF+España+numero+25008,+in
tento+cobro+cliente+en+Black+List&
Page 65
Gateway Wap Spain
Yoigo cancellation due to final error in billing:
sid=3DF6FE959E7046A281639F0DFFCE9D46&
metadata=2e65f2f2fd&
msisdn=nnnnnnnnn&
price=0.01&
date=2013-09-10+17%3A58%3A43&
operator=yoigo&
error_code=200&
error_description=The+subscriber+has+blocked+this+service+%28from+operator%29&
fail_code=1007&
Movistar cancellation due to final error in billing:
Page 66
Gateway Wap Spain
sid=114AC8C7D55AE54A15A3ADA66BC55C70&
metadata=24896ee4c6&
msisdn=638137441&
price=2.47&
date=2013-09-12+13%3A50%3A07&
operator=movistar&
api_key=8db51b5c7832d74a77216be96ec86c39&
error_code=Unsub_API_Merchant&
error_description=Merchant+request&
Billing OK orange:
http://fcbarcelonaesp.com/orange/notifications?
type=BILLING_OK&
operator=orange&
date=2018-03-21+15%3A11%3A52&
api_key=2ebee4e988a71e2e0a001af2c971184f&
sid=878E5814C3C649C7B1B7959824F32476&
Page 67
Gateway Wap Spain
msisdn= nnnnnnnnn&
campaign=unknown&
provider= The+service+provider+service+name+Payment+DC&
subsidiary=20022018_carga1&
pid=01446a64010ca57f2fda00005ab26828&
price=2.47
Orange refund OK for a subscription renewal payment:
type=BILLING_REFUND&
operator=orange&
date=2018-03-22+10%3A00%3A20&
api_key=19f0c2cbb57008f2a0f0954a28fa6b3c&
sid=031396a8040ca53fccc000005a591d4d&
msisdn=nnnnnnnnn&
metadata=c2VsZW5lOmZiMzNjZmZmcGE&
pid=052fca74020cabbc3f2500005aac3e65&
price=2.47
Subscription cancellation via API
Page 68
Gateway Wap Spain
1. The cancelation method is called and the UNSUBSCRIPTION_REQUEST notification is received:
REQUEST /gw/cancelSubscription
api_key=dd1a391eb75522832782b3e2e0178945
sid=05d32b10030cabd6366400005cf97c3f
type=UNSUBSCRIPTION_REQUEST&
operator=orange&
date=2019-06-06+22%3A51%3A29&
api_key=dd1a391eb75522832782b3e2e0178945&
sid=05d32b10030cabd6366400005cf97c3f&
msisdn=695734779&
metadata=2019065cf97c3466ffa40e7c4fa95e%7Cprivate.todo-viral.mobi&
price=2.89&
error_description=Unsubscription+via+API
Page 69
Gateway Wap Spain
2. But note that the UNSUBSCRIPTION notification is received later on when last renewal period has
expired:
operator=orange&
date=2019-06-13+22%3A50%3A14&
api_key=dd1a391eb75522832782b3e2e0178945&
sid=05d32b10030cabd6366400005cf97c3f&
msisdn=695734779&
metadata=2019065cf97c3466ffa40e7c4fa95e%7Cprivate.todo-viral.mobi&
price=2.89&
error_description=Unsubscription+via+API
When Evina detects the request as fraud
subscribeBack/orange?
request_id=01b2bcf8-030c-a396-00a4-00005d01e60c&
result=ERROR&
Page 70
Gateway Wap Spain
error_code=INVALID_REQUEST&
message=Invalid+request&
session_id=043593c4-8619-ad07-fcfb-00005d01e60d
error_type=UNKNOWN_ERROR&
operator=orange&
date=2019-06-13+08%3A00%3A04&
api_key=57f5958b46e203132304a094c9d3a301&
metadata=2330557591&
error_code=INVALID_REQUEST&
Page 71
Gateway Wap Spain
14. Error Code List
UNKNOWN_SERVICE: The service is not found.
UNKNOWN_OPERATOR: The operator doesn’t exist.
UNKNOWN_ERROR: Generic error. Check error code for further information.
IDENTIFICATION_ERROR: Identification process error.
INVALID_TOKEN: The token doesn’t exist or it has expired.
VALIDATION_ERROR: There are invalid parameters.
SUBSCRIPTION_NOT_FOUND: Subscription not found.
ALREADY_UNSUBSCRIBED: Consumer already unsubscribed.
ALREADY_SUBSCRIBED: Consumer already subscribed.
USER_CANCEL: Request cancelled by user.
LIMIT_REACHED: The maximum limit of active subscriptions in the system has been reached.
Page 72
Gateway Wap Spain
OPERATOR_LIMIT_REACHED: The maximum number of active subscriptions in the operator

has been reached.
OPERATOR_ERROR: Generic operator error.
NO_CREDIT: The consumer has insufficient funds for the renewal.
NOT_ACTIVE: The subscription is not active.
BLACKLIST: Consumer blacklisted for payment services.
LIFECYCLE: Expired subscription.
WRONG_PIN: The PIN inserted is incorrect.
SPEND_LIMIT_REACHED: Spending limit reached.
PAYMENT_NOT_FOUND: The payment is not found.
CAPPING_LIMIT_REACHED: The limit for daily amount of subscriptions created for a service has
been reached.
Page 73
Gateway WAP Portugal MEO
resonancetech.com
Juan Ignacio Luca de Tena 1, Planta 3ª - 28027 Madrid.
Tel. 902 01 02 01 Page 27

Gateway Wap en v7

Uploaded by

Document Information

Original Description:

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Gateway Wap en v7

Uploaded by

Copyright:

Available Formats

Gateway Wap Spain

1. REVISION HISTORY ................................................................................................................................... 2

Revi Changes from previous release Date

api_key: service identification hash.

ip: IP from which the user is browsing.

<?xml version="1.0" encoding="ISO-8859-1" ?>

<?xml version="1.0" encoding="ISO-8859-1" ?>

The identification process chart is as follows:

The description of the identification process is as follows:

1. The user requests access to the client’s Wap subscription portal.

api_key: service identification hash.

3. A user identification URL is returned.

Example response to a correct request:

<?xml version="1.0" encoding="ISO-8859-1" ?>

Example response to an erroneous request:

<?xml version="1.0" encoding="ISO-8859-1" ?>

<reason>Invalid or return_url not found</reason>

5. The user accesses the identification URL from their terminal.

status: Indicates the status of identification. Possible values: "OK", "ERROR"

error_type: Error code in case of identification failure (see list of errors).

The URL of the method is http://passwap.com/gw/checkIdentifyUser, with the following parameters:

api_key: service identification hash.

token: identification hash received.

<?xml version="1.0" encoding="ISO-8859-1" ?>

status: Indicates the status of identification. Possible values: “OK”, “ERROR”

code: Error code in case of identification failure (see list of errors).

Example of erroneous identification:

<?xml version="1.0" encoding="ISO-8859-1" ?>

5. Subscription Status Query

The subscription query method URL is http://passwap.com/gw/checkSubscription, with the following

api_key: Service identification hash.

sid: Unique subscription identifier (*1)

msisdn: user MSISDN (*1)

(*1) Only one of the two parameters is required.

Example call with subscription identifier:

Example call with user MSISDN:

An XML with the subscription information is returned.

In case of error with the following structure:

<?xml version="1.0" encoding="ISO-8859-1" ?>

<reason>Subscription not found</reason>

status: Call status.

code: Error code. (See table of errors)

reason: Brief description of error.

If the subscription is found an XML with the following structure is returned:

<?xml version="1.0" encoding="ISO-8859-1" ?>

sid: Unique subscription identifier

msisdn: user MSISDN

startDate: Subscription start date

endDate: subscription cancellation date

lastBillingStatus: Status of last payment processed. Possible values: “OK”, “ERROR”

lastBillingDate: Date of last payment processed.

Example of the status of a subscription with last payment failed:

<?xml version="1.0" encoding="ISO-8859-1" ?>

Example of a cancelled subscription:

<?xml version="1.0" encoding="ISO-8859-1" ?>

6. Wap Subscription - URL method

The flowchart of subscription by the URL method is as follows:

The description of the subscription process is as follows:

2. The client then requests a subscription URL by the subscribeUrl method.

The URL of the method is http://passwap.com/gw/subscribeUrl, with the following parameters:

api_key: Service identification hash

Example call to the subscribe Url method:

3. Response to the subscribeUrl call.