atms m-payment Dokumentation Info Hotline: Autor: Christian Hutzinger Version 2.8 Stand: Seite 1

Transkript

1 atms m-payment Dokumentation Info Hotline: Autor: Christian Hutzinger Version 2.8 Stand: Seite 1

2 Inhaltsverzeichnis: 1 Grundlagen Operator-Identifizierung ÖSTERREICH T-Mobile ONE telering H3G: Mobilkom: SCHWEIZ Swisscom: Orange: Sunrise: DEUTSCHLAND Vodafone: T-Mobile: o2: E-Plus: Anbindung HTTP-REDIRECT URL Session Übergabe - SinglePayment/AboStart/Identify HTTP-Redirect - Schema URL-Parameter - SinglePayment/AboStart/Identify Session Rückgabe - SinglePayment/AboStart/Identify AboCharge/AboStop URL-Parameter AboCharge/AboStop Fehlercodes Dokument-Historie Seite 2

3 1 Grundlagen Mit dem atms WAP-Billing besteht die Möglichkeit einen Artikel, der per WAP angeboten wird zu verrechnen. Dafür stellt die mobileworx trading GmbH als Technik-Tochter die nötige Funktionalität zur Verfügung. Diese Möglichkeit des Billings steht momentan nur für folgende Netzbetreiber zur Verfügung: Österreich o T-Mobile [2.1.1] o ONE [2.1.2] o telering [2.1.3] o H3G [2.1.4] o Mobilkom [2.1.5] Schweiz o Swisscom [2.2.1] o Orange [2.2.2] o Sunrise [2.2.3] Deutschland o Vodafone [2.3.1] o T-Mobile [2.3.2] o o2 [2.3.3] o E-Plus [2.3.4] Seite 3

4 2 Operator-Identifizierung Da in der WAP-Session die MSISDN nicht immer mit übertragen wird, müssen die Operatoren anhand anderer Parameter erkannt werden. 2.1 Österreich T-Mobile Für T-Mobile Österreich gelten folgende Werte: WAP-GW IP-Adresse: , ONE Für ONE Österreich gelten folgende Werte: WAP-GW IP-Adresse: ; ; telering Für telering Österreich gelten folgende Werte: WAP-GW IP-Adresse: , , (Achtung: diese Angaben sind noch mit Vorsicht zu verwenden!) H3G: Für Hutchison Österreich gelten folgende Werte: WAP-GW IP-Adresse: (Achtung: diese Angaben sind noch mit Vorsicht zu verwenden!) Bei H3G gibt es keine automatische MSISDN Erkennung! Die MSISDN muss im Parameter mobileuser mit gesendet werden! Mobilkom: Für Mobilkom Österreich gelten folgende Werte: WAP-GW IP-Adresse: Seite 4

5 2.2 Schweiz Swisscom: Für Swisscom Schweiz gelten folgende Werte: WAP-GW IP-Adresse: (Achtung: diese IP-Adresse könnte sich in Zukunft ändern. Falls eine IP-adresse im Subnetz /16 kommt bitte sofort Info an uns.) Orange: Für Orange Schweiz gelten folgende Werte: WAP-GW IP-Adresse: , , (Achtung: offiziell sind nur die ersten beiden IP- Adressen angegeben. Beim Testen haben wir die dritte IP-Adresse bekommen. Man kann auch die gesamte IP-Range von Orange einstellen /17) Folgendes ist bei Festlegung der Tarife zu beachten: Bis 5,00 CHF sind nur Tarife in 0,10 CHF Schritten möglich Ab 5,00 CHF sind nur Tarife in 0,50 CHF Schritten möglich Sunrise: Für Sunrise Schweiz gelten folgende Werte: WAP-GW IP-Adresse: Seite 5

6 2.3 Deutschland Vodafone: T-Mobile: WAP-GW IP-Adresse: WAP-GW IP-Adressen: / o2: WAP-GW IP-Adressen: E-Plus: WAP-GW IP-Adressen: Seite 6

7 3 Anbindung Die Anbindung kann zum jetzigen Zeitpunkt auf folgende Weise realisiert werden: HTTP-Redirect [3.1] 3.1 HTTP-Redirect Die Funktionsweise der HTTP-Redirect - Anbindung läuft so ab, dass die bestehende WAP-Session auf den mobileworx WAP-Server übergeben wird. Dabei werden die nötigen Daten direkt an die Redirect-URL angehängt. Nach erfolgreicher Abwicklung wird die Session auf die Success-Url wieder zurückgegeben. Dabei wird Ihnen die msgid zur Identifizierung der Session wieder zurückgegeben. Wird der Billing-Vorgang abgebrochen wird die Session auf die Reject-Url zurückgegeben. Im Errror-Fall wird die Session auf die Error-Url zurückgegeben. Wichtig dabei ist, dass bei Rückgabe der Session diese durch den Parameter msgid identifiziert wird. Seite 7

