Die Schnittstelle ist derzeit mit Hilfe zweier alternativer Technologien implementiert.

http://webservice-url/?action=func-name&param-name=param-value&param-name=param-value&...

error=0
result-name=result-value
result-name=result-value
...

error=error-code
errormessage=error-message

http://webservice-url/?...&param[index]=value&param.property=value

result[index]=value
result.property=value

<?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:dbt="http://webservices.micropayment.de/public/debit/version1.0" 
  xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <soap-env:Body>
    <dbt:func-name>
      <param xsi:type="dbt:Dbtfunc-nameRequestTyp">
        <param-name xsi:type="param-type">param-value</param-name>
        <param-name xsi:type="param-type">param-value</param-name>
        ... 
      </param>
    </dbt:func-name>
  </soap-env:Body>
</soap-env:Envelope>

<?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:dbt="http://webservices.micropayment.de/public/debit/version1.0" 
  xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <soap-env:Body>
    <dbt:func-nameResponse>
      <return xsi:type="dbt:Dbtfunc-nameResponseTyp">
        <result-name xsi:type="result-type">result-value</result-name>
        <result-name xsi:type="result-type">result-value</result-name>
        ... 
      </return>
    </dbt:func-nameResponse>
  </soap-env:Body>
</soap-env:Envelope>

<?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/" 
  <soap-env:Body>
    <soap-env:Fault>
      <faultcode>error-code</faultcode>
      <faultstring>error-message</faultstring>
      <faultactor></faultactor>
      <detail></detail>
    </soap-env:Fault>
  </soap-env:Body>
</soap-env:Envelope>

Jeder Aufruf erfolgt mittels definierter URL der Serviceschnittstelle und dem erforderlichen Parameter accessKey zur Identifizierung des Aufrufers. Der AccessKey wird automatisch bei der Partnerregistrierung im Micropayment-System erzeugt, und kann im Controlcenter ermittelt werden. Optional erwarten alle Funktionen den Parameter testMode. Mit seiner Hilfe lässt sich die integrierte Testumgebung aktivieren.

Scheitert eine Funktion, wird der aufgetretene Fehler durch die Rückgaben error und errorMessage beschrieben. error enthält hier einen numerischen Code, der programmseitig ausgewertet werden kann. errorMessage hingegen enthält die nähere Beschreibung im Klartext und sollte im Fehlerfall mitprotokolliert werden.

Die API ist in der Lage verschiedene Ereignisse an eine Schnittstelle des Projektbetreibers zu senden. Dafür muss in der Projektkonfiguration die URL der Schnittstelle eingetragen werden. Alle Benachrichtigungen übermitteln den Parameter testMode, der angibt, ob sie von der Testumgebung ausgelöst wurden.

Wird beim Aufruf der Benachrichtigungsurl ein Fehler zurückgegeben, wird eine automatische Email an den Betreiber mit den Aufrufparametern versandt.

Alle Funktionen erwarten den optionalen Parameter testMode, der festlegt, dass die Daten in einer abgetrennten Umgebung (der sogenannten Sandbox) erzeugt und abgerufen werden sollen. Keiner der hier angelegten Bezahlvorgänge wird jemals ausgeführt, es können aber mit speziellen Funktionen einige externe Ereignisse simuliert werden.

Die Testumgebung soll es ermöglichen, während und nach Integration der API, alle Abläufe realitätsnah auszutesten oder sogar automatisierte Testfälle zu implementieren (Unittests).

Um Fehlerbehandlung zu vereinfachen, sind die Fehlercodes der Rückgabe error in vier verschiedene Klassen mit eigenem Nummernkreis unterteilt.

Die Funktion löscht alle Customer und Sessions in der Testumgebung. Mit ihrer Hilfe können u.a. Kollisionen für customerId und sessionId zu vermieden werden im Zusammenhang mit automatischen Unittests.

Vor jedem Bezahlvorgang muss ein Kunde angelegt werden. Zur Identifizierung kann mit customerId eine eigene Kundennummer, der Username oder die Emailadresse übergeben werden, andernfalls wird von der API eine eindeutige ID erzeugt und zurückgegeben. Die Funktion scheitert, wenn der Wert in customerId bereits für den Account existiert.

An den Kundensatz können mit der assoziativen Liste freeParams beliebig viele zusätzliche Daten als freie Parameter gebunden werden. Diese können später mit customerGet abgerufen oder mit customerSet verändert bzw. erweitert werden. Dadurch ist prinzipiell eine Anbindung der API ohne eigene Datenbank möglich, indem alle anderen Kundendaten wie Email, Passwort oder Sperrstatus als freie Parameter hinterlegt werden.

