Call2Pay API Time

1. Einleitung

1.1. Allgemein

Die Call2Pay API Time bietet dem Partner die Möglichkeit, seinen Kunden Inhalte zur zeitabhängigen Bezahlung anzubieten. Hierfür ist der Partner selbst verantwortlich, dem Kunden die benötigten Eingabeformulare und Informationen anzuzeigen und ihn durch den Bezahlvorgang zu führen.

Im wesendlichen erfolgt die Bezahlung in 3 Schritten:

  1. Auswahl des Landes, aus dem der Kunde anrufen möchte.

  2. Anzeige der reservierten Call2Pay Rufnummer mit den gesetzlichen Preisinformationen, und Warten auf Kundenanruf.

  3. Anzeige des kostenpflichtigen Inhalts während des Anrufs, und unterbrechen, sobald Kunde auflegt.

Für einen typischen Ablauf findet sich am Ende des Dokuments ein Beispiel.

nach oben

2. Schnittstelle

2.1. Allgemein

2.1.1. Abstrakt

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

nach oben

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

nach oben

2.1.3. Fehlercodes

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

2.1.4. Serviceprotokolle

Die Schnittstelle ist mit Hilfe zweier alternativen Technologien implementiert.

2.1.4.1. SOAP Webservice

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:c2pt="http://webservices.micropayment.de/public/call2paytime/version1.0" 
  xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <SOAP-ENV:Body>
    <c2pt:{function}>
      <param xsi:type="c2pt:C2PTime{function}RequestTyp">
        <{name} xsi:type="{type}">{value}</{name}>
        <{name} xsi:type="{type}">{value}</{name}>
        ... 
      </param>
    </c2pt:{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:c2pt="http://webservices.micropayment.de/public/call2paytime/version1.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>
    <c2pt:{function}Response>
      <return xsi:type="c2pt:C2PTime{function}ResponseTyp">
        <{name} xsi:type="{type}">{value}</{name}>
        <{name} xsi:type="{type}">{value}</{name}>
        ...
      </return>
    </c2pt:{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
2.1.4.2. Simple HTTP

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. Funktionen

2.2.1. Verfügbare Länder und Tarife ermitteln mit country

Die Funktion ermittelt für einen bestimmten Zahlbetragsbereich die Liste der verfügbaren Länder mit ihren jeweiligen Tarifen je Minute. Zusätzlich kann das Herkunftsland des Kunden ermittelt werden.

Parameter:

project :string

Bezeichnung des bezogenen Projekts, für den die Bezahlung initiiert werden soll

amount :integer

Gibt den Betrag je Minute in 100stel der angeforderten Währung (z.B in Cent) an, den der Kunde bezahlen soll. Ist der Tarif nicht verfügbar, wird der nächsthöhere bzw. -niedrigere zurückgeliefert.

(amountmin :integer)

Schränkt den Suchbereich für amount nach unten ein, d.h. ist in einem Land nur ein kleinerer Tarif als dieser Wert verfügbar, wird es nicht zurückgeliefert.

(amountmax :integer)

Schränkt den Suchbereich für amount nach oben ein (siehe amountmin).

(currency :string(3)) ="EUR"

Gibt an, in welcher Währung die Parameter amount, amountmin und amountmax angegeben sind.

(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) für: 0 <= n < countrycount

Liefert jeweils einen Ländercode (z.B: "DE", "AT") in denen der Tarif verfügbar ist.

amount[n] :integer für: 0 <= n < countrycount

Enthält den ermittelten Tarif für das entsprechende Land in country[n]. Sind im abgefragten Bereich mehrere verfügbar, wird der jeweil höchste zurückgeliefert.

currency[n] :string(3) für: 0 <= n < countrycount

Gibt die Grundwährung des Betrags in amount[n] an

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 je Minute in 100stel der angeforderten Währung (z.B in Cent) an, den der Kunde bezahlen soll. Ist der Tarif nicht verfügbar, wird der nächsthöhere bzw. -niedrigere zurückgeliefert.

(amountmin :integer)

Schränkt den Suchbereich für amount nach unten ein, d.h. ist im Land country nur ein kleinerer Tarif als dieser Wert verfügbar scheitert diese Funktion.

(amountmax :integer)

Schränkt den Suchbereich für amount nach oben ein (wie amountmin).

currency :string(3)

Gibt an, in welcher Währung die amount-Parameter angegeben sind.

(title :string)

Benennt die zu kaufende Sache (z.B: Kundennummer, Username, Contentbezeichnung, 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.

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.

"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 Anruf je Minute bezahlt.

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

Bisherige Anrufdauer in Sekunden, wenn status = "CALL".

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 aufgelegt hat.

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.

"CALL" = Der Kunde ruft grade an

"COMPLETE" = Anruf wurde beendet. 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

Bisherige Dauer bzw. Gesamtdauer des Anrufs in Sekunden.

(freeparam :string)

enthält den Wert, der bei der Funktion init übergeben wurde

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 und beendete Zahlungsvorgänge ständig 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 nachträglich überprüft werden.

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.

"EXPIRED" = Reservierung ist ohne Anruf abgelaufen

"CALL" = Der Kunde ruft grade an

"COMPLETE" = Anruf wude beendet

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 beendet, darf die Nummer nicht mehr angerufen werden, da sie ggf. bereits für einen anderen Kunden reserviert sein könnte.

amount :integer

der Betrag je Minute für den Anruf. Der Gesamtbetrag kann mit Hilfe von duration ermittelt werden.

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.

title :string

die Artikelbezeichnung für diesen Vorgang

(freeparam :string)

enthält den Wert, der bei der Funktion init übergeben wurde

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" und letztendlich auf "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.

duration: 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 duration. Am Ende taucht dieser Wert zusammen mit Status "COMPLETE" auf.

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

2.3. Beispiel

Hier wird ein typischer Ablauf mit den erforderlichen Webserviceinteraktionen skizziert.

  1. 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=200&currency=EUR&ip=127.0.0.1
    
    error=0
    countrycount=3
    country[0]=DE
    country[1]=CH
    country[2]=AT
    amount[0]=200
    amount[1]=423
    amount[2]=217
    currency[0]=EUR
    currency[1]=CHF
    currency[2]=EUR
    ipcountry=DE
    ipprovider=UNKNOWN
    http://{service-url}/?action=init&accesskey=0123abc
    &project=demo&sessionid=aabbccddeeff&ip=127.0.0.1
    &country=DE&amount=200&currency=EUR&title=Supportchat
    
    error=0
    status=INIT
    handle=1000abcdef
    expire=2007-01-15 12:00:00
    number=09005 000 111 22
    numberinfo=2,00 EUR/min aus dem deutschen Festnetz
    origin=BOTH
    amount=200
    currency=EUR
    mode=DIRECT
    tan=
    duration=0
    

    Diese Informationen werden dem Kunden angezeigt.

    Rufen Sie die folgende Nummer an, um den Supportchat zu starten.
    
        09005 000 111 22 *
    
    * 2,00 EUR/min aus dem deutschen Festnetz
    
    Wählen Sie Ihr Land: Deutschland | Schweiz | Östereich
    

  2. Auf der Webseite läuft ein zyklischer Aufruf (z.B. alle 5 sek. per Javascript) an den Applikationserver. Dieser fragt den Status des Vorgangs 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=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=5
    

    Der zyklische Aufruf aktualisiert die Webseite und zeigt dem Kunden den kostenpflichtigen Inhalt an, z.B:

    SupportChat
     Operator> Willkommen beim Supportchat, wie kann ich Ihnen helfen?
    
     Ihr Text: |
    
  3. Im Hintergrund wird weiterhin zyklisch geprüft ob die Verbindung noch besteht:

    http://{service-url}/?action=status&accesskey=0123abc&handle=1000abcdef
    
    error=0
    status=CALL
    expire=2007-01-15 12:00:25
    caller=03012345xxx
    duration=20
    

    Der Kunde trennt nun die Verbindung. Die Status-Funktion liefert jetzt:

    http://{service-url}/?action=status&accesskey=0123abc&handle=1000abcdef
    
    error=0
    status=COMPLETE
    expire=2007-01-15 12:00:35
    caller=03012345xxx
    duration=30
    

    Die Seite wird wiederum aktualisiert und der kostenpflichtige Dienst gestoppt, z.B:

    SupportChat
     Operator> Willkommen beim Supportchat, wie kann ich Ihnen helfen?
     Sie> Wie installiere ich die Demoapplikation?
     Operator> Haben Sie schon die readme.txt gelesen?
     Sie> Ooops, nö... Danke für den Tipp!
     
     Verbindung wurde unterbrochen. Vielen Dank für die Nutzung des Supportchats. 
nach oben

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 /min.
amountmin integer unbegrenzt minimaler Betrag /min.
amountmax integer unbegrenzt maximaler Betrag /min.
currency string(3) "EUR" 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
amount[n] integer bei countrycount > 0 Betrag /min. für Land
currency[n] string(3) bei countrycount > 0 Währung des Betrags
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 /min.
amountmin integer unbegrenzt minimaler Betrag /min.
amountmax integer unbegrenzt maximaler Betrag /min.
currency string(3) "EUR" Währung
title string Artikel aus Projekteinstellung Kaufgegenstand
freeparam string leer freier Parameter
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", "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   Betrag /min.
currency string(3)   Währung
mode string   Modus d. Useridentifikation "DIRECT", "DTMF"
tan string bei mode = "DTMF" TAN-Eingabe beim Anruf
duration integer   bisherige Anrufdauer in Sek.

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", "CALL", "COMPLETE"
expire datetimestring   Ablauf der Reservierung
caller string wenn status >= "INIT" und verfügbar Telefonnummer d. Users
origin string leer Netz des Anrufers "MOBILE", "LANDLINE"
duration integer   bisherige Anrufdauer in Sek.
freeparam string leer freier Parameter

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", "EXPIRED", "CALL", "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   Betrag /min.
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   bisherige Anrufdauer in Sek.
title string   Kaufgegenstand
freeparam string leer freier Parameter

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
duration 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 Minutenbetrags
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