8 3.1.1 URL Es stehen grundsätzlich folgende Schnittstellen zur Verfügung: SinglePayment/AboStart: Einzelbuchung und AboAnmeldung Identify : die MSISDN des Handyusers wird ermittelt AboCharge: Abo-Betrag wird abgebucht AboStop: Abo wird beendet Die Nutzung der Schnittstellen für SinglePayment/AboStart/Identify erfolgt asynchron per Redirect des Users auf die entsprechende URL, die Schnittstellen AboCharge und AboStop werden synchron per Request durch den Kundenserver getriggert. Es ist sinnvoll den im DNS eingetragenen Host-Name zu verwenden. Falls es damit aber aus irgendeinem Grund Probleme geben sollte, entspricht dieser momentan folgender IP-Adresse: wapgw.mobileworx.at Wir behalten uns vor die IP-Adresse (auch ohne Benachrichtigung) zu ändern Session Übergabe - SinglePayment/AboStart/Identify Die Session-Übergabe erfolgt per Redirect. Die Daten werden direkt an die Redirect- URL angehängt. Beispiel: HTTP/ Date: Mon, 20 Jun :25:13 GMT Server: Apache/ X-Powered-By: PHP/ Location: amount=199&tax=2000&quantity=1&text=game&msgid=123456abc Connection: close Transfer-Encoding: chunked Content-Type: text/html; charset=iso Seite 8

9 3.1.3 HTTP-Redirect - Schema Billing Identify Session- Übergabe Session- Übergabe uid+upw+pid prüfen falsch Error uid+upw+pid prüfen falsch Error richtig richtig mobileuser übergeben Nein mobileuser übergeben Nein Ja mobileuser wird ermittelt Ja mobileuser wird ermittelt operator übergeben Nein Session- Rückgabe mit MSISDN Ja operator wird ermittelt Billing Session- Rückgabe mit MSISDN Seite 9

10 3.1.4 URL-Parameter - SinglePayment/AboStart/Identify Mandatory Optional Name: Billing Identify Beschreibung: Beispiel: uid M M User-ID (wird Ihnen von uns mitgeteilt) 4099 upw M M MD5-Hash aus Passwort und Parameter msgid. zb.: Hash aus 58er62je123456abc Passwort=58er62je msgid=123456abc pid M M Projekt-ID (wird Ihnen von uns mitgeteilt) Identifiziert das Projekt und den damit verbundenen Ablauf. mobileuser O O Kennung des Handyusers: ONE: Client-IP-Adresse oder MSISDN Rest: MSISDN. upw=7cbc a5201f4fd17e69fd17c0d urlreject O O Reject URL Vollständige Reject-Rückgabe URL urlerror O O Error URL Vollständige Error-Rückgabe URL Parameter- msgid M M Identifizierung des Requests abc operator O O Österreich: A_TMobile T-Mobile CH_Swisscom A_ONE ONE A_telering telering A_H3G Hutchison 3G A_Mobilkom Mobilkom Austria Schweiz: CH_Swisscom Swisscom CH_Orange Orange CH_Sunrise Sunrise Deutschland: D_Vodafone Vodafone D_TMobile T-Mobile D_O2 o2 D_EPlus E-Plus amount M --- Zu verrechnender Betrag (Brutto) in 199 Eurocent oder Rappen tax O --- Steuersatz in %*100: 2000 Österreich= % Schweiz=760 7,6% Deutschland= % quantity O --- Mengenangabe Anzahl der zu verrechnenden Artikel 1 urlsuccess O O Success - URL Vollständige Seccess-Rückgabe URL text M --- Rechnungstext Game textdetail O --- Detailbeschreibung des Artikels Java-Game Nr Zusätzlich für Abo-Anmeldung: (im Beispiel erfolgt die Abbuchung 4x pro Woche) chargeunits O --- Häufigkeit der Abbuchung 4 periodtype O --- Typ der Periode [day week month] week periodlength O --- Periodenlänge 1 Seite 10