Einem Kunden können mit customerSet jederzeit weitere freie Parameter hinzugefügt werden, oder bestehende geändert werden. Dabei werden nur Werte erzeugt oder überschrieben, die im Parameter freeParams enthalten sind; bestehende bleiben unverändert. Zum Löschen eines Wertes kann einfach ein leerer String ("") übergeben werden.

Nachdem ein Kunde angelegt wurde und vor der Bezahlung, muss die Bankverbindung mit bankaccountSet hinterlegt werden. Sollte sich diese einmal ändern kann auch die neue Bankverbindung mit dieser Funktion übergeben werden. Der Parameter customerId identifiziert dabei den Kunden. Die Funktion prüft Kontonummer und Bankleitzahl auf Plausibilität nach den Vorgaben der Bundesbank und scheitert gegebenenfalls. Im Erfolgsfall wird der ermittelte Name der Bank zurückgeliefert.

Die hinterlegten Bankdaten des Kunden können mit bankaccountGet wieder ermittelt werden, z.B. um sie vom Kunden bearbeiten zu lassen. Beide Funktionen liefern zusätzlich den Sperrstatus der Bankverbindung (siehe bankaccountBar).

Mit Hilfe der Funktionen bankCheck und bankaccountCheck können Bankname ermittelt und die Kontonummer geprüft werden, ohne dass sie einem Kunden zugeordnet werden. Die Funktion bankaccountBar ermöglicht es, eine bestimmte Bankverbindung generell zu sperren bzw. wieder freizugeben. Ein Aufruf mit sessionCreate würde dann scheitern, wenn der zugehörige Kunde eine gesperrte Bankverbindung besitzt. bankaccountSet und bankaccountGet liefern mit barStatus den jeweiligen Sperrstatus

Mit den Funktionen addressSet und contactDataSet kann ein Kundendatensatz um Namen und Anschrift erweitert werden. Für den Bezahlvorgang ist dies nicht unbedingt notwendig, kann aber für evtl. Forderungsmaßnahmen sinnvoll sein. Zum Abruf der Daten stehen die Funktionen addressGet sowie contactDataGet zur Verfügung.

Während bei addressSet alle Daten angegeben werden müssen, kann bei contactDataSet jeder Bestandteil separat übermittelt werden. Die anderen Parameter sind in diesem Fall wegzulassen, und werden nicht gelöscht.

Nachdem Kunde und Bankverbindung angelegt wurden, kann ein neuer Bezahlvorgang erzeugt werden. Der Parameter sessionId muss eindeutig sein und wird ggf. generiert und zurückgegeben - ähnlich, wie customerId in der Funktion customerCreate. Es ist sinnvoll hier z.B. die aktuelle Sitzungsnummer des Users anzugeben, um Doppelbuchungen zu vermeiden.

Die Parameter project und projectCampaign legen fest, welchem Projekt und welcher Kampagne der Erlös zugeordnet werden soll. Die Parameter account und webmasterCampaign werden benötigt, wenn das Projekt webmasterfähig ist.

Mit amount, currency und title werden Artikel und Preis (in Cent) festgelegt. Werden die Parameter weggelassen, werden die Standardwerte aus der Projekteinstellung angenommen. Der Verwendungszweck entspricht dem Parameter payText, bzw. wird aus dem Projektnamen und dem Wert in title zusammengesetzt. Mit der Funktion sessionGet können alle übergebenen oder generierten Werte zurückgegeben werden, um sie z.B. dem Kunden zur Bestätigung anzuzeigen.

Ähnlich wie bei der Funktion customerCreate, können auch dem Bezahlvorgang freie Parameter übergeben und mit der Funktion sessionGet wieder ermittelt werden. Der separate Parameter ip wird zusammen mit dem Zeitstempel für Missbrauchsfälle vorgehalten und sollte die IP des Benutzers enthalten, der die Bezahlung veranlasst.

Die Funktion liefert typischerweise den Status "INIT" zurück. Wurde allerdings für den Kunden ein unbestätigter Vorgang gefunden, wird dieser mit den Werten dieses Aufrufs überschrieben und es wird der Status "REINIT" zurüchgegeben.

Bei erfolgreichem Aufruf von sessionCreate, wird die Benachrichtigung sessionStatus ausgelöst. Wurde die Bankverbindung des Kunden mit bankaccountBar generell gesperrt, scheitert der Aufruf.

Die Funktion ermittelt den aktuellen Status eines Vorgangs, sowie alle Daten entsprechend der Parameter aus der Funktion sessionCreate. Die Rückgabe status kann folgende Zustände annehmen:

