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 programm seitig 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.

Im Anhang sind alle Fehlercodes, Ursachen und Tipps zur Behebung zusammengefasst.

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.

Alle Parameter und Rückgaben sind in der Kurzreferenz zusammengefasst.

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.

	Achtung
	Wenn mehrere Projekte betrieben werden, in denen sich die Kunden getrennt anmelden müssen, sollten verschiedene Präfixe vor den Wert in customerId gesetzt werden, z.B: "prj1:max@muster.de".

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.

Alle Parameter und Rückgaben sind in der Kurzreferenz zusammengefasst.

Einem Kunden können 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.

Alle Parameter und Rückgaben sind in der Kurzreferenz zusammengefasst.

Die Funktion ermittelt alle freien Parameter, die mit customerCreate oder customerSet an den Kundensatz übergeben wurden.

Alle Parameter und Rückgaben sind in der Kurzreferenz zusammengefasst.

Nachdem ein Kunde angelegt wurde und vor der Bezahlung, muss die Bankverbindung 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.

Alle Parameter und Rückgaben sind in der Kurzreferenz zusammengefasst.

Die hinterlegten Bankdaten des Kunden können mit dieser Funktion wieder ermittelt werden, z.B. um sie vom Kunden bearbeiten zu lassen.

Alle Parameter und Rückgaben sind in der Kurzreferenz zusammengefasst.

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.

	Wichtig
	Die Funktion scheitert, wenn im Parameter projectCampaign eine ungültige oder gesperrte Kampagne angegeben wurde. Ist hingegen webmasterCampaign ungültig, wird der Parameter lediglich ignoriert.

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.

	Wichtig
	Wurde in der Konfiguration festgelegt, dass NUR die Standardwerte verwendet werden sollen, werden die Parameter amount und title ignoriert.

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

	Achtung
	Die Benachrichtigung sessionStatus erfolgt sofort, noch bevor die Rückgabe geliefert wird.

Alle Parameter und Rückgaben sind in der Kurzreferenz zusammengefasst.

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.

Alle Parameter und Rückgaben sind in der Kurzreferenz zusammengefasst.

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.

	Achtung
	Die Benachrichtigung sessionStatus erfolgt sofort, noch bevor die Rückgabe geliefert wird.

Alle Parameter und Rückgaben sind in der Kurzreferenz zusammengefasst.

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.

Alle Parameter und Rückgaben sind in der Kurzreferenz zusammengefasst.

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. Die Funktion dient dazu, um diesen Geldeingang in der Testumgebung zu simulieren.

Alle Parameter und Rückgaben sind in der Kurzreferenz zusammengefasst.

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 das Zielsystem benachrichtigt.

Alle Parameter und Rückgaben sind in der Kurzreferenz zusammengefasst.

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.

Alle Parameter und Rückgaben sind in der Kurzreferenz zusammengefasst.