Atms MobilePayment 0.4

atms
Mobile Payment Interface

Technical Whitepaper
for Service Providers
Info Hotline: 0820 240 403
+43 6216 20211
technik@mobileworx.at
Author: Christian Hutzinger

Version: 0.4
Last modified: 20/08/11
1/16
Table of Contents
Document History...................................................................................................................3
Introduction.............................................................................................................................4
Session Timeout.....................................................................................................................4
MNO Coverage......................................................................................................................4
MSISDN Lookup (WAP).........................................................................................................4
Usecases................................................................................................................................5
WEB-Handshake......................................................................................................................... 5
WAP-Handshake......................................................................................................................... 5
SMS-Handshake.......................................................................................................................... 5
WEB & WAP Flow........................................................................................................................ 6
SMS Flow.................................................................................................................................... 6
Interfaces................................................................................................................................7
Start-Transaction-Interface.......................................................................................................... 7
WEB-Handshake.................................................................................................................................... 7
WAP-Handshake.................................................................................................................................... 8
SMS-Handshake..................................................................................................................................... 9
Success/Failure Redirect/Request........................................................................................................ 10
Query-Operator-Interface (WAP)...............................................................................................10
Charge-Subscription-Interface...................................................................................................11
Stop-Subscription-Interface........................................................................................................11
Statuscodes.........................................................................................................................12
MNO Token..........................................................................................................................12
Responseformats.................................................................................................................13
XML (default)............................................................................................................................. 13
JSON......................................................................................................................................... 13
TEXT......................................................................................................................................... 13
Screenshots.........................................................................................................................13
Examples..............................................................................................................................14
Event based Service.................................................................................................................. 14
Start-Transaction-Interface................................................................................................................... 14
Subscription Service.................................................................................................................. 15
Start-Transaction-Interface................................................................................................................... 15
Charge-Subscription-Interface.............................................................................................................. 16
Stop-Subscription-Interface.................................................................................................................. 16
2/16
Document History
Date
Author
Changes
July 08, 2011
Christian Hutzinger Initial release
July 28, 2011
Christian Hutzinger - msgid parameter removed

- subscription parameter removed
- added link to screenshots
July 29, 2011
Christian Hutzinger - added SMS-Handshake

- added Query-Operator-Interface
- added MSISDN-Lookup Info
- added Session Timeout Info
- added Flow Graphics
- structure changes
18.08.11
Christian Hutzinger - changed MNO Token
3/16
Introduction
ATMS mobile-payment provides an easy way to charge your customers to their mobile-phone contract. The
following use-cases and description will use the terms service provider (you) , customer (end-user),
MNO (Mobile Network Operator) and atms (we) for the involved parties.
Mobile-payment is split into three separate use-cases:
1)
WEB-Handshake
2)
WAP-Handshake
3)
SMS-Handshake
Each of them can be either used for Event based Services or Subscription Services.
Session Timeout
The Session Timeout is 5 minutes. If a user does not confirm the payment within this timeframe, the session
is marked as timed out. No further action is done at this point.
MNO Coverage
MNO
WEB
Handshake
WAP
Handshake
SMS
Handshake
Subscription
Services
Austria
A1
(+bob/bfree)
T-Mobile
Orange
Dez. 2011
H3G
Yesss
Table 1: Current MNO Coverage in Austria
MSISDN Lookup (WAP)

The msisdn can be obtained for customers of A1, T-Mobile, Orange and Yesss after the payment-process.
The msisdn is appended to the success/failure-url when redirecting the user back to the service provider.
Please consider that the msisdn forwarding could be turned off in the future by the MNOs, so don't base your
flow on this feature!
4/16
Usecases
WEB-Handshake
1.
2.
3.
4.
5.
6.
Customer enters service provider web shop

Customer decides to buy a product in the web shop (click on buy-button)
Customer has to enter his mobile phone number at the web shop
Service provider makes a server-side request to atms MobilePayment Interface
atms MobilePayment Interface returns a Redirect-URL and/or a Popup-URL
Service provider either redirects the customer to the Confirmation-Dialog with the Redirect-URL or
shows the Confirmation-Dialog in a Popup
7. When the Confirmation-Dialog opens, a PIN-SMS is sent to the customer.
8. Customer enters the received PIN in the Confirmation-Dialog and confirms the transaction
9. Customer ist charged and redirected back to the service provider's success/failure URLs (in case of
subscription services the customer is only registered for the service at this point; charging
has to be done with the Charge-Subscription-Interface)
WAP-Handshake
1.
2.
3.
4.
5.
6.
7.
Customer enters service provider wap shop

