Die Call2Pay API Event bietet dem Partner die Möglichkeit, die
Micropayment Zahlart "Call2Pay" für seine Kunden anzubieten und
gleichzeitig maximale Kontrolle über die Kundeninteraktionen zu
erhalten. Hierfür ist der Partner selbst verantwortlich, dem Kunden die
benötigten Eingabeformulare und Informationen anzuzeigen und ihn durch
den Bezahlvorgang zu führen. Da seit dem 01.04.08 in Deutschland nur
noch ein Maximalbetrag von 10 EUR per Dropcharge gebucht werden kann,
gibt es den erweiterten Modus "Multicall" der es erleichtert größere
Beträge abzurechnen.
Im wesendlichen erfolgt die Bezahlung in 3 Schritten:
Auswahl des Landes, aus dem der Kunde anrufen möchte und ggf.
Wahl des gewünschten Tarifs Anzeige der reservierten Call2Pay Rufnummer mit den
gesetzlichen Preisinformationen, und Wartefunktion, bis
erforderliche Anrufdauer vollständig ist. Bestätigung über den Erfolg der Bezahlung an den
Kunden. Da seit dem 01.04.08 in Deutschland nur noch ein Maximalbetrag von
10 EUR per Dropcharge gebucht werden kann, gibt es den erweiterten Modus
"Multicall" der es erleichtert, größere Beträge abzurechnen. Wird ein
Betrag größer 10 EUR für Deutschland angefordert ergeben sich nun 2
Möglichkeiten.
-
Multicall nicht erwünscht:
Der Betrag wird für einen Call reserviert. Abrechnung erfolgt
ausschließlich über Zeittakt. Dies ist auch der Modus für die
Call2Pay API Event 1.0
-
Multicall erwünscht:
Der Gesamtbetrag wird in kleinere Calls (ebend der Maxbetrag
von derzeit 10 EUR) aufgesplittet, und wenn nötig einem Call mit dem
Restbetrag < 10 EUR.
Bsp.: angefordert 29,99 EUR ergibt 3 Calls ( 2* 10 EUR + 1*
9,99 EUR)
Alle Calls des Multicalls haben den gleichen Wert für
"handle".
Alle Calls haben den gleichen Wert für "number", d.h. der
Endkunde kann/soll immer die Wahlwiederholung benutzen. In der
Statistik erscheint dann auch nur immer ein Satz über den
Gesamtbetrag.
Für einen typischen Ablauf findet sich am Ende des Dokuments ein
Beispiel.
nach oben
Die Beschreibunssyntax der Parameter und Rückgaben in den
folgenden Abschnitten definiert sich wie folgt:
- name
:type
Pflichtparameter mit Parametertyp - (name
:type)
optionaler Parameter, wird er nicht angegeben wird
abhängig vom Typ Leere Zeichenkette (""), numerische Null (0)
oder logisches Falsch (0) angenommen - (name
:type)
=defaultwert
optionaler Parameter, wird dieser nicht angegeben wird
für diesen defaultwert angenommen.
Wichtig! Wird der Parameter mit leerer Zeichenkette angegeben,
wird diese, und nicht der Defaultwert verwendet. - name
:type wenn:
bedingung
Pflichtparameter, wenn die bezeichnete Bedingung
zutrifft. - (name
:type) wenn:
bedingung
Parameter ist auch dann optional, wenn die Bedingung
zutrifft, hat aber anderenfalls keine Bedeutung - (name
:type)
=defaultwert wenn:
abhängigkeit
wie voriger, mit definierter Voreinstellung - name[n]
:type
indizierter Parameter name[0], name[1], ...
name[n-1], kooexistiert
typischerweise mit einem parameter mit dem wert von
n
2.1.2. Standardparameter und -rückgaben
Jeder Aufruf erfolgt mittels definierter URL der
Serviceschnittstelle und den erforderlichen Parametern zur
Identifizierung des Aufrufers. Die Standardparameter sind für alle
Funktionen gültig und werden im folgenden Text nicht mehr
beschrieben.
Parameter:
- accesskey :string
enthält den persönlichen AccessKey des Partners. Dieser
wird automatisch bei der Partnerregistrierung im
Micropayment-System erzeugt, und kann im Controlcenter
ermittelt werden. - (testmode :boolean) =0
schaltet optional auf eine interne Testumgebung um,
unter der der Partner ohne die Kosten des Bezahlsystems seine
Implementierung testen kann Rückgabe:
- error :integer
enthält 0 bei Erfolg bzw. liefert die Fehlernummer des
gescheiterten Aufrufs - errormessage :string wenn:
error <> 0
enthält die nähere Beschreibung des Fehlers im
Klartext
Um Fehlerbehandlung zu vereinfachen, sind die Fehlercodes der
Rückgabe error in vier verschiedene Klassen mit eigenem Nummernkreis
unterteilt.
- permanenter Serverfehler 1xxx
Bei diese Fehlerklasse liegt meist ein permanentes Problem
beim Webdienst vor. Bei Fehlern dieser Klasse sollte der Support
informiert werden. - temporärer Serverfehler 2xxx
Fehler dieses Typs sind auch vom Webdienst bedingt, haben
aber nur eine vorrübergehenden Ursache, wie Wartungsarbeiten
oder erschöpfte Ressourcen. Der Kunde kann hierbei auf spätere
Nutzung des Dienstes vertröstet werden. - Clientfehler 3xxx
Die Ursache der Fehler aus dieser Klasse liegt
typischerweise bei der aufrufende Applikation. Es ist sinnvoll
diese Fehler mit dem Text aus errormessage mitzuloggen, und die
Anwendung ensprechend zu modifizieren. Zur Behebung kann die
Dokumentation oder der Support zu Rate gezogen werden. - Userfehler 4xxx
Zu dieser Klasse gehören alle Fehler, die typischerweise
aus falschen Eingaben des Kunden resultieren, z.B. falsches
Passwort etc. Dem User ist hier eine aussagekräftige
Fehlerbeschreibung anzuzeigen, damit er die Falscheingabe
korregieren kann. Die Ursache kann aber auch hier bei der
Applikation liegen, die z.B. eingegebene Werte fehlerhaft
formatiert. In Anhang sind alle
Fehlercodes, Ursachen und Tipps zur Behebung zusammengefasst.
nach oben
Die Schnittstelle ist unter der Adresse
http://webservices.micropayment.de/public/c2p/v2/
erreichbar und wird im weiteren als
{service-url} angesprochen. Momentan ist sie
mit Hilfe zweier alternativen Technologien implementiert.
An die Service-URL werden Funktion und Parameter als
Soap-Envelop gesendet (HTTP Methode POST). Alle Parameter sind
hierbei in einem strukturierten Typ enthalten:
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope
SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:c2p="http://webservices.micropayment.de/public/call2pay/version2.0"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<SOAP-ENV:Body>
<c2p:{function}>
<param xsi:type="c2p:C2P{function}RequestTyp">
<{name} xsi:type="{type}">{value}</{name}>
<{name} xsi:type="{type}">{value}</{name}>
...
</param>
</c2p:{function}>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Das Ergebnisdokument enthält im Erfolgsfall die
Rückgabestruktur, ...
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope
SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:c2p="http://webservices.micropayment.de/public/call2pay/version2.0"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/">
<SOAP-ENV:Body>
<c2p:{function}Response>
<return xsi:type="c2p:C2P{function}ResponseTyp">
<{name} xsi:type="{type}">{value}</{name}>
<{name} xsi:type="{type}">{value}</{name}>
...
</return>
</c2p:{function}Response>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
... oder einen Soap-Fault mit den Standardrückgaben
error und
errormessage:
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Body>
<SOAP-ENV:Fault>
<faultcode>{error value}</faultcode>
<faultstring>{errormessage value}</faultstring>
<faultactor></faultactor>
<detail></detail>
</SOAP-ENV:Fault>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
nach oben
Die Webservice-URL wird um die Parameterliste als HTTP
Querystring (GET-Methode) erweitert. Für den Funktionsnamen ist der
Parameter action vorgesehen:
http://{service-url}/?action={function}&{name}={value}&{name}={value}&...
Die Rückgabewerte werden zeilenweise als Name-Wert-Paare im
Ergebnisdokument geliefert:
error=0
{name}={value}
{name}={value}
...
Im Fehlerfall werden nur die beiden Standardrückgaben
error und
errormessage geliefert:
error={error value}
errormessage={errormessage value}
Die jeweiligen Parameter- und Rückgabewerte sind URL-codiert.
Sonderzeichen sind nach ISO-8859-1 Standard zu codieren.
nach oben
2.2.1. Verfügbare Länder ermitteln mit
country
Die Funktion ermittelt für einen bestimmten Zahlbetrag die Liste
der verfügbaren Länder. Einerseits kann mit Hilfe dieser Funktion dem
Kunden eine Liste der verfügbaren Länder angeboten, andererseits sein
Herkunftsland vorausgewählt werden.
Parameter:
- project :string
Bezeichnung des bezogenen Projekts, für den die
Bezahlung initiiert werden soll - (amount :integer)
Gibt den Betrag in 100stel der angeforderten Währung
(z.B in Cent) an, den der Kunde bezahlen soll. Ist der
Parameter leer, wird auf die Vorgabe aus der
Projekteinstellung zurückgegriffen. Der Betrag wird für jedes
Land in dessen Währung umgerechnet und anschließend geprüft,
ob für diesen eine Rufnummer verfügbar wäre. - (currency :string(3)) ="EUR" wenn:
amount angegeben
Gibt an, in welcher Währung der Parameter
amount angegeben ist. - (ip :string)
Anhand der IP des Kunden kann mit dieser Funktion
gleichzeitig das bevorzugte Land ermittelt werden (Rückgabe
ipcountry und
ipprovider). Rückgabe:
- countrycount :integer
Enthält die Anzahl der gefunden Länder und
zurückgelieferter
country[n]
Werte. - country[n]
:string(2) wenn: countrycount >
0
Liefert jeweils einen Ländercode (z.B: "DE", "AT") in
denen der umgerechnete Preis bezahlt werden kann. - ipcountry :string(2) wenn:
ip angegeben
Enthält das Land, in dem die übergebene IP gehostet ist.
Dies muss zwar nicht zwangsläufig die Herkunft des Kunden
sein, ist es aber dennoch mit hoher Wahrscheinlichkeit. Der
Wert muss nicht zwangläufig in der Länderliste enthalten
sein. - ipprovider :string wenn:
ip angegeben
-
Enthält, sofern ermittelbar, die Bezeichnung größerer
ISP. Derzeit mögliche Werte:
"UNKNOWN" = ISP nicht bekannt, hat aber seinen Sitz in
ipcountry
"AOL" = IP ist im AOL-Netz, der Kunde kann aber aus
jedem anderen Land stammen.
ipcountry enthält meistens
"US"
Alle Parameter und Rückgaben sind in der Kurzreferenz zusammengefasst.
nach oben
2.2.2. Rufnummer reservieren mit init
Mit dieser Funktion wird ein neuer Bezahlvorgang gestartet. Als
Ergebnis wird eine Rufnummer für den Kunden reserviert und
zurückgeliefert. Der Kunde sollte anschließend aufgefordert werden
diese Nummer anzurufen.
Parameter:
- project :string
Bezeichnung des bezogenen Projekts, für den die
Bezahlung initiiert werden soll - (projectcampaign :string)
legt fest welcher Projekt-Kampagne dieser Vorgang
zugeordnet werden soll - (account :string)
Accountnummer bzw. -bezeichnung des partiziperenden
Webmasters. Standardmäßig wird der Account des Projektinhabers
angenommen. - (webmastercampaign :string)
-
legt fest welcher Webmaster-Kampagne dieser Vorgang
zugeordnet werden soll
- sessionid :string
Ein eindeutiges Handle, das die Kundensitzung
identifiziert. Diese wird für den offenen Vorgang gespeichert.
Sollte der Kunde den Bezahlvorgang ein zweites mal starten,
erhält er die selbe Rufnummer. - ip :string
Die IP des Kunden, der den Vorgang startet. Sie wird
einerseits für die Fehlersuche gespeichert und andererseits
verwendet, um ein Flooding des Dienstes zu vermeiden. - country :string(2)
Das Land des Anrufers um dem Kunden eine nationale
Service-Rufnummer anzubieten. - (language : string(2))
-
Legt die Sprache der telefonischen Ansagen fest.
Standardmäßig wird die landestypische Sprache für
country herangezogen.
- (amount :integer)
-
Gibt den Betrag in 100stel der angeforderten Währung
(z.B in Cent) an, den der Kunde bezahlen soll. Ist der
Parameter leer, wird auf die Vorgabe aus der
Projekteinstellung zurückgegriffen.
Achtung! Der dem Kunden anzuzeigende Betrag und dessen
Währung hängt von der gewählen Landeseinstellung in
country ab. Er wird bei Bedarf aus den
übergebenen Werten errechnet und von der Funktion
zurückgeliefert.
- (currency :string(3)) ="EUR" wenn:
amount angegeben
-
Gibt an, in welcher Währung der Parameter
amount angegeben ist.
- (title :string)
Benennt die zu kaufende Sache (z.B: Kundennummer,
Username, Artikelbezeichnung, o.ä.). Diese wird in den
Statistikdetails des Partners mit angezeigt. Wird der
Parameter leer gelassen, wird der Standard-Artikel in der
Projekteinstellung verwendet. - (freeparam :string)
-
Bindet einen beliebigen Text an den Vorgang und kann mit
anderen Funktionen wieder abgefragt werden. Das kann ein
externes Handle des Partners sein oder aber auch mehrere
kommaseparierte Werte.
- multicall :integer
-
0 = Multicall nicht erwünscht (default)
1 = Multicall erwünscht
Rückgabe:
- status :string(20)
-
Der Reservierungsstatus des Vorgangs. Im Fehlerfall
werden die Standardrückgaben error
und errormessage gesetzt. Mögliche
Werte sind:
"INIT" = Ein neuer Vorgang wurde gestartet.
"REINIT" = Ein unterbrochener Vorgang wurde
reinitialisiert oder ein Call eines Multicalls wurde
abgeschlossen.
"CALL" = Der Kunde ruft grade an
- handle :string(50)
Die eindeutige ID des Vorgangs. Diese wird für andere
Funktionen benötigt, um den aktuellen Status
abzufragen. - expire :datetimestring
-
Der Zeitpunkt, wann die Reservierung abläuft und die
Rufnummer verfällt. Die Zeitspanne ist sehr kurz gehalten (30
sek.), um den Rufnummernvorrat zu schonen. Durch zyklisches
Aufrufen der Funktion status wird die
Lebensdauer der Reservierung aufgefrischt.
- number :string
Liefert die vom Kunden anzurufende Servicenummer. Sie
ist bereits optisch formatiert. - (numberinfo :string)
Enthält, falls gesetzlich erforderlich, zusätzliche
Tarifangaben und Hinweise zur angezeigten Rufnummer. Der Text
ist dem Kunden in unmittelbarem Zusammenhang mit der Rufnummer
anzuzeigen und mit dieser z.B: mit Hilfe einer Fußnote
(Sternchen *) visuell zu verknüpfen. - origin :string
-
Gibt an, ob die zurückgegebene Rufnummer nur aus einem
bestimmten Netz (Mobilfunk- oder Festnetz) erreichbar ist.
Dies kann gelegentlich vorkommen, typischerweise enthält diese
Rückgabe den Wert "BOTH". Bei einer Einschränkung sollte der
Kunde aber entsprechend darauf hingewiesen werden (z.B:
"Rufnummer ist nur aus dem Festnetz erreichbar").
"BOTH"
"LANDLINE"
"MOBILE"
- amount :integer
Betrag, den der Kunde für den gesamten Anruf bezahlt. Er
ist, unabhängig von numberinfo,
zusammen mit currency dem Kunden
anzuzeigen. - currency :string
-
Währung des Betrags in Rückgabe
amount.
- mode: string
-
Diese Rückgabe legt den Modus für die Rufnummer
fest.
"DIRECT" = Die Rufnummer ist eindeutig für den Kunden
reserviert, alleine durch den Anruf kann er zugeordnet
werden.
"DTMF" = Gelegentlich, meist bei ausländischen
Rufnummern, kann keine durchwahlfähige Rufnummer reserviert
werden. In diesem Fall identifiziert sich der Kunde mit einer
TAN durch Eingabe auf der Telefontastatur während des
Anrufs.
- tan :string wenn:
mode = "DTMF"
-
Im Modus "DTMF" die vom Kunden via Telefon einzugebende
TAN.
- duration : integer
Gesamtdauer des Anrufs in Sekunden. - durationpart :integer
Bisherige Anrufdauer in Sekunden. Diese ist beim Status
"INIT" Null, bei "REINIT" oder "CALL" größer Null und kleiner
als "duration" (Siehe durationpart
in Funktion status) - split :integer
-
Gleiches Format wie Parameter
"amount".
Wenn "split" > 0 handelt es
sich um einen Multicall und gibt den Betrag des aktuellen
Calls an.
Abhängig von "split" wird dann
auch "numberinfo" entsprechend
formatiert. Für obiges Beispiel würde beim ersten Aufruf von
init folgendes zurückgegeben
werden:
"split" => 1000
"amount" => 2999
"numberinfo" => 10,00
EUR/Anruf aus dt. Festnetz, ggf. abweichend aus
Mobilnetz.
beim letzten Aufruf entsprechend:
"split" => 999
"amount" => 2999
"numberinfo" => 9,99 EUR/Anruf
aus dt. Festnetz, ggf. abweichend aus Mobilnetz.
- paid :integer
-
Gleiches Format wie Parameter
"amount".
Enthällt den aufsummierter Betrag aller bisherigen
(abgeschlossenen) Calls eines Multicalls.
- callcnt :integer
Anzahl der erfolgreich abgeschlossenen Calls eines
Multicalls Alle Parameter und Rückgaben sind in der Kurzreferenz zusammengefasst.
nach oben
2.2.3. Anrufüberwachung mit status
Die Funktion ermittelt den aktuellen Status einer Reservierung.
Sie sollte zyklisch aufgerufen werden, einerseits um die Reservierung
zu erhalten, andererseits um festzustellen, ob der Kunde grade anruft
oder bereits angerufen hat. Zusätzlich kann dem Kunden der Fortschritt
bei zeitabhängigen Anrufen angezeigt werden, z.B durch eine
AJAX-Lösung.
Parameter:
- handle :string(40)
Die ID des Vorgangs aus der Funktion
init. Rückgabe:
- status :string(20)
-
Der Reservierungsstatus des Vorgangs. Im Fehlerfall
werden die Standardrückgaben error
und errormessage gesetzt. Mögliche
Werte sind:
"INIT" = Reservierung wartet auf Anruf.
"REINIT" = Reservierung wartet auf Anruf nach
unterbrochener Verbindung.
"CALL" = Der Kunde ruft grade an
"RECALL" = Der Anruf wurde vorzeitig abgebrochen, der
Kunde muss erneut anrufen um die Bezahlung abzuschließen. Bei
diesem Wert muss die Funktion init mit
den gleichen Werten aufgerufen werde, da u.a. eine neue
Servicerufnummer reserviert werden kann.
"COMPLETE" = Anruf ist vollständig und erfolgreich.
Dieser Status wird nur unmittelbar nach Abschluss geliefert
(ca. 10 min. lang). Danach liefert die Funktion einen Fehler
für das übergebene handle. Die
Eigenschaften des Vorgangs können aber jederzeit mit
info ermittelt werden.
- expire :datetimestring
-
Der Zeitpunkt, wann die Reservierung abläuft und die
Rufnummer verfällt. Durch wiederholtes Aufrufen der Funktion
wird dieser Wert immer aktualisiert. (siehe Erklärung
expire in Funktion
init)
- (caller :string) wenn:
status <> "INIT"
Liefert die Rufnummer des Anrufers während und nach
einem Anruf, falls sie ermittelbar ist. In jedem Fall ist sie
aber verkürzt angegeben (z.B "01719988XXX") - (origin :string)
-
Enthält unabhängig von caller das Herkunftnetz, während
oder nach dem Anruf. Bei Auslandsnummern ist dies meist nicht
ermittelbar, und die Rückgabe leer.
"LANDLINE"
"MOBILE"
- duration :integer
Gesamtdauer des Anrufs in Sekunden. Dieser Wert kann
währen eines Anrufs von dem aus der Funktion
init abweichen, wenn der Kunde z.B. aus
dem Mobilnetz anruft. - durationpart :integer
Noch benötigte Anrufdauer in Sekunden. Dieser ist beim
Status "CALL" oder "RECALL" typischerweise kleiner als
duration. Somit kann aus
durationpart und
duration ein prozentualer Wert
ermittelt werden, um dem Kunden z.B. einen Fortschrittsbalken
anzuzeigen. Beim Status "COMPLETE" ist er 0. - (freeparam :string)
enthält den Wert, der bei der Funktion
init übergeben wurde - split :integer
-
Gleiches Format wie Parameter
"amount".
Wenn "split" > 0 handelt es
sich um einen Multicall und gibt den Betrag des aktuellen
Calls an.
Abhängig von "split" wird dann
auch "numberinfo" entsprechend
formatiert. Für obiges Beispiel würde beim ersten Aufruf von
init folgendes zurückgegeben
werden:
"split" => 1000
"amount" => 2999
"numberinfo" => 10,00
EUR/Anruf aus dt. Festnetz, ggf. abweichend aus
Mobilnetz.
beim letzten Aufruf entsprechend:
"split" => 999
"amount" => 2999
"numberinfo" => 9,99 EUR/Anruf
aus dt. Festnetz, ggf. abweichend aus Mobilnetz.
- paid :integer
-
Gleiches Format wie Parameter
"amount".
Enthällt den aufsummierter Betrag aller bisherigen
(abgeschlossenen) Calls eines Multicalls.
- callcnt :integer
Anzahl der erfolgreich abgeschlossenen Calls eines
Multicalls Alle Parameter und Rückgaben sind in der Kurzreferenz zusammengefasst.
nach oben
2.2.4. Detailierte Statusabfrage mit info
Im Unterschied zur Funktion status liefert
die Funktion alle Eigenschaften für einen Zahlungsvorgang. Außerdem
lassen sich mit ihr auch abgelaufene Reservierungen, erfolgreiche und
gescheiterte Zahlungsvorgänge abfragen. Die Funktion sollte nicht
zyklisch aufgerufen werden (z.B. beim Warten auf den Anruf), da sie
deutlich höhere Anwortzeiten benötigt und mehr Last erzeugt. Mit ihr
kann beispielsweise ein Zahlungsvorgang überprüft werden, bevor der
Kunde den bezahlten Dienst in Anspruch nimmt..
Parameter:
- handle :string(40)
Die ID des Vorgangs aus der Funktion
init. Rückgabe:
- status :string(20)
-
Der Status des Vorgangs. Mögliche Werte sind:
"INIT" = Reservierung wartet auf Anruf.
"REINIT" = Reservierung wartet auf Anruf nach
unterbrochener Verbindung.
"EXPIRED" = Reservierung ist ohne Anruf
abgelaufen
"CALL" = Der Kunde ruft grade an
"RECALL" = Der Anruf wurde vorzeitig abgebrochen, der
Kunde muss erneut anrufen um die Bezahlung
abzuschließen.
"FAILED" = Anruf wurde vorzeitig abgebrochen,
Reservierung ist aber bereits abgelaufen
"COMPLETE" = Anruf ist vollständig und
erfolgreich
Wurde kein Vorgang unter handle
gefunden, sind error und
errormessage gesetzt.
- expire :datetimestring
-
Der Zeitpunkt, wann die Reservierung abläuft oder
abgelaufen ist. Im Gegensatz zur Funktion
status wird eine bestehende Reservierung
durch diese Funktion nicht aufgefrischt.
- project :string
die bei init übergebene Bezeichnung
des bezogenen Projekts - projectcampaign :string
liefert die Kampagne der die Transaktion zugeordnet
wurde - account :string
die übergebene Accountnummer bzw. -bezeichnung des
partiziperenden Webmasters bzw. die des
Projektbetreibers - webmastercampaign
:string
-
Kampagne des Webmasters
- country :string(2)
das initialisierte Land des Anrufers - number :string
Liefert die für den Vorgang reservierte Servicenummer.
Ist dieser abgeschlossen, darf die Nummer nicht mehr angerufen
werden, da sie ggf. bereits für einen anderen Kunden
reserviert sein könnte. - amount :integer
der Gesamtbetrag für den Anruf - currency :string
-
die Währung des Wertes in
amount.
- mode: string
Der Modus des Bezahlvorgangs "DIRECT" oder "DTMF" aus
Funktion init - tan :string wenn:
mode = "DTMF"
-
Für Modus "DTMF" die TAN.
- (caller :string) wenn:
status >= "CALL"
Liefert die Rufnummer des Anrufers während und nach
einem Anruf, falls sie ermittelbar ist. In jedem Fall ist sie
aber verkürzt angegeben (z.B "01719988XXX") - (origin :string)
-
Enthält unabhängig von caller das Herkunftnetz, während
oder nach dem Anruf. Bei Auslandsnummern ist dies meist nicht
ermittelbar, und die Rückgabe leer.
"LANDLINE"
"MOBILE"
- duration : integer
Gesamtdauer des Anrufs in Sekunden. - durationpart :integer
-
die bereits verstrichene Anrufdauer
- title :string
die Artikelbezeichnung für diesen Vorgang - (freeparam :string)
enthält den Wert, der bei der Funktion
init übergeben wurde - split :integer
-
Gleiches Format wie Parameter
"amount".
Wenn "split" > 0 handelt es
sich um einen Multicall und gibt den Betrag des aktuellen
Calls an.
Abhängig von "split" wird dann
auch "numberinfo" entsprechend
formatiert. Für obiges Beispiel würde beim ersten Aufruf von
init folgendes zurückgegeben
werden:
"split" => 1000
"amount" => 2999
"numberinfo" => 10,00
EUR/Anruf aus dt. Festnetz, ggf. abweichend aus
Mobilnetz.
beim letzten Aufruf entsprechend:
"split" => 999
"amount" => 2999
"numberinfo" => 9,99 EUR/Anruf
aus dt. Festnetz, ggf. abweichend aus Mobilnetz.
- paid :integer
-
Gleiches Format wie Parameter
"amount".
Enthällt den aufsummierter Betrag aller bisherigen
(abgeschlossenen) Calls eines Multicalls.
- callcnt :integer
Anzahl der erfolgreich abgeschlossenen Calls eines
Multicalls Alle Parameter und Rückgaben sind in der Kurzreferenz zusammengefasst.
nach oben
2.2.5. Anrufsimulation mit testcall
Die Funktion testcall kann bei der
Anbindung des Webservices und für Testzwecke hilfreich sein. Sie
ermöglicht es einen Kundenanruf zu simulieren, und ist deshalb auch
nur im Testmodus verfügbar. Wurde ein Bezahlvorgang mit
init im Testmodus erzeugt, kann durch separaten
Aufruf dieser Funktion, der Status auf "CALL", "RECALL" oder
"COMPLETE" gesetzt werden, um das Verhalten der eigenen Applikation zu
testen..
- testmode :boolean
Dieser allgemeine Parameter muss für die Funktion auf
"1" gesetzt sein. - number: string
Die Servicerufnummer aus der Funktion
init, die der Kunde anrufen würde. - (origin: string) ="LANDLINE"
Legt fest, aus welchem Netz der Anruf stammen soll.
Möglich sind "LANDLINE" oder "MOBILE" - (caller :string)
Kann die Anrufernummer enthalten, sie wird dann von der
Funktion status direkt
zurückgegeben. - tan :string wenn:
mode = "DTMF"
Im Modus "DTMF" die TAN. - durationpart: integer
Gibt an, wielange der simulierte Anruf dauern soll.
Obwohl der Aufruf sofort zurückkehrt, wird die angegebene
Dauer gewartet, bis der Anruf beendet wird. Wiederholte
Aufrufe der Funktion status liefert also
den Status "CALL" und aufsteigende Werte für
durationpart. Wurde dieser
Parameter kleiner als duration
gewählt taucht er am Ende zusammen mit Status "RECALL" auf,
ansonsten sind duration und
durationpart gleich und der Status
auf "COMPLETE". Rückgabe:
- handle :string(50)
Die ID des Vorgangs, wie aus der Funktion
init. Alle Parameter und Rückgaben sind in der Kurzreferenz zusammengefasst.
nach oben
Hier wird ein typischer Ablauf mit den erforderlichen
Webserviceinteraktionen skizziert. Das Beispiel demonstriert ausserdem
den Fall, in dem der Kunde zu früh die Verbindung unterbricht und erneut
zum Anruf aufgefordert wird.
-
Der Kunde enscheidet sich für einen Kauf und startet die
Call2Pay Applikation des Partners. Diese ermittelt die verfügbaren
Länder und bietet sie dem Kunden zur Auswahl an. Für das
wahrscheinlichste Land initiiert sie einen neuen
Bezahlvorgang.
http://{service-url}/?action=country&accesskey=0123abc
&project=demo&amount=100¤cy=EUR&ip=127.0.0.1
error=0
countrycount=3
country[0]=DE
country[1]=CH
country[2]=AT
ipcountry=DE
ipprovider=UNKNOWN
http://{service-url}/?action=init&accesskey=0123abc
&project=demo&sessionid=aabbccddeeff&ip=127.0.0.1
&country=DE&amount=100¤cy=EUR&title=10 Coins&multicall=1
error=0
status=INIT
handle=1000abcdef
expire=2007-01-15 12:00:00
number=09005 000 111 22
numberinfo=2,00 EUR/min aus dt. Festnetz, ggf. abweichend aus Mobilnetz.
origin=BOTH
amount=100
currency=EUR
mode=DIRECT
tan=
duration=30
durationpart=0
split=0
paid=0
callcnt=0
Diese Informationen werden dem Kunden angezeigt.
Rufen Sie die folgende Nummer an und halten Sie sie 30 Sekunden,
bis automatisch aufgelegt wird!
Anschließend werden Ihrem Konto 10 Coins gutgeschrieben.
09005 000 111 22 *
* 2,00 EUR/min aus dt. Festnetz, ggf. abweichend aus Mobilnetz.
Die Gesamtkosten des Anrufs betragen 1,00 EUR.
Wählen Sie Ihr Land: Deutschland | Schweiz | Östereich
-
Auf der Webseite läuft ein zyklischer Aufruf (z.B. alle 5 sek.
per Javascript) an den Applikationserver. Dieser fragt den Status
des Vogangs ab und erhält somit die Reservierung.
http://{service-url}/?action=status&accesskey=0123abc&handle=1000abcdef
error=0
status=INIT
expire=2007-01-15 12:00:05
caller=
duration=30
durationpart=0
split=0
paid=0
callcnt=0
Sobald der Kunde den Anruf tätigt, liefert die Funktion z.B:
folgendes
http://{service-url}/?action=status&accesskey=0123abc&handle=1000abcdef
error=0
status=CALL
expire=2007-01-15 12:00:10
caller=03012345xxx
duration=30
durationpart=5
split=0
paid=0
callcnt=0
Der zyklische Aufruf aktualisiert die Webseite und zeigt den
Forschritt dem Kunden an:
Der Bezahlvorgang läuft ... halten Sie die Verbindung
noch 25 Sekunden
bis automatisch getrennt wird!
Jetzt legt der Kunde 10 sek. zu früh auf.
status liefert:
http://{service-url}/?action=status&accesskey=0123abc&handle=1000abcdef
error=0
status=RECALL
expire=2007-01-15 12:00:25
caller=03012345xxx
duration=30
durationpart=20
split=0
paid=0
callcnt=0
-
Die Applikation fordert nun neue Daten vom Webservice an,
...
http://{service-url}/?action=init&accesskey=0123abc
&project=demo&sessionid=aabbccddeeff&ip=127.0.0.1
&country=DE&amount=100¤cy=EUR&title=10 Coins&multicall=1
error=0
status=REINIT
handle=1000abcdef
expire=2007-01-15 12:00:25
number=09005 000 111 88
numberinfo=2,00 EUR/min aus dt. Festnetz, ggf. abweichend aus Mobilnetz.
origin=BOTH
amount=100
currency=EUR
mode=DIRECT
tan=
duration=30
durationpart=20
split=0
paid=0
callcnt=0
... und fordert den Kunden auf, erneut anzurufen:
Sie haben leider zu früh aufgelegt!
Rufen Sie erneut an und halten Sie die Verbindung 10 Sekunden,
bis automatisch aufgelegt wird!
09005 000 111 88 *
* 2,00 EUR/min aus dt. Festnetz, ggf. abweichend aus Mobilnetz.
Die Gesamtkosten beider Anrufe betragen insgesamt 1,00 EUR.
Die Status-Funktion liefert jetzt:
http://{service-url}/?action=status&accesskey=0123abc&handle=1000abcdef
error=0
status=REINIT
expire=2007-01-15 12:00:25
caller=03012345xxx
duration=30
durationpart=20
split=0
paid=0
callcnt=0
... und nach jeweils 5 sek seit Kundenanruf:
http://{service-url}/?action=status&accesskey=0123abc&handle=1000abcdef
error=0
status=CALL
expire=2007-01-15 12:00:30
caller=03012345xxx
duration=30
durationpart=25
split=0
paid=0
callcnt=0
http://{service-url}/?action=status&accesskey=0123abc&handle=1000abcdef
error=0
status=COMPLETE
expire=2007-01-15 12:00:35
caller=03012345xxx
duration=30
durationpart=30
split=0
paid=0
callcnt=0
-
Die Bezahlvorgang ist nun abgeschlossen, und der Kunde kann
den bezahlten Dienst in Anspruch nehmen. Für Wartung und Support
kann ab hier jederzeit die Funktion info
benutzt werden, um die Transaktion nachzuvollziehen:
http://{service-url}/?action=info&accesskey=0123abc&handle=1000abcdef
error=0
expire=2007-01-15 12:00:35
project=demo
projectcampaign=
account=10010
webmastercampaign=
country=DE
number=09005 000 111 88
amount=100
currency=EUR
mode=DIRECT
tan=
caller=03012345xxx
duration=30
durationpart=20
title=10 Coins
freeparam=
split=0
paid=0
callcnt=0
-
Das Beispiel aus Punkt 1 wird alternativ mit 13, 50 EUR
abgerechnet und es soll wenn nötig von der Multicall-Methode
gebrauch gemacht werden. Das sieht dann wie folgt aus.
http://{service-url}/?action=init&accesskey=0123abc
&project=demo&sessionid=aabbccddeeff&ip=127.0.0.1
&country=DE&amount=1350¤cy=EUR&title=10 Coins&multicall=1
error=0
status=INIT
handle=1000abcdef
expire=2007-01-15 12:00:00
number=09005 000 111 22
numberinfo=10,00 EUR/Anruf aus dt. Festnetz, ggf. abweichend aus Mobilnetz.
origin=BOTH
amount=1350
currency=EUR
mode=DIRECT
tan=
duration=45
durationpart=0
split=1000
paid=0
callcnt=0
Diese Informationen werden dem Kunden angezeigt.
Rufen Sie die folgende Nummer an und halten Sie die Verbindung,
bis automatisch getrennt wird!
Anschließend werden Ihrem Konto 10 Coins gutgeschrieben.
Bei Anrufen aus dem deutschen Festnetz werden Sie gebeten,
mit 2 Anrufen zu bezahlen. Erst wenn Sie den Gesamtbetrag bezahlt haben,
wird dieser auf Ihrer Telefonrechnung belastet.
09005 000 111 22 *
* 10,00 EUR aus dem deutschen Festnetz, ggf. abweichende Preise im Mobilnetz.
Die Gesamtkosten betragen 13,50 EUR.
nach erfolgtem Anruf per Festnetz ergibt die Abfrage mit
status folgendes:
http://{service-url}/?action=status&accesskey=0123abc&handle=1000abcdef
error=0
status=REINIT
expire=2007-01-15 12:00:35
caller=03012345xxx
duration=45
durationpart=0
origin=LANDLINE
freeparam=
split=350
paid=1000
callcnt=1
daraufhin muß erneut init aufgerufen
werden. Alles so lange bis alle Multicalls erfolgreich abgeschlossen
wurden, siehe status.
http://{service-url}/?action=init&accesskey=0123abc
&project=demo&sessionid=aabbccddeeff&ip=127.0.0.1
&country=DE&amount=1350¤cy=EUR&title=10 Coins&multicall=1
error=0
status=REINIT
handle=1000abcdef
expire=2007-01-15 12:10:00
number=09005 000 111 22
numberinfo=10,00 EUR/Anruf aus dt. Festnetz, ggf. abweichend aus Mobilnetz.
origin=BOTH
amount=1350
currency=EUR
mode=DIRECT
tan=
duration=45
durationpart=0
split=350
paid=1000
callcnt=1
http://{service-url}/?action=status&accesskey=0123abc&handle=1000abcdef
error=0
status=COMPLETE
expire=2007-01-15 12:00:35
caller=03012345xxx
duration=45
durationpart=45
origin=LANDLINE
freeparam=
split=0
paid=1350
callcnt=2
A. Kurzreferenz
Funktion
country
Tabelle A.1. Funktion country Parameter
| Parameter |
Typ |
Standard |
Beschreibung |
| accesskey |
string |
|
Zugangsschlüssel |
| testmode |
boolean |
0 |
Testmodus aktivieren |
| project |
string |
|
Projektname |
| amount |
integer |
Betrag aus Projekteinstellung |
Zahlbetrag |
| currency |
string(3) |
"EUR", wenn amount
|
Währung |
| ip |
string |
leer |
Land für IP ermitteln |
Tabelle A.2. Funktion country Rückgabe
| Parameter |
Typ |
Standard |
Beschreibung |
| error |
integer |
0 |
Fehlercode |
| errormessage |
string |
bei error <> 0 |
Fehlermeldung |
| countrycount |
integer |
|
Anzahl
country[n]
|
| country[n] |
string(2) |
bei countrycount > 0 |
Unterstützte Länder |
| ipcountry |
string(2) |
bei ip <> "" |
Sitz des ISP mit IP |
| ipprovider |
string |
bei ip <> "" |
ISP "UNKNOWN", "AOL" |
Funktion
init
Tabelle A.3. Funktion init Parameter
| Parameter |
Typ |
Standard |
Beschreibung |
| accesskey |
string |
|
Zugangsschlüssel |
| testmode |
boolean |
0 |
Testmodus aktivieren |
| project |
string |
|
Projektname |
| projectcampaign |
string |
keine |
Kampagne des Projektbetreibers |
| account |
string |
Account des Projektbetr. |
Webmasteraccount |
| webmastercampaign |
string |
keine |
Kampagne des Webmasters |
| sessionid |
string |
|
Usersession |
| ip |
string |
|
User IP |
| country |
string(2) |
|
Land des Users |
| language |
string(2) |
Landessprache |
Ansagesprache bei Anruf |
| amount |
integer |
Betrag aus Projekteinstellung |
Zahlbetrag |
| currency |
string(3) |
"EUR", wenn amount
|
Währung |
| title |
string |
Artikel aus Projekteinstellung |
Kaufgegenstand |
| freeparam |
string |
leer |
freier Parameter |
| multicall |
integer |
0 |
Multicall erlauben |
Tabelle A.4. Funktion init Rückgabe
| Parameter |
Typ |
Standard |
Beschreibung |
| error |
integer |
0 |
Fehlercode |
| errormessage |
string |
bei error <> 0 |
Fehlermeldung |
| status |
string |
|
Reservierungsstatus "INIT", "REINIT", "CALL" |
| handle |
string(50) |
|
Reservierungs ID |
| expire |
datetimestring |
|
Ablauf der Reservierung |
| number |
string |
|
Rufnummer |
| numberinfo |
string |
|
gesetzl.Tarifangaben |
| origin |
string |
|
Erreichbarkeit d. Nummer "MOBILE", "LANDLINE",
"BOTH" |
| amount |
integer |
|
Zahlbetrag |
| currency |
string(3) |
|
Währung |
| mode |
string |
|
Modus d. Useridentifikation "DIRECT", "DTMF" |
| tan |
string |
bei mode = "DTMF" |
TAN-Eingabe beim Anruf |
| duration |
integer |
|
gesamte Anrufdauer in Sek. |
| durationpart |
integer |
|
verstrichene Anrufsekunden |
| split |
integer |
|
Betrag des aktuellen (Multi)Calls |
| paid |
integer |
|
Betrag abgeschlossene (Multi)Calls |
| callcnt |
integer |
|
Anzahl abgeschlossene (Multi)Calls |
Funktion
status
Tabelle A.5. Funktion status Parameter
| Parameter |
Typ |
Standard |
Beschreibung |
| accesskey |
string |
|
Zugangsschlüssel |
| testmode |
boolean |
0 |
Testmodus aktivieren |
| handle |
string(50) |
|
Reservierungs ID |
Tabelle A.6. Funktion status Rückgabe
| Parameter |
Typ |
Standard |
Beschreibung |
| error |
integer |
0 |
Fehlercode |
| errormessage |
string |
bei error <> 0 |
Fehlermeldung |
| status |
string |
|
Reservierungsstatus "INIT", "REINIT", "CALL", "RECALL",
"COMPLETE" |
| expire |
datetimestring |
|
Ablauf der Reservierung |
| caller |
string |
wenn status >= "REINIT" und
verfügbar |
Telefonnummer d. Users |
| origin |
string |
leer |
Netz des Anrufers "MOBILE", "LANDLINE" |
| duration |
integer |
|
gesamte Anrufdauer in Sek. |
| durationpart |
integer |
|
verstrichene Anrufsekunden |
| freeparam |
string |
leer |
freier Parameter |
| split |
integer |
|
Betrag des aktuellen (Multi)Calls |
| paid |
integer |
|
Betrag abgeschlossene (Multi)Calls |
| callcnt |
integer |
|
Anzahl abgeschlossene (Multi)Calls |
Funktion
info
Tabelle A.7. Funktion info Parameter
| Parameter |
Typ |
Standard |
Beschreibung |
| accesskey |
string |
|
Zugangsschlüssel |
| testmode |
boolean |
0 |
Testmodus aktivieren |
| handle |
string(50) |
|
Reservierungs ID |
Tabelle A.8. Funktion info Rückgabe
| Parameter |
Typ |
Standard |
Beschreibung |
| error |
integer |
0 |
Fehlercode |
| errormessage |
string |
bei error <> 0 |
Fehlermeldung |
| status |
string |
|
Reservierungsstatus "INIT", "REINIT", "EXPIRED", "CALL",
"RECALL", "FAILED", "COMPLETE" |
| expire |
datetimestring |
|
Ablauf der Reservierung |
| project |
string |
|
Projektname |
| projectcampaign |
string |
leer |
Kampagne des Projektbetreibers |
| account |
string |
|
Webmasteraccount |
| webmastercampaign |
string |
leer |
Kampagne des Webmasters |
| country |
string(2) |
|
Land der Rufnummer |
| number |
string |
|
Rufnummer |
| amount |
integer |
|
Zahlbetrag |
| currency |
string(3) |
|
Währung |
| mode |
string |
|
Modus d. Useridentifikation "DIRECT", "DTMF" |
| tan |
string |
bei mode = "DTMF" |
TAN-Eingabe beim Anruf |
| caller |
string |
wenn status >= "REINIT" und
verfügbar |
Telefonnummer d. Users |
| origin |
string |
leer |
Netz des Anrufers "MOBILE", "LANDLINE" |
| duration |
integer |
|
gesamte Anrufdauer in Sek. |
| durationpart |
integer |
|
verstrichene Anrufsekunden |
| title |
string |
|
Kaufgegenstand |
| freeparam |
string |
leer |
freier Parameter |
| split |
integer |
|
Betrag des aktuellen (Multi)Calls |
| paid |
integer |
|
Betrag abgeschlossene (Multi)Calls |
| callcnt |
integer |
|
Anzahl abgeschlossene (Multi)Calls |
Funktion
testcall
Tabelle A.9. Funktion testcall Parameter
| Parameter |
Typ |
Standard |
Beschreibung |
| accesskey |
string |
|
Zugangsschlüssel |
| testmode |
boolean |
|
Muss "1" sein |
| number |
string |
|
Rufnummer |
| origin |
string |
"LANDLINE" |
Anrufnetz "LANDLINE", "MOBILE" |
| caller |
string |
leer |
Telefonnummer d. Users |
| tan |
string |
bei mode = "DTMF" |
TAN-Eingabe beim Anruf |
| durationpart |
integer |
|
anzurufende Sekunden |
Tabelle A.10. Funktion testcall Rückgabe
| Parameter |
Typ |
Standard |
Beschreibung |
| error |
integer |
0 |
Fehlercode |
| errormessage |
string |
bei error <> 0 |
Fehlermeldung |
| handle |
string(50) |
|
Reservierungs ID |
nach oben
B. Fehlercodes
Tabelle B.1. durch Server verursachte Fehler (permanent)
| error |
Funktionen |
Ursache |
Reaktion |
| 1000 |
alle |
unbekannter Fehler |
Information an micropayment Support |
| 1001 |
alle |
Fehler während Datenbankoperation |
Information an micropayment Support |
| 1002 |
alle |
Initialisierung des Services ist fehlgeschlagen |
Information an micropayment Support |
Tabelle B.2. durch Server verursachte Fehler (temporär)
| error |
Funktionen |
Ursache |
Reaktion |
| 2001 |
alle |
Dienst vorübergehend nicht verfügbar (meist bei kurzzeitige
Wartungsarbeiten) |
Anzeige für User: "Bitte versuchen Sie es später
nocheinmal" |
| 2002 |
init |
Reservierung ist vorübergehend nicht möglich (meist ist der
Rufnummernpool erschöpft) |
Anzeige für User: "Bitte versuchen Sie es später
nocheinmal" |
Tabelle B.3. vom Clienten verursachte Fehler
| error |
Funktionen |
Ursache |
Reaktion |
| 3001 |
alle |
Authorisierung ist fehlgeschlagen (accesskey oder IP des
Clienten ist falsch) |
Prüfen der Projekteinstellungen |
| 3002 |
alle |
Funktion nicht unterstützt oder verfügbar |
Prüfen der Dokumentation, evtl. ist Funktion nur im
Testmodus erlaubt |
| 3003 |
alle |
Parameter im falschen Format oder mit falschen Werten
(meist bei fehlenden Pflichtparametern) |
Prüfen der Dokumentation, Angabe aller erforderlichen
Parameter, Angabe korrekter Werte |
| 3004 |
alle |
Fehler in Projektkonfiguration |
Prüfen der Projekteinstellungen, errormessage liefert
genauere Details |
| 3005 |
init |
Angefordertes Land ist nicht verfügbar |
Anzeige für User: "Land wird nicht unterstützt" |
| 3006 |
init,
country
|
Angeforderter Betrag ist nicht erlaubt |
Wahl eines anderen Zahlbetrags |
| 3007 |
init,
country
|
Angeforderte Währung kann nicht verarbeitet werden |
Angabe der Währung nach ISO 4217 |
| 3008 |
status,
info
|
handle ist ungültig |
Angabe eines gültigen Handles, status
liefert nur begrenzte Zeit Daten, verwenden der Funktion
info
|
Tabelle B.4. durch User verursachte Fehler
| error |
Funktionen |
Ursache |
Reaktion |
| 4001 |
testcall |
Rufnummer bzw. TAN nicht reserviert oder Anruf läuft
bereits |
Angabe korrekter Werte, einmaliger Aufruf |
nach oben
|