Diese Dokumentation beschreibt allgemein die Vorgehensweise wie Sie eine Anfrage an die
micropayment API's (NVP-Protokoll) stellen und die zurückgelieferte Antwort auszuwerten haben.
NVP steht für Name-Value-Pair was übersetzt Name-Wert-Paar bedeutet.
Es wird an vielen Stellen Bezug auf die Referenz der jeweiligen API genommen, es empfiehlt sich also parallel eine Referenz zu öffnen, z.B. die Kreditkarten API.
Die Referenzen sind in der Technische Dokumentation verlinkt.
Nutzer der micropayment API's die aber nicht den Service-Client verwenden können oder wollen, da Dieser PHP als Voraussetzung hat, sind Nutzer anderer serverseitiger Sprachen/Umgebungen (ASP/ASP.net, Java, Perl, Python, etc.) die Zielgruppe dieser Dokumentation.
Für das Verständnis der Dokumentation werden Kenntnisse in der von Ihnen verwendeten Sprache/Umgebung, sowie grundlegende Kenntnisse über das HTTP-Protokoll vorausgesetzt.
Die Grundlage stellt das HTTP 1.0 Protokoll dar - das bedeutet die Anfragen erfolgen über die Methoden GET und/oder POST.
Die Aufruf-Syntax ist dementsprechend einfach gehalten, wobei dem Parameter action eine besondere Rolle zufällt:
http(s)://webservices.micropayment.de/path/to/{service}/{version}/nvp/?action={method}¶m1=value1¶mN=valueN
Der Platzhalter {service} identifiziert eine Zusammenstellung von Funktionalitäten (i.d.R. eine Zahlungsart),
die durch eine Versionsnummer der API ({version}) ergänzt wird,
um bei der Veröffentlichung einer neuen Version die Abwärtskompatibilität zu wahren.
Die exakte URL der zu verwendenden API entnehmen Sie bitte der jeweiligen API-Referenz, im Abschnitt "URL der API".
Der Parameter action identifiziert die Methode (Funktionalität) die durch den Aufruf ausgelöst werden soll.
Wobei der Platzhalter {method} durch den gewünschten Namen aus der Referenz zu ersetzen ist (Groß-/Kleinschreibung ist zu beachten).
Welche Methoden zur Verfügung stehen, können Sie der die jeweilige API-Referenz, im Abschnitt "Funktionsumfang der API" > "Methoden", entnehmen.
Alle Parameter müssen selbstverständlich enkodiert werden. Verwenden Sie hierfür eine Funktion Ihrer Sprache, die die Parameter entsprechend dem MIME-Type
application/x-www-form-urlencoded kodiert.
In den Parameterlisten der Methoden erhalten Sie in der Spalte "Pflicht" die Information darüber ob der Parameter
gesetzt werden muss (ja) oder nicht (nein)
Ist er nicht Pflicht, gibt es einen Standardwert.
Ein Parameter gilt als nicht gesetzt, wenn er nicht im QueryString bzw. im HTTP-Body enthalten ist.
Der Standardwert [NULL] signalisiert das der Standardwert dem Nullwert entspricht
und daher als nicht gesetzt gilt.
[NULL] bitte nicht mit dem String "[NULL]" verwechseln!
Einige Methoden der API's, z.B. "sessionCreate" oder "customerCreate" stellen die
Möglichkeit zur Verfügung, eigene frei definierbare Daten zuzuweisen - bspw. über den Parameter "freeParams").
Die Daten werden in Form einer Datenstruktur, die man assoziatives Arrays oder auch HashMap nennt, gespeichert.
Um diese Struktur zu übermitteln, werden die Schlüssel (Name des Feldes/Eigenschaft) in eckige Klammern
parameter[Schlüssel]=Wert eingefasst.
Ihre Daten:
foo=bar
bar=foo
foobar=foobar
Ihre Daten in kodierter Form:
&freeParams%5Bfoo%5D=barBei dem Rückgabewert eines API-Aufrufs handelt es sich um einen semi-strukturierten Text.
Die Struktur ist einfach gehalten:
field1=value1<line-delimiter>
fieldN=valueN<line-delimiter>
Der Platzhalter <line-delimiter> entspricht dem Steuerungszeichen
\n bzw. als Hex \x0A.
Da es möglich ist strukturierte Daten in Objekten (z.B. Session/Customer) zu hinterlegen ist, müssen diese Daten verständlicherweise auch wieder abgefragt werden können.
Die Vorgehensweise ähnelt dabei der Übergabe strukturierte Parameter.
Es gibt allerdings einen Unterschied in der Kodierung der jedoch später noch erläutert wird.
Auch in der Rückgabe werden werden die Schlüssel (Name des Feldes/Eigenschaft) in eckige Klammern eingefasst:
Feldname[Schlüssel]=Wert
Ihre Daten:
foo=bar
bar=foo
foobar=foobar
Daten in kodierter Form:
freeParams[foo]=bar
Listen stellen eine spezielle Form eines strukturierten Rückgabewertes dar,
da der Schlüssel/Index in diesen Fällen numerisch (unsigned integer) ist.
Feldname[<index>]=Wert
Zu beachten ist, dass der Index immer bei 0 beginnt und mit jedem Eintrag um 1 erhöht wird.
Bsp. für "fieldname string[]" mit 2 Listeneinträgen:
fieldname[0]=stringvalue1
fieldname[1]=stringvalue2
Es gibt einige spezielle Rückgabewerte/-verhalten auf die hingewiesen werden muss.
Bei jeder Antwort wird als erste Zeile immer ein Fehlercode zurückgeliefert:
error=<errorcode>
Hierbei gilt, dass der Fehlercode 0 keinem Fehler entspricht.
Wenn der Fehlercode einen Wert ungleich 0 entspricht,
stellt der Servers in der Antwort ein weiteres Feld mit dem Fehlertext zur Verfügung:
errorMessage=<errormessage>
Bsp. für den Aufruf einer nicht existierenden Funktion :
error=3002
errorMessage=method+to+invoke+%22not_existing_method%22+not+exists
Wenn Funktionen nur einen einzigen Rückgabewert haben, wie z.B. "resetTest",
dann lautet der Name des Rückgabewertes result.
Auch die Rückgabewerte sind enkodiert (application/x-www-form-urlencoded); allerdings NUR die Werte der Felder!
Diese zusätzliche Kodierung ist auf Grund von historischem Wachstum notwendig, um die UTF-8 kodierten Daten der Kreditkarten-API korrekt zu übertragen.
Die Benachrichtigungen dienen dazu, Sie über Ereignisse zu informieren, die asynchron zu der von Ihnen mit unseren APIs getätigten Kommunikation auftreten.
Es wird die gleiche Syntax wie bei den API-Requests verwendeten, nur das die aufgerufene URL auf Ihrem Server liegt. Dem Parameter action fällt auch hier eine gesonderte Rolle zu:
{notification-url}?action={notification}¶m1=value1¶mN=valueN
Der Parameter action identifiziert das Ereignis über das die Benachrichtigung informiert.
Der Platzhalter {notification} wird durch den gewünschten Namen aus der Referenz ersetzt. (Groß-/Kleinschreibung ist zu beachten)
Welche Benachrichtigungen von der verwendeten API versendet werden, entnehmen Sie der die jeweilige API-Referenz im Abschnitt "Funktionsumfang der API" > "Benachrichtigungen".
Die Konfiguration der URL nehmen Sie im ControlCenter Ihres Accounts vor, indem Sie im Hauptmenü den Punkt "Meine Konfiguration" und im darauf zur Verfügung gestellten Untermenü "APIs & Berechtigungen" wählen, um zu der Liste der verfügbaren APIs zu gelangen.
Wählen Sie die zu konfigurierende Zahlungsart sowie das Projekt, um diese im Rahmen der zur Verfügung gestellten Optionen, zu denen in jedem Fall die "Benachrichtungs-URL" gehört, zu konfigurieren.
Die Herangehensweise bei den Benachrichtigungen entspricht der von API-Request & API-Response
mit dem Unterschied das die Rollen von Client &Server getauscht wurden.
Das bedeutet vereinfacht, das der micropayment Server die Rolle des Clients übernimmt, Anfragen an Ihren Server stellt,
und entsprechend der übermittelten {notification} eine Antwort erwartet.