Allgemeine Beschreibung des NVP-Protokolls

Einführung

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.

Zielgruppe

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.

Vorraussetzungen

Für das Verständnis der Dokumentation werden Kenntnisse in der von Ihnen verwendeten Sprache/Umgebung, sowie grundlegende Kenntnisse über das HTTP-Protokoll vorausgesetzt.

API-Request

Die Grundlage stellt das HTTP 1.0 Protokoll dar - das bedeutet die Anfragen erfolgen über die Methoden GET und/oder POST.

Syntax

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}​&param1=value1​&paramN=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.

Kodierung

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.

Optionale Parameter

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!

Strukturierte Parameter

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.

Beispiel anhand des Parameters "freeParams"

Ihre Daten:

foo=bar
bar=foo
foobar=foobar

Ihre Daten in kodierter Form:

&freeParams%5Bfoo%5D=bar
&freeParams%5Bbar%5D=foo
&freeParams%5Bfoobar%5D=foobar

API-Response

Bei dem Rückgabewert eines API-Aufrufs handelt es sich um einen semi-strukturierten Text.

Allgemeiner Aufbau

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.

Strukturierte Rückgabewerte

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

Beispiel anhand des Parameters "freeParams"

Ihre Daten:

foo=bar
bar=foo
foobar=foobar

Daten in kodierter Form:

freeParams[foo]=bar
freeParams[bar]=foo
freeParams[foobar]=foobar

Listen als besondere Form strukturierter Rückgabewerte

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

Besonderheiten bei Rückgabewerten

Es gibt einige spezielle Rückgabewerte/-verhalten auf die hingewiesen werden muss.

Fehlerbehandlung

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

Einzelne Rückgabewerte

Wenn Funktionen nur einen einzigen Rückgabewert haben, wie z.B. "resetTest", dann lautet der Name des Rückgabewertes result.

Kodierung

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.

Benachrichtigungen (Notification)

Die Benachrichtigungen dienen dazu, Sie über Ereignisse zu informieren, die asynchron zu der von Ihnen mit unseren APIs getätigten Kommunikation auftreten.

Syntax

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}​&param1=value1​&paramN=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".

Konfiguration der URL

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.

Requests/Response

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.