In den Fällen "FAILED" und "REVERSED", wird mit statusDetail die detaillierte Ursache im Klartext zurückgegeben.

Zusätzlich werden alle Daten entsprechend der Parameter aus der Funktion sessionCreate zurückgegeben. Für optionale Parameter werden dabei die Voreinstellungen bzw. Vorgaben aus der Konfiguration geliefert.

Angelegte Bezahlvorgänge müssen mit dieser Funktion bestätigt werden. Sie sollte unmittelbar nach dem ausdrücklichen Abbuchungauftrags des Kunden aufgerufen werden, oder sogar nach der Bereitstellung des gekauften Artikels, z.B. nach abgeschlossenem Download eines Dokuments.

Bei Aufruf von sessionApprove, wird die Benachrichtigung sessionStatus ausgelöst.

Mit Hilfe dieser Funktion können alle offenen, sowie abgeschlossenen Vorgänge eines Kunden ermittelt werden. Die Rückgabe besteht aus einer numerisch indizierten Liste aller zugehöriger SessionID's. Die Details der Sessions können wiederum mit sessionGet ermittelt werden.

Alle bestätigten Zahlungen werden zusammengefasst und der Bank zur Abbuchung vorgelegt. Der anschließende Geldeingang löst typischerweise die Statusänderung "CHARGED" und die entsprechenden Benachrichtigung sessionStatus aus. Ausserdem wird eine Transaktion des Typs "BOOKING" angelegt und die Benachrichtigung transactionCreate ausgelöst. Die Funktion dient dazu, um diesen Geldeingang in der Testumgebung zu simulieren.

Die Funktion simuliert im Testmodus eine Rückbelastung des Betrages. In der Realität kann das z.B. durch Widerspruch des Kontoinhabers oder mangelnde Deckung ausgelöst werden. Auch hier wird mittels sessionStatus und transactionCreate das Zielsystem benachrichtigt, sowie eine Transaktion des Typs "REVERSAL" erzeugt.

Wurde mit sessionReverseTest ein Storno in der Testumgebung simuliert, kann anschliessend die Nachzahlung simuliert werden. Der optionale Parameter amount enthält den bezahlten (Teil-)Betrag, wird er weggelassen, wird die Nachzahlung des gesamten offenen Betrags simuliert und als Rückgabe amount zurückgeliefert. sessionRechargeTest sowie das reale Ereignis eines Zahlungeingangs erzeugt eine Transaktion vom Typ "BACKPAY" und löst die zugehörige Benachrichtigung transactionCreate aus. Wurde der gesamte offene Betrag bezahlt, wird zusätzlich sessionStatus auf "RECHARGED" gesetzt und die Benachrichtiung sessionStatus ausgelöst.

Mit Hilfe dieser Funktion kann ein eigener Zahlungseingang, oder eine nachträgliche Forderungsminderung verbucht werden. Sie erzeugt eine neue Transaktion vom Typ "EXTERNAL" und löst zusätzlich die Benachrichtigung transactionCreate aus. Neben Datum und Betrag kann zusätzlich ein Beschreibungstext zur eigenen Verwendung übermittelt werden. Wird der gesamte offene Betrag oder mehr verbucht ändert sich der Status der Session in "RECHARGED". Es besteht auch die Möglichkeit mit einem negativem Betrag die offene Summe wieder zu erhöhen oder überzahlte Sessions auszugleichen.

Diese Funktionen dienen der Ermittlung aller Transaktionen einer Session. transactionList liefert eine Liste der Transactions-IDs, die wiederum als Eingangsparameter für transactionGet genutzt werden können, um die Details abzurufen. Der Typ der Transaktion in der Rückgabe type kann folgende Werte enthalten:

Jede Statusänderung, auch die Erzeugung, eines Bezahlvorgangs führt zu jeweils einer Benachrichtigung mit dieser Funktion z.B. wenn der Betrag bestätigt, eingezogen oder storniert wird. Es werden sessionId und der aktuelle Status, sowie alle freien Parameter mitgeschickt.

Als Ergebnis können neue oder veränderte freeParams zurückgegeben werden, die anschließend zur Session hinzugefügt werden.

Wie oben beschrieben, können mehrere verschiede Transaktionen je Session erzeugt werden. Die Benachrichtigung dient dazu das Zielsystem darüber zu informieren. Bei den Transaktionsarten "BOOKING" und "REVERSAL" geht dies immer mit einer Statusänderung der Session einher und der zugehörigen Benachrichtigung sessionStatus. Wurde bei "BACKPAY" und "EXTERNAL" nicht der komplette offene Betrag gebucht, ändert sich der Status der Session jedoch nicht.