Customer decides to buy a product in the wap shop (click on buy-button)
atms MobilePayment Interface returns a Redirect-URL
Service provider redirects the customer to the Confirmation-Dialog with the Redirect-URL
Customer confirms the Confirmation-Dialog
Customer ist charged and redirected back to the service provider's success/failure URLs (in case of
subscription services the customer is only registered for the service at this point; charging
has to be done with the Charge-Subscription-Interface)
SMS-Handshake
1.
2.
3.
4.
5.
Customer orders a service via SMS (e.g. via keyword on a shortcode)

atms MobilePayment Interface sends an Offer-SMS to the customer
Customer confirms/rejects the transaction by answering the Offer-SMS
Customer ist charged and the service provider's success/failure URLs are called by the atms
MobilePayment Platform (in case of subscription services the customer is only registered for
the service at this point; charging has to be done with the Charge-Subscription-Interface)
5/16
WEB & WAP Flow
SMS Flow
6/16
Interfaces
Start-Transaction-Interface
WEB-Handshake
REQUEST
URL: http://mp.mobileworx.at/mp.php
Parameter
Description
Sample
O/M
pid
Your Project-Id (provided by us)
100000
uid
Your User-Id (provided by us)
1000
upw
Your Passwort (provided by us)
xxx
amount
amount in Euro-Cent
100
text
Billing-Text
ContentXY
urlsuccess
For redirection after successful transaction
http://www.yoursuccessurl.com
urlfailure
For redirection after failed transaction
http://www.yourfailureurl.com
msisdn
MSISDN of the end customer
43664123456
format
Xml (default), json, text
xml
If the following parameters are set, we handle it as subscription transaction

chargeunits
periodtype
day, week, month
week
periodlength
In this example, payment is possible 2 times in 3 weeks

RESPONSE
Parameter
Description
Sample
status-code
Status Code of the transaction
100
status-message
Status Message
OK
status-detail
Status Detail - detailed error info from operator if

available
hash
Unique Transaction-Id
493b7aa32fced5f87adf64cad9e
966a36462680e
mno
Token of the operator
A_MK
msisdn
43664123456
url-popup
URL to open the Confirmation Dialog via

Javascript (openInsitePopup() and openPopup())
(at the moment only for A1, Drei and Yesss!
available)
http://mp.mtms.at/web_popup.js
.php?
id=493b7aa32fced5f87adf64cad
9e966a36462680e
url-redirect
URL to redirect the end customer to the

Confirmation Dialog
(recommended all MNOs supported)
http://mp.mtms.at/web.php?
id=493b7aa32fced5f87adf64cad
9e966a36462680e
7/16
WAP-Handshake
REQUEST
Parameter
Description
Sample
O/M
pid
100000
uid
1000
upw
xxx
amount
amount in Euro-Cent
100
text
Billing-Text
ContentXY
urlsuccess
urlfailure
format
xml

chargeunits
periodtype
day, week, month
week
periodlength

RESPONSE
Parameter
Description
Sample
status-code
100
status-message
Status Message
OK
status-detail

available
hash
966a36462680e
url-redirect
URL to redirect the end customer to the

Confirmation Dialog
http://mp.mtms.at/wap.php?
id=e5f3eb99e1983882d1e9cfb1
33b398fab258a780
8/16
SMS-Handshake
REQUEST
Parameter
Description
Sample
O/M
pid
100000
uid
1000
upw
xxx
amount
amount in Euro-Cent
100
text
Billing-Text
ContentXY
urlsuccess
urlfailure
msisdn
43664123456
format
xml

chargeunits
periodtype
day, week, month
week
periodlength

RESPONSE
Parameter
Description
Sample
status-code
100
status-message
Status Message
OK
status-detail

available
hash
966a36462680e
mno
A_MK
msisdn
43664123456
9/16
Success/Failure Redirect/Request
In the case of WEB & WAP Handshake, after confirmation the customer is redirected back to your success
or failure url. When using the SMS Handshake the request to your success or failure url is done by the
atms MobilePayment Platform. In both cases, the following parameters are appended.
REDIRECT to your Success/Failure URL after confirmation this parameters are appended
Parameter
Description
Sample
statuscode
100
statusmessage
Status Message
OK
statusdetail