11 3.1.5 Session Rückgabe - SinglePayment/AboStart/Identify Die Session wird auf vorher definierte oder vorher übergebene URL s zurück Redirectet. Dabei gibt es 3 verschiedene URL s: Success-URL Billing/Abo-Anmeldung erfolgreich ausgelöst Reject-URL User hat das Billing abgelehnt Error-URL es ist ein Fehler aufgetreten (siehe Tabelle [3.2.5]) Es wird jeweils die msgid und - sofern möglich - die msisdn mit übergeben. Bei einer AboAnmeldung wird auf die SuccessUrl zusätzlich eine aboid mitgeliefert, die bei einem späteren AboCharge bzw. AboStop verwendet werden muss. Bei der Error-URL wird zusätzlich der Error-Code und Error-Beschreibung mitgeliefert. Die Session wird auf folgende Weise zurückgegeben: Beispiel Success-URL : HTTP/ Date: Mon, 20 Jun :43:06 GMT Server: Apache/ X-Powered-By: PHP/ Location: Content-Length: 0 Connection: close Content-Type: text/html; charset=iso Beispiel Reject-URL : HTTP/ Date: Mon, 20 Jun :43:06 GMT Server: Apache/ X-Powered-By: PHP/ Location: Content-Length: 0 Connection: close Content-Type: text/html; charset=iso Beispiel Error-URL : HTTP/ Date: Mon, 20 Jun :43:06 GMT Server: Apache/ X-Powered-By: PHP/ Location: &errmsg=transaction%20%error Content-Length: 0 Connection: close Content-Type: text/html; charset=iso Seite 11

12 3.1.6 AboCharge/AboStop Der Aufruf erfolgt per HTTP GET oder POST Request an die entsprechende URL. Die Response wird ohne HTML-Code zurückgesendet, sodass zum Beispiel nur: HTTP/ OK Date: Mon, 20 Jun :25:13 GMT Server: Apache/ X-Powered-By: PHP/ Connection: close Transfer-Encoding: chunked Content-Type: text/plain; charset=iso ok oder für den Error-Fall (siehe Fehlercodes [3.1.8]): HTTP/ OK Date: Wed, 22 Dec :00:00 GMT Server: Apache/ (Unix) Debian GNU/Linux PHP/4.3.4 Connection: close Transfer-Encoding: chunked Content-Type: text/plain; charset=iso Payment problem zurückgeliefert wird URL-Parameter AboCharge/AboStop Beispiel: Parameter- Mandatory Name: Optional Beschreibung: Beispiel: uid M User-ID (wird Ihnen von uns mitgeteilt) 4099 upw M Passwort (wird Ihnen von uns mitgeteilt) 58er62je pid M Projekt-ID (wird Ihnen von uns mitgeteilt) Identifiziert das Projekt und den damit verbundenen Ablauf. aboid M ID des Abos (wird beim erfolgreichen AboStart auf die SuccessUrl mitgesendet) f2fc13d69198f8742b4b6c Seite 12

13 3.1.8 Fehlercodes Error- Billing Beschreibung: Code 100 OK X X Billing-Provider Error-Codes 200 Transaction error X X 300 Payment problem X 305 Invalid userid X X 308 Prepaid customer not allowed X 310 Customer locked account X 500 System error X X 600 Expired (async) 610 Customer Reclamation atms WAP-Billing Error-Codes: 901 uid missing X X 902 uid wrong X X 911 upw missing X X 912 upw wrong X X 921 pid missing X X 922 pid wrong X X 931 msgid missing X X 951 operator wrong X X 961 amount missing X 962 amount wrong X 967 tax wrong X 972 quantity wrong X 981 text missing X 986 msgid already in use X 987 user blocked X 988 user limit reached X 998 system error X X 999 system error X X Identify Seite 13

14 4 Dokument-Historie Version Datum Beschreibung: erste Vorab-Version falsche Bezeichnung für Punkt [3.1.2] - zusätzliche Error-Codes 308, 310 und 952 [3.1.5] - Operator-Identifizierung ONE geändert [2.1] - Parameter operator jetzt Mandatory [3.1.2] zusätzliche Error-Codes 998 und 999 [3.1.5] - Änderung bei den VPN-Daten [4.1] zusätzlicher Operator Swisscom [2.2] - zusätzliche Methoide: HTTP-Redirect [3.2] zusätzlicher Operator telering [2.2] - Parameter tax auf %*100 geändert (altes Format funktioniert auch noch) [3.1.2]+[3.2.3] zusätzlicher Operatoren T-Mobile (A) [2.1] + Orange (CH) [2.5] - Parameter urlsuccess, urlreject und urlerror [3.2.3] zusätzliche Operator Hutchison 3G [2.4] - bei A_ONE + A_telering HTTP-Redirect zusätzliche Operator Sunrise [2.6] - zusätzliche Funktion: HTTP-Redirekt Identify Erweiterung um Vodafone Deutschland [2.8] - zusätzliche Error-Codes 386 und Erweiterung um T-Mobile Deutschland [2.3.2] - Erweiterung um o2 Deutschland [2.3.3] - Erweiterung um E-Plus Deutschland [2.3.4] - Erweiterung um Mobilkom Austria [2.1.5] Parameter textdetail optional - Parameter quantity optional (default=1) - Error 971 entfernt Abo-Funktionalität Seite 14