available
hash
966a36462680e
msisdn
MSISDN of the end customer if available!
43664123456
mno
A_MK
Query-Operator-Interface (WAP)
With this interface you can identify a customers MNO when surfing on your WAP-Shop.
REQUEST
URL: http://mp.mobileworx.at/mp-mno.php
Parameter
Description
Sample
O/M
pid
100000
uid
1000
upw
xxx
ip
Remote-IP address of the mobile client
80.75.55.136
RESPONSE
Parameter
Description
Sample
status-code
100
status-message
Status Message
OK
status-detail
Status Detail - detailed error info if available
mno
A_MK
10/16
Charge-Subscription-Interface
REQUEST
URL: http://mp.mobileworx.at/mp-charge.php
Parameter
Erklrung
Beispiel
pid
100000
uid
1000
upw
xxx
hash
Unique Transaction-Id, you received when calling the

493b7aa32fced5f87adf64cad9e96
6a36462680e
format
xml (default), json, text
xml
RESPONSE
Parameter
Erklrung
Beispiel
status-code
100
status-message
Status Message
OK
status-detail
Status Detail - detailed error info from operator

if available
mno
A_MK
msisdn
43664123456
Stop-Subscription-Interface
REQUEST
URL: http://mp.mobileworx.at/mp-stop.php
Parameter
Erklrung
Beispiel
pid
100000
uid
1000
upw
xxx
hash
Unique Transaction-Id, you received when calling the

493b7aa32fced5f87adf64cad9e96
6a36462680e
format
xml (default), json, text
xml
RESPONSE
Parameter
Erklrung
Beispiel
status-code
100
status-message
Status Message
OK
status-detail
Status Detail - detailed error info from operator

if available
mno
A_MK
msisdn
43664123456
11/16
Statuscodes
Code
Message
Detail
100
OK
200
Client Error
e.g. Parameter 'pid' missing.
300
Payment Problem
e.g. User rejected payment
MNO Token
Token
MNO
AT_A1
A1 (Mobilkom Austria)
AT_T-Mobile
T-Mobile Austria
AT_Orange
Orange Austria
AT_Drei
Drei (Hutchison/H3G)
AT_Yesss
Yesss!
12/16
Responseformats
XML (default)
<?xml version="1.0" encoding="UTF-8"?>
<response>
<status-code>100</status-code>
<status-message>OK</status-message>
<hash>493b7aa32fced5f87adf64cad9e966a36462680e</hash>
<mno>A_MK</mno>
<msisdn>436XXX</msisdn>
<url-popup><![CDATA[http://vas.a1.net/wappaen/web_popup.js?
pID=224XXX&pToken=e48e351a48e58019e013cdf6XXX]]></url-popup>
<url-redirect><![CDATA[http://vas.a1.net/wappaen/web?2246981-e48e351a48e58019e013cdfXXX]]></urlredirect>
</response>
JSON
{"status-code":100,
"status-message":"OK",
"hash":"20cb099654eb56a1555ca6d0fd9fef88512c01d6",
"mno":"A_MK",
"msisdn":"436XXX",
"url-popup":"http:\/\/vas.a1.net\/wappaen\/web_popup.js?
pID=2247XXX&pToken=e48e351a48e58019e013cdf6753XXX",
"url-redirect":"http:\/\/vas.a1.net\/wappaen\/web?2247492-e48e351a48e58019e013cdf675XXX"}
TEXT
status-code:100
status-message:OK
hash:922dfa7b790b3b8596c9e5ad247da01c1ab00c65
mno:A_MK
msisdn:436XXX
url-popup:http://vas.a1.net/wappaen/web_popup.js?
pID=2247XXX&pToken=e48e351a48e58019e013cdf6753689d
url-redirect:http://vas.a1.net/wappaen/web?2247495-e48e351a48e58019e013cdf6753689d
Screenshots
Screenshots of the WEB and WAP Flows are available here:
http://mp.mtms.at/demo/screenshots/index.html
13/16
Examples
Event based Service
WEB-Handshake
Request:
http://mp.mobileworx.at/mp.php?pid=xxx&uid=xxx&upw=xxx&amount=100&text=ContentXY&urlsuccess=http
%3A%2F%2Fwww.mobileworx.at%2F%3Fstatus%3Dsuccess&urlfailure=http%3A%2F
%2Fwww.mobileworx.at%2F%3Fstatus%3Dfailure&msisdn=436XXX
Response:
<response>
<hash>224b530d7933e57ed755959646aded05f66f349f</hash>
<mno>A_MK</mno>
<url-popup><![CDATA[http://mp.mtms.at/web_popup.js.php?
id=224b530d7933e57ed755959646aded05f66f349f]]></url-popup>
<url-redirect><![CDATA[http://mp.mtms.at/web.php?
id=224b530d7933e57ed755959646aded05f66f349f]]></url-redirect>
</response>
WAP-Handshake
Request:
%2Fwww.mobileworx.at%2F%3Fstatus%3Dfailure
Response:
<response>
<mno>A_MK</mno>
</response>
SMS-Handshake
Request:
http://mp.mobileworx.at/mp.php?pid=xxx&uid=xxx&upw=xxx&amount=100&text= ContentXY&urlsuccess=http
%2Fwww.mobileworx.at%2F%3Fstatus%3Dfailure&msisdn=43664XXX
Response:
<response>
<mno>A_MK</mno>
14/16
</response>
Subscription Service
Example (Subscription: payment 2 times a week EUR 1,- ):
WEB-Handshake
Request:
%2Fwww.mobileworx.at%2F%3Fstatus
%3Dfailure&msisdn=436XXX&chargeunits=2&periodtype=week&periodlength=1
Response:
<response>
<mno>A_MK</mno>
<url-popup><![CDATA[http://mp.mtms.at/web_popup.js.php?
id=224b530d7933e57ed755959646aded05f66f349f]]></url-popup>
</response>
WAP-Handshake
Request:
%2Fwww.mobileworx.at%2F%3Fstatus%3Dfailure&chargeunits=2&periodtype=week&periodlength=1
Response:
<response>
<mno>A_MK</mno>
</response>
SMS-Handshake
Request:
%2Fwww.mobileworx.at%2F%3Fstatus
%3Dfailure&msisdn=43664XXX&chargeunits=2&periodtype=week&periodlength=1
Response:
15/16

<response>
<mno>A_MK</mno>
</response>
Charge-Subscription-Interface
Request:
http://mp.mobileworx.at/mp-charge.php?
pid=xxx&uid=xxx&upw=xxx&hash=493b7aa32fced5f87adf64cad9e966a36462680e
Response:
<response>
<mno>A_MK</mno>
</response>
Stop-Subscription-Interface
Request:
http://mp.mobileworx.at/mp-stop.php?
pid=xxx&uid=xxx&upw=xxx&hash=493b7aa32fced5f87adf64cad9e966a36462680e
Response:
<response>
<mno>A_MK</mno>
</response>
16/16

Atms MobilePayment 0.4

Transféré par

Informations du document

Titre original

Copyright

Formats disponibles

Partager ce document

Partager ou intégrer le document

Options de partage

Avez-vous trouvé ce document utile ?

Ce contenu est-il inapproprié ?

Droits d'auteur :

Formats disponibles

Atms MobilePayment 0.4

Transféré par

Droits d'auteur :

Formats disponibles

atms

Mobile Payment Interface

Author: Christian Hutzinger

July 08, 2011

Christian Hutzinger Initial release

July 28, 2011

Christian Hutzinger - msgid parameter removed

July 29, 2011

Christian Hutzinger - added SMS-Handshake

Christian Hutzinger - changed MNO Token

MSISDN Lookup (WAP)

Customer enters service provider web shop

Customer enters service provider wap shop

Customer orders a service via SMS (e.g. via keyword on a shortcode)

WEB & WAP Flow

Your Project-Id (provided by us)

Your User-Id (provided by us)

Your Passwort (provided by us)

For redirection after successful transaction

For redirection after failed transaction

MSISDN of the end customer

Xml (default), json, text

If the following parameters are set, we handle it as subscription transaction

day, week, month

In this example, payment is possible 2 times in 3 weeks

Status Code of the transaction

Status Detail - detailed error info from operator if

Token of the operator

MSISDN of the end customer

URL to open the Confirmation Dialog via

URL to redirect the end customer to the

Your Project-Id (provided by us)

Your User-Id (provided by us)

Your Passwort (provided by us)

For redirection after successful transaction

For redirection after failed transaction

Xml (default), json, text

If the following parameters are set, we handle it as subscription transaction

day, week, month

In this example, payment is possible 2 times in 3 weeks

Status Code of the transaction

Status Detail - detailed error info from operator if

URL to redirect the end customer to the

Your Project-Id (provided by us)

Your User-Id (provided by us)

Your Passwort (provided by us)

For redirection after successful transaction

For redirection after failed transaction

MSISDN of the end customer

Xml (default), json, text

If the following parameters are set, we handle it as subscription transaction

day, week, month

In this example, payment is possible 2 times in 3 weeks

Status Code of the transaction

Status Detail - detailed error info from operator if

Token of the operator

MSISDN of the end customer

Status Code of the transaction

Status Detail - detailed error info from operator if

MSISDN of the end customer if available!

Token of the operator

Your Project-Id (provided by us)

Your User-Id (provided by us)