Einführung
paydirekt ist das Bezahlverfahren der deutschen Privatbanken, Volks- und Raiffeisenbanken und Sparkassen.
Der Zweck dieses Dokuments ist die Beschreibung der Schnittstellen (REST-API) zur Integration des Bezahlverfahrens für Payment Service Provider (PSP) oder Collecting Payment Service Provider (CPSP).
Ablauf einer paydirekt-Zahlung
Um eine paydirekt-Zahlung durchzuführen, wird ein HTTP POST-Request mit den
Bestell- und Transaktionsdaten (Checkout) an das paydirekt-System geschickt. Wenn dieser
POST-Aufruf erfolgreich war, wird eine Checkout-Ressource angelegt, die einen
approve
-Link enthält. Auf diesen Link muss der Händler den Kunden per HTTP Redirect
weiterleiten. Der Kunde kann sich dort in paydirekt einloggen und die Zahlung bestätigen.
In diesem Checkout hat der Händler auch die Möglichkeit, verschiedene URLs zu hinterlegen und so die Weiterleitung des Kunden von paydirekt zurück in das Webshop-System zu steuern. Beim Abschluss der Zahlungsinitiierung durch das paydirekt-System wird je nach Status des Abschlusses auf eine dieser URLs weitergeleitet. Es werden drei Zustände unterstützt: Erfolg, Abbruch und Ablehnung. Der Käufer kann somit auf eine Seite mit einer passenden Meldung im Händlershop weitergeleitet werden.
Zusätzlich ist es möglich den Checkout abzufragen. Der Checkout enthält
nach Abschluss der Zahlungsinitiierung alle Transaktionen zum betroffenen Vorgang und deren Status.
Eine erfolgreiche Zahlung wird durch eine CAPTURE-Transaktion mit dem
Status SUCCESSFUL
gekennzeichnet.
Dies entspricht der Zahlungsgarantie für den Händler.
paydirekt ermöglicht sowohl die Abwicklung von Direktbestellungen als auch Vorbestellungen. Bei Direktbestellungen erfolgt die Zahlung automatisch sofort nach der Bestätigung durch den Kunden. Bei Vorbestellungen erfolgt keine automatische Zahlung. Der Händler löst die Zahlung nach eigenem Ermessen aus, sobald die Bestellung erfüllt werden kann. Dies kann in Form von einem oder mehreren Teilbeträgen erfolgen.

Endpoint
Die paydirekt-Schnittstellen sind über folgende URL erreichbar:
https://api.paydirekt.de
Zum Test der Schnittstelle steht eine Test-Umgebung (Sandbox) mit folgendem Endpoint zur Verfügung. In der Sandbox werden keine Buchungen auf Bankkonten ausgelöst, auch nicht innerhalb einer Testbank:
https://api.sandbox.paydirekt.de
Die festen IP-Adressen der Endpoints lauten:
Produktiv: 213.95.157.133 Sandbox: 213.95.255.167
Die festen IP-Adressen, von denen Callback URLs aufgerufen werden, lauten:
Produktiv: 213.95.26.236 Sandbox: 213.95.26.164
Transport Layer Security
paydirekt ist ausschließlich über verschlüsselte Endpoints (HTTPS) erreichbar. Der Payment Card Industry Security Standards Council empfiehlt bereits heute die Verwendung von TLS 1.2 bei API-Anbindungen. Folgende Cipher-Suites werden für TLS 1.2 empfohlen: ECDHE-RSA-AES256-GCM-SHA384
Erklärung:
-
Diese Cipher-Suite wird durch das BSI empfohlen und kann noch mindestens bis 2021 und darüber hinaus verwendet werden.
-
ECDHE bietet Perfect Forward Secrecy.
-
ECDHE benötigt weniger Ressourcen als DHE.
-
AES256 ist eine starke Verschlüsselung.
-
RSA ist das zugrundeliegende Verfahren für das Private/Public-Key Schlüsselmaterial.
-
SHA384 ist eine sichere schnelle Hash-Funktion für Signaturen.
-
SHA384 bietet Schutz auch gegen Length-Extension-Attacks (im Gegensatz zu SHA256).
-
GCM ist ein moderner Cipher-Block-Mode für AES, der bestimmte Angriffsvektoren, die bei der Alternative CBC möglich sind, verhindert.
-
GCM etabliert eine Authenticated Encryption.
Eine Übersicht darüber, welche älteren Versionen von TLS aktuell noch unterstützt werden, finden Sie auf folgender Seite: https://www.ssllabs.com/ssltest/analyze.html?d=api.paydirekt.de&hideResults=on
Falls Java verwendet wird, müssen die Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files installiert sein. |
REST-Prinzipien
Das paydirekt-System stellt eine REST-Schnittstelle zur Integration von Zahlungen in Webshops zur Verfügung.
Die API folgt den HATEOAS-Prinzipien, basiert auf der HAL-Spezifikation und verwendet JSON als Datenformat.
HTTP-Methoden
Die REST-API definiert Ressourcen, die Geschäftsobjekten entsprechen und die per URL referenziert werden. Zur Erzeugung, Änderung und Datenabfrage dieser Ressourcen werden Standard-HTTP-Methoden entsprechend RFC 2616 verwendet:
Methode | Art | Beschreibung |
---|---|---|
|
Query |
Liefert die Repräsentation eines oder mehrerer Geschäftsobjekte zurück. Es werden keine Veränderungen auf dieser Ressource durchgeführt. |
|
Command |
Legt ein neues Geschäftsobjekt an. |
HTTP Header-Felder
Die nachfolgenden Header sind in allen Serviceaufrufen (GET/POST) mit Ausnahme des Access-Token Endpoints mit zu übermitteln.
Header-Feld | Wert | Beispiel |
---|---|---|
|
Access-Token aus dem OAuth2-Aufruf |
|
|
Eindeutige Request-ID, wird zur Protokollierung verwendet. Wenn im Request keine gesetzt ist, wird serverseitig eine
erzeugt und in der HTTP Response zurückgegeben. |
8eb5d811-ad7f-4e08-94e4-5dcfa03a4b15 |
|
Der Internet Media Type des Request Body.
Es wird nur |
|
|
Die akzeptierten und erwarteten Internet Media Types der Response.
Es wird nur |
|
|
Datum und Zeit zum Sendezeitpunkt der Anfrage. Format nach [RFC 7231] IMF-fixdate. |
Fri, 30 May 2014 09:46:48 GMT |
HTTP Status Codes und Fehlermeldungen
Die folgenden allgemeinen Status Codes können potentiell bei allen Service-Aufrufen auftreten und müssen entsprechend behandelt werden. Besonderheiten für eine Ressource sind jeweils im Abschnitt Return Codes erläutert.
HTTP Status Code | Beschreibung |
---|---|
200 (OK) |
Der Request wurde erfolgreich ausgeführt. |
201 (Created) |
Die gewünschte Ressource wurde angelegt.
Sie ist unter der im Header hinterlegten |
204 (No Content) |
Der Request wurde erfolgreich ausgeführt. In der Response gibt es keinen Body. |
400 (Bad Request) |
Der Request wurde nicht angenommen. Details stehen in Response Body. |
401 (Unauthorized) |
Es wurde versucht, auf eine Ressource zuzugreifen, die geschützt ist. Entweder ist der API-Key falsch, das OAuth2 Token fehlt bzw. ist abgelaufen oder der Zugriff auf die Ressource wird verweigert. |
403 (Forbidden) |
Der Zugriff ist auf diese Ressource mit der verwendeten HTTP-Methode nicht erlaubt. |
404 (Not Found) |
Unter dieser URL kennt der Server keine Ressource. |
410 (Gone) |
Die API steht in dieser Version nicht mehr zur Verfügung. |
422 (Unprocessable Entity) |
Es ist ein fachlicher Fehler aufgetreten. Details stehen im Response Body. |
500 (Internal Server Error) |
Es ist ein serverseitiger Fehler aufgetreten. Details stehen im Response Body. |
503 (Service Unavailable) |
Das paydirekt System ist vorübergehend nicht erreichbar (z. B. wegen Wartung). |
Error Messages
Wenn ein Fehler auftritt, dann werden neben dem HTTP-Status Code Details zum Fehler
in einem Array von Message-Objekten mit dem Namen messages
im Response-Body zurückgegeben.
Messages haben einen definierten, eindeutigen Message Code (Feld code
) und eine Fehlerstufe (severity
).
Außerdem kann ein Attribut logref
enthalten sein, das den Fehler eindeutig referenziert und die Fehleranalyse vereinfacht.
Geben Sie diese logref
bei Support-Anfragen bitte immer mit an.
Die möglichen Message Codes sind jeweils im Abschnitt Return Codes aufgeführt.
Es muss ein Default-Verhalten für unbekannte oder fehlende Message Codes im Falle eines 4xx oder 5xx Status Codes implementiert werden.
Attribut | Typ | Beschreibung |
---|---|---|
|
Liste von Messages |
Eine Liste aller aufgetretener Fehler. |
Sonderfall Validierungsfehler
Validierungsfehler werden ebenfalls in der zuvor beschriebenen Form, zusammen mit dem HTTP-Status Code 400, zurückgeliefert.
Der Pfad eines betroffenen Attributs wird im Feld path
angegeben.
Komplexe Objekte werden durch Punkte getrennt. Arrays werden über [n]
referenziert.
Zusätzlich kann in einem weiteren optionalen Feld reasonCode
eine detaillierte Ursache der Validierungsmeldung spezifiziert werden.
Für den Message Code VALIDATION_ERROR
sind derzeit folgende Reason Codes definiert:
Reason Code | Beschreibung |
---|---|
|
Der Wert entspricht nicht den Formatvorgaben. |
|
Ein Pflichtfeld ist nicht angegeben. |
|
Es wurde ein Wert verwendet, der nicht im angegebenen Aufzählungstyp enthalten ist. |
Beispiel
POST /api/checkout/v1/checkouts HTTP/1.1
Content-Type: application/json;charset=utf-8
Authorization: Bearer <access_token>
{
"type" : "DIRECT_SALE",
"totalAmount" : 100.0,
"shippingAmount" : 5.999,
"orderAmount" : 96.5,
"refundLimit" : 200,
"items" : [ {
"quantity" : 3,
"name" : "Bobbycar",
"ean" : "800001303",
"price" : 25.99
}, {
"quantity" : 1,
"name" : "Helm",
"price" : 18.53
} ],
"shoppingCartType" : "MIXED",
"currency" : "EUR",
"overcapture" : false,
"shippingAddress" : {
"addresseeGivenName" : "Marie",
"addresseeLastName" : "Mustermann",
"company" : "Musterbau GmbH & Co KG",
"street" : "Kastanienallee",
"streetNr" : "999",
"additionalAddressInformation" : "Im Rückgebäude",
"zip" : "90402",
"city" : "Schwaig",
"countryCode" : "DE",
"state" : "Bayern"
},
"merchantCustomerNumber" : "cust-732477",
"merchantOrderReferenceNumber" : "order-A12223412",
"merchantReconciliationReferenceNumber" : "recon-A12223412",
"merchantInvoiceReferenceNumber" : "20150112334345",
"note" : "Ihr Einkauf bei Spielauto-Versand.",
"sha256hashedEmailAddress" : "fxP4R-IxH1Eaxpb0f_i5Shc8-FrYrtmx5lx35f9Xzgg",
"expiryTime" : 1800,
"redirectUrlAfterSuccess" : "https://spielauto-versand.de/order/123/success",
"redirectUrlAfterCancellation" : "https://spielauto-versand.de/order/123/cancellation",
"redirectUrlAfterAgeVerificationFailure" : "https://spielauto-versand.de/order/123/underAge",
"redirectUrlAfterRejection" : "https://spielauto-versand.de/order/123/rejection",
"callbackUrlStatusUpdates" : "https://spielauto-versand.de/callback/status"
}
HTTP/1.1 400 Bad Request
Content-Type: application/hal+json;charset=utf-8
{
"messages" : [ {
"severity" : "ERROR",
"code" : "VALIDATION_ERROR",
"path" : "shippingAmount",
"reasonCode" : "INVALID_FORMAT",
"logref" : "bddc9682-574a-4913-a743-9ae9d78b2690:7yk5DGxxCfL"
} ]
}
Links
In den Response-Daten können Links zu anderen Ressourcen enthalten sein. Die Links sind abhängig vom Kontext und Status der Ressource und geben einen Rückschluss auf mögliche Aktionen, die für eine Ressource derzeit möglich sind. Es kann sein, dass ein Link, zum Beispiel nach Ablauf einer gewissen Frist, nicht mehr enthalten ist, weil die Aktion nicht mehr möglich ist.
Die Rückgabedaten folgen dem Hypertext Application Language (HAL) Format.
Es wird dringend empfohlen, immer Links zu verwenden, um Aktionen durchzuführen.
Zusätzliche Felder
Zusätzliche Felder, die bei Anfragen oder Antworten übertragen werden und nicht in diesem Dokument beschrieben sind, werden vom paydirekt-System ignoriert. Ein Fehler oder eine Warnung wird dabei nicht zurückgegeben.
Authentifizierung als PSP
Das paydirekt-System ermöglicht es PSPs, Anfragen an das paydirekt-System im Namen eines Shops zu tätigen. Zusätzlich können sie ihre Transaktionsreports per API abzurufen.
Zur zeitgleichen Authentifizierung eines PSP und gegebenenfalls einen Shops wird ein API-Key Verfahren in Verbindung mit OAuth2 verwendet.
Der PSP muss dazu sowohl den eigenen API-Key und API-Secret besitzen, als auch zusätzlich den API-Key und das API-Secret des entsprechenden Shops eines Händlers, in dessen Auftrag ein Endpoint angesprochen werden soll. Dabei wird in beiden Fällen jeweils nur ein Access Token zurückgeliefert. Je nachdem mit welchen Credentials das Token erstellt wurde (PSP mit oder ohne Shop) hat das Token unterschiedliche Berechtigungen.
Für Report-Abfragen darf ausschließlich der API-Key und API-Secret des PSPs zur Generierung des Access Tokens übermittelt werden.
Die paydirekt API für PSPs unterscheidet sich von der Händler-API derzeit nur in dem nachfolgend beschriebenen Authentifizierungsprozess für PSPs und in den Feldern der über die API abrufbaren Transaktionsreports.
Um Anfragen an das paydirekt-System zu tätigen, wird zunächst für einen API-Key ein zeitlich auf wenige Minuten befristetes Access Token ausgestellt.
In allen folgenden Requests (z. B. Anlage eines neuen Checkouts) authentifiziert sich der PSP für sich und für einen bestimmten Shop einfach über dieses Access Token.
Begriffsdefinition
- API-Key
-
Der API-Key dient der Identifikation eines bestimmten Shops eines Händlers bzw. eines PSPs. Ein weiterer API-Key dient der Identifikation eines bestimmten PSPs. Ein API-Key kann im Intermediärportal jederzeit erzeugt oder deaktiviert werden. Es können mehrere API-Keys gleichzeitig gültig sein. Auf der Sandbox sind die ersten 8 Stellen neu erstellter API-Keys immer "00000000".
Ein API-Key wird vom paydirekt-System generiert und hat folgendes Format:
Länge: 36 Zeichen
Kodierung: UUID Type 4 Random [RFC 4122]
Beispiel:87dbc6cd-91d2-4574-bcb5-2aaaf924386d
Beispiel auf der Sandbox:00000000-91d2-4574-bcb5-2aaaf924386d
- API-Secret
-
Das API-Secret dient der Authentifizierung des Shops bzw. PSPs. Es wird verwendet, um eine Signatur (Auth-Code) der Authentifizierungsanfrage zu erzeugen. Das API-Secret selbst wird in der Kommunikation so niemals übertragen, wodurch die Sicherheit deutlich erhöht wird. Ein API-Secret ist genau einem API-Key zugeordnet und wird zusammen mit diesem verwaltet.
Ein API-Secret wird vom paydirekt-System generiert und hat folgendes Format:
Länge: 44 Zeichen
Kodierung: Base64 URL Encoding [RFC 4648 Section 5] mit Base64 Padding
Beispiel:9Tth0qty_9zplTyY0d_QbHYvKM4iSngjoipWO6VxAao=
- Access Token
-
Für alle Requests gegen die paydirekt-API ist ein OAuth2 Access Token [RFC 6749 1.4] erforderlich. In diesem sind die Authentifizierungsinformationen des Aufrufers gespeichert. Ein Access Token wird durch Aufruf des Access Token-Endpoints durch Angabe des Grant Type
api_key
erzeugt und wird bei allen folgenden Requests im Request HeaderAuthorization
alsBearer
angegeben:Authorization: Bearer <accessToken>
Der Access Token hat eine begrenzte Gültigkeitsdauer von einer Stunde. Nach Ablauf der Gültigkeit kann einfach ein neuer Access Token bezogen werden. Die Gültigkeitsdauer wird im Response des Access Token zurückgeliefert.
Bei Bedarf kann das aufrufende System mehrere Access Tokens gleichzeitig verwenden. Besteht das aufrufende System aus mehreren Knoten, so kann jeder Knoten für seine Anfragen einen eigenen Access Token verwenden. Es ist aus Performance-Gründen jedoch nicht gestattet, für jeden einzelnen Request einen neuen Access Token anzufordern.
paydirekt bietet auf GitHub eine Beispielimplementierung für die Erstellung der Signatur und das Anfordern des Tokens in Java und PHP. |
- Grant Type
-
Der Grant Type definiert die Methode, wie sich ein Benutzer oder ein System gegenüber dem paydirekt-System authentifiziert. Für die REST-API wird der Grant Type
api_key
verwendet.
Signatur (Auth-Code)
Die Signatur (Auth-Code) bestätigt, dass der PSP im Besitz des API-Secrets ist und gültige Anfragen im Namen des Shops an das paydirekt-System senden darf.
Es muss sowohl für den PSP-API-Key als auch für den Händler-API-Key eine Signatur erstellt werden.
Die Signatur wird aus einem String-to-Sign und einem API-Secret erzeugt. In ersteres fließen folgende Werte in der hier angegebenen Reihenfolge ein:
Nr. | Wert | Quelle | Format | Beispiel |
---|---|---|---|---|
1. |
Request-ID |
Request Header |
UUID Type 4 Random [RFC 4122] |
ec85749b-aa36-412a-a397-2b40200c119c |
2. |
Datum |
Request Header |
yyyyMMddHHmmss |
20141231235859 |
3. |
API-Key |
Request Header |
UUID Type 4 Random [RFC 4122] |
4c15310a-7936-4a19-8d80-f2b7bd95dc9b |
4. |
Random Nonce |
Request Body-Feld |
Base64 URL Encoding [RFC 4648 Section 5] |
Ns0WLCI3qA2AMH98wUYyhqALyVlzS0q7n Hh7NdeMyvUgKJoyF0rNXkgq5fq2VNJs |
Die Random Nonce muss pro Anfrage durch das aufrufende System per Zufallsgenerator neu generiert werden; sie fließt in
die Signatur mit ein und wird im Request Body-Feld randomNonce
an das paydirekt-System übertragen.
Aus den oben angegebenen Werten wird zunächst der sogenannte String-to-Sign gebildet.
Dazu werden die Werte in der angegebenen Reihenfolge unter Trennung mittels des Trennzeichens :
zu einer Zeichenkette verbunden (String Konkatenation).
Das Trennzeichen wird nur eingefügt, sofern ein weiterer Wert folgt. Keiner der Werte darf fehlen oder als null kodiert werden.
Format-Beispiel für einen String-to-Sign Z
:
Z = ec85749b-aa36-412a-a397-2b40200c119c:20141231235859:4c15310a-7936-4a19-8d80-f2b7bd95dc9b:Ns0WLCI3qA2AMH98wUYyhqALyVlzS0q7nHh7NdeMyvUgKJoyF0rNXkgq5fq2VNJs
Auf Basis eines String-to-Sign Z
zu einem Request R
sowie des API-Secrets S
wird die Signatur der Anfrage
mittels der Funktion HMAC-SHA-256 [RFC 2104] gebildet:
Signatur(Request) = new String(encodeBase64URLCompatible(HMAC-SHA-256(getBytes(Z, "UTF-8"), decodeBase64URLCompatible(getBytes(S, "UTF-8")))), "UTF-8")
Die Signatur wird per Base64 URL Encoding [RFC 4648 Section 5] kodiert. Die problematischen Zeichen + und / werden durch - (Minus) und _ (Unterstrich) ersetzt.
|
Diese Signatur wird im Request Header X-Auth-Code
oder X-Auth-Code-PSP
angegeben.
Im Vergleich zu Basic Auth oder einer reinen Hash-Signatur bietet das API-Key Verfahren auf Basis von HMAC einen wesentlich höheren Grad der Sicherheit, da die Signatur nicht gefälscht oder wiederverwendet werden kann und das Geheimnis in der Kommunikation niemals übertragen wird.
Access Token
POST /api/merchantintegration/v1/token/obtain
Über diesen Endpoint wird, wie oben beschrieben, ein Access Token ausgestellt.
Findet eine Authentifizierung von PSPs inklusive Shop statt, müssen alle vier Felder X-Auth-Key
, X-Auth-Code
, X-Auth-Key-PSP
und X-Auth-Code-PSP
übergeben werden. Bei einer Authentifizierung eines PSPs ohne Shop sind nur die Felder X-Auth-Key-PSP
und
X-Auth-Code-PSP
zu übergeben; siehe Erläuterungen unter Authentifizierung.
Request
Feld | Typ | Eigenschaften | Beschreibung |
---|---|---|---|
Header-Felder |
|||
|
String |
Pflichtfeld. 36 Zeichen. |
API-Key des Shops |
|
String |
Pflichtfeld. Maximal 44 Zeichen. |
Signatur (Auth-Code) der Anfrage |
|
String |
Pflichtfeld. 36 Zeichen. |
API-Key des PSPs |
|
String |
Pflichtfeld. Maximal 44 Zeichen. |
Signatur der Anfrage bzgl. PSP |
|
String |
Pflichtfeld. 36 Zeichen. |
Zufällig erzeugte UUID der Anfrage |
|
String |
Pflichtfeld. |
Datum und Zeit zum Sendezeitpunkt der Anfrage |
|
String |
Pflichtfeld. |
Immer |
Body-Felder |
|||
|
String |
Pflichtfeld. |
Immer |
|
String |
Pflichtfeld. 64 Zeichen. |
Zufällige Zeichenkette zur Diversifizierung der Request Body Inhalte |
Response
Feld |
Typ |
Eigenschaften |
Beschreibung |
|
String |
Immer vorhanden. |
OAuth2 Access Token für Anfragen gegen die paydirekt-API. Die Länge des Tokens ist abhängig von den in ihm codierten Datenfeldern und eine Maximallänge ist nicht vorgesehen. Sie soll deshalb bei der Implementierung des Clients nicht limitiert werden. |
|
String |
Immer vorhanden. |
Immer |
|
Number |
Immer vorhanden. |
Gültigkeitsdauer des Access Tokens in Sekunden zur Information. |
|
String |
Immer vorhanden. |
Gültigkeitsbereich des Access Tokens zur Information. |
|
String |
Immer vorhanden. |
UUID aus 36 Zeichen zur eindeutigen Identifikation des Tokens. |
|
String |
Immer vorhanden. |
JSON Web Token ID des Access Tokens zu Debugging Zwecken. |
Return Codes
Status Code | Message Code | Beschreibung |
---|---|---|
200 (Ok) |
Access Token wurde erfolgreich erstellt. |
|
400 (Bad Request) |
INVALID_GRANT |
Einer der |
401 (Unauthorized) |
API_KEY_IN_REQUEST_UNKNOWN |
Einer der API-Keys ist im paydirekt-System nicht hinterlegt. |
401 (Unauthorized) |
API_KEY_REQUEST_HEADER_INVALID |
Die Anfrage enthält mehr als einen |
401 (Unauthorized) |
API_KEY_IN_REQUEST_INACTIVE |
Einer der API-Keys ist deaktiviert. |
401 (Unauthorized) |
API_KEY_REQUEST_SIGNATURE_INVALID |
Einer der |
Beispiel
POST /api/merchantintegration/v1/token/obtain HTTP/1.1
Content-Type: application/json;charset=utf-8
Date: Mon Jul 19 19:03:17 CEST 2021
X-Request-ID: 1836f467-958a-4ddf-81e3-a0a4da656ce6
Content-Length: 115
X-Auth-Key: 4fb26d01-2bb1-4fc8-943e-05090c73c6a7
X-Auth-Code: mXMoTvOILl_rSCqQZNWUpvGBlEbi0aPTayS5a9neIPY=
X-Auth-Key-PSP: 02aec37d-cd35-4c06-9338-b46498ee817e
X-Auth-Code-PSP: wAo8ekmAAgpnfafleZzlNYu2qHBPuCyIhlHqqhN44Zc=
Host: api.paydirekt.de
{
"grantType" : "api_key",
"randomNonce" : "SH4A_DyuvKvCPea2T7d6LdHi7ogenaqHpkaZWDIo8Dx0IN3YjN0h9iTMC2J42LzY"
}
HTTP/1.1 200 OK
Content-Type: application/json;charset=utf-8
Content-Length: 2516
{
"access_token" : "nMiHfB9lWfVUSkGDs_BG4XcrHB0_XxqqPNdY4TMDkpyItPqPkTxOew_PCQbPXXM4QFAkC3J5w8Eb8vv7fPgNv8dfj6_mH5v-BAykiqpDm39Y4MtqtmM35eJ3gWfxKJ5Q3dOmQtVmuLiSWMRbHnimTwhMZlIXU53pIXvPjDrv27Lh6vmInElqnkIT1K7NdZ2vRi3oDByEEErzt-Qb9BoBqyp0sQKR9mzgCmsbHCYEn0E-RV7M57cqLIkK8yLDMhF-Yo1T9Q_qAPwAWzY7kUrxmL9Qq8VnnvG3OHQPBu5OvGX_Y3orwtBd8DymPXGBPCnsyzGM1RQJaUY1M2VH9bgLWQr9OF3q2Ht68x-3EqJRwKel6Gt2Gy9EU7wfThMzA_IILUPnSPiioga6WxpLXjtcgER-TdVzoHzLOJb1i7cScZdJGWAcGZf0sOiGH5sgCyRyxd-Syd5E469xrDSNdFzhwRDk9MiWAAls7OBWaWUtwOW5qn77iaNWHXKEdJWEtLB-asokLarTM0FG4TLMZ4gpczVlQzMtoKJj0Y4jiEOBnz0lqxo38x7EGXhfTkMQR2VevhBzPg6h0eUQf6ivHiiPyV5w8ediXGIqw-myIjFOjWgPNOhtm7k_8L50MThXLzEfLCytuH_43URq2Puu52VsTn4UR4iWOo-aLdG8fFiCZf7CUKZC5hbsJMcPqOYuhL5UQlIGiMM34Gc5875PlAcPlPDUWEsnY1x6ZQDSfoijMZ4e5g5vhlGnH7QtX3D-vWVfIQ_K4MTvwbP_pupwV_06zC0vXLimpMRCHSRk-As989TtlXo6td_8HOZp8XEcAPGA5_opA6MJLT9CdVLXW--9D5yAsxwwX4ErVTxOI6cM3gPW45gnmAqUhB85q7F6IKc35DcmB85Wguza5hls0liSL0OwSvaMaydFemLMnAyy1mZihRSqrWjEVI66xVRAN95DBlg39-4J2bkOfLGZ4O45c7-fja5DPcOmsbyJEoJQ7tQ3uUOENrV-NrqGNiSJhdln9b37FLdIkaAlTO6_UGcIn7Ol3Ts8qLup2B-S5P4ESYJSrOjpisRV0j50Y7aEactg8w_fGQBxhsG2d9sThEeX_d_A_LVv5DQ_S_IFL_GQUe6_jvGi2MNeDQ5Y6PgcAC8Dj4Kx957ShJgNNbmldlqR-lxxx0zW2Hew0fatNgPHUGJ9S9PY6esMNLCS5X_dsM3vmiDOZ6s-EeuqDAjnuku04aQDJ9FC5uJo2TQc0yh55sVCuvQt4l2THJ0Z3_frZM7eQU2aZdh-oMLaS0fv_Q3-SF9sI19JLV3AouG6PUMkQOT2_2a36lDFl8IfoJJubkPXHXMNVCjaivHEiIY-2h8LNvVdO-6uhFE4v8FH7ofUYkWVOhbFNmin9USbQbicLeftNZnoe2QGpdRNRt_uTodEk-X5fzWMUbffp7idx0P7GCqZPv7a3tRtrLGZN9FIznrjp4g9pTaWNlds5gIW4mANxSHnmSlrQ7bP4Dl1zG_fOAQx3x-Ih7y6u_UKTlIQpPsy9f48QaCnZJndUG6mDBJOQcldmBJ1Vr6yTCFyA5WRLVvNxKJr5ZwY6S69g2bDdNcMLdUK-7ISH5Dxkxv35ZEuh3a9yW-jbzx0tN7sc6xV9LqNidAdFuiZjL4tq5Z9zQLYtYj2vKqLRGsEW24RlPfaotp9NNd9ElnFbUFPyHUI7EBCvLTKB6bmiLXVVY1FDMQyuvcFwHhOb64iRXba3OYQoK2YATLX9I0FENRJs4v0qs5hMmvpqbSPJlJvXFcoz9ihlC6SUvDMA9gdmbpdC2nt4wdmjR_DdfyuGj508qanrVc2LrCAwcQ4m-2C9jqmSIaepRGhj863o4shpQTjKfVDXrhDJbUQ_FL3LH2QihRPl1nbYdYL-N7Sax1THiAKQw07YD8W967rOu-pOg7OkarTb9qlax_ODiwa41m3gf4PZJDmhxWU-reiKsqT8tXjk13SXkewxcSPeTofOCE2Td8ZJLHh2BtFHrYCeAw8VAto89Rcg21Mh0sM8pvzIk8yzAl7-b_p_Wut_aGdGDaKViVXLz2RE5DC4DW1e3xh3pJrEocyvZAh5mRFVjMODBBkJrIKBRFK46UIX-mSoOlAv93yVg2I3si6A9Yyq_Sov9ksSozC-PX97aDXLSbnJRG3ch2HI",
"token_type" : "bearer",
"expires_in" : 3599,
"scope" : "account accountsummary checkout credit merchant intermediary reporting thirdparty thirdpartycustomerauthorization thirdpartymerchantauthorization transaction",
"aid" : "1dac3422-9798-466a-a051-ca7945a1d9b7",
"jti" : "eCZ_aOt9DUTodX6WypOWhS0msmY"
}
Beispiel (Falscher Auth-Code)
POST /api/merchantintegration/v1/token/obtain HTTP/1.1
Content-Type: application/json;charset=utf-8
X-Request-ID: 612a191c-9cf9-448a-a43c-f7d16420651b
Content-Length: 115
X-Auth-Key: 3e05d28e-5832-4f57-84d4-e833db6bb98a
X-Auth-Code: 3B-wVDheHbKc6dEE-oaybxeW53e0OqyRDV7THbBN6I8=
X-Auth-Key-PSP: f04ff772-4198-4791-845c-29ba3f0d971f
X-Auth-Code-PSP: DKHXmrm0pdYumqEVX-uE4fpn6mMP4RowtW5K-aPn1bQ=
Host: api.paydirekt.de
X-Date: Mon, 19 Jul 2021 17:03:17 GMT
{
"grantType" : "api_key",
"randomNonce" : "1QuLQIqtrSqcc5FLqi1Y6vanZdu1Wq5RMjK-W-Ih9UFkjaQyo6VlU--HQxHh4Hnf"
}
HTTP/1.1 401 Unauthorized
Content-Type: application/hal+json;charset=utf-8
Content-Length: 170
{
"messages" : [ {
"severity" : "ERROR",
"code" : "API_KEY_REQUEST_SIGNATURE_INVALID",
"logref" : "612a191c-9cf9-448a-a43c-f7d16420651b:6vDOC0c2H2q"
} ]
}
Resource Access
Mit dem gültigen Access Token kann nun auf die API zugegriffen werden, z. B. um einen neuen Checkout anzulegen oder abzufragen. Das paydirekt-System identifiziert den Aufrufer anhand dieses Tokens.
Der Access Token wird im Header-Feld Authorization
mit dem Prefix Bearer
angegeben (vgl. HTTP Header-Felder).
Der Access Token ist befristet gültig (vergleiche expires_in
) und
sollte aus Performance-Gründen für alle Anfragen im Rahmen dieser Gültigkeit genutzt werden.
Beispiel (Abgelaufener Access Token)
Kurz vor Ablauf dieser Zeit sollte ein neuer Access Token angefordert werden. Für den Fall, dass die Gültigkeit eines Access Token aufgrund der zeitlichen Begrenzung abgelaufen ist, liefert das paydirekt-System auf eine fachliche Anfrage hin den HTTP Status Code 401
mit dem Message Code ACCESS_TOKEN_EXPIRED
.
Das aufrufende System muss an dieser Stelle einen neuen Access Token beziehen und den Aufruf wiederholen.
Der Body der HTTP Response enthält neben der Message-Struktur auch die in [RFC-6749]
definierten Felder error
und error_description
.
GET /api/merchantintegration/v1/some-endpoint HTTP/1.1
Date: Mon Jul 19 19:03:16 CEST 2021
Authorization: Bearer J5rt_Y5xIXBmTPYP0kaas_AkIA_ACMP7ynf8OICVL8ridznpC0nJHVBwLbenePWesLxqQ6mc6h8ysdyFjMSLZyndzqBsixUhIesRAekNOF2o9W5BTaVshRiN3bPbsiG0yr-JHmDZVowlB2zqD2WLFV3yGzipvHfamMdPnR7EsMJMA02OJkGctR3464rMH4LVqvJKe7f62OzAZdxhhpzUKVPczcA8zF2aaKodsG1OquSBcJX7G6iVeg5I58JIRhKPQt4BVpl2tI6-E63bD2xHXVaAsGiMhZDg0ayDtbTNNOzvFJxmc4byLz5EzKGdctg6cM3t9E7KJOHEUWOktHLn0DNyixAtvKYBXAwFP71wckTJiThzey6s8_ZZ1ZHwAKWGUuHtPd7XbGTPDzIvQm8PKIKozgS6nXwFTGmodxDGA5v2mSSqieqRp6oQo8i_C4OBybBcDjrjJ8PgFPu_z6BgsatnIuAmoye7Xk2JPf1ISR46tQljy1CqsuCjsFL9nEhZaN_THHY-GM-iXUGzpkNtiz7fszBfozQ4312YNQaXTp939UwYIbW5LQBPh8h6fDyFaJt6eedyKEs9dtWM3ATrjDRXVYOXBNqdVV8HEZ6FngISNoQCkjCg-lz_UP4_v7Kv791ojDjmCB3EjgVKwCIP36RXCdirCPxEhOPkfXCee0ivyBfvvjyZ1UymCpf02Kk3gb073tpmzG_O1LZ8x0tfqcw1ar7SbTbiB88PcMu9fvFw1HYW-LD1Dp7-XiDJf1V76ewwDJoWw4h7eMFMBla9wcfQXBjB2lgz-EG3eBI7u6KaX37oCeMZJTkxUTHixYQ__3jAlR9RZ99ui0x-Btl3gxnNEPey94J8tofVW2DCEPuiz-of5TP-z425aY9FLE9x_XLtJKzGDWddvvmbezuYvDPatB3iI5cGqXicMlGnLT8v80ubYai81OAzLxDXF29eb2yvb3iut9r1f7NjvUR5Kp5TO7TZgFP1pk4dIG6BS58yaRvkLBvADldt6vebQSC6PThhwnbSOMLNer8GfW9oNijY6T6n4f7CooW5y1FGZpJz5RNq8B8yJ8hpTOmmbnw34UWX8phvIX4fExF3TtsRYC88mZhBZJP7YqOD80893rfEwpc47Ukz_QtwA5it08MGK8yzEIDfCUHsDkOTW1sy3TgrS19iP65QHep0lI8CZJU52q2Gcg84dZpOWKhZ95VuhcP9W-XoekZ0DS94fi3xBFwMINdBBGEuWyEdPfG2cp8lSmEU_YyrDjryKOcz3VFTo9gSGO5S3TqnQIaVRx3uBNtVB01ObJR43wgZlcPNmYA40d7ldxIKiq6c0p0DBRGnDM-TDjDH0jo6-6HNfut22Eh_lpBlgtbF2WzJP0ycSkb5q_pUp-6VU_uHGW-DCYo1vbRY9EBXdLs5wQW7jh7LAas9rV0i0ZuMPVxo_RDk5Okh9GYQVRVku6fvTbg21t1cC3WL7PX_88fO9nDnfmY4RLvLvR2Amym8EI8G0ODB0jLDnvQvUlw33YRzYQsZnMUnTqEEwLNn43lma-qEhYe1mLpAr3IWKiRuRxJBFt2u2DhKc-8veHA9v9s-Y8-0pqyLwYjnACd-3Ii4LWDGNQcs6GJCSy813IxbFIu3-bSAttL87BvonV5zI3mLDdSSkmEknv_W5u0C550yRHMVlqiULiKpqR4Ae24wlAvIP_X4H0P3VeCNN_cGeXOP2qiukYhYDxSi4N6hwbgx7wBw6ukQtEVS9tevHQ6DWvk3ykp1J8QF5FOVw0ObcLREXSmyj-U_t8AanplLmcZq8dgVpC-lR3QFaoo9MGiu-HCzrVzMQvM
Host: api.paydirekt.de
HTTP/1.1 401 Unauthorized
Content-Type: application/hal+json;charset=utf-8
Content-Length: 2034
{
"messages" : [ {
"severity" : "ERROR",
"code" : "ACCESS_TOKEN_EXPIRED",
"logref" : "2YIxkcrA6kV"
} ],
"error" : "invalid_token",
"error_description" : "Access token expired: J5rt_Y5xIXBmTPYP0kaas_AkIA_ACMP7ynf8OICVL8ridznpC0nJHVBwLbenePWesLxqQ6mc6h8ysdyFjMSLZyndzqBsixUhIesRAekNOF2o9W5BTaVshRiN3bPbsiG0yr-JHmDZVowlB2zqD2WLFV3yGzipvHfamMdPnR7EsMJMA02OJkGctR3464rMH4LVqvJKe7f62OzAZdxhhpzUKVPczcA8zF2aaKodsG1OquSBcJX7G6iVeg5I58JIRhKPQt4BVpl2tI6-E63bD2xHXVaAsGiMhZDg0ayDtbTNNOzvFJxmc4byLz5EzKGdctg6cM3t9E7KJOHEUWOktHLn0DNyixAtvKYBXAwFP71wckTJiThzey6s8_ZZ1ZHwAKWGUuHtPd7XbGTPDzIvQm8PKIKozgS6nXwFTGmodxDGA5v2mSSqieqRp6oQo8i_C4OBybBcDjrjJ8PgFPu_z6BgsatnIuAmoye7Xk2JPf1ISR46tQljy1CqsuCjsFL9nEhZaN_THHY-GM-iXUGzpkNtiz7fszBfozQ4312YNQaXTp939UwYIbW5LQBPh8h6fDyFaJt6eedyKEs9dtWM3ATrjDRXVYOXBNqdVV8HEZ6FngISNoQCkjCg-lz_UP4_v7Kv791ojDjmCB3EjgVKwCIP36RXCdirCPxEhOPkfXCee0ivyBfvvjyZ1UymCpf02Kk3gb073tpmzG_O1LZ8x0tfqcw1ar7SbTbiB88PcMu9fvFw1HYW-LD1Dp7-XiDJf1V76ewwDJoWw4h7eMFMBla9wcfQXBjB2lgz-EG3eBI7u6KaX37oCeMZJTkxUTHixYQ__3jAlR9RZ99ui0x-Btl3gxnNEPey94J8tofVW2DCEPuiz-of5TP-z425aY9FLE9x_XLtJKzGDWddvvmbezuYvDPatB3iI5cGqXicMlGnLT8v80ubYai81OAzLxDXF29eb2yvb3iut9r1f7NjvUR5Kp5TO7TZgFP1pk4dIG6BS58yaRvkLBvADldt6vebQSC6PThhwnbSOMLNer8GfW9oNijY6T6n4f7CooW5y1FGZpJz5RNq8B8yJ8hpTOmmbnw34UWX8phvIX4fExF3TtsRYC88mZhBZJP7YqOD80893rfEwpc47Ukz_QtwA5it08MGK8yzEIDfCUHsDkOTW1sy3TgrS19iP65QHep0lI8CZJU52q2Gcg84dZpOWKhZ95VuhcP9W-XoekZ0DS94fi3xBFwMINdBBGEuWyEdPfG2cp8lSmEU_YyrDjryKOcz3VFTo9gSGO5S3TqnQIaVRx3uBNtVB01ObJR43wgZlcPNmYA40d7ldxIKiq6c0p0DBRGnDM-TDjDH0jo6-6HNfut22Eh_lpBlgtbF2WzJP0ycSkb5q_pUp-6VU_uHGW-DCYo1vbRY9EBXdLs5wQW7jh7LAas9rV0i0ZuMPVxo_RDk5Okh9GYQVRVku6fvTbg21t1cC3WL7PX_88fO9nDnfmY4RLvLvR2Amym8EI8G0ODB0jLDnvQvUlw33YRzYQsZnMUnTqEEwLNn43lma-qEhYe1mLpAr3IWKiRuRxJBFt2u2DhKc-8veHA9v9s-Y8-0pqyLwYjnACd-3Ii4LWDGNQcs6GJCSy813IxbFIu3-bSAttL87BvonV5zI3mLDdSSkmEknv_W5u0C550yRHMVlqiULiKpqR4Ae24wlAvIP_X4H0P3VeCNN_cGeXOP2qiukYhYDxSi4N6hwbgx7wBw6ukQtEVS9tevHQ6DWvk3ykp1J8QF5FOVw0ObcLREXSmyj-U_t8AanplLmcZq8dgVpC-lR3QFaoo9MGiu-HCzrVzMQvM"
}
Authentifizierung als Collecting PSP
Das paydirekt-System ermöglicht es Collecting Payment Service Providern (CPSPs) Anfragen für vom CPSP verwaltete Händler-Shops zu tätigen, beispielsweise zur Anlage von Checkouts. Zusätzlich können CPSPs ihre Transaktionsreports per API abrufen.
Die paydirekt-API für CPSPs unterscheidet sich von der konventionellen PSP-API derzeit nur in dem nachfolgend beschriebenen Authentifizierungsprozess für CPSPs.
Im Gegensatz zu einem PSP benötigt ein CPSP keinen API-Key und kein API-Secret für einen Händler-Shop.
Stattdessen übergibt er dem paydirekt-System bei der Authenifizierung ein Indentifikationsmerkmal des Händler-Shops, für den er eine Anfrage tätigen will.
Dieser Händler-Shop muss ein Shop eines Händlers sein, der von dem CPSP verwaltet wird.
Das Identifikationsmerkmal für diesen Shop, die sogenannte merchantAuthorizationReference
, kann der CPSP im Intermediärportal abrufen.
Zur Authentifizierung eines CPSPs wird wie bei PSPs ein API-Key-Verfahren in Verbindung mit OAuth2 verwendet.
Der CPSP muss dazu einen seiner eigenen API-Keys, das zugehörige API-Secret, sowie eine merchantAuthorizationReference
besitzen.
Seine eigenen API-Keys und -Secrets kann sich der CPSP im Intermediärportal erstellen lassen.
Interaktionen mit dem paydirekt-System verlaufen für CPSPs immer in zwei Schritten.
-
Zunächst lässt sich der CPSP für seinen API-Key und eine
merchantAuthorizationReference
ein zeitlich auf wenige Minuten befristetes Access Token ausstellen. -
In allen folgenden Requests (beispielsweise der Anlage eines neuen Checkouts) authentifiziert sich der CPSP für sich und für einen bestimmten Shop über die Vorlage dieses Access Token.
Für Report-Abfragen darf bei der Ausstellung des Access Token ausschließlich der API-Key und API-Secret des CPSPs zur Generierung des Access Tokens übermittelt werden.
Eine merchantAuthorizationReference
ist in diesem Fall nicht zulässig.
Begriffsdefinition
- API-Key
-
Der API-Key dient der Identifikation eines CPSPs. Ein API-Key kann im Intermediärportal jederzeit erzeugt und deaktiviert werden. Es können mehrere API-Keys gleichzeitig gültig sein. Auf der Sandbox sind die ersten 8 Stellen neu erstellter API-Keys immer "00000000".
Ein API-Key wird vom paydirekt-System generiert und hat folgendes Format:
Länge: 36 Zeichen
Kodierung: UUID Type 4 Random [RFC 4122]
Beispiel:87dbc6cd-91d2-4574-bcb5-2aaaf924386d
Beispiel auf der Sandbox:00000000-91d2-4574-bcb5-2aaaf924386d
- API-Secret
-
Das API-Secret dient der Authentifizierung des CPSPs. Es wird verwendet, um eine Signatur (Auth-Code) der Authentifizierungsanfrage zu erzeugen. Das API-Secret selbst wird in der Kommunikation so niemals übertragen, wodurch die Sicherheit deutlich erhöht wird. Ein API-Secret ist genau einem API-Key zugeordnet und wird zusammen mit diesem verwaltet.
Ein API-Secret wird vom paydirekt-System generiert und hat folgendes Format:
Länge: 44 Zeichen
Kodierung: Base64 URL Encoding [RFC 4648 Section 5] mit Base64 Padding
Beispiel:9Tth0qty_9zplTyY0d_QbHYvKM4iSngjoipWO6VxAao=
- merchantAuthorizationReference
-
Die
merchantAuthorizationReference
dient als Identifikationsmerkmal für einen vom CPSP verwalteten Händler-Shop. Sie wird bei der Anfrage eines Access Tokens übermittelt. Das ausgestellte Access Token bestitzt dadurch die Rechte des referenzierten Händler-Shops. DiemerchantAuthorizationReference
wird vom paydirekt-System generiert, kann im Intermediärportal für die Händler-Shops des CPSP abgerufen werden und besitzt das folgende Format:Länge: 44 Zeichen
Kodierung: Base64 URL Encoding [RFC 4648 Section 5] mit Base64 Padding
Beispiel:P_piZRwAxsaGBiXQ6gz0d2sC0dkAAIpLZhdwca-XppY=
- Access Token
-
Für alle Requests gegen die paydirekt-API ist ein OAuth2 Access Token [RFC 6749 1.4] erforderlich. In diesem sind die Authentifizierungsinformationen des Aufrufers gespeichert. Ein Access Token wird durch Aufruf des Access Token-Endpoints durch Angabe des Grant Type
api_key
erzeugt und wird bei allen folgenden Requests im Request HeaderAuthorization
alsBearer
angegeben:Authorization: Bearer <accessToken>
Der Access Token hat eine begrenzte Gültigkeitsdauer von einer Stunde. Nach Ablauf der Gültigkeit kann einfach ein neuer Access Token bezogen werden. Die Gültigkeitsdauer wird im Response des Access Token zurückgeliefert.
Bei Bedarf kann das aufrufende System mehrere Access Tokens gleichzeitig verwenden. Besteht das aufrufende System aus mehreren Knoten, so kann jeder Knoten für seine Anfragen einen eigenen Access Token verwenden. Es ist aus Performance-Gründen jedoch nicht gestattet, für jeden einzelnen Request einen neuen Access Token anzufordern.
- Grant Type
-
Der Grant Type definiert die Methode, wie sich ein Benutzer oder ein System gegenüber dem paydirekt-System authentifiziert. Für die REST-API wird der Grant Type
api_key
verwendet.
Signatur (Auth-Code)
Die Signatur (Auth-Code) bestätigt, dass der CPSP im Besitz des API-Secrets ist und gültige Anfragen an das paydirekt-System senden darf.
Die Signatur wird aus einem String-to-Sign und einem API-Secret erzeugt. In ersteres fließen folgende Werte in der hier angegebenen Reihenfolge ein:
Nr. | Wert | Quelle | Format | Beispiel |
---|---|---|---|---|
1. |
Request-ID |
Request Header |
UUID Type 4 Random [RFC 4122] |
ec85749b-aa36-412a-a397-2b40200c119c |
2. |
Datum |
Request Header |
yyyyMMddHHmmss |
20141231235859 |
3. |
API-Key |
Request Header |
UUID Type 4 Random [RFC 4122] |
4c15310a-7936-4a19-8d80-f2b7bd95dc9b |
4. |
Random Nonce |
Request Body-Feld |
Base64 URL Encoding [RFC 4648 Section 5] |
Ns0WLCI3qA2AMH98wUYyhqALyVlzS0q7n Hh7NdeMyvUgKJoyF0rNXkgq5fq2VNJs |
Die Random Nonce muss pro Anfrage durch das aufrufende System per Zufallsgenerator neu generiert werden; sie fließt in
die Signatur mit ein und wird im Request Body-Feld randomNonce
an das paydirekt-System übertragen.
Aus den oben angegebenen Werten wird zunächst der sogenannte String-to-Sign gebildet.
Dazu werden die Werte in der angegebenen Reihenfolge unter Trennung mittels des Trennzeichens :
zu einer Zeichenkette verbunden (String Konkatenation).
Das Trennzeichen wird nur eingefügt, sofern ein weiterer Wert folgt. Keiner der Werte darf fehlen oder als null kodiert werden.
Format-Beispiel für einen String-to-Sign Z
:
Z = ec85749b-aa36-412a-a397-2b40200c119c:20141231235859:4c15310a-7936-4a19-8d80-f2b7bd95dc9b:Ns0WLCI3qA2AMH98wUYyhqALyVlzS0q7nHh7NdeMyvUgKJoyF0rNXkgq5fq2VNJs
Auf Basis eines String-to-Sign Z
zu einem Request R
sowie des API-Secrets S
wird die Signatur der Anfrage
mittels der Funktion HMAC-SHA-256 [RFC 2104] gebildet:
Signatur(Request) = new String(encodeBase64URLCompatible(HMAC-SHA-256(getBytes(Z, "UTF-8"), decodeBase64URLCompatible(getBytes(S, "UTF-8")))), "UTF-8")
Die Signatur wird per Base64 URL Encoding [RFC 4648 Section 5] kodiert. Die problematischen Zeichen + und / werden durch - (Minus) und _ (Unterstrich) ersetzt.
|
Diese Signatur wird im Request Header X-Auth-Code
oder X-Auth-Code-PSP
angegeben.
Im Vergleich zu Basic Auth oder einer reinen Hash-Signatur bietet das API-Key Verfahren auf Basis von HMAC einen wesentlich höheren Grad der Sicherheit, da die Signatur nicht gefälscht oder wiederverwendet werden kann und das Geheimnis in der Kommunikation niemals übertragen wird.
Access Token
POST /api/merchantintegration/v1/token/obtain
Über diesen Endpoint wird, wie oben beschrieben, ein Access Token ausgestellt.
Findet eine Authentifizierung von CPSPs inklusive Shop statt, sind alle drei Felder X-Auth-Key-TP
, X-Auth-Code-TP
und X-Auth-Merchant-Ref
zu übergeben.
Bei einer Authentifizierung eines CPSPs ohne Shop sind nur die Felder X-Auth-Key-TP
und X-Auth-Code-TP
zu übergeben;
siehe Erläuterungen unter Authentifizierung als Collecting PSP.
Request
Feld | Typ | Eigenschaften | Beschreibung |
---|---|---|---|
Header-Felder |
|||
|
String |
Pflichtfeld. 36 Zeichen. |
API-Key des CPSPs. |
|
String |
Pflichtfeld. Maximal 44 Zeichen. |
Signatur (Auth-Code) der Anfrage |
|
String |
Optional. 44 Zeichen. |
Identifikationsmerkmal für einen Händler-Shop. |
|
String |
Pflichtfeld. 36 Zeichen. |
Zufällig erzeugte UUID der Anfrage |
|
String |
Pflichtfeld. |
Datum und Zeit zum Sendezeitpunkt der Anfrage |
|
String |
Pflichtfeld. |
Immer |
Body-Felder |
|||
|
String |
Pflichtfeld. |
Immer |
|
String |
Pflichtfeld. 64 Zeichen. |
Zufällige Zeichenkette zur Diversifizierung der Request Body Inhalte |
Response
Feld |
Typ |
Eigenschaften |
Beschreibung |
|
String |
Immer vorhanden. |
OAuth2 Access Token für Anfragen gegen die paydirekt-API. Die Länge des Tokens ist abhängig von den in ihm codierten Datenfeldern und eine Maximallänge ist nicht vorgesehen. Sie soll deshalb bei der Implementierung des Clients nicht limitiert werden. |
|
String |
Immer vorhanden. |
Immer |
|
Number |
Immer vorhanden. |
Gültigkeitsdauer des Access Tokens in Sekunden zur Information. |
|
String |
Immer vorhanden. |
Gültigkeitsbereich des Access Tokens zur Information. |
|
String |
Immer vorhanden. |
UUID aus 36 Zeichen zur eindeutigen Identifikation des Tokens. |
|
String |
Immer vorhanden. |
JSON Web Token ID des Access Tokens zu Debugging Zwecken. |
Return Codes
Status Code | Message Code | Beschreibung |
---|---|---|
200 (Ok) |
Access Token wurde erfolgreich erstellt. |
|
400 (Bad Request) |
INVALID_GRANT |
|
401 (Unauthorized) |
API_KEY_IN_REQUEST_UNKNOWN |
Der API-Key ist im paydirekt-System nicht hinterlegt. |
401 (Unauthorized) |
API_KEY_REQUEST_HEADER_INVALID |
Die Anfrage enthält mehr als einen |
401 (Unauthorized) |
API_KEY_IN_REQUEST_INACTIVE |
Der API-Key ist deaktiviert. |
401 (Unauthorized) |
API_KEY_REQUEST_SIGNATURE_INVALID |
Der |
403 (Forbidden) |
THIRD_PARTY_API_LOCKED |
Der Zugang zur API ist für Sie gesperrt, bitte wenden Sie sich an den paydirekt-Händlersupport. |
403 (Forbidden) |
AUTHORIZATION_INVALID |
Die übergebene |
404 (Not found) |
THIRD_PARTY_AUTHORIZATION_NOT_FOUND |
Die |
Beispiel
POST /api/merchantintegration/v1/token/obtain HTTP/1.1
Date: Mon Jan 23 13:06:19 CET 2017
X-Request-ID: 1e2c7830-e001-4eb3-a705-38efacf3cd01
Accept: application/hal+json
Content-Type: application/hal+json;charset=utf-8
X-Auth-Key-TP: ee3f9f0e-17fd-4ff3-bebc-3a16a867fd98
X-Auth-Code-TP: AYLRvNW-zp2Z9RVF6KYYezN9DMHI5Wo8rcQdT02TOMg=
X-Auth-Merchant-Ref: P_piZRwAxsaGBiXQ6gz0d2sC0dkAAIpLZhdwca-XppY=
Host: api.paydirekt.de
Content-Length: 115
{
"grantType" : "api_key",
"randomNonce" : "0Lt5zqnh4w3IR1w1crv3jsg5UuZcpBc7kPzJ25KNATYN8CCfp0EZ0mtrLBPZz7Cb"
}
HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=utf-8
Content-Length: 1344
{
"access_token" : "w8d2D2wdoO7CnFrBXAZCIYivneVnUv-uI0kwcfa_1LtS7-ysX3QgeVv2qVGm1Ktz1eDwOQTFFBB6HIr0Mcw656VqwGF0ossAz32jbB-koJaZr_ibCQNxV18kjoCvESTyKrJnI2p8a0D8SPrgYXD-g4likvP0OvCJh0bUvQyFU8ndY2H_o5L-8Kk0i3Gt4GDADb2toHOOyR2d1EKaT-4ON021RZf4_PTe9T2i1qJw4lwsls4GMqgLNyhTd8Y6_kPlMHHefavxzX2jCCyORmwGYD1H8UtVrIuAHpXSNJFIBiAnMJTwxuAUIjZiPB8masXkoF0vib6NINu3ABvqV4VQADVX_PZsDR_cxlma74ovmMgxnwE-QPNzG1zf8zR7kgCmJ4FjB4JyoqO9_XwFDNN23jiKC3CnAnqmnIS_nQB9F52OGyy_6PqmFNMZYIFjI9FxtwrWoa7N_AQuZtub2Bbfh85545Jdd0TX_VeAmqCN1cu5QZF8PwHYacbrdGVSR3XkywIX8KiXRPi2736YnmozGKsHfpqTLGGz-ZFpAjyV5VCjsWDM1YH9TWXUy0cUCTwqonHf3hptfWwJect2S5cn_2nC32LflJUDxWpnU-7BAzIf_qWjC6nqDg9zvmrdRmd1OxfxgGHre1Fc461eIipqemDq7el6YnDTfskuOA6n6KJAMZqwkYEHAK-tb00uEpPASQyjYY5NBIhAAH8YHloDuwednjn3yGnBqr3Gg6RijxZxJL5cF08jqQ_Ihe2ythPfslaXC6_qo16RAL93B6ydHBPGK0PzpEVRk6IKmY_H_yex7GnPYhJbYnxMQcwHkABE-uEe7WGXklOQEkALUgtNrCkllD3Li3Y_Rl6St4SWGIShfkA8PhbGrgVZ7UId-Qy5egsMVtJMVfZi9ltmR38obxg16IQcye3_KOfqi_zDQY7T6j_H2U3C_VYB1KwWLaTyATg5DDd57CmzRvMT_CL_xwjXbP-E26I_xVYl5hMrvw6SR6uVTSAiWlWEOOIJ6W3UDWDdR-IU4vnEbqjA7IkJdVMrXw0C10j-he367DoWdswHzecbuTsp_ncGvtVmpNwdbxzEO8F82TR7DSh4LqXWlbpo36rNKdWOVCDiMpB2b2A9jy8ZzXNZ-kIcvXTAnrAWYNZpuVY311PMVyDRv2Y6w8",
"token_type" : "bearer",
"expires_in" : 3599,
"scope" : "checkout reporting intermediary",
"jti" : "842f0703-db73-4132-ac8e-005103f07d8a"
}
Beispiel (Falscher Auth-Code)
POST /api/merchantintegration/v1/token/obtain HTTP/1.1
X-Request-ID: 2346b3bd-174d-41d3-a82a-1730dabb1592
Content-Type: application/json;charset=utf-8
X-Auth-Key-TP: 96a57c6a-ae4e-4c96-9952-2bf830d42031
X-Auth-Code-TP: 2KXQl8oSV-m1hUWUhDGmYV8HtTXXTRcyXz3SdZGOQlw=
X-Auth-Merchant-Ref: P_piZRwAxsaGBiXQ6gz0d2sC0dkAAIpLZhdwca-XppY=
Host: api.paydirekt.de
Content-Length: 115
X-Date: Mon, 23 Jan 2017 12:06:20 GMT
{
"grantType" : "api_key",
"randomNonce" : "KVGQy-bAtKTFhNesYLzFIyUHK_iUA7Qlfw0z7YzFUMqrE3_PB8cOOrlNPScY8S_N"
}
HTTP/1.1 401 Unauthorized
Content-Type: application/json;charset=UTF-8
Content-Length: 170
{
"messages" : [ {
"severity" : "ERROR",
"code" : "API_KEY_REQUEST_SIGNATURE_INVALID",
"logref" : "2346b3bd-174d-41d3-a82a-1730dabb1592:9eLz9fnG9ok"
} ]
}
Resource Access
Mit dem gültigen Access Token kann nun auf die API zugegriffen werden, z. B. um einen neuen Checkout anzulegen oder abzufragen. Das paydirekt-System identifiziert den Aufrufer anhand dieses Tokens.
Der Access Token wird im Header-Feld Authorization
mit dem Prefix Bearer
angegeben (vgl. HTTP Header-Felder).
Der Access Token ist befristet gültig (vergleiche expires_in
) und
sollte aus Performance-Gründen für alle Anfragen im Rahmen dieser Gültigkeit genutzt werden.
Beispiel (Abgelaufener Access Token)
Kurz vor Ablauf dieser Zeit sollte ein neuer Access Token angefordert werden. Für den Fall, dass die Gültigkeit eines Access Token aufgrund der zeitlichen Begrenzung abgelaufen ist, liefert das paydirekt-System auf eine fachliche Anfrage hin den HTTP Status Code 401
mit dem Message Code ACCESS_TOKEN_EXPIRED
.
Das aufrufende System muss an dieser Stelle einen neuen Access Token beziehen und den Aufruf wiederholen.
Der Body der HTTP Response enthält neben der Message-Struktur auch die in [RFC-6749]
definierten Felder error
und error_description
.
GET /api/merchantintegration/v1/some-endpoint HTTP/1.1
Date: Mon Jul 19 19:03:16 CEST 2021
Authorization: Bearer J5rt_Y5xIXBmTPYP0kaas_AkIA_ACMP7ynf8OICVL8ridznpC0nJHVBwLbenePWesLxqQ6mc6h8ysdyFjMSLZyndzqBsixUhIesRAekNOF2o9W5BTaVshRiN3bPbsiG0yr-JHmDZVowlB2zqD2WLFV3yGzipvHfamMdPnR7EsMJMA02OJkGctR3464rMH4LVqvJKe7f62OzAZdxhhpzUKVPczcA8zF2aaKodsG1OquSBcJX7G6iVeg5I58JIRhKPQt4BVpl2tI6-E63bD2xHXVaAsGiMhZDg0ayDtbTNNOzvFJxmc4byLz5EzKGdctg6cM3t9E7KJOHEUWOktHLn0DNyixAtvKYBXAwFP71wckTJiThzey6s8_ZZ1ZHwAKWGUuHtPd7XbGTPDzIvQm8PKIKozgS6nXwFTGmodxDGA5v2mSSqieqRp6oQo8i_C4OBybBcDjrjJ8PgFPu_z6BgsatnIuAmoye7Xk2JPf1ISR46tQljy1CqsuCjsFL9nEhZaN_THHY-GM-iXUGzpkNtiz7fszBfozQ4312YNQaXTp939UwYIbW5LQBPh8h6fDyFaJt6eedyKEs9dtWM3ATrjDRXVYOXBNqdVV8HEZ6FngISNoQCkjCg-lz_UP4_v7Kv791ojDjmCB3EjgVKwCIP36RXCdirCPxEhOPkfXCee0ivyBfvvjyZ1UymCpf02Kk3gb073tpmzG_O1LZ8x0tfqcw1ar7SbTbiB88PcMu9fvFw1HYW-LD1Dp7-XiDJf1V76ewwDJoWw4h7eMFMBla9wcfQXBjB2lgz-EG3eBI7u6KaX37oCeMZJTkxUTHixYQ__3jAlR9RZ99ui0x-Btl3gxnNEPey94J8tofVW2DCEPuiz-of5TP-z425aY9FLE9x_XLtJKzGDWddvvmbezuYvDPatB3iI5cGqXicMlGnLT8v80ubYai81OAzLxDXF29eb2yvb3iut9r1f7NjvUR5Kp5TO7TZgFP1pk4dIG6BS58yaRvkLBvADldt6vebQSC6PThhwnbSOMLNer8GfW9oNijY6T6n4f7CooW5y1FGZpJz5RNq8B8yJ8hpTOmmbnw34UWX8phvIX4fExF3TtsRYC88mZhBZJP7YqOD80893rfEwpc47Ukz_QtwA5it08MGK8yzEIDfCUHsDkOTW1sy3TgrS19iP65QHep0lI8CZJU52q2Gcg84dZpOWKhZ95VuhcP9W-XoekZ0DS94fi3xBFwMINdBBGEuWyEdPfG2cp8lSmEU_YyrDjryKOcz3VFTo9gSGO5S3TqnQIaVRx3uBNtVB01ObJR43wgZlcPNmYA40d7ldxIKiq6c0p0DBRGnDM-TDjDH0jo6-6HNfut22Eh_lpBlgtbF2WzJP0ycSkb5q_pUp-6VU_uHGW-DCYo1vbRY9EBXdLs5wQW7jh7LAas9rV0i0ZuMPVxo_RDk5Okh9GYQVRVku6fvTbg21t1cC3WL7PX_88fO9nDnfmY4RLvLvR2Amym8EI8G0ODB0jLDnvQvUlw33YRzYQsZnMUnTqEEwLNn43lma-qEhYe1mLpAr3IWKiRuRxJBFt2u2DhKc-8veHA9v9s-Y8-0pqyLwYjnACd-3Ii4LWDGNQcs6GJCSy813IxbFIu3-bSAttL87BvonV5zI3mLDdSSkmEknv_W5u0C550yRHMVlqiULiKpqR4Ae24wlAvIP_X4H0P3VeCNN_cGeXOP2qiukYhYDxSi4N6hwbgx7wBw6ukQtEVS9tevHQ6DWvk3ykp1J8QF5FOVw0ObcLREXSmyj-U_t8AanplLmcZq8dgVpC-lR3QFaoo9MGiu-HCzrVzMQvM
Host: api.paydirekt.de
HTTP/1.1 401 Unauthorized
Content-Type: application/hal+json;charset=utf-8
Content-Length: 2034
{
"messages" : [ {
"severity" : "ERROR",
"code" : "ACCESS_TOKEN_EXPIRED",
"logref" : "2YIxkcrA6kV"
} ],
"error" : "invalid_token",
"error_description" : "Access token expired: J5rt_Y5xIXBmTPYP0kaas_AkIA_ACMP7ynf8OICVL8ridznpC0nJHVBwLbenePWesLxqQ6mc6h8ysdyFjMSLZyndzqBsixUhIesRAekNOF2o9W5BTaVshRiN3bPbsiG0yr-JHmDZVowlB2zqD2WLFV3yGzipvHfamMdPnR7EsMJMA02OJkGctR3464rMH4LVqvJKe7f62OzAZdxhhpzUKVPczcA8zF2aaKodsG1OquSBcJX7G6iVeg5I58JIRhKPQt4BVpl2tI6-E63bD2xHXVaAsGiMhZDg0ayDtbTNNOzvFJxmc4byLz5EzKGdctg6cM3t9E7KJOHEUWOktHLn0DNyixAtvKYBXAwFP71wckTJiThzey6s8_ZZ1ZHwAKWGUuHtPd7XbGTPDzIvQm8PKIKozgS6nXwFTGmodxDGA5v2mSSqieqRp6oQo8i_C4OBybBcDjrjJ8PgFPu_z6BgsatnIuAmoye7Xk2JPf1ISR46tQljy1CqsuCjsFL9nEhZaN_THHY-GM-iXUGzpkNtiz7fszBfozQ4312YNQaXTp939UwYIbW5LQBPh8h6fDyFaJt6eedyKEs9dtWM3ATrjDRXVYOXBNqdVV8HEZ6FngISNoQCkjCg-lz_UP4_v7Kv791ojDjmCB3EjgVKwCIP36RXCdirCPxEhOPkfXCee0ivyBfvvjyZ1UymCpf02Kk3gb073tpmzG_O1LZ8x0tfqcw1ar7SbTbiB88PcMu9fvFw1HYW-LD1Dp7-XiDJf1V76ewwDJoWw4h7eMFMBla9wcfQXBjB2lgz-EG3eBI7u6KaX37oCeMZJTkxUTHixYQ__3jAlR9RZ99ui0x-Btl3gxnNEPey94J8tofVW2DCEPuiz-of5TP-z425aY9FLE9x_XLtJKzGDWddvvmbezuYvDPatB3iI5cGqXicMlGnLT8v80ubYai81OAzLxDXF29eb2yvb3iut9r1f7NjvUR5Kp5TO7TZgFP1pk4dIG6BS58yaRvkLBvADldt6vebQSC6PThhwnbSOMLNer8GfW9oNijY6T6n4f7CooW5y1FGZpJz5RNq8B8yJ8hpTOmmbnw34UWX8phvIX4fExF3TtsRYC88mZhBZJP7YqOD80893rfEwpc47Ukz_QtwA5it08MGK8yzEIDfCUHsDkOTW1sy3TgrS19iP65QHep0lI8CZJU52q2Gcg84dZpOWKhZ95VuhcP9W-XoekZ0DS94fi3xBFwMINdBBGEuWyEdPfG2cp8lSmEU_YyrDjryKOcz3VFTo9gSGO5S3TqnQIaVRx3uBNtVB01ObJR43wgZlcPNmYA40d7ldxIKiq6c0p0DBRGnDM-TDjDH0jo6-6HNfut22Eh_lpBlgtbF2WzJP0ycSkb5q_pUp-6VU_uHGW-DCYo1vbRY9EBXdLs5wQW7jh7LAas9rV0i0ZuMPVxo_RDk5Okh9GYQVRVku6fvTbg21t1cC3WL7PX_88fO9nDnfmY4RLvLvR2Amym8EI8G0ODB0jLDnvQvUlw33YRzYQsZnMUnTqEEwLNn43lma-qEhYe1mLpAr3IWKiRuRxJBFt2u2DhKc-8veHA9v9s-Y8-0pqyLwYjnACd-3Ii4LWDGNQcs6GJCSy813IxbFIu3-bSAttL87BvonV5zI3mLDdSSkmEknv_W5u0C550yRHMVlqiULiKpqR4Ae24wlAvIP_X4H0P3VeCNN_cGeXOP2qiukYhYDxSi4N6hwbgx7wBw6ukQtEVS9tevHQ6DWvk3ykp1J8QF5FOVw0ObcLREXSmyj-U_t8AanplLmcZq8dgVpC-lR3QFaoo9MGiu-HCzrVzMQvM"
}
Checkout
Ein Checkout repräsentiert den gesamten Zahlungsvorgang. In den folgenden Kapiteln wird beschrieben, wie Checkouts angelegt werden und wie die zu einem Zahlungsvorgang hinterlegten Daten abgefragt werden können. Hier wird zwischen den Typen Einmalzahlung und Vorbestellung unterschieden.
Anlage
POST /api/checkout/v1/checkouts
Neben dem Authentifizierungsendpoint ist dies der einzige Endpoint, der im Webshop fest hinterlegt werden muss. Alle weiteren Ressourcen können über entsprechende Links angesprochen werden.
Overcapture und gesicherte Vorbestellung müssen explizit für Ihren Händleraccount freigeschaltet werden. Bitte wenden Sie sich hierzu an haendler@paydirekt.de. |
Request
Feld | Typ | Eigenschaften | Beschreibung |
---|---|---|---|
|
String |
Pflichtfeld. |
Die Art der Bestellung: |
|
Number |
Pflichtfeld. |
Der Gesamtbetrag der Bestellung, inkl. aller Lieferkosten. Es werden maximal 2 Nachkommastellen unterstützt. |
|
Number |
Optional. Mindestens 0.00. |
Die Versandkosten der Bestellung. Dieser Wert wird nicht für Berechnungen verwendet, sondern dient nur zur Information. |
|
Number |
Optional. |
Der Warenwert der Bestellung, ohne Versandkosten. Dieser Wert wird nicht für Berechnungen verwendet, sondern dient nur zur Information. |
|
Number |
Optional. |
Maximal zurückzahlbarer Betrag als Prozentwert des Gesamtwertes der Bestellung. |
|
Boolean |
Optional. |
Flag für Overcapture-Checkouts. |
|
String |
Pflichtfeld. |
Die Währung des Gesamtbetrags. Derzeit wird nur EUR unterstützt. |
|
Array von Items |
Optional. |
Die einzelnen Positionen des Warenkorbs. |
|
String |
Optional. |
Kategorisiert den Warenkorb eines Checkouts anhand der Eigenschaften der enthaltenen Güter: Der Standardwert ist |
|
String |
Optional. |
Der Bestimmungsort einer Lieferung: |
|
Optional bei AUTHORITIES_PAYMENT und ANONYMOUS_DONATION Warenkörben. Sonst Pflichtfeld. Darf bei Expresscheckoutanlage nicht enthalten sein. |
Die Lieferanschrift des Empfängers. Diese Adresse wird dem Kunden nach dem Login im paydirekt-System zur Kontrolle angezeigt. |
|
|
String |
Optional. |
Händler-interne Kundennummer des Käufers. Wird dem Kunden in der Transaktionsübersicht angezeigt. Wird dem Händler in der Transaktionsübersicht angezeigt. |
|
String |
Pflichtfeld. |
Händler-interne, eindeutige Bestellnummer für diesen Kaufvorgang. Wird dem Kunden in der Transaktionsübersicht angezeigt. Wird dem Händler in der Transaktionsübersicht angezeigt. Die Bestellnummer wird in der Händler-Lastschrift als |
|
String |
Optional. |
Händler-interne, eindeutige Rechnungsnummer für diesen Kauf- bzw. Zahlvorgang. Wird dem Händler in der Transaktionsübersicht angezeigt. |
|
String |
Optional. |
Reconciliation-Nummer. Diese wird bei Direct-Sales in den Verwendungszweck der Händlerzahlung eingefügt. Bei Vorbestellungen wird stattdessen die bei Anlage der Captures gesetzte |
|
String |
Optional. |
Die E-Mail Adresse des Käufers als Base-64 encodierter SHA-256 Hash-Wert ohne Padding, sofern vorhanden. Pseudo-Code: |
|
String |
Pflichtfeld, außer bei oneKlick-Checkouts. |
Die Rücksprung-Adresse des Webshops (inkl. Referenz auf die Bestellung), die nach erfolgreicher Bezahlung aufgerufen wird. |
|
String |
Pflichtfeld, außer bei oneKlick-Checkouts. |
Die Rücksprung-Adresse des Webshops (inkl. Referenz auf die Bestellung), die im Falle eines Abbruchs oder technischen Fehlers aufgerufen wird. Damit wird signalisiert, dass der Kaufvorgang grundsätzlich fortgeführt werden kann und im Anschluss ein weiterer, neuer Checkout initiiert werden kann, beispielsweise, weil der Kunde noch einen Artikel in der Bestellung hinzufügen möchte. |
|
String |
Pflichtfeld, außer bei oneKlick-Checkouts. |
Die Rücksprung-Adresse des Webshops (inkl. Referenz auf die Bestellung), die im Falle einer Abweisung der Zahlung aufgerufen wird. Damit wird signalisiert, dass keine Zahlung autorisiert wurde (z. B. aufgrund falscher TAN-Eingabe, fehlender Bank-Autorisierung oder Betrugsverdacht). Falls das Webshop-System keine Unterscheidung zwischen redirectUrlAfterCancellation und redirectUrlAfterRejection unterstützt, kann in beiden Feldern die gleiche URL angegeben werden. |
|
String |
Optional. |
URL des Endpoints, der Mitteilungen zu Statusänderungen des Checkouts empfangen soll. |
|
Number |
Optional. |
Das Mindestalter (in Jahren), das der Käufer erreicht haben muss, um die Bestellung ausführen zu dürfen, beispielsweise, weil sie Artikel enthält, die einer Altersbeschränkung unterliegen (Filme, Computerspiele, …). Die Prüfung erfolgt direkt nach dem Login des Käufers in das paydirekt-System. Bei erfolgreicher Verifikation wird der Ablauf ohne weitere Meldung wie gewohnt fortgesetzt. Bei nicht-erfolgreicher Verifikation, d. h. der Kunde hat das erforderliche Mindestalter noch nicht erreicht, erfolgt eine Umleitung auf den Link |
|
String |
Pflichtfeld, wenn |
Die Rücksprung-Adresse des Webshops (inkl. Referenz auf die Bestellung), die im Falle einer nicht erfolgreichen Altersverifikation aufgerufen wird. Damit wird signalisiert, dass die Bestellung abgebrochen wurde, da der Käufer das erforderliche Mindestalter für mindestens einen Artikel in der Bestellung noch nicht erreicht hat. Dieses Feld wird im Falle einer geforderten Altersverifikation, d. h. bei Angabe des Feldes |
|
String |
Optional. |
Freitextfeld, das auf dem Kontoauszug im Feld Verwendungzweck erscheint (nur |
|
Number |
Optional. |
Zahl, die die Gültigkeit des Checkouts ab Anlage in Sekunden angibt. Bei Nicht-Angabe werden 1800 Sekunden angenommen. |
|
Object |
Optional. |
Enthält Informationen über die Lieferung. |
|
String |
Optional. |
Erwartetes Versanddatum. |
|
String |
Optional. |
Paket-Dienstleister. |
|
String |
Optional. |
Sendungsnummer. |
|
String |
Optional. |
Gewünschter Garantiezeitraum (maximal 15 Kalendertage) für eine gesicherte Vorbestellung (ORDER_SECURED). |
Response
In der Response wird der angelegte Checkout zurückgegeben. Die Struktur ist identisch mit dem Checkout Endpoint GET-Aufruf.
Im HTTP Header-Feld Location
ist die URL der angelegten Checkout-Ressource, inkl.
Checkout-ID enthalten. Die Checkout-ID wird im Response Body ebenfalls zurückgegeben.
Links
Relation | Description |
---|---|
|
Link zu dieser Ressource. |
|
Link zur paydirekt-Webseite, zu dem der Käufer per HTTP Code 302 weitergeleitet werden muss, um die Zahlung zu bestätigen. Die Weiterleitung darf nicht über ein HTML Formular (unter Nutzung des |
|
Link zum Update der Lieferinformation. Dieser Link ist nur vorhanden, wenn die Update Frist für diesen Checkout noch nicht überschritten ist. |
|
Link zum Update der Rechnungsreferenznummer. Dieser Link ist nur vorhanden, wenn die Update Frist für diesen Checkout noch nicht überschritten ist. |
Der approve
-Link gibt an, zu welcher Seite der Benutzer via HTTP
Redirect (302) weitergeleitet werden muss, um die Zahlung zu bestätigen.
Return Codes
Status Code | Message Code | Beschreibung |
---|---|---|
201 (Created) |
Der Checkout wurde angelegt. Anschließend muss ein Redirect auf den in der Resource hinterlegten Link approve durchgeführt werden. |
|
400 (Bad Request) |
|
Der Request ist syntaktisch ungültig. |
400 (Bad Request) |
|
Der Request enthält ungültige Zeichen. Häufigste Ursache hierfür ist, dass der Request nicht korrekt UTF-8 codiert ist. Falls die ungültigen Zeichen einem Attribut im Request zugeordnet werden können, wird dieses im Feld |
401 (Unauthorized) |
|
Siehe Resource Access. |
401 (Unauthorized) |
|
Der Zugriff wurde verweigert. Bitte wenden Sie sich an den paydirekt-Support. |
422 (Unprocessable Entity) |
|
Das Bankkonto des Händlers wurde gesperrt und es können keine neue Checkouts oder Captures angelegt werden. Der Händler sollte sich an den paydirekt-Support wenden. |
422 (Unprocessable Entity) |
|
Der Payment Service Provider (PSP) ist gesperrt, es können keine neuen Checkouts oder Captures angelegt werden. |
Beispiel (Direct Sale, inkl. Altersverifikation)
POST /api/checkout/v1/checkouts HTTP/1.1
Content-Type: application/json;charset=utf-8
Authorization: Bearer <access_token>
{
"type" : "DIRECT_SALE",
"totalAmount" : 100.0,
"shippingAmount" : 3.5,
"orderAmount" : 96.5,
"refundLimit" : 200,
"items" : [ {
"quantity" : 3,
"name" : "Bobbycar",
"ean" : "800001303",
"price" : 25.99
}, {
"quantity" : 1,
"name" : "Helm",
"price" : 18.53
} ],
"shoppingCartType" : "MIXED",
"currency" : "EUR",
"overcapture" : false,
"shippingAddress" : {
"addresseeGivenName" : "Marie",
"addresseeLastName" : "Mustermann",
"company" : "Musterbau GmbH & Co KG",
"street" : "Kastanienallee",
"streetNr" : "999",
"additionalAddressInformation" : "Im Rückgebäude",
"zip" : "90402",
"city" : "Schwaig",
"countryCode" : "DE",
"state" : "Bayern"
},
"deliveryInformation" : {
"expectedShippingDate" : "2016-10-19T12:00:00.000Z",
"logisticsProvider" : "DHL",
"trackingNumber" : "1234567890"
},
"merchantCustomerNumber" : "cust-732477",
"merchantOrderReferenceNumber" : "order-A12223412",
"merchantReconciliationReferenceNumber" : "recon-A12223412",
"merchantInvoiceReferenceNumber" : "20150112334345",
"note" : "Ihr Einkauf bei Spielauto-Versand.",
"sha256hashedEmailAddress" : "fxP4R-IxH1Eaxpb0f_i5Shc8-FrYrtmx5lx35f9Xzgg",
"minimumAge" : 18,
"expiryTime" : 1800,
"redirectUrlAfterSuccess" : "https://spielauto-versand.de/order/123/success",
"redirectUrlAfterCancellation" : "https://spielauto-versand.de/order/123/cancellation",
"redirectUrlAfterAgeVerificationFailure" : "https://spielauto-versand.de/order/123/ageverificationfailed",
"redirectUrlAfterRejection" : "https://spielauto-versand.de/order/123/rejection",
"callbackUrlStatusUpdates" : "https://spielauto-versand.de/callback/status"
}
HTTP/1.1 201 Created
Location: https://api.paydirekt.de/api/checkout/v1/checkouts/d091ffc7-3655-489f-aed2-9c4b3a4735cd
Content-Type: application/hal+json;charset=utf-8
{
"checkoutId" : "d091ffc7-3655-489f-aed2-9c4b3a4735cd",
"type" : "DIRECT_SALE",
"status" : "OPEN",
"creationTimestamp" : "2021-08-03T12:21:11.764Z",
"totalAmount" : 100.0,
"shippingAmount" : 3.5,
"orderAmount" : 96.5,
"refundLimit" : 200,
"currency" : "EUR",
"items" : [ {
"quantity" : 3,
"name" : "Bobbycar",
"ean" : "800001303",
"price" : 25.99
}, {
"quantity" : 1,
"name" : "Helm",
"price" : 18.53
} ],
"shoppingCartType" : "MIXED",
"deliveryType" : "STANDARD",
"shippingAddress" : {
"addresseeGivenName" : "Marie",
"addresseeLastName" : "Mustermann",
"company" : "Musterbau GmbH & Co KG",
"street" : "Kastanienallee",
"streetNr" : "999",
"additionalAddressInformation" : "Im Rückgebäude",
"zip" : "90402",
"city" : "Schwaig",
"countryCode" : "DE",
"state" : "Bayern"
},
"merchantOrderReferenceNumber" : "order-A12223412",
"merchantCustomerNumber" : "cust-732477",
"merchantInvoiceReferenceNumber" : "20150112334345",
"merchantReconciliationReferenceNumber" : "recon-A12223412",
"note" : "Ihr Einkauf bei Spielauto-Versand.",
"minimumAge" : 18,
"redirectUrlAfterSuccess" : "https://spielauto-versand.de/order/123/success",
"redirectUrlAfterCancellation" : "https://spielauto-versand.de/order/123/cancellation",
"redirectUrlAfterAgeVerificationFailure" : "https://spielauto-versand.de/order/123/ageverificationfailed",
"redirectUrlAfterRejection" : "https://spielauto-versand.de/order/123/rejection",
"callbackUrlStatusUpdates" : "https://spielauto-versand.de/callback/status",
"deliveryInformation" : {
"expectedShippingDate" : "2016-10-19T12:00:00.000Z",
"logisticsProvider" : "DHL",
"trackingNumber" : "1234567890"
},
"expiryTimestamp" : "2021-08-03T12:51:11.764Z",
"_links" : {
"approve" : {
"href" : "https://localhost/checkout/?p=d091ffc7-3655-489f-aed2-9c4b3a4735cd#/checkout/d091ffc7-3655-489f-aed2-9c4b3a4735cd"
},
"updateDeliveryInformation" : {
"href" : "https://api.paydirekt.de/api/checkout/v1/checkouts/d091ffc7-3655-489f-aed2-9c4b3a4735cd/deliveryInformation"
},
"updateMerchantInvoiceReferenceNumber" : {
"href" : "https://api.paydirekt.de/api/checkout/v1/checkouts/d091ffc7-3655-489f-aed2-9c4b3a4735cd/merchantInvoiceReferenceNumber"
},
"self" : {
"href" : "https://api.paydirekt.de/api/checkout/v1/checkouts/d091ffc7-3655-489f-aed2-9c4b3a4735cd"
}
}
}
Beispiel (Order)
POST /api/checkout/v1/checkouts HTTP/1.1
Content-Type: application/json;charset=utf-8
Authorization: Bearer <access_token>
{
"type" : "ORDER",
"totalAmount" : 100.0,
"shippingAmount" : 3.5,
"orderAmount" : 96.5,
"refundLimit" : 200,
"items" : [ {
"quantity" : 3,
"name" : "Bobbycar",
"ean" : "800001303",
"price" : 25.99
}, {
"quantity" : 1,
"name" : "Helm",
"price" : 18.53
} ],
"shoppingCartType" : "PHYSICAL",
"deliveryType" : "STANDARD",
"currency" : "EUR",
"shippingAddress" : {
"addresseeGivenName" : "Marie",
"addresseeLastName" : "Mustermann",
"company" : "Musterbau GmbH & Co KG",
"street" : "Kastanienallee",
"streetNr" : "999",
"additionalAddressInformation" : "Im Rückgebäude",
"zip" : "90402",
"city" : "Schwaig",
"countryCode" : "DE",
"state" : "Bayern"
},
"merchantCustomerNumber" : "cust-732477",
"merchantOrderReferenceNumber" : "order-A12223412",
"merchantInvoiceReferenceNumber" : "20150112334345",
"expiryTime" : 1800,
"redirectUrlAfterSuccess" : "https://spielauto-versand.de/order/123/success",
"redirectUrlAfterCancellation" : "https://spielauto-versand.de/order/123/cancellation",
"redirectUrlAfterRejection" : "https://spielauto-versand.de/order/123/rejection",
"callbackUrlStatusUpdates" : "https://spielauto-versand.de/callback/status"
}
HTTP/1.1 201 Created
Location: https://api.paydirekt.de/api/checkout/v1/checkouts/cb5d2624-3f2e-4aed-b546-fb5dd73f04f9
Content-Type: application/hal+json;charset=utf-8
{
"checkoutId" : "cb5d2624-3f2e-4aed-b546-fb5dd73f04f9",
"type" : "ORDER",
"status" : "OPEN",
"creationTimestamp" : "2021-08-03T12:22:10.282Z",
"totalAmount" : 100.0,
"shippingAmount" : 3.5,
"orderAmount" : 96.5,
"refundLimit" : 200,
"currency" : "EUR",
"items" : [ {
"quantity" : 3,
"name" : "Bobbycar",
"ean" : "800001303",
"price" : 25.99
}, {
"quantity" : 1,
"name" : "Helm",
"price" : 18.53
} ],
"shoppingCartType" : "PHYSICAL",
"deliveryType" : "STANDARD",
"shippingAddress" : {
"addresseeGivenName" : "Marie",
"addresseeLastName" : "Mustermann",
"company" : "Musterbau GmbH & Co KG",
"street" : "Kastanienallee",
"streetNr" : "999",
"additionalAddressInformation" : "Im Rückgebäude",
"zip" : "90402",
"city" : "Schwaig",
"countryCode" : "DE",
"state" : "Bayern"
},
"merchantOrderReferenceNumber" : "order-A12223412",
"merchantCustomerNumber" : "cust-732477",
"merchantInvoiceReferenceNumber" : "20150112334345",
"redirectUrlAfterSuccess" : "https://spielauto-versand.de/order/123/success",
"redirectUrlAfterCancellation" : "https://spielauto-versand.de/order/123/cancellation",
"redirectUrlAfterRejection" : "https://spielauto-versand.de/order/123/rejection",
"callbackUrlStatusUpdates" : "https://spielauto-versand.de/callback/status",
"expiryTimestamp" : "2021-08-03T12:52:10.282Z",
"_links" : {
"approve" : {
"href" : "https://localhost/checkout/?p=cb5d2624-3f2e-4aed-b546-fb5dd73f04f9#/checkout/cb5d2624-3f2e-4aed-b546-fb5dd73f04f9"
},
"updateDeliveryInformation" : {
"href" : "https://api.paydirekt.de/api/checkout/v1/checkouts/cb5d2624-3f2e-4aed-b546-fb5dd73f04f9/deliveryInformation"
},
"updateMerchantInvoiceReferenceNumber" : {
"href" : "https://api.paydirekt.de/api/checkout/v1/checkouts/cb5d2624-3f2e-4aed-b546-fb5dd73f04f9/merchantInvoiceReferenceNumber"
},
"self" : {
"href" : "https://api.paydirekt.de/api/checkout/v1/checkouts/cb5d2624-3f2e-4aed-b546-fb5dd73f04f9"
}
}
}
Beispiel (Order Secured)
POST /api/checkout/v1/checkouts HTTP/1.1
Content-Type: application/json;charset=utf-8
Authorization: Bearer <access_token>
{
"type" : "ORDER_SECURED",
"totalAmount" : 100.0,
"shippingAmount" : 3.5,
"orderAmount" : 96.5,
"refundLimit" : 200,
"items" : [ {
"quantity" : 3,
"name" : "Bobbycar",
"ean" : "800001303",
"price" : 25.99
}, {
"quantity" : 1,
"name" : "Helm",
"price" : 18.53
} ],
"shoppingCartType" : "PHYSICAL",
"deliveryType" : "STANDARD",
"currency" : "EUR",
"shippingAddress" : {
"addresseeGivenName" : "Marie",
"addresseeLastName" : "Mustermann",
"company" : "Musterbau GmbH & Co KG",
"street" : "Kastanienallee",
"streetNr" : "999",
"additionalAddressInformation" : "Im Rückgebäude",
"zip" : "90402",
"city" : "Schwaig",
"countryCode" : "DE",
"state" : "Bayern"
},
"merchantCustomerNumber" : "cust-732477",
"merchantOrderReferenceNumber" : "order-A12223412",
"merchantInvoiceReferenceNumber" : "20150112334345",
"expiryTime" : 1800,
"redirectUrlAfterSuccess" : "https://spielauto-versand.de/order/123/success",
"redirectUrlAfterCancellation" : "https://spielauto-versand.de/order/123/cancellation",
"redirectUrlAfterRejection" : "https://spielauto-versand.de/order/123/rejection",
"callbackUrlStatusUpdates" : "https://spielauto-versand.de/callback/status",
"requestedPreauthorizationValidity" : "2021-08-06"
}
HTTP/1.1 201 Created
Location: https://api.paydirekt.de/api/checkout/v1/checkouts/bf7ae4e9-512a-4b75-a9a9-f9c3e08a8c8a
Content-Type: application/hal+json;charset=utf-8
{
"checkoutId" : "bf7ae4e9-512a-4b75-a9a9-f9c3e08a8c8a",
"type" : "ORDER_SECURED",
"status" : "OPEN",
"creationTimestamp" : "2021-08-03T12:23:37.566Z",
"totalAmount" : 100.0,
"shippingAmount" : 3.5,
"orderAmount" : 96.5,
"refundLimit" : 200,
"currency" : "EUR",
"items" : [ {
"quantity" : 3,
"name" : "Bobbycar",
"ean" : "800001303",
"price" : 25.99
}, {
"quantity" : 1,
"name" : "Helm",
"price" : 18.53
} ],
"shoppingCartType" : "PHYSICAL",
"deliveryType" : "STANDARD",
"shippingAddress" : {
"addresseeGivenName" : "Marie",
"addresseeLastName" : "Mustermann",
"company" : "Musterbau GmbH & Co KG",
"street" : "Kastanienallee",
"streetNr" : "999",
"additionalAddressInformation" : "Im Rückgebäude",
"zip" : "90402",
"city" : "Schwaig",
"countryCode" : "DE",
"state" : "Bayern"
},
"merchantOrderReferenceNumber" : "order-A12223412",
"merchantCustomerNumber" : "cust-732477",
"merchantInvoiceReferenceNumber" : "20150112334345",
"redirectUrlAfterSuccess" : "https://spielauto-versand.de/order/123/success",
"redirectUrlAfterCancellation" : "https://spielauto-versand.de/order/123/cancellation",
"redirectUrlAfterRejection" : "https://spielauto-versand.de/order/123/rejection",
"callbackUrlStatusUpdates" : "https://spielauto-versand.de/callback/status",
"expiryTimestamp" : "2021-08-03T12:53:37.566Z",
"_links" : {
"approve" : {
"href" : "https://localhost/checkout/?p=bf7ae4e9-512a-4b75-a9a9-f9c3e08a8c8a#/checkout/bf7ae4e9-512a-4b75-a9a9-f9c3e08a8c8a"
},
"updateDeliveryInformation" : {
"href" : "https://api.paydirekt.de/api/checkout/v1/checkouts/bf7ae4e9-512a-4b75-a9a9-f9c3e08a8c8a/deliveryInformation"
},
"updateMerchantInvoiceReferenceNumber" : {
"href" : "https://api.paydirekt.de/api/checkout/v1/checkouts/bf7ae4e9-512a-4b75-a9a9-f9c3e08a8c8a/merchantInvoiceReferenceNumber"
},
"self" : {
"href" : "https://api.paydirekt.de/api/checkout/v1/checkouts/bf7ae4e9-512a-4b75-a9a9-f9c3e08a8c8a"
}
}
}
Beispiel (Validierungsfehler)
POST /api/checkout/v1/checkouts HTTP/1.1
Content-Type: application/json;charset=utf-8
Authorization: Bearer <access_token>
{
"type" : "DIRECT_SALE",
"totalAmount" : 100.0,
"shippingAmount" : 5.999,
"orderAmount" : 96.5,
"refundLimit" : 200,
"items" : [ {
"quantity" : 3,
"name" : "Bobbycar",
"ean" : "800001303",
"price" : 25.99
}, {
"quantity" : 1,
"name" : "Helm",
"price" : 18.53
} ],
"shoppingCartType" : "MIXED",
"currency" : "EUR",
"overcapture" : false,
"shippingAddress" : {
"addresseeGivenName" : "Marie",
"addresseeLastName" : "Mustermann",
"company" : "Musterbau GmbH & Co KG",
"street" : "Kastanienallee",
"streetNr" : "999",
"additionalAddressInformation" : "Im Rückgebäude",
"zip" : "90402",
"city" : "Schwaig",
"countryCode" : "DE",
"state" : "Bayern"
},
"merchantCustomerNumber" : "cust-732477",
"merchantOrderReferenceNumber" : "order-A12223412",
"merchantReconciliationReferenceNumber" : "recon-A12223412",
"merchantInvoiceReferenceNumber" : "20150112334345",
"note" : "Ihr Einkauf bei Spielauto-Versand.",
"sha256hashedEmailAddress" : "fxP4R-IxH1Eaxpb0f_i5Shc8-FrYrtmx5lx35f9Xzgg",
"expiryTime" : 1800,
"redirectUrlAfterSuccess" : "https://spielauto-versand.de/order/123/success",
"redirectUrlAfterCancellation" : "https://spielauto-versand.de/order/123/cancellation",
"redirectUrlAfterAgeVerificationFailure" : "https://spielauto-versand.de/order/123/underAge",
"redirectUrlAfterRejection" : "https://spielauto-versand.de/order/123/rejection",
"callbackUrlStatusUpdates" : "https://spielauto-versand.de/callback/status"
}
HTTP/1.1 400 Bad Request
Content-Type: application/hal+json;charset=utf-8
{
"messages" : [ {
"severity" : "ERROR",
"code" : "VALIDATION_ERROR",
"path" : "shippingAmount",
"reasonCode" : "INVALID_FORMAT",
"logref" : "bddc9682-574a-4913-a743-9ae9d78b2690:7yk5DGxxCfL"
} ]
}
Beispiel (Fachlicher Fehler)
POST /api/checkout/v1/checkouts HTTP/1.1
Content-Type: application/json;charset=utf-8
Authorization: Bearer <access_token>
{
"type" : "DIRECT_SALE",
"totalAmount" : 100.0,
"shippingAmount" : 3.5,
"orderAmount" : 96.5,
"refundLimit" : 200,
"items" : [ {
"quantity" : 3,
"name" : "Bobbycar",
"ean" : "800001303",
"price" : 25.99
}, {
"quantity" : 1,
"name" : "Helm",
"price" : 18.53
} ],
"shoppingCartType" : "MIXED",
"currency" : "EUR",
"overcapture" : false,
"shippingAddress" : {
"addresseeGivenName" : "Marie",
"addresseeLastName" : "Mustermann",
"company" : "Musterbau GmbH & Co KG",
"street" : "Kastanienallee",
"streetNr" : "999",
"additionalAddressInformation" : "Im Rückgebäude",
"zip" : "90402",
"city" : "Schwaig",
"countryCode" : "DE",
"state" : "Bayern"
},
"merchantCustomerNumber" : "cust-732477",
"merchantOrderReferenceNumber" : "order-A12223412",
"merchantReconciliationReferenceNumber" : "recon-A12223412",
"merchantInvoiceReferenceNumber" : "20150112334345",
"note" : "Ihr Einkauf bei Spielauto-Versand.",
"sha256hashedEmailAddress" : "fxP4R-IxH1Eaxpb0f_i5Shc8-FrYrtmx5lx35f9Xzgg",
"expiryTime" : 1800,
"redirectUrlAfterSuccess" : "https://spielauto-versand.de/order/123/success",
"redirectUrlAfterCancellation" : "https://spielauto-versand.de/order/123/cancellation",
"redirectUrlAfterAgeVerificationFailure" : "https://spielauto-versand.de/order/123/underAge",
"redirectUrlAfterRejection" : "https://spielauto-versand.de/order/123/rejection",
"callbackUrlStatusUpdates" : "https://spielauto-versand.de/callback/status"
}
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/hal+json;charset=utf-8
{
"messages" : [ {
"severity" : "ERROR",
"code" : "MERCHANT_BANKACCOUNT_LOCKED",
"logref" : "1e04ae2b-7c53-470f-8274-814be0015609:4fPGWU2EkIk"
} ]
}
Beispiel (Konvertierungsfehler)
POST /api/checkout/v1/checkouts HTTP/1.1
Content-Type: application/json;charset=utf-8
Authorization: Bearer <access_token>
{
"type" : "DIRECT_SALE",
"totalAmount" : 100.0,
"shippingAmount" : 3.5,
"orderAmount" : 96.5,
"refundLimit" : 200,
"items" : [ {
"quantity" : 3,
"name" : "Bobbycar",
"ean" : "800001303",
"price" : 25.99
}, {
"quantity" : 1,
"name" : "Helm",
"price" : 18.53
} ],
"shoppingCartType" : "MIXED",
"currency" : "EUR",
"overcapture" : false,
"shippingAddress" : {
"addresseeGivenName" : "Marie",
"addresseeLastName" : "Mustermann",
"company" : "ungültige Zeichen sind z.B.: €¥£˚\\˙¯⁀",
"street" : "Kastanienallee",
"streetNr" : "999",
"additionalAddressInformation" : "Im Rückgebäude",
"zip" : "90402",
"city" : "Schwaig",
"countryCode" : "DE",
"state" : "Bayern"
},
"merchantCustomerNumber" : "cust-732477",
"merchantOrderReferenceNumber" : "order-A12223412",
"merchantReconciliationReferenceNumber" : "recon-A12223412",
"merchantInvoiceReferenceNumber" : "20150112334345",
"note" : "Ihr Einkauf bei Spielauto-Versand.",
"sha256hashedEmailAddress" : "fxP4R-IxH1Eaxpb0f_i5Shc8-FrYrtmx5lx35f9Xzgg",
"expiryTime" : 1800,
"redirectUrlAfterSuccess" : "https://spielauto-versand.de/order/123/success",
"redirectUrlAfterCancellation" : "https://spielauto-versand.de/order/123/cancellation",
"redirectUrlAfterAgeVerificationFailure" : "https://spielauto-versand.de/order/123/underAge",
"redirectUrlAfterRejection" : "https://spielauto-versand.de/order/123/rejection",
"callbackUrlStatusUpdates" : "https://spielauto-versand.de/callback/status"
}
HTTP/1.1 400 Bad Request
Content-Type: application/hal+json;charset=utf-8
{
"messages" : [ {
"severity" : "ERROR",
"code" : "CONVERSION_ERROR",
"path" : "shippingAddress.company",
"reasonCode" : "HTTP_MESSAGE_NOT_READABLE",
"logref" : "bb985f88-9675-497f-ba5e-5fb8ecf26084:48E4SG4I57m",
"content" : "ungültige Zeichen sind z.B.: €¥£˚\\˙¯⁀"
} ]
}
Abfrage
GET /api/checkout/v1/checkouts/{checkoutId}
Ein zuvor angelegter Checkout kann über die GET-Methode aufgerufen werden, um den Status der Zahlung und andere Eigenschaften abzufragen, sowie um die Links zu weiteren Ressourcen, z. B. Captures und Refunds, zu ermitteln.
Response
Feld | Typ | Eigenschaften | Beschreibung |
---|---|---|---|
|
String |
Immer vorhanden. |
Eindeutige UUID aus 36 Zeichen für diesen Checkout-Vorgang. Wird vom paydirekt-System vergeben. |
|
String |
Immer vorhanden. |
Die Art der Bestellung: |
|
String |
Immer vorhanden. |
Status des Checkouts: |
|
String |
Vorhanden, sobald sich ein Kunde eingeloggt hat. UUID aus 36 Zeichen. |
Die eindeutige Identifikation des Checkouts und aller dazugehöriger Transaktionen. |
|
String |
Immer vorhanden. |
Der Erzeugungszeitpunkt dieses Checkouts. Wird vom paydirekt-System vergeben. Formatierung entsprechend ISO-8601 durch den Standard Java DateTimeFormatter. Abweichend davon werden immer drei Nachkommastellen für die Millisekunden ausgegeben. |
|
String |
Immer vorhanden. |
Der Ablaufzeitpunkt dieses Checkouts. Kann über das Feld |
|
Number |
Immer vorhanden. |
Der Gesamtbetrag der Bestellung, inkl. aller Lieferkosten. Es werden maximal 2 Nachkommastellen unterstützt. |
|
Number |
Vorhanden, falls bei Anlage übergeben. |
Die Versandkosten der Bestellung. Dieser Wert wird nicht für Berechnungen verwendet, sondern dient nur zur Information. |
|
Number |
Vorhanden, falls bei Anlage übergeben. |
Der Warenwert der Bestellung, ohne Versandkosten. Dieser Wert wird nicht für Berechnungen verwendet, sondern dient nur zur Information. |
|
Number |
Vorhanden, falls bei Anlage übergeben. |
Maximal zurückzahlbarer Betrag als Prozentwert des Gesamtwertes der Bestellung. |
|
Boolean |
Vorhanden, falls bei Anlage übergeben. |
Flag für Overcapture-Checkouts. |
|
Number |
Vorhanden, falls Overcapture-Flag gesetzt. |
Bei gesetztem Overcapture-Flag enthält dieses Feld den maximalen Betrag, der insgesamt abgerufen werden kann. |
|
Number |
Vorhanden, falls Overcapture-Flag vorhanden. |
Bei gesetztem Overcapture-Flag enthält dieses Feld den zum Gesamtbetrag zusätzlichen Betrag, der in der Summe abgerufen werden kann. |
|
String |
Immer vorhanden. |
Die Währung des Gesamtbetrags. Derzeit wird nur EUR unterstützt. |
|
Array von Items |
Vorhanden, falls bei Anlage übergeben. |
Die einzelnen Positionen des Warenkorbs. |
|
String |
Vorhanden, falls bei Anlage übergeben. |
Kategorisiert den Warenkorb eines Checkouts anhand der Eigenschaften der enthaltenen Güter: Der Standardwert ist |
|
String |
Vorhanden, falls bei Anlage übergeben. |
Der Bestimmungsort einer Lieferung: |
|
Vorhanden, falls bei Anlage übergeben. |
Die Lieferanschrift des Empfängers. Diese Adresse wird dem Kunden nach dem Login im paydirekt-System zur Kontrolle angezeigt. |
|
|
String |
Vorhanden, falls bei Anlage übergeben. |
Händler-interne Kundennummer des Käufers. Wird dem Kunden in der Transaktionsübersicht angezeigt. Wird dem Händler in der Transaktionsübersicht angezeigt. |
|
String |
Immer vorhanden. |
Händler-interne, eindeutige Bestellnummer für diesen Kaufvorgang. Wird dem Kunden in der Transaktionsübersicht angezeigt. Wird dem Händler in der Transaktionsübersicht angezeigt. Die Bestellnummer wird in der Händler-Lastschrift als |
|
String |
Vorhanden, falls bei Anlage übergeben. |
Händler-interne, eindeutige Rechnungsnummer für diesen Kauf- bzw. Zahlvorgang. Wird dem Händler in der Transaktionsübersicht angezeigt. |
|
String |
Vorhanden, falls bei Anlage übergeben. |
Reconciliation-Nummer. Diese wird bei Direct-Sales in den Verwendungszweck der Händlerzahlung eingefügt. Bei Vorbestellungen wird stattdessen die bei Anlage der Captures gesetzte |
|
String |
Immer vorhanden, außer bei oneKlick-Checkouts. |
Die Rücksprung-Adresse des Webshops (inkl. Referenz auf die Bestellung), die nach erfolgreicher Bezahlung aufgerufen wird. |
|
String |
Immer vorhanden, außer bei oneKlick-Checkouts. |
Die Rücksprung-Adresse des Webshops (inkl. Referenz auf die Bestellung), die im Falle eines Abbruchs oder technischen Fehlers aufgerufen wird. Damit wird signalisiert, dass der Kaufvorgang grundsätzlich fortgeführt werden kann und im Anschluss ein weiterer, neuer Checkout initiiert werden kann, beispielsweise, weil der Kunde noch einen Artikel in der Bestellung hinzufügen möchte. |
|
String |
Immer vorhanden, außer bei oneKlick-Checkouts. |
Die Rücksprung-Adresse des Webshops (inkl. Referenz auf die Bestellung), die im Falle einer Abweisung der Zahlung aufgerufen wird. Damit wird signalisiert, dass keine Zahlung autorisiert wurde (z. B. aufgrund falscher TAN-Eingabe, fehlender Bank-Autorisierung oder Betrugsverdacht). Falls das Webshop-System keine Unterscheidung zwischen redirectUrlAfterCancellation und redirectUrlAfterRejection unterstützt, kann in beiden Feldern die gleiche URL angegeben werden. |
|
String |
Vorhanden, falls bei Anlage übergeben. |
URL des Endpoints, der Mitteilungen zu Statusänderungen des Checkouts empfangen soll. |
|
Number |
Vorhanden, falls bei Anlage übergeben. |
Das Mindestalter (in Jahren), das der Käufer erreicht haben muss, um die Bestellung ausführen zu dürfen, beispielsweise, weil sie Artikel enthält, die einer Altersbeschränkung unterliegen (Filme, Computerspiele, …). Die Prüfung erfolgt direkt nach dem Login des Käufers in das paydirekt-System. Bei erfolgreicher Verifikation wird der Ablauf ohne weitere Meldung wie gewohnt fortgesetzt. Bei nicht-erfolgreicher Verifikation, d. h. der Kunde hat das erforderliche Mindestalter noch nicht erreicht, erfolgt eine Umleitung auf den Link |
|
String |
Vorhanden, falls bei Anlage übergeben. |
Die Rücksprung-Adresse des Webshops (inkl. Referenz auf die Bestellung), die im Falle einer nicht erfolgreichen Altersverifikation aufgerufen wird. Damit wird signalisiert, dass die Bestellung abgebrochen wurde, da der Käufer das erforderliche Mindestalter für mindestens einen Artikel in der Bestellung noch nicht erreicht hat. Dieses Feld wird im Falle einer geforderten Altersverifikation, d. h. bei Angabe des Feldes |
|
String |
Vorhanden, falls bei Anlage übergeben. |
Freitextfeld, das auf dem Kontoauszug im Feld Verwendungzweck erscheint (nur |
|
Object |
Optional. |
Enthält Informationen über die Lieferung. |
|
String |
Optional. |
Erwartetes Versanddatum. |
|
String |
Optional. |
Paket-Dienstleister. |
|
String |
Optional. |
Sendungsnummer. |
|
String |
Optional. |
Garantiezeitraum für die gesicherte Vorbestellung (ORDER_SECURED). Captures innerhalb dieses Zeitraums sind für den Händler garantiert. |
|
Object |
Embedded Ressourcen |
Links
Relation | Description |
---|---|
|
Link zu dieser Ressource. |
|
Link zur paydirekt-Webseite, zu dem der Käufer per HTTP Code 302 weitergeleitet werden muss, um die Zahlung zu bestätigen. Die Weiterleitung darf nicht über ein HTML Formular (unter Nutzung des |
|
Link zum Endpoint, über den die Order geschlossen werden kann. Dieser Link ist nur vorhanden, wenn es sich um einen Checkout vom Typ |
|
Link zu Captures. Dieser Link ist nur vorhanden, wenn für diese Bestellung ein Capture möglich ist. |
|
Link zu Refunds. Dieser Link ist nur vorhanden, wenn für diese Bestellung eine Rückzahlung möglich ist, d. h. wenn mindestens ein Capture im Status |
|
Link zum Update der Lieferinformation. Dieser Link ist nur vorhanden, wenn die Update Frist für diesen Checkout noch nicht überschritten ist. |
|
Link zum Update der Rechnungsreferenznummer. Dieser Link ist nur vorhanden, wenn die Update Frist für diesen Checkout noch nicht überschritten ist. |
Embedded Resources
Resource | Beschreibung |
---|---|
|
Array von Captures, sofern Captures zu diesem Checkout vorhanden sind. |
|
Array von Refunds, sofern Refunds zu diesem Checkout vorhanden sind. |
Return Codes
Status Code | Message Code | Beschreibung |
---|---|---|
200 (Ok) |
Der Checkout wurde gefunden. |
|
401 (Unauthorized) |
|
Siehe Resource Access. |
404 (Not Found) |
|
Der angefragte Checkout existiert nicht |
Beispiel (Direct Sale nach der Anlage)
GET /api/checkout/v1/checkouts/d091ffc7-3655-489f-aed2-9c4b3a4735cd HTTP/1.1
Content-Type: application/json;charset=utf-8
Authorization: Bearer <access_token>
HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=utf-8
{
"checkoutId" : "d091ffc7-3655-489f-aed2-9c4b3a4735cd",
"type" : "DIRECT_SALE",
"status" : "OPEN",
"creationTimestamp" : "2021-08-03T12:21:11.764Z",
"totalAmount" : 100.0,
"shippingAmount" : 3.5,
"orderAmount" : 96.5,
"refundLimit" : 200,
"currency" : "EUR",
"items" : [ {
"quantity" : 3,
"name" : "Bobbycar",
"ean" : "800001303",
"price" : 25.99
}, {
"quantity" : 1,
"name" : "Helm",
"price" : 18.53
} ],
"shoppingCartType" : "MIXED",
"deliveryType" : "STANDARD",
"shippingAddress" : {
"addresseeGivenName" : "Marie",
"addresseeLastName" : "Mustermann",
"company" : "Musterbau GmbH & Co KG",
"street" : "Kastanienallee",
"streetNr" : "999",
"additionalAddressInformation" : "Im Rückgebäude",
"zip" : "90402",
"city" : "Schwaig",
"countryCode" : "DE",
"state" : "Bayern"
},
"merchantOrderReferenceNumber" : "order-A12223412",
"merchantCustomerNumber" : "cust-732477",
"merchantInvoiceReferenceNumber" : "20150112334345",
"merchantReconciliationReferenceNumber" : "recon-A12223412",
"note" : "Ihr Einkauf bei Spielauto-Versand.",
"minimumAge" : 18,
"redirectUrlAfterSuccess" : "https://spielauto-versand.de/order/123/success",
"redirectUrlAfterCancellation" : "https://spielauto-versand.de/order/123/cancellation",
"redirectUrlAfterAgeVerificationFailure" : "https://spielauto-versand.de/order/123/ageverificationfailed",
"redirectUrlAfterRejection" : "https://spielauto-versand.de/order/123/rejection",
"callbackUrlStatusUpdates" : "https://spielauto-versand.de/callback/status",
"deliveryInformation" : {
"expectedShippingDate" : "2016-10-19T12:00:00.000Z",
"logisticsProvider" : "DHL",
"trackingNumber" : "1234567890"
},
"expiryTimestamp" : "2021-08-03T12:51:11.764Z",
"_links" : {
"approve" : {
"href" : "https://localhost/checkout/?p=d091ffc7-3655-489f-aed2-9c4b3a4735cd#/checkout/d091ffc7-3655-489f-aed2-9c4b3a4735cd"
},
"updateDeliveryInformation" : {
"href" : "https://api.paydirekt.de/api/checkout/v1/checkouts/d091ffc7-3655-489f-aed2-9c4b3a4735cd/deliveryInformation"
},
"updateMerchantInvoiceReferenceNumber" : {
"href" : "https://api.paydirekt.de/api/checkout/v1/checkouts/d091ffc7-3655-489f-aed2-9c4b3a4735cd/merchantInvoiceReferenceNumber"
},
"self" : {
"href" : "https://api.paydirekt.de/api/checkout/v1/checkouts/d091ffc7-3655-489f-aed2-9c4b3a4735cd"
}
}
}
Beispiel (Direct Sale nach Approval durch Kunden)
GET /api/checkout/v1/checkouts/d091ffc7-3655-489f-aed2-9c4b3a4735cd HTTP/1.1
Content-Type: application/json;charset=utf-8
Authorization: Bearer <access_token>
HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=utf-8
{
"checkoutId" : "d091ffc7-3655-489f-aed2-9c4b3a4735cd",
"type" : "DIRECT_SALE",
"status" : "APPROVED",
"correlationId" : "ext0815-00000015",
"creationTimestamp" : "2021-08-03T12:21:11.764Z",
"totalAmount" : 100.0,
"shippingAmount" : 3.5,
"orderAmount" : 96.5,
"refundLimit" : 200,
"currency" : "EUR",
"items" : [ {
"quantity" : 3,
"name" : "Bobbycar",
"ean" : "800001303",
"price" : 25.99
}, {
"quantity" : 1,
"name" : "Helm",
"price" : 18.53
} ],
"shoppingCartType" : "MIXED",
"deliveryType" : "STANDARD",
"shippingAddress" : {
"addresseeGivenName" : "Marie",
"addresseeLastName" : "Mustermann",
"company" : "Musterbau GmbH & Co KG",
"street" : "Kastanienallee",
"streetNr" : "999",
"additionalAddressInformation" : "Im Rückgebäude",
"zip" : "90402",
"city" : "Schwaig",
"countryCode" : "DE",
"state" : "Bayern"
},
"merchantOrderReferenceNumber" : "order-A12223412",
"merchantCustomerNumber" : "cust-732477",
"merchantInvoiceReferenceNumber" : "20150112334345",
"merchantReconciliationReferenceNumber" : "recon-A12223412",
"note" : "Ihr Einkauf bei Spielauto-Versand.",
"minimumAge" : 18,
"redirectUrlAfterSuccess" : "https://spielauto-versand.de/order/123/success",
"redirectUrlAfterCancellation" : "https://spielauto-versand.de/order/123/cancellation",
"redirectUrlAfterAgeVerificationFailure" : "https://spielauto-versand.de/order/123/ageverificationfailed",
"redirectUrlAfterRejection" : "https://spielauto-versand.de/order/123/rejection",
"callbackUrlStatusUpdates" : "https://spielauto-versand.de/callback/status",
"deliveryInformation" : {
"expectedShippingDate" : "2016-10-19T12:00:00.000Z",
"logisticsProvider" : "DHL",
"trackingNumber" : "1234567890"
},
"expiryTimestamp" : "2021-08-03T12:51:11.764Z",
"_links" : {
"refunds" : {
"href" : "https://api.paydirekt.de/api/checkout/v1/checkouts/d091ffc7-3655-489f-aed2-9c4b3a4735cd/refunds"
},
"updateDeliveryInformation" : {
"href" : "https://api.paydirekt.de/api/checkout/v1/checkouts/d091ffc7-3655-489f-aed2-9c4b3a4735cd/deliveryInformation"
},
"updateMerchantInvoiceReferenceNumber" : {
"href" : "https://api.paydirekt.de/api/checkout/v1/checkouts/d091ffc7-3655-489f-aed2-9c4b3a4735cd/merchantInvoiceReferenceNumber"
},
"self" : {
"href" : "https://api.paydirekt.de/api/checkout/v1/checkouts/d091ffc7-3655-489f-aed2-9c4b3a4735cd"
}
},
"_embedded" : {
"captures" : [ {
"type" : "CAPTURE_DIRECT_SALE",
"transactionId" : "2a45ea30-b467-4a88-a1f3-6275e9d5e0a0",
"amount" : 100.0,
"callbackUrlStatusUpdates" : "https://spielauto-versand.de/callback/status",
"deliveryInformation" : {
"expectedShippingDate" : "2016-10-19T12:00:00.000Z",
"logisticsProvider" : "DHL",
"trackingNumber" : "1234567890"
},
"status" : "SUCCESSFUL",
"_links" : {
"self" : {
"href" : "https://api.paydirekt.de/api/checkout/v1/checkouts/d091ffc7-3655-489f-aed2-9c4b3a4735cd/captures/2a45ea30-b467-4a88-a1f3-6275e9d5e0a0"
}
}
} ]
}
}
Callback für Statusupdates
Wenn Händler/PSPs bei Anlage von Checkouts eine Callback URL callbackUrlStatusUpdates
übergeben,
sendet das paydirekt-System bei Statusänderungen des Checkouts an diese URL einen HTTP-Request.
Bei DIRECT_SALE
werden für den eingebetteten Capture ebenfalls Statusupdates versendet.
Bei Verbindungsfehlern oder Responses mit einem HTTP-Statuscode von 5xx wird das paydirekt-System die Übermittlung der Statusänderung in einem Zeitfenster von 24 Stunden bis zu 5 Mal wiederholen.
Statusänderungen werden dabei immer in der Reihenfolge übermittelt, in der sie am Checkout aufgetreten sind.
Kann eine Statusänderung nicht übermittelt werden, so werden auch alle nachfolgenden Statusänderungen nicht übermittelt, bis entweder die fehlgeschlagene Übermittlung nachgeholt werden konnte oder alle wiederholten Versuche fehlgeschlagen sind.
POST callbackUrlStatusUpdates
Request
Feld | Typ | Eigenschaften | Beschreibung |
---|---|---|---|
|
String |
Immer vorhanden. |
Eindeutige UUID aus 36 Zeichen für diesen Checkout-Vorgang. Wird vom paydirekt-System vergeben. |
|
String |
Pflichtfeld. |
Händler-interne, eindeutige Bestellnummer für diesen Kaufvorgang. Wird dem Kunden in der Transaktionsübersicht angezeigt. Wird dem Händler in der Transaktionsübersicht angezeigt. Die Bestellnummer wird in der Händler-Lastschrift als |
|
String |
Immer vorhanden. |
Status des Checkouts: |
|
String |
Immer vorhanden. |
Zeitstempel der Statusänderung. |
|
Number |
Immer vorhanden. |
Sequenznummer der Statusänderung. Anhand der Sequenznummer kann ein Shop die Reihenfolge der Statusänderungen nachvollziehen und gegebenenfalls fehlende Statusänderungen erkennen. |
Beispiel
POST /webhooktest/v1/checkout/status HTTP/1.1
Content-Type: application/json;charset=utf-8
{
"checkoutId" : "a563306c-dff8-4eb5-bf89-3369a6377715",
"checkoutStatus" : "APPROVED",
"merchantOrderReferenceNumber" : "order-A12223412",
"statusUpdateTimestamp" : "2020-01-01T12:00:00.000Z",
"sequenceNumber" : 4
}
Aktualisierung der Versandbedingungen
PUT /api/checkout/v1/checkouts/{checkoutId}/deliveryInformation
Über diesen Endpoint können die Versandbedingungen eines bereits angelegten Checkouts aktualisiert werden. Alle im Request angegebenen Felder werden an der Checkout-Ressource überschrieben. Bei allen nicht im Request enthaltenen Feldern bleibt der Wert in der Ressource unangetastet. Die aktuellen Versandbedingungen des Checkouts sind für den Käufer sichtbar. Aktualisierungen sind nur bis 25 Tage nach dem letzten Capture auf den Checkout gestattet.
Request
Feld | Typ | Eigenschaften | Beschreibung |
---|---|---|---|
|
String |
Optional. |
Erwartetes Versanddatum. |
|
String |
Optional. |
Paket-Dienstleister. |
|
String |
Optional. |
Sendungsnummer. |
Response
In der Response wird der aktualisierte Checkout zurückgegeben. Die Struktur ist identisch mit dem Checkout Endpoint GET-Aufruf.
Return Codes
Status Code | Message Code | Beschreibung |
---|---|---|
200 (Ok) |
Der Checkout wurde gefunden. |
|
401 (Unauthorized) |
|
Siehe Resource Access. |
404 (Not Found) |
|
Der zu aktualisierende Checkout existiert nicht. |
422 (Unprocessable Entity) |
|
Der Checkout kann nicht mehr aktualisiert werden, da mehr als 25 Tage seit dem letzten Capture verstrichen sind. |
Beispielrequest
PUT /api/checkout/v1/checkouts/2deac850-363f-4171-8691-49b2db659566/deliveryInformation HTTP/1.1
Content-Type: application/json;charset=utf-8
Authorization: Bearer <access_token>
{
"expectedShippingDate" : "2016-10-19T12:00:00Z",
"logisticsProvider" : "DHL",
"trackingNumber" : "1234567890"
}
Aktualisierung der Rechnungsreferenz
PUT /api/checkout/v1/checkouts/{checkoutId}/merchantInvoiceReferenceNumber
Über diesen Endpoint kann die Rechnungsreferenz eines bereits angelegten Checkouts aktualisiert werden. Die aktuelle Rechnungsreferenz des Checkouts ist für Käufer nicht einsehbar. Aktualisierungen sind nur bis 25 Tage nach dem letzten Capture auf den Checkout gestattet.
Request
Feld | Typ | Eigenschaften | Beschreibung |
---|---|---|---|
|
String |
Optional. |
Händler-interne, eindeutige Rechnungsnummer für diesen Kauf- bzw. Zahlvorgang. Wird dem Händler in der Transaktionsübersicht angezeigt. |
Response
In der Response wird der aktualisierte Checkout zurückgegeben. Die Struktur ist identisch mit dem Checkout Endpoint GET-Aufruf.
Return Codes
Status Code | Message Code | Beschreibung |
---|---|---|
200 (Ok) |
Der Checkout wurde gefunden. |
|
401 (Unauthorized) |
|
Siehe Resource Access. |
404 (Not Found) |
|
Der zu aktualisierende Checkout existiert nicht. |
422 (Unprocessable Entity) |
|
Der Checkout kann nicht mehr aktualisiert werden, da mehr als 25 Tage seit dem letzten Capture verstrichen sind. |
Beispielrequest
PUT /api/checkout/v1/checkouts/2685d7ef-9b85-4bfc-ae24-e81e575a9501/merchantInvoiceReferenceNumber HTTP/1.1
Content-Type: application/json;charset=utf-8
Authorization: Bearer <access_token>
{
"merchantInvoiceReferenceNumber" : "12345678"
}
Capture
Durch ein Capture wird das Konto des Käufers um einen bestimmten Betrag belastet und dem Händler eine Zahlungsgarantie ausgesprochen.
Jedes Capture wird von der Käuferbank autorisiert. Eine erfolgreiche Bank-Autorisierung führt zu einer Zahlungsgarantie über den angefragten Betrag und einer entsprechenden Buchung auf dem Konto.
Dies führt je nach Ergebnis zu einem finalen Status SUCCESSFUL
oder REJECTED
.
Es gibt folgende Typen von Captures:
- CAPTURE_DIRECT_SALE
-
Wird automatisch erzeugt, wenn der Käufer einen Checkout vom Typ
DIRECT_SALE
bestätigt und die Autorisierung durch die Käuferbank erfolgreich war. - CAPTURE_ORDER
-
Nach erfolgreicher Anlage eines Checkouts vom Typ
ORDER
kann der Händler bis maximal 182 Tage nach Erstellung der Order einen oder mehrere Capture(s) vom TypCAPTURE_ORDER
erzeugen. Währenddessen ist die Anzahl der Captures unbegrenzt. Die maximale Summe aller Captures ist auf den Checkout-Betrag (totalAmount) begrenzt. Der letzte Capture sollte mit einem FlagfinalCapture
versehen werden, um die Bestellung für den Kunden zu schließen.
Eine Bestellung vom Typ ORDER
wird dem Kunden in der Transaktionsübersicht so lange als offen angezeigt, bis
-
der volle Betrag der Order abgerufen wurde und die Order dadurch automatisch geschlossen wird, oder
-
ein Capture mit finalCapture markiert wurde, oder
-
die Order explizit geschlossen wurde, oder
-
182 Tage abgelaufen sind.
Falls die genaue Höhe des Bestellbetrags bei Anlage der Order noch nicht feststeht, kann
-
die Overcapture-Funktionalität verwendet werden (siehe entsprechende Feldbeschreibung in Checkout - Anlage), oder
-
eine entsprechende Warenkorbposition verwendet werden, um den Checkout-Betrag zu erhöhen, oder
-
ein höherer Checkout-Betrag (totalAmount) angegeben werden (ohne separate Warenkorbposition).
In jedem Fall soll der Händler den Kunden auf diesen Sachverhalt bereits im Shop hinweisen. Der Käufer autorisiert immer den gesamthaften Checkout-Betrag inklusive einer möglichen Erhöhung.
Anlage
POST /api/checkout/v1/checkouts/{checkoutId}/captures
Der Endpoint zur Anlage eines Captures ist als captures -Link in der Checkout -Ressource enthalten,
sofern es sich um eine ORDER handelt und die Anlage weiterer Captures noch möglich ist.
Es sollte immer der Link aus der Checkout -Ressource verwendet werden.
|
Es wird ein neuer Capture angestoßen, um einen Betrag abzurufen. Der Capture ist nach der Generierung zunächst im Status PENDING
bis eine Prüfung durch die Käuferbank erfolgt ist, was in der Regel weniger als eine Sekunde dauert.
Request
Feld | Typ | Eigenschaften | Beschreibung |
---|---|---|---|
|
Number |
Pflichtfeld. |
Der Betrag der Zahlung in Währung der ursprünglichen Order. Der Maximalbetrag liegt bei 50 000,00 EUR. |
|
Boolean |
Optional. |
Gibt an, ob durch diesen Capture der letzte Betrag abgerufen wurde, insbesondere dann, wenn der Betrag dieser Zahlung geringer ist als der Gesamtbetrag der zugrunde liegenden Order. Die Order gilt damit als vollständig bezahlt und wird dem Kunden entsprechend als geschlossen angezeigt. Weitere Captures sind für diese Order nicht mehr möglich. |
|
String |
Optional. |
Ein Freitext für den Kunden. Der Freitext wird dem Kunden für diese Zahlung im Verwendungszweck angezeigt. |
|
String |
Optional. |
Händler-interne Referenznummer für diesen Capture-Vorgang. |
|
String |
Optional. |
Reconciliation-Nummer. Diese wird in den Verwendungszweck der Händlerzahlung eingefügt. |
|
String |
Optional. |
Händler-interne, eindeutige Rechnungsnummer für diesen Capture-Vorgang. |
|
String |
Optional. |
URL des Endpoints, der Mitteilungen zu Statusänderungen des Captures empfangen soll. |
|
Object |
Optional. |
Enthält Informationen über die Lieferung. |
|
String |
Optional. |
Erwartetes Versanddatum. |
|
String |
Optional. |
Paket-Dienstleister. |
|
String |
Optional. |
Paketnummer. |
Response
In der Response wird der angelegte Capture zurückgegeben. Die Struktur ist identisch mit dem Capture Endpoint GET-Aufruf.
Im HTTP Header Feld Location
ist die URL der angelegten Capture-Ressource, inkl.
Transaction-ID enthalten. Die Transaction-ID wird im Response Body ebenfalls zurückgegeben.
Return Codes
Status Code | Message Code | Beschreibung |
---|---|---|
201 (Created) |
Der Capture wurde erfolgreich angelegt. |
|
400 (Bad Request) |
|
Der Request ist syntaktisch ungültig. |
401 (Unauthorized) |
|
Siehe Resource Access. |
401 (Unauthorized) |
|
Der Zugriff wurde verweigert. Bitte wenden Sie sich an den paydirekt Support. |
404 (Not Found) |
|
Der Checkout wurde nicht gefunden. |
422 (Unprocessable Entity) |
|
Die Summe aller Captures übersteigt den Gesamtbetrag des Checkouts. |
422 (Unprocessable Entity) |
|
Für diesen Checkout-Typ kann kein Capture angelegt werden. |
422 (Unprocessable Entity) |
|
Es wurde versucht, ein Capture für einen bereits geschlossenen Checkout anzulegen. |
422 (Unprocessable Entity) |
|
Es wurde versucht, einen Capture für eine Order anzulegen, die vom Kunden nicht bestätigt wurde. |
422 (Unprocessable Entity) |
|
Der Capture-Betrag wurde von der Käuferbank nicht autorisiert. |
422 (Unprocessable Entity) |
|
Ihr Händlerkonto ist gesperrt. Bitte wenden Sie sich an den paydirekt Support. |
422 (Unprocessable Entity) |
|
Der Checkout wurde abgelehnt. Es kann kein Capture angelegt werden. |
422 (Unprocessable Entity) |
|
Es wurde versucht, einen Capture für einen Kunden anzulegen, welcher nicht mehr bei paydirekt teilnimmt. |
Beispiel
POST /api/checkout/v1/checkouts/bf7ae4e9-512a-4b75-a9a9-f9c3e08a8c8a/captures HTTP/1.1
Content-Type: application/json;charset=utf-8
Authorization: Bearer <access_token>
{
"amount" : 10,
"finalCapture" : false,
"note" : "Thanks for shopping.",
"merchantCaptureReferenceNumber" : "capture-21323",
"merchantReconciliationReferenceNumber" : "recon-1234",
"captureInvoiceReferenceNumber" : "invoice-1234",
"callbackUrlStatusUpdates" : "https://spielauto-versand.de/callback/status",
"deliveryInformation" : {
"expectedShippingDate" : "2016-10-19T12:00:00.000Z",
"logisticsProvider" : "DHL",
"trackingNumber" : "1234567890"
}
}
HTTP/1.1 201 Created
Location: https://api.paydirekt.de/api/checkout/v1/checkouts/bf7ae4e9-512a-4b75-a9a9-f9c3e08a8c8a/captures/8978dc99-f4b0-499e-bc7e-64a12772d4fc
Content-Type: application/hal+json;charset=utf-8
{
"type" : "CAPTURE_ORDER",
"transactionId" : "8978dc99-f4b0-499e-bc7e-64a12772d4fc",
"amount" : 10,
"merchantReconciliationReferenceNumber" : "recon-1234",
"finalCapture" : false,
"merchantCaptureReferenceNumber" : "capture-21323",
"captureInvoiceReferenceNumber" : "invoice-1234",
"callbackUrlStatusUpdates" : "https://spielauto-versand.de/callback/status",
"deliveryInformation" : {
"expectedShippingDate" : "2016-10-19T12:00:00.000Z",
"logisticsProvider" : "DHL",
"trackingNumber" : "1234567890"
},
"status" : "SUCCESSFUL",
"_links" : {
"self" : {
"href" : "https://api.paydirekt.de/api/checkout/v1/checkouts/bf7ae4e9-512a-4b75-a9a9-f9c3e08a8c8a/captures/8978dc99-f4b0-499e-bc7e-64a12772d4fc"
}
}
}
Abfrage
GET /api/checkout/v1/checkouts/{checkoutId}/captures/{captureId}
Die Abfrage liefert die Daten eines spezifischen Captures. Die Capture-Transaktionen sind in der Checkout-Resource eingebettet. Eine explizite Abfrage einer Capture-Transaktion ist im Allgemeinen nicht notwendig.
Response
Feld | Typ | Eigenschaften | Beschreibung |
---|---|---|---|
|
String |
Immer vorhanden. |
Typ der Capture-Transaktion. Entweder |
|
String |
Immer vorhanden. |
Eindeutige Transaktions-ID dieses Captures (UUID aus 36 Zeichen). Der Wert wird durch das paydirekt-System vergeben. |
|
Number |
Immer vorhanden. |
Der Betrag der Zahlung in Währung der ursprünglichen Order. Der Maximalbetrag liegt bei 50 000,00 EUR. |
|
Boolean |
Vorhanden, falls bei Anlage übergeben. |
Gibt an, ob durch diesen Capture der letzte Betrag abgerufen wurde, insbesondere dann, wenn der Betrag dieser Zahlung geringer ist als der Gesamtbetrag der zugrunde liegenden Order. Die Order gilt damit als vollständig bezahlt und wird dem Kunden entsprechend als geschlossen angezeigt. Weitere Captures sind für diese Order nicht mehr möglich. |
|
String |
Vorhanden, falls bei Anlage übergeben. |
Händler-interne Referenznummer für diesen Capture-Vorgang. |
|
String |
Vorhanden, falls bei Anlage übergeben. |
Reconciliation-Nummer. Diese wird in den Verwendungszweck der Händlerzahlung eingefügt. |
|
String |
Vorhanden, falls bei Anlage übergeben. |
Händler-interne, eindeutige Rechnungsnummer für diesen Capture-Vorgang. |
|
String |
Vorhanden, falls bei Anlage übergeben. |
URL des Endpoints, der Mitteilungen zu Statusänderungen des Checkouts empfangen soll. |
|
String |
Ist erst vorhanden, wenn die Transaktion im Zahlungsverkehr verarbeitet wurde. |
PaymentInformation-Id, die zu dieser Transaktion gehört. Sie dient der Zuordnung einzelner Transaktionen zu einer Sammelbuchung. |
|
String |
Immer vorhanden. |
Gibt an, ob die Autorisierung durch die Bank noch aussteht ( |
|
Object |
Vorhanden, falls bei Anlage übergeben. |
Enthält Informationen über die Lieferung. |
|
String |
Vorhanden, falls bei Anlage übergeben. |
Erwartetes Versanddatum. |
|
String |
Vorhanden, falls bei Anlage übergeben. |
Paket-Dienstleister. |
|
String |
Vorhanden, falls bei Anlage übergeben. |
Paketnummer. |
|
Object |
Links zu Ressourcen und verfügbaren Aktionen. |
Return Codes
Status Code | Message Code | Beschreibung |
---|---|---|
200 (Ok) |
Der Capture wurde erfolgreich gesendet. |
|
401 (Unauthorized) |
|
Siehe Resource Access. |
404 (Not Found) |
|
Der Checkout wurde nicht gefunden. |
404 (Not Found) |
|
Die Transaktion wurde nicht gefunden. |
Beispiel
GET /api/checkout/v1/checkouts/bf7ae4e9-512a-4b75-a9a9-f9c3e08a8c8a/captures/8978dc99-f4b0-499e-bc7e-64a12772d4fc HTTP/1.1
Content-Type: application/json;charset=utf-8
Authorization: Bearer <access_token>
HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=utf-8
{
"type" : "CAPTURE_ORDER",
"transactionId" : "8978dc99-f4b0-499e-bc7e-64a12772d4fc",
"amount" : 10,
"merchantReconciliationReferenceNumber" : "recon-1234",
"finalCapture" : false,
"merchantCaptureReferenceNumber" : "capture-21323",
"captureInvoiceReferenceNumber" : "invoice-1234",
"callbackUrlStatusUpdates" : "https://spielauto-versand.de/callback/status",
"deliveryInformation" : {
"expectedShippingDate" : "2016-10-19T12:00:00.000Z",
"logisticsProvider" : "DHL",
"trackingNumber" : "1234567890"
},
"status" : "SUCCESSFUL",
"paymentInformationId" : "0000000-1111-2222-3333-444444444444",
"_links" : {
"self" : {
"href" : "https://api.paydirekt.de/api/checkout/v1/checkouts/bf7ae4e9-512a-4b75-a9a9-f9c3e08a8c8a/captures/8978dc99-f4b0-499e-bc7e-64a12772d4fc"
}
}
}
Callback für Statusupdates
Händler/PSPs können bei Anlage des Captures eine Callback URL callbackUrlStatusUpdates
übergeben.
Das paydirekt-System sendet bei Statusänderungen des Captures an diese einen HTTP-Request.
Bei Verbindungsfehlern oder Responses mit einem HTTP-Statuscode von 5xx wird das paydirekt-System die Übermittlung der Statusänderung in einem Zeitfenster von 24 Stunden bis zu 5 Mal wiederholen.
Statusänderungen werden dabei immer in der Reihenfolge übermittelt, in der sie am Checkout aufgetreten sind.
Kann eine Statusänderung nicht übermittelt werden, so werden auch alle nachfolgenden Statusänderungen nicht übermittelt, bis entweder die fehlgeschlagene Übermittlung nachgeholt werden konnte oder alle wiederholten Versuche fehlgeschlagen sind.
POST callbackUrlStatusUpdates
Request
Feld | Typ | Eigenschaften | Beschreibung |
---|---|---|---|
|
String |
Immer vorhanden. |
Eindeutige UUID aus 36 Zeichen für diesen Checkout-Vorgang. Wird vom paydirekt-System vergeben. |
|
String |
Pflichtfeld. |
Händler-interne, eindeutige Bestellnummer für diesen Kaufvorgang. Wird dem Kunden in der Transaktionsübersicht angezeigt. Wird dem Händler in der Transaktionsübersicht angezeigt. Die Bestellnummer wird in der Händler-Lastschrift als |
|
String |
Immer vorhanden. |
Eindeutige Transaktions-ID dieses Captures (UUID aus 36 Zeichen). Der Wert wird durch das paydirekt-System vergeben. |
|
String |
Optional. |
Händler-interne Referenznummer für diesen Capture-Vorgang. |
|
String |
Immer vorhanden. |
Gibt an, ob die Autorisierung durch die Bank noch aussteht ( |
|
String |
Immer vorhanden. |
Zeitstempel der Statusänderung. |
|
Number |
Immer vorhanden. |
Sequenznummer der Statusänderung. Anhand der Sequenznummer kann ein Shop die Reihenfolge der Statusänderungen nachvollziehen und gegebenenfalls fehlende Statusänderungen erkennen. |
Beispiel
POST /webhooktest/v1/capture/status HTTP/1.1
Content-Type: application/json;charset=utf-8
{
"checkoutId" : "060f9016-c995-44d6-8a36-c55a34a3a4a8",
"merchantOrderReferenceNumber" : "order-A12223412",
"transactionId" : "8eba8017-a5da-46fd-8fc2-dd917d32865a",
"captureStatus" : "SUCCESSFUL",
"merchantCaptureReferenceNumber" : "3aeeea9d-713f-437f-b342-eaa29b39ac49",
"statusUpdateTimestamp" : "2020-01-01T12:00:00.000Z",
"sequenceNumber" : 2
}
Order (Secured) schließen
POST /api/checkout/v1/checkouts/{checkoutId}/close
Bestellungen vom Typ ORDER
als auch ORDER_SECURED
können und sollen im paydirekt-System geschlossen werden,
wenn für die Bestellung kein weiterer CAPTURE
durchgeführt werden wird.
Damit wird die Bestellung dem Kunden nicht weiter als offen angezeigt.
Bestellungen können nur geschlossen werden, wenn sie vorher vom Kunden durch seinen Login bestätigt worden sind.
Request
Die Anfrage benötigt keinen Request Body.
Response
In der Response wird der angelegte Checkout zurückgegeben. Die Struktur ist identisch mit dem Checkout Endpoint GET-Aufruf des Checkouts.
Return Codes
Status Code | Message Code | Beschreibung |
---|---|---|
200 (OK) |
Die Bestellung wurde erfolgreich geschlossen. |
|
401 (Unauthorized) |
|
Siehe Resource Access. |
422 (Unprocessable Entity) |
|
Die Bestellung ist vom Kunden nicht bestätigt worden. Unbestätigte Bestellungen können nicht geschlossen werden. |
422 (Unprocessable Entity) |
|
Die Bestellung ist bereits geschlossen. |
422 (Unprocessable Entity) |
|
Dieser Checkout ist nicht vom Typ |
Refund
Für Bestellungen können Rückzahlungen (Refunds) an den Kunden angestoßen werden.
Die Anlage eines Refunds bezieht sich immer auf einen gesamten Checkout und nicht auf einen konkreten Capture.
Ein Refund ist nur nach erfolgreichen Direct Sales und Orders mit mindestens einem erfolgreichen Capture möglich.
In diesem Fall ist an der Checkout-Resource ein refunds
-Link vorhanden. Der Rückzahlungsbetrag ist auf maximal 200% der Summe der bisher getätigten Zahlungen limitiert.
Refunds sind zeitlich und in der Anzahl unbeschränkt möglich, sofern der maximale Rückzahlungsbetrag nicht überschritten wird.
Anlage
POST /api/checkout/v1/checkouts/{checkoutId}/refunds
Der Endpoint zur Anlage eines Refunds ist als refunds -Link in der Checkout -Ressource enthalten,
sofern der Checkout eine Rückzahlung ermöglicht. Der Endpoint sollte nicht direkt aufgerufen werden.
Es sollte immer der Link aus der Checkout -Ressource verwendet werden.
|
Mit der Erzeugung einer Refund-Ressource wird eine Rückzahlung an den Kunden initiiert.
Request
Feld | Typ | Eigenschaften | Beschreibung |
---|---|---|---|
|
Number |
Pflichtfeld. |
Der Betrag der Rückzahlung in Währung der ursprünglichen Bestellung. Die Summe der Rückzahlungen für eine Bestellung ist begrenzt durch den im Feld refundLimit gegebenen Prozentwert des Gesamtwertes der Bestellung. |
|
String |
Optional. |
Ein Freitext für den Kunden. Der Freitext wird dem Kunden im Verwendungszweck angezeigt. |
|
String |
Optional. |
Grund des Refunds |
|
String |
Optional. |
Händler-interne Referenznummer für diesen Refund-Vorgang. |
|
String |
Optional. |
Reconciliation-Nummer. Diese wird in den Verwendungszweck der Händlerzahlung eingefügt. |
|
String |
Optional. |
URL des Endpoints, der Mitteilungen zu Statusänderungen des Refunds empfangen soll. |
Response
In der Response werden die Daten des angelegten Refunds zurückgegeben. Die Struktur ist identisch mit dem Refund Endpoint GET-Aufruf.
Im HTTP Header Feld Location
ist die URL der angelegten Refund-Ressource, inkl.
Transaction-ID enthalten. Die Transaction-ID wird im Response Body ebenfalls zurückgegeben.
Return Codes
Status Code | Message Code | Beschreibung |
---|---|---|
201 (Refund created) |
Der Refund wurde erfolgreich angelegt. Er befindet sich im Status |
|
400 (Bad Request) |
VALIDATION_ERROR |
Der Request ist syntaktisch ungültig. |
401 (Unauthorized) |
|
Siehe Resource Access. |
401 (Unauthorized) |
UNAUTHORIZED |
Der Zugriff wurde verweigert. Bitte wenden Sie sich an den paydirekt Support. |
404 (Not Found) |
CHECKOUT_NOT_FOUND |
Der Checkout wurde nicht gefunden, oder Sie haben keine Zugriff auf diesen Checkout. |
422 (Unprocessable Entity) |
REFUND_AMOUNT_EXCEEDED |
Die Summe aller Rückzahlungen übersteigt die maximale Rückzahlungssumme. |
422 (Unprocessable Entity) |
USER_DEBOARDED |
Der Käuferaccount wurde endgültig geschlossen. |
Beispiel
POST /api/checkout/v1/checkouts/cb5d2624-3f2e-4aed-b546-fb5dd73f04f9/refunds HTTP/1.1
Content-Type: application/json;charset=utf-8
Authorization: Bearer <access_token>
{
"amount" : 10,
"note" : "Ihre Bestellung vom 31.03.2015",
"merchantRefundReferenceNumber" : "refund-99989",
"merchantReconciliationReferenceNumber" : "recon-1234",
"reason" : "MERCHANT_CAN_NOT_DELIVER_GOODS",
"callbackUrlStatusUpdates" : "https://spielauto-versand.de/callback/status"
}
HTTP/1.1 201 Created
Location: https://api.paydirekt.de/api/checkout/v1/checkouts/cb5d2624-3f2e-4aed-b546-fb5dd73f04f9/refunds/7b13f884-4833-45ab-b0aa-f074ca878239
Content-Type: application/hal+json;charset=utf-8
{
"type" : "REFUND",
"transactionId" : "7b13f884-4833-45ab-b0aa-f074ca878239",
"amount" : 10,
"merchantReconciliationReferenceNumber" : "recon-1234",
"note" : "Ihre Bestellung vom 31.03.2015",
"merchantRefundReferenceNumber" : "refund-99989",
"status" : "PENDING",
"reason" : "MERCHANT_CAN_NOT_DELIVER_GOODS",
"callbackUrlStatusUpdates" : "https://spielauto-versand.de/callback/status",
"_links" : {
"self" : {
"href" : "https://api.paydirekt.de/api/checkout/v1/checkouts/cb5d2624-3f2e-4aed-b546-fb5dd73f04f9/refunds/7b13f884-4833-45ab-b0aa-f074ca878239"
}
}
}
Abfrage
GET /api/checkout/v1/checkouts/{checkoutId}/refunds/{refundId}
Liefert die Daten zu einer Rückzahlung. Nach einer Initiierung eines Refunds befindet sich der Refund mindestens einen Tag
im Status PENDING
. Es wird empfohlen, den Status 1-2 mal pro Tag abzufragen, bis ein finaler Status (SUCCESS
oder FAILED
)
erreicht ist.
Die Refund-Transaktionen sind in der Checkout-Ressource embedded. Refundinformationen können also auch durch Abfrage des zugehörigen Checkouts abgerufen werden. |
Response
Feld | Typ | Eigenschaften | Beschreibung |
---|---|---|---|
|
String |
Immer vorhanden. |
Typ der Transaktion. Hier immer |
|
String |
Immer vorhanden. |
Eindeutige Transaktions-ID dieses Refunds (UUID aus 36 Zeichen). Der Wert wird durch das paydirekt-System vergeben. |
|
Number |
Immer vorhanden. |
Der Betrag der Rückzahlung in Währung der ursprünglichen Bestellung. Die Summe der Rückzahlungen für eine Bestellung ist begrenzt durch den im Feld refundLimit gegebenen Prozentwert des Gesamtwertes der Bestellung. |
|
String |
Vorhanden, falls bei Anlage übergeben. |
Ein Freitext für den Kunden. Der Freitext wird dem Kunden im Verwendungszweck angezeigt. |
|
String |
Optional. |
Grund des Refunds |
|
String |
Vorhanden, falls bei Anlage übergeben. |
Händler-interne Referenznummer für diesen Refund-Vorgang. |
|
String |
Vorhanden, falls bei Anlage übergeben. |
Reconciliation-Nummer. Diese wird in den Verwendungszweck der Händlerzahlung eingefügt. |
|
String |
Dieses Feld ist erst vorhanden, wenn die Transaktion im Zahlungsverkehr verarbeitet wurde. |
PaymentInformation-Id, die zu dieser Transaktion gehört. Sie dient der Zuordnung einzelner Transaktionen zu einer Sammelbuchung. |
|
String |
Vorhanden, falls bei Anlage übergeben. |
URL des Endpoints, der Mitteilungen zu Statusänderungen des Refunds empfangen soll. |
|
String |
Immer vorhanden. |
Status des Refunds |
|
Object |
Links zu Ressourcen und verfügbaren Aktionen. |
Return Codes
Status Code | Message Code | Beschreibung |
---|---|---|
200 (Ok) |
Die Anfrage wurde korrekt verarbeitet. |
|
401 (Unauthorized) |
|
Siehe Resource Access. |
404 (Not Found) |
|
Der Checkout wurde nicht gefunden, oder Sie haben keine Zugriff auf diesen Checkout. |
404 (Not Found) |
|
Die Rückzahlung mit der angegebenen |
Beispiel
GET /api/checkout/v1/checkouts/cb5d2624-3f2e-4aed-b546-fb5dd73f04f9/refunds/7b13f884-4833-45ab-b0aa-f074ca878239 HTTP/1.1
Content-Type: application/json;charset=utf-8
Authorization: Bearer <access_token>
HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=utf-8
{
"type" : "REFUND",
"transactionId" : "7b13f884-4833-45ab-b0aa-f074ca878239",
"amount" : 10,
"merchantReconciliationReferenceNumber" : "recon-1234",
"note" : "Ihre Bestellung vom 31.03.2015",
"merchantRefundReferenceNumber" : "refund-99989",
"status" : "PENDING",
"reason" : "MERCHANT_CAN_NOT_DELIVER_GOODS",
"callbackUrlStatusUpdates" : "https://spielauto-versand.de/callback/status",
"paymentInformationId" : "0000000-1111-2222-3333-444444444444",
"_links" : {
"self" : {
"href" : "https://api.paydirekt.de/api/checkout/v1/checkouts/cb5d2624-3f2e-4aed-b546-fb5dd73f04f9/refunds/7b13f884-4833-45ab-b0aa-f074ca878239"
}
}
}
Callback für Statusupdates
Händler/PSPs können bei Anlage des Refunds eine Callback URL callbackUrlStatusUpdates
übergeben.
Das paydirekt-System sendet bei Statusänderungen des Refunds an diese einen HTTP-Request.
Bei Verbindungsfehlern oder Responses mit einem HTTP-Statuscode von 5xx wird das paydirekt-System die Übermittlung der Statusänderung in einem Zeitfenster von 24 Stunden bis zu 5 Mal wiederholen.
Statusänderungen werden dabei immer in der Reihenfolge übermittelt, in der sie am Checkout aufgetreten sind.
Kann eine Statusänderung nicht übermittelt werden, so werden auch alle nachfolgenden Statusänderungen nicht übermittelt, bis entweder die fehlgeschlagene Übermittlung nachgeholt werden konnte oder alle wiederholten Versuche fehlgeschlagen sind.
POST callbackUrlStatusUpdates
Request
Feld | Typ | Eigenschaften | Beschreibung |
---|---|---|---|
|
String |
Immer vorhanden. |
Eindeutige UUID aus 36 Zeichen für diesen Checkout-Vorgang. Wird vom paydirekt-System vergeben. |
|
String |
Immer vorhanden. |
Eindeutige Transaktions-ID dieses Refunds (UUID aus 36 Zeichen). Der Wert wird durch das paydirekt-System vergeben. |
|
String |
Optional. |
Händler-interne Referenznummer für diesen Refund-Vorgang. |
|
String |
Optional. |
Reconciliation-Nummer. Diese wird in den Verwendungszweck der Händlerzahlung eingefügt. |
|
String |
Status des Refunds |
|
|
String |
Immer vorhanden. |
Zeitstempel der Statusänderung. |
|
Number |
Immer vorhanden. |
Sequenznummer der Statusänderung. Anhand der Sequenznummer kann ein Shop die Reihenfolge der Statusänderungen nachvollziehen und gegebenenfalls fehlende Statusänderungen erkennen. |
Beispiel
POST /webhooktest/v1/refund/status HTTP/1.1
Content-Type: application/json;charset=utf-8
{
"checkoutId" : "d7ded1f3-f595-410a-82a0-03429f08a1ab",
"transactionId" : "f75c1502-e398-46b1-b5c2-5d474b8bbf77",
"merchantRefundReferenceNumber" : "refund-12345",
"merchantReconciliationReferenceNumber" : "reconciliation-12345",
"refundStatus" : "SUCCESSFUL",
"statusUpdateTimestamp" : "2020-01-01T12:00:00.000Z",
"sequenceNumber" : 2
}
Express
paydirekt Express ermöglicht die Bezahlung mit Rückmeldung der Versandadresse an den Händler. Auf diese Weise ist eine Bestellung möglich, ohne dass der Kunde seine Adresse beim Händler eingeben oder ein Käuferkonto anlegen muss. Wir haben dafür hier eine Auswahl an Buttons hinterlegt, die Sie in Ihren Shop einbinden können.
Der Kunde kann bei paydirekt Express während des Bezahlvorgangs eine seiner bei paydirekt hinterlegten Lieferadressen auswählen. Das paydirekt-System kann dabei dem Händler eine anonymisierte Vorschau aller Lieferadressen des Kunden übermitteln. Daraufhin kann er für jede Lieferadresse zurückmelden, ob und mit welchen Versandoptionen und -kosten die Adresse beliefert werden kann.
Alternativ kann Der Händler bei der Anlage des Checkouts fixe Versandkosten angeben. In diesem Fall wird angenommen, dass der Händler jede beliebige Lieferadresse mit diesen Versandkosten beliefern kann. Sollte der Händler die vom Kunden gewählte Lieferadresse doch nicht beliefern können, kann das Händlersystem den Bezahlvorgang abbrechen, indem es die Zahlung nicht abschließt.
Um die Zahlung abzuschließen, muss nach der Bestätigung durch den Kunden im paydirekt System noch der execute-Link aufgerufen werden, um die Zahlung final zu bestätigen. Typischerweise erfolgt hier eine Weiterleitung zurück auf den Shop und der Kunde wird aufgefordert, die AGB des Händlers zu bestätigen.
Falls Sie diese Art des Zahlverfahrens umsetzen wollen, nehmen Sie bitte vorher unter haendler@paydirekt.de Kontakt mit uns auf, damit wir Sie individuell begleiten können. |

Anlage
POST /api/checkout/v1/checkouts
Die Anlage eines neuen Checkouts erfolgt analog zur Anlage eines regulären Checkouts. Es können alle Typen von Checkouts (Direct Sale und Vorbestellungen) angelegt werden.
Ein Express-Checkout wird durch das Flag express
signalisiert.
Die Angabe einer Lieferadresse ist hingegen nicht vorgesehen, da diese vom Kunden im paydirekt-System ausgewählt wird.
Wenn das Händlersystem die Lieferadressen des Kunden vorfiltern und mit Versandoptionen versehen will, muss die URL des Callback-Endpoints angegeben werden.
Alternativ kann es einen shippingAmount
und einen totalAmount
unter der Annahme angeben, dass alle Lieferadressen des Kunden zu diesen Lieferkosten beliefert werden können.
In jedem Fall muss zwingend ein Link zu den Lieferbedingungen angegeben werden.
Request
Feld | Typ | Eigenschaften | Beschreibung |
---|---|---|---|
|
String |
Pflichtfeld. |
Die Art der Bestellung: |
|
Boolean |
Pflichtfeld für Express-Checkout. |
Flag, gibt an, dass es sich um einen Express-Checkout handelt. Muss |
|
Number |
Pflichtfeld. |
Der Gesamtbetrag der Bestellung, inkl. aller Lieferkosten. Es werden maximal 2 Nachkommastellen unterstützt. |
|
Number |
Optional. |
Die wahrscheinlichen Versandkosten der Bestellung für einen Standard-Versand nach Deutschland. Dieser Wert kann später durch eine andere Versandoption durch den Kunden verändert werden. Wenn keine |
|
Number |
Optional. |
Der Warenwert der Bestellung, ohne Versandkosten. Dieser Wert wird nicht für Berechnungen verwendet, sondern dient nur zur Information. |
|
Number |
Optional. |
Maximal zurückzahlbarer Betrag als Prozentwert des Gesamtwertes der Bestellung. |
|
Boolean |
Optional. |
Flag für Overcapture-Checkouts. |
|
String |
Pflichtfeld. |
Die Währung des Gesamtbetrags. Derzeit wird nur EUR unterstützt. |
|
Array von Items |
Optional. |
Die einzelnen Positionen des Warenkorbs. |
|
String |
Optional. |
Kategorisiert den Warenkorb eines Checkouts anhand der Eigenschaften der enthaltenen Güter: Der Standardwert ist |
|
String |
Optional. |
Der Bestimmungsort einer Lieferung: |
|
String |
Optional. |
Händler-interne Kundennummer des Käufers. Wird dem Kunden in der Transaktionsübersicht angezeigt. Wird dem Händler in der Transaktionsübersicht angezeigt. |
|
String |
Optional. |
Vorläufige Händler-interne, eindeutige Bestellnummer für diesen Kaufvorgang. Wird dem Kunden in der Transaktionsübersicht angezeigt. Wird dem Händler in der Transaktionsübersicht angezeigt. Die Bestellnummer wird in der Händler-Lastschrift als |
|
String |
Optional. |
Händler-interne, eindeutige Rechnungsnummer für diesen Kauf- bzw. Zahlvorgang. Wird dem Händler in der Transaktionsübersicht angezeigt. |
|
String |
Optional. |
Reconciliation-Nummer. Diese wird bei Direct-Sales in den Verwendungszweck der Händlerzahlung eingefügt. Bei Vorbestellungen wird stattdessen die bei Anlage der Captures gesetzte |
|
String |
Optional. |
Die E-Mail Adresse des Käufers als Base-64 encodierter SHA-256 Hash-Wert ohne Padding, sofern vorhanden. Pseudo-Code: |
|
String |
Pflichtfeld, außer bei oneKlick-Checkouts. |
Die Rücksprung-Adresse des Webshops (inkl. Referenz auf die Bestellung), die nach erfolgreicher Bezahlung aufgerufen wird. |
|
String |
Pflichtfeld, außer bei oneKlick-Checkouts. |
Die Rücksprung-Adresse des Webshops (inkl. Referenz auf die Bestellung), die im Falle eines Abbruchs oder technischen Fehlers aufgerufen wird. Damit wird signalisiert, dass der Kaufvorgang grundsätzlich fortgeführt werden kann und im Anschluss ein weiterer, neuer Checkout initiiert werden kann, beispielsweise, weil der Kunde noch einen Artikel in der Bestellung hinzufügen möchte. |
|
String |
Pflichtfeld, außer bei oneKlick-Checkouts. |
Die Rücksprung-Adresse des Webshops (inkl. Referenz auf die Bestellung), die im Falle einer Abweisung der Zahlung aufgerufen wird. Damit wird signalisiert, dass keine Zahlung autorisiert wurde (z. B. aufgrund falscher TAN-Eingabe, fehlender Bank-Autorisierung oder Betrugsverdacht). Falls das Webshop-System keine Unterscheidung zwischen redirectUrlAfterCancellation und redirectUrlAfterRejection unterstützt, kann in beiden Feldern die gleiche URL angegeben werden. |
|
String |
Optional. |
URL des Endpoints, der Mitteilungen zu Statusänderungen des Checkouts empfangen soll. |
|
Number |
Optional. |
Das Mindestalter (in Jahren), das der Käufer erreicht haben muss, um die Bestellung ausführen zu dürfen, beispielsweise, weil sie Artikel enthält, die einer Altersbeschränkung unterliegen (Filme, Computerspiele, …). Die Prüfung erfolgt direkt nach dem Login des Käufers in das paydirekt-System. Bei erfolgreicher Verifikation wird der Ablauf ohne weitere Meldung wie gewohnt fortgesetzt. Bei nicht-erfolgreicher Verifikation, d. h. der Kunde hat das erforderliche Mindestalter noch nicht erreicht, erfolgt eine Umleitung auf den Link |
|
String |
Pflichtfeld, wenn |
Die Rücksprung-Adresse des Webshops (inkl. Referenz auf die Bestellung), die im Falle einer nicht erfolgreichen Altersverifikation aufgerufen wird. Damit wird signalisiert, dass die Bestellung abgebrochen wurde, da der Käufer das erforderliche Mindestalter für mindestens einen Artikel in der Bestellung noch nicht erreicht hat. Dieses Feld wird im Falle einer geforderten Altersverifikation, d. h. bei Angabe des Feldes |
|
String |
Optional. |
Freitextfeld, das auf dem Kontoauszug im Feld Verwendungzweck erscheint (nur |
|
Number |
Optional. |
Zahl, die die Gültigkeit des Checkouts ab Anlage in Sekunden angibt. Bei Nicht-Angabe werden 1800 Sekunden angenommen. |
|
String |
Optional für Express-Checkouts. |
URL zum Callback, der für eine Liste von Destinationen Rechnungs- und Lieferadressen des Kunden prüft. Falls nicht übergeben, kann der Kunde beliebige Adressen für den Checkout verwenden. Versandoptionen können nicht gewählt werden. Es gelten die am Checkout übermittelten Beträge. |
|
String |
Pflichtfeld für Express-Checkouts. |
Link zu einer Webseite mit den Versandbedingungen des Händlers. |
Response
Feld | Typ | Eigenschaften | Beschreibung |
---|---|---|---|
|
String |
Immer vorhanden. |
Eindeutige UUID aus 36 Zeichen für diesen Checkout-Vorgang. Wird vom paydirekt-System vergeben. |
|
String |
Immer vorhanden. |
Die Art der Bestellung: |
|
Boolean |
Immer vorhanden bei Express-Checkouts. |
Flag, gibt an, dass es sich um einen Express-Checkout handelt. Muss |
|
String |
Immer vorhanden. |
Status des Checkouts: |
|
String |
Immer vorhanden. |
Der Erzeugungszeitpunkt dieses Checkouts. Wird vom paydirekt-System vergeben. Formatierung entsprechend ISO-8601 durch den Standard Java DateTimeFormatter. Abweichend davon werden immer drei Nachkommastellen für die Millisekunden ausgegeben. |
|
String |
Immer vorhanden. |
Der Ablaufzeitpunkt dieses Checkouts. Kann über das Feld |
|
Number |
Immer vorhanden. |
Der Gesamtbetrag der Bestellung, inkl. aller Lieferkosten. Es werden maximal 2 Nachkommastellen unterstützt. |
|
Number |
Immer vorhanden. |
Die wahrscheinlichen Versandkosten der Bestellung für einen Standard-Versand nach Deutschland. Dieser Wert kann später durch eine andere Versandoption durch den Kunden verändert werden. Wenn keine |
|
Number |
Immer vorhanden. |
Der Warenwert der Bestellung, ohne Versandkosten. Dieser Wert wird nicht für Berechnungen verwendet, sondern dient nur zur Information. |
|
Number |
Vorhanden, falls bei Anlage übergeben. |
Maximal zurückzahlbarer Betrag als Prozentwert des Gesamtwertes der Bestellung. |
|
String |
Immer vorhanden. |
Die Währung des Gesamtbetrags. Derzeit wird nur EUR unterstützt. |
|
Array von Items |
Vorhanden, falls bei Anlage übergeben. |
Die einzelnen Positionen des Warenkorbs. |
|
Boolean |
Vorhanden, falls bei Anlage übergeben. |
Flag für Overcapture-Checkouts. |
|
Number |
Vorhanden, falls Overcapture-Flag gesetzt. |
Bei gesetztem Overcapture-Flag enthält dieses Feld den maximalen Betrag, der insgesamt abgerufen werden kann. |
|
Number |
Vorhanden, falls Overcapture-Flag vorhanden. |
Bei gesetztem Overcapture-Flag enthält dieses Feld den zum Gesamtbetrag zusätzlichen Betrag, der in der Summe abgerufen werden kann. |
|
String |
Vorhanden, falls bei Anlage übergeben. |
Kategorisiert den Warenkorb eines Checkouts anhand der Eigenschaften der enthaltenen Güter: Der Standardwert ist |
|
String |
Vorhanden, falls bei Anlage übergeben. |
Der Bestimmungsort einer Lieferung: |
|
String |
Vorhanden, falls bei Anlage übergeben. |
Händler-interne Kundennummer des Käufers. Wird dem Kunden in der Transaktionsübersicht angezeigt. Wird dem Händler in der Transaktionsübersicht angezeigt. |
|
String |
Immer vorhanden. |
Händler-interne, eindeutige Bestellnummer für diesen Kaufvorgang. Wird dem Kunden in der Transaktionsübersicht angezeigt. Wird dem Händler in der Transaktionsübersicht angezeigt. Die Bestellnummer wird in der Händler-Lastschrift als |
|
String |
Vorhanden, falls bei Anlage übergeben. |
Händler-interne, eindeutige Rechnungsnummer für diesen Kauf- bzw. Zahlvorgang. Wird dem Händler in der Transaktionsübersicht angezeigt. |
|
String |
Vorhanden, falls bei Anlage übergeben. |
Reconciliation-Nummer. Diese wird bei Direct-Sales in den Verwendungszweck der Händlerzahlung eingefügt. Bei Vorbestellungen wird stattdessen die bei Anlage der Captures gesetzte |
|
String |
Immer vorhanden, außer bei oneKlick-Checkouts. |
Die Rücksprung-Adresse des Webshops (inkl. Referenz auf die Bestellung), die nach erfolgreicher Bezahlung aufgerufen wird. |
|
String |
Immer vorhanden, außer bei oneKlick-Checkouts. |
Die Rücksprung-Adresse des Webshops (inkl. Referenz auf die Bestellung), die im Falle eines Abbruchs oder technischen Fehlers aufgerufen wird. Damit wird signalisiert, dass der Kaufvorgang grundsätzlich fortgeführt werden kann und im Anschluss ein weiterer, neuer Checkout initiiert werden kann, beispielsweise, weil der Kunde noch einen Artikel in der Bestellung hinzufügen möchte. |
|
String |
Immer vorhanden, außer bei oneKlick-Checkouts. |
Die Rücksprung-Adresse des Webshops (inkl. Referenz auf die Bestellung), die im Falle einer Abweisung der Zahlung aufgerufen wird. Damit wird signalisiert, dass keine Zahlung autorisiert wurde (z. B. aufgrund falscher TAN-Eingabe, fehlender Bank-Autorisierung oder Betrugsverdacht). Falls das Webshop-System keine Unterscheidung zwischen redirectUrlAfterCancellation und redirectUrlAfterRejection unterstützt, kann in beiden Feldern die gleiche URL angegeben werden. |
|
String |
Vorhanden, falls bei Anlage übergeben. |
URL des Endpoints, der Mitteilungen zu Statusänderungen des Checkouts empfangen soll. |
|
String |
Vorhanden, falls bei Anlage übergeben. |
URL zum Callback, der für eine Liste von Destinationen Rechnungs- und Lieferadressen des Kunden prüft. Falls nicht übergeben, kann der Kunde beliebige Adressen für den Checkout verwenden. Versandoptionen können nicht gewählt werden. Es gelten die am Checkout übermittelten Beträge. |
|
String |
Immer vorhanden bei Express-Checkouts. |
Link zu einer Webseite mit den Versandbedingungen des Händlers. |
|
Number |
Vorhanden, falls bei Anlage übergeben. |
Das Mindestalter (in Jahren), das der Käufer erreicht haben muss, um die Bestellung ausführen zu dürfen, beispielsweise, weil sie Artikel enthält, die einer Altersbeschränkung unterliegen (Filme, Computerspiele, …). Die Prüfung erfolgt direkt nach dem Login des Käufers in das paydirekt-System. Bei erfolgreicher Verifikation wird der Ablauf ohne weitere Meldung wie gewohnt fortgesetzt. Bei nicht-erfolgreicher Verifikation, d. h. der Kunde hat das erforderliche Mindestalter noch nicht erreicht, erfolgt eine Umleitung auf den Link |
|
String |
Vorhanden, falls bei Anlage übergeben. |
Die Rücksprung-Adresse des Webshops (inkl. Referenz auf die Bestellung), die im Falle einer nicht erfolgreichen Altersverifikation aufgerufen wird. Damit wird signalisiert, dass die Bestellung abgebrochen wurde, da der Käufer das erforderliche Mindestalter für mindestens einen Artikel in der Bestellung noch nicht erreicht hat. Dieses Feld wird im Falle einer geforderten Altersverifikation, d. h. bei Angabe des Feldes |
|
String |
Vorhanden, falls bei Anlage übergeben. |
Freitextfeld, das auf dem Kontoauszug im Feld Verwendungzweck erscheint (nur |
|
Object |
Links zu Ressourcen und verfügbaren Aktionen des Checkouts. |
Return Codes
siehe Return Codes.
Beispiel
POST /api/checkout/v1/checkouts HTTP/1.1
Content-Type: application/json;charset=utf-8
Authorization: Bearer <access_token>
{
"type" : "DIRECT_SALE",
"express" : true,
"totalAmount" : 100.0,
"shippingAmount" : 3.5,
"orderAmount" : 96.5,
"refundLimit" : 200,
"items" : [ {
"quantity" : 3,
"name" : "Bobbycar",
"ean" : "800001303",
"price" : 25.99
}, {
"quantity" : 1,
"name" : "Helm",
"price" : 18.53
} ],
"shoppingCartType" : "MIXED",
"deliveryType" : "PACKSTATION",
"currency" : "EUR",
"overcapture" : false,
"merchantCustomerNumber" : "cust-732477",
"merchantOrderReferenceNumber" : "order-A12223412",
"merchantReconciliationReferenceNumber" : "recon-A12223412",
"merchantInvoiceReferenceNumber" : "20150112334345",
"note" : "Ihr Einkauf bei Spielauto-Versand.",
"sha256hashedEmailAddress" : "fxP4R-IxH1Eaxpb0f_i5Shc8-FrYrtmx5lx35f9Xzgg",
"minimumAge" : 18,
"expiryTime" : 1800,
"redirectUrlAfterSuccess" : "https://spielauto-versand.de/order/123/success",
"redirectUrlAfterCancellation" : "https://spielauto-versand.de/order/123/cancellation",
"redirectUrlAfterAgeVerificationFailure" : "https://spielauto-versand.de/order/123/ageverification",
"redirectUrlAfterRejection" : "https://spielauto-versand.de/order/123/rejection",
"callbackUrlCheckDestinations" : "https://spielauto-versand.de/destinations/check",
"callbackUrlStatusUpdates" : "https://spielauto-versand.de/callback/status",
"webUrlShippingTerms" : "https://spielauto-versand.de//shippingterms"
}
HTTP/1.1 201 Created
Location: https://api.paydirekt.de/api/checkout/v1/checkouts/c7ef2cd9-325a-40b4-8aa1-eee246cfd130
Content-Type: application/hal+json;charset=utf-8
{
"checkoutId" : "c7ef2cd9-325a-40b4-8aa1-eee246cfd130",
"type" : "DIRECT_SALE",
"express" : true,
"status" : "OPEN",
"creationTimestamp" : "2021-08-03T12:24:58.310Z",
"totalAmount" : 100.0,
"shippingAmount" : 3.5,
"orderAmount" : 96.5,
"refundLimit" : 200,
"currency" : "EUR",
"items" : [ {
"quantity" : 3,
"name" : "Bobbycar",
"ean" : "800001303",
"price" : 25.99
}, {
"quantity" : 1,
"name" : "Helm",
"price" : 18.53
} ],
"shoppingCartType" : "MIXED",
"deliveryType" : "PACKSTATION",
"merchantOrderReferenceNumber" : "order-A12223412",
"merchantCustomerNumber" : "cust-732477",
"merchantInvoiceReferenceNumber" : "20150112334345",
"merchantReconciliationReferenceNumber" : "recon-A12223412",
"note" : "Ihr Einkauf bei Spielauto-Versand.",
"minimumAge" : 18,
"redirectUrlAfterSuccess" : "https://spielauto-versand.de/order/123/success",
"redirectUrlAfterCancellation" : "https://spielauto-versand.de/order/123/cancellation",
"redirectUrlAfterAgeVerificationFailure" : "https://spielauto-versand.de/order/123/ageverification",
"redirectUrlAfterRejection" : "https://spielauto-versand.de/order/123/rejection",
"callbackUrlStatusUpdates" : "https://spielauto-versand.de/callback/status",
"callbackUrlCheckDestinations" : "https://spielauto-versand.de/destinations/check",
"webUrlShippingTerms" : "https://spielauto-versand.de//shippingterms",
"expiryTimestamp" : "2021-08-03T12:54:58.310Z",
"_links" : {
"approve" : {
"href" : "https://localhost/checkout/?p=c7ef2cd9-325a-40b4-8aa1-eee246cfd130#/checkout/c7ef2cd9-325a-40b4-8aa1-eee246cfd130"
},
"updateDeliveryInformation" : {
"href" : "https://api.paydirekt.de/api/checkout/v1/checkouts/c7ef2cd9-325a-40b4-8aa1-eee246cfd130/deliveryInformation"
},
"updateMerchantInvoiceReferenceNumber" : {
"href" : "https://api.paydirekt.de/api/checkout/v1/checkouts/c7ef2cd9-325a-40b4-8aa1-eee246cfd130/merchantInvoiceReferenceNumber"
},
"self" : {
"href" : "https://api.paydirekt.de/api/checkout/v1/checkouts/c7ef2cd9-325a-40b4-8aa1-eee246cfd130"
}
}
}
Abfrage
GET /api/checkout/v1/checkouts/{checkoutId}
Die Abfrage erfolgt analog zur regulären Checkout Endpoint GET-Abfrage.
Nach der erfolgreichen Bestätigung des Checkouts durch den Kunden werden über diesen Aufruf die vom Kunden gewählte, vollständige Rechnungsadresse, Versandadresse und Versandoption bereitgestellt, eingebettet in die regulären Daten des Checkouts.
Außerdem ist der Link zur tatsächlichen Ausführung des Checkouts enthalten.
Response
Feld | Typ | Eigenschaften | Beschreibung |
---|---|---|---|
|
String |
Immer vorhanden. |
Eindeutige UUID aus 36 Zeichen für diesen Checkout-Vorgang. Wird vom paydirekt-System vergeben. |
|
String |
Immer vorhanden. |
Die Art der Bestellung: |
|
Boolean |
Immer vorhanden bei Express-Checkouts. |
Flag, gibt an, dass es sich um einen Express-Checkout handelt. Muss |
|
String |
Immer vorhanden. |
Status des Checkouts: |
|
String |
Immer vorhanden. |
Der Erzeugungszeitpunkt dieses Checkouts. Wird vom paydirekt-System vergeben. Formatierung entsprechend ISO-8601 durch den Standard Java DateTimeFormatter. Abweichend davon werden immer drei Nachkommastellen für die Millisekunden ausgegeben. |
|
String |
Immer vorhanden. |
Der Ablaufzeitpunkt dieses Checkouts. Kann über das Feld |
|
Number |
Immer vorhanden. |
Der Gesamtbetrag der Bestellung, inkl. aller Lieferkosten. Es werden maximal 2 Nachkommastellen unterstützt. |
|
Number |
Immer vorhanden. |
Die wahrscheinlichen Versandkosten der Bestellung für einen Standard-Versand nach Deutschland. Dieser Wert kann später durch eine andere Versandoption durch den Kunden verändert werden. Wenn keine |
|
Array von Items |
Vorhanden, falls bei Anlage übergeben. |
Die einzelnen Positionen des Warenkorbs. |
|
String |
Vorhanden, falls bei Anlage übergeben. |
Kategorisiert den Warenkorb eines Checkouts anhand der Eigenschaften der enthaltenen Güter: Der Standardwert ist |
|
String |
Vorhanden, falls bei Anlage übergeben. |
Der Bestimmungsort einer Lieferung: |
|
Number |
Vorhanden, falls bei Anlage übergeben. |
Der Warenwert der Bestellung, ohne Versandkosten. Dieser Wert wird nicht für Berechnungen verwendet, sondern dient nur zur Information. |
|
Number |
Vorhanden, falls bei Anlage übergeben. |
Maximal zurückzahlbarer Betrag als Prozentwert des Gesamtwertes der Bestellung. |
|
String |
Immer vorhanden. |
Die Währung des Gesamtbetrags. Derzeit wird nur EUR unterstützt. |
|
Boolean |
Vorhanden, falls bei Anlage übergeben. |
Flag für Overcapture-Checkouts. |
|
Number |
Vorhanden, falls Overcapture-Flag gesetzt. |
Bei gesetztem Overcapture-Flag enthält dieses Feld den maximalen Betrag, der insgesamt abgerufen werden kann. |
|
Number |
Vorhanden, falls Overcapture-Flag vorhanden. |
Bei gesetztem Overcapture-Flag enthält dieses Feld den zum Gesamtbetrag zusätzlichen Betrag, der in der Summe abgerufen werden kann. |
|
String |
Vorhanden, sobald sich ein Kunde eingeloggt hat. UUID aus 36 Zeichen. |
Die eindeutige Identifikation des Checkouts und aller dazugehöriger Transaktionen. |
|
String |
Vorhanden, falls bei Anlage übergeben. |
Freitextfeld, das auf dem Kontoauszug im Feld Verwendungzweck erscheint (nur |
|
Vorhanden bei Express-Checkouts nach dem Wechsel in den Status |
Die vom Kunden angegebene, vollständige Lieferadresse. |
|
|
Object |
Vorhanden bei Express-Checkouts nach dem Wechsel in den Status |
Die vom Kunden ausgewählte Versandoption. |
|
Vorhanden bei Express-Checkouts nach dem Wechsel in den Status |
Die vom Kunden angegebene, vollständige Rechnungsadresse. |
|
|
String |
Vorhanden bei Express-Checkouts nach dem Wechsel in den Status |
Die E-Mail Adresse des Kunden. |
|
String |
Vorhanden, falls bei Anlage übergeben. |
Händler-interne Kundennummer des Käufers. Wird dem Kunden in der Transaktionsübersicht angezeigt. Wird dem Händler in der Transaktionsübersicht angezeigt. |
|
String |
Immer vorhanden. |
Händler-interne, eindeutige Bestellnummer für diesen Kaufvorgang. Wird dem Kunden in der Transaktionsübersicht angezeigt. Wird dem Händler in der Transaktionsübersicht angezeigt. Die Bestellnummer wird in der Händler-Lastschrift als |
|
String |
Vorhanden, falls bei Anlage übergeben. |
Händler-interne, eindeutige Rechnungsnummer für diesen Kauf- bzw. Zahlvorgang. Wird dem Händler in der Transaktionsübersicht angezeigt. |
|
String |
Vorhanden, falls bei Anlage übergeben. |
Reconciliation-Nummer. Diese wird bei Direct-Sales in den Verwendungszweck der Händlerzahlung eingefügt. Bei Vorbestellungen wird stattdessen die bei Anlage der Captures gesetzte |
|
Number |
Vorhanden, falls bei Anlage übergeben. |
Das Mindestalter (in Jahren), das der Käufer erreicht haben muss, um die Bestellung ausführen zu dürfen, beispielsweise, weil sie Artikel enthält, die einer Altersbeschränkung unterliegen (Filme, Computerspiele, …). Die Prüfung erfolgt direkt nach dem Login des Käufers in das paydirekt-System. Bei erfolgreicher Verifikation wird der Ablauf ohne weitere Meldung wie gewohnt fortgesetzt. Bei nicht-erfolgreicher Verifikation, d. h. der Kunde hat das erforderliche Mindestalter noch nicht erreicht, erfolgt eine Umleitung auf den Link |
|
String |
Immer vorhanden, außer bei oneKlick-Checkouts. |
Die Rücksprung-Adresse des Webshops (inkl. Referenz auf die Bestellung), die nach erfolgreicher Bezahlung aufgerufen wird. |
|
String |
Immer vorhanden, außer bei oneKlick-Checkouts. |
Die Rücksprung-Adresse des Webshops (inkl. Referenz auf die Bestellung), die im Falle eines Abbruchs oder technischen Fehlers aufgerufen wird. Damit wird signalisiert, dass der Kaufvorgang grundsätzlich fortgeführt werden kann und im Anschluss ein weiterer, neuer Checkout initiiert werden kann, beispielsweise, weil der Kunde noch einen Artikel in der Bestellung hinzufügen möchte. |
|
String |
Immer vorhanden, außer bei oneKlick-Checkouts. |
Die Rücksprung-Adresse des Webshops (inkl. Referenz auf die Bestellung), die im Falle einer Abweisung der Zahlung aufgerufen wird. Damit wird signalisiert, dass keine Zahlung autorisiert wurde (z. B. aufgrund falscher TAN-Eingabe, fehlender Bank-Autorisierung oder Betrugsverdacht). Falls das Webshop-System keine Unterscheidung zwischen redirectUrlAfterCancellation und redirectUrlAfterRejection unterstützt, kann in beiden Feldern die gleiche URL angegeben werden. |
|
String |
Vorhanden, falls bei Anlage übergeben. |
Die Rücksprung-Adresse des Webshops (inkl. Referenz auf die Bestellung), die im Falle einer nicht erfolgreichen Altersverifikation aufgerufen wird. Damit wird signalisiert, dass die Bestellung abgebrochen wurde, da der Käufer das erforderliche Mindestalter für mindestens einen Artikel in der Bestellung noch nicht erreicht hat. Dieses Feld wird im Falle einer geforderten Altersverifikation, d. h. bei Angabe des Feldes |
|
String |
Vorhanden, falls bei Anlage übergeben. |
URL des Endpoints, der Mitteilungen zu Statusänderungen des Checkouts empfangen soll. |
|
String |
Vorhanden, falls bei Anlage übergeben. |
URL zum Callback, der für eine Liste von Destinationen Rechnungs- und Lieferadressen des Kunden prüft. Falls nicht übergeben, kann der Kunde beliebige Adressen für den Checkout verwenden. Versandoptionen können nicht gewählt werden. Es gelten die am Checkout übermittelten Beträge. |
|
String |
Immer vorhanden bei Express-Checkouts. |
Link zu einer Webseite mit den Versandbedingungen des Händlers. |
|
Object |
Links zu Ressourcen und verfügbaren Aktionen des Checkouts. |
Beispiel
GET /api/checkout/v1/checkouts/c7ef2cd9-325a-40b4-8aa1-eee246cfd130 HTTP/1.1
Content-Type: application/json;charset=utf-8
Authorization: Bearer <access_token>
HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=utf-8
{
"checkoutId" : "c7ef2cd9-325a-40b4-8aa1-eee246cfd130",
"type" : "DIRECT_SALE",
"express" : true,
"status" : "PENDING",
"correlationId" : "ext0815-00000003",
"creationTimestamp" : "2021-08-03T12:24:58.310Z",
"totalAmount" : 106.5,
"shippingAmount" : 10.0,
"orderAmount" : 96.5,
"refundLimit" : 200,
"currency" : "EUR",
"items" : [ {
"quantity" : 3,
"name" : "Bobbycar",
"ean" : "800001303",
"price" : 25.99
}, {
"quantity" : 1,
"name" : "Helm",
"price" : 18.53
} ],
"shoppingCartType" : "MIXED",
"deliveryType" : "PACKSTATION",
"shippingAddress" : {
"addresseeGivenName" : "Hans",
"addresseeLastName" : "Mustermann",
"street" : "Musterstr.",
"streetNr" : "1",
"zip" : "12345",
"city" : "Musterstadt",
"countryCode" : "DE"
},
"merchantOrderReferenceNumber" : "order-A12223412",
"merchantCustomerNumber" : "cust-732477",
"merchantInvoiceReferenceNumber" : "20150112334345",
"merchantReconciliationReferenceNumber" : "recon-A12223412",
"note" : "Ihr Einkauf bei Spielauto-Versand.",
"minimumAge" : 18,
"redirectUrlAfterSuccess" : "https://spielauto-versand.de/order/123/success",
"redirectUrlAfterCancellation" : "https://spielauto-versand.de/order/123/cancellation",
"redirectUrlAfterAgeVerificationFailure" : "https://spielauto-versand.de/order/123/ageverification",
"redirectUrlAfterRejection" : "https://spielauto-versand.de/order/123/rejection",
"callbackUrlStatusUpdates" : "https://spielauto-versand.de/callback/status",
"callbackUrlCheckDestinations" : "https://spielauto-versand.de/destinations/check",
"webUrlShippingTerms" : "https://spielauto-versand.de//shippingterms",
"shippingOption" : {
"code" : "1234",
"name" : "DHL",
"description" : "DHL ist toll.",
"amount" : 10.0
},
"billingAddress" : {
"addresseeGivenName" : "Hans",
"addresseeLastName" : "Mustermann",
"street" : "Musterstr.",
"streetNr" : "1",
"zip" : "12345",
"city" : "Musterstadt",
"countryCode" : "DE"
},
"buyerEmailAddress" : "hannes.schroeder@senacor.com",
"expiryTimestamp" : "2021-08-03T12:54:58.310Z",
"_links" : {
"execute" : {
"href" : "https://api.paydirekt.de/api/checkout/v1/checkouts/c7ef2cd9-325a-40b4-8aa1-eee246cfd130/execute"
},
"updateDeliveryInformation" : {
"href" : "https://api.paydirekt.de/api/checkout/v1/checkouts/c7ef2cd9-325a-40b4-8aa1-eee246cfd130/deliveryInformation"
},
"updateMerchantInvoiceReferenceNumber" : {
"href" : "https://api.paydirekt.de/api/checkout/v1/checkouts/c7ef2cd9-325a-40b4-8aa1-eee246cfd130/merchantInvoiceReferenceNumber"
},
"self" : {
"href" : "https://api.paydirekt.de/api/checkout/v1/checkouts/c7ef2cd9-325a-40b4-8aa1-eee246cfd130"
}
}
}
Ausführung
POST /api/checkout/v1/checkouts/{checkoutId}/execute
Aus rechtlichen Gründen muss der Käufer den Kauf im Händlershop abschließen und explizit bestätigen.
Beim Klick auf den Kaufen-Button des Shops teilt der Händler dem paydirekt-System mit, ob der Kaufabschluss erfolgt ist. Im Fall Direct Sale findet zudem die Zahlungsautorisierung statt.
Der Checkout bleibt so lange im Status PENDING
, bis die Bestätigung eingegangen ist.
Anschließend wechselt der Checkout in den Status APPROVED
, sofern die Zahlung durch die Bank erfolgreich war,
sonst REJECTED
.
Die Bestätigung muss innerhalb von 30 Minuten nach Anlage des Checkouts erfolgen.
Request
Feld | Typ | Eigenschaften | Beschreibung |
---|---|---|---|
|
String |
Pflichtfeld. |
Zeitpunkt, an dem der Kunde die Geschäfts- und Lieferbedingungen im Webshop akzeptiert hat. |
|
String |
Pflichtfeld. |
Endgültige Händler-interne, eindeutige Bestellnummer für diesen Kaufvorgang. Wird dem Kunden in der Transaktionsübersicht angezeigt. Wird dem Händler in der Transaktionsübersicht angezeigt. Die Bestellnummer wird in der Händler-Lastschrift als |
Response
Kein Response Body.
Return Codes
Status Code | Message Code | Beschreibung |
---|---|---|
200 (OK) |
Die Ausführung des Checkouts war erfolgreich. |
|
400 (Bad Request) |
VALIDATION_ERROR |
Der Request ist syntaktisch ungültig. |
401 (Unauthorized) |
|
Siehe Resource Access. |
401 (Unauthorized) |
UNAUTHORIZED |
Der Zugriff wurde verweigert. Bitte wenden Sie sich an den paydirekt Support. |
404 (Not Found) |
CHECKOUT_NOT_FOUND |
Der Checkout wurde nicht gefunden. |
409 (Conflict) |
CHECKOUT_ALREADY_EXECUTED |
Die Bestellung wurde bereits ausgeführt. |
422 (Unprocessable Entity) |
CHECKOUT_REJECTED |
Die Zahlung konnte nicht bestätigt werden, da diese von der Bank des Käufers abgelehnt wurde. Die Bestellung ist somit nicht erfolgreich! |
422 (Unprocessable Entity) |
CHECKOUT_INVALIDATED |
Die Ausführung ist nicht möglich, da der Checkout mittlerweile abgelaufen ist oder vom Kunden abgebrochen wurde. Die Ausführung muss innerhalb von 30 Minuten nach Anlage des Checkouts erfolgen. |
422 (Unprocessable Entity) |
NOT_A_EXPRESS_CHECKOUT |
Bei diesem Checkout handelt es sich nicht um einen Express Checkout. |
422 (Unprocessable Entity) |
INVALID_STATUS |
Der Checkout kann nicht ausgeführt werden (z. B. weil dieser vom Kunden nicht bestätigt, abgebrochen oder abgelehnt wurde). |
Beispiel
POST /api/checkout/v1/checkouts/18a2e3e6-34ab-4911-b6fe-6ab26e7dcf8f/execute HTTP/1.1
Content-Type: application/json;charset=utf-8
Authorization: Bearer <access_token>
{
"termsAcceptedTimestamp" : "2015-09-16T16:58:37+02:00",
"merchantOrderReferenceNumber" : "order-A12223412"
}
HTTP/1.1 200 OK
Callback für Adressprüfung
POST callbackUrlCheckDestinations
Wenn der Händler die Lieferadressen des Kunden validieren und mit Lieferoptionen versehen will, muss er einen optionalen Endpoint zur Verfügung stellen, der prüft, ob Versand- und Rechnungsadressen für eine Bestellung valide sind, welche Versandoptionen es gibt und wie hoch die Versandkosten sind.
Der Endpoint muss über HTTPS abgesichert sein.
Die URL des Endpoints kann bei der Anlage des Checkouts im Feld callbackUrlCheckDestinations
angegeben werden. Hier kann auch eine ID oder ein Token zur Referenz auf die Bestellung enthalten sein, falls auf weitere Informationen zur Bestellung bzw. zu den Bestellpositionen zugegriffen werden soll (z. B. Gewicht, Gefahrgüter).
Das paydirekt-System ruft diesen Endpoint nach dem Login des Benutzers einmal oder mehrfach auf (Callback).
Aus Datenschutzgründen werden nicht die vollständigen Adressdaten übermittelt, sondern nur die relevanten Informationen des Bestimmungsorts (Destination):
-
Land als Ländercode im zweistelligen ISO 3166-1 Format
-
Postleitzahl
-
Flag, ob es sich um eine Packstation handelt
Die vom Benutzer ausgewählte, vollständige Liefer- und Versandadresse, sowie die gewählte Versandoption, werden im Checkout gespeichert und können später, nachdem der Kunde die Zahlung bestätigt hat, abgerufen werden.
Wenn der Endpoint nicht erreichbar ist, wird der Checkout mit einem technischen Fehler abgebrochen.
Request
Feld | Typ | Eigenschaften | Beschreibung |
---|---|---|---|
|
String |
Immer vorhanden. |
Eindeutige UUID aus 36 Zeichen für diesen Checkout-Vorgang. Wird vom paydirekt-System vergeben. |
|
String |
Immer vorhanden. |
Händler-interne, eindeutige Bestellnummer für diesen Kaufvorgang. |
|
Number |
Optional. |
Der Warenwert der Bestellung, ohne Versandkosten. Dieser Wert wird nicht für Berechnungen verwendet, sondern dient nur zur Information. |
|
Array |
Immer vorhanden. |
Ein Array von möglichen Rechnungs- und Lieferadressen des Kunden, mit der Angabe des Lands, der Postleitzahl und ob es sich um eine Packstation handelt. |
|
String |
Immer vorhanden. |
Eindeutige ID der Destination. |
|
String |
Immer vorhanden. |
Der Ländercode im ISO 3166-1 Format. |
|
String |
Optional. |
Postleitzahl. |
|
Boolean |
Optional. |
Flag, ob es sich um eine Packstation handelt. |
Response
Feld | Typ | Eigenschaften | Beschreibung |
---|---|---|---|
|
Array |
Pflichtfeld. |
Ein Array von geprüften Rechnungs- und Lieferadressen des Kunden mit Angabe möglicher Lieferoptionen. |
|
String |
Pflichtfeld. |
Eindeutige ID der Destination. |
|
String |
Pflichtfeld. |
Der Ländercode im ISO 3166-1 Format. |
|
String |
Optional. |
Postleitzahl. |
|
Boolean |
Optional. |
Flag, ob es sich um eine Packstation handelt. |
|
Boolean |
Pflichtfeld. |
Flag, ob die Destination als Rechnungsadresse verwendet werden kann. |
|
Boolean |
Pflichtfeld. |
Flag, ob die Destination als Lieferadresse verwendet werden kann. |
|
Array |
Pflichtfeld. |
Ein Array von möglichen Versandoptionen für diese Destination. Wert ist eine Zahl zwischen 0 und 10 sein. |
|
String |
Pflichtfeld. |
Ein Händler-interner Code zur Identifizierung der Versandoption. Wird später im Checkout zurückgegeben. |
|
String |
Pflichtfeld. |
Die Bezeichnung der Versandoption (in Deutsch). Wird dem Kunden zur Auswahl angezeigt. |
|
String |
Pflichtfeld. |
Die Beschreibung der Versandoption (in Deutsch). Wird dem Kunden zur Auswahl angezeigt. |
|
Number |
Pflichtfeld. |
Die Versandkosten für diese Versandoption. Wird dem Kunden zur Auswahl angezeigt. |
Beispiel
POST /paydirekt/v1/order/order-A12223412/destinations/check HTTP/1.1
Content-Type: application/json;charset=utf-8
Authorization: Bearer <access_token>
{
"checkoutId" : "4f498d16-c6ce-48f3-81ed-4e2ac32daae1",
"merchantOrderReferenceNumber" : "order-A12223412",
"orderAmount" : 96.5,
"destinations" : [ {
"id" : "f1ef551a-c380-402e-a853-b4d31740d643",
"countryCode" : "DE",
"zip" : "91781",
"dhlPackstation" : false
} ]
}
HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
{
"checkedDestinations" : [ {
"id" : "f1ef551a-c380-402e-a853-b4d31740d643",
"countryCode" : "DE",
"zip" : "91781",
"dhlPackstation" : false,
"validBillingDestination" : true,
"validShippingDestination" : true,
"shippingOptions" : [ {
"code" : "DHL_PAKET",
"name" : "DHL Paket",
"description" : "Lieferung am nächsten Werktag",
"amount" : 6.99
} ]
} ]
}
Callback für Statusupdates
Händler/PSPs können auch bei der Anlage von Express-Checkouts eine Callback URL callbackUrlStatusUpdates
übergeben. Das paydirekt-System versendet dann die gleichen Benachrichtigungen wie bei normalen Checkouts.
Reports
Transaktionen
GET /api/reporting/v1/reports/transactions
PSPs und CPSPs können Reports über die Transaktionen abrufen, die von den ihm zugeordneten Shops bzw. Händlern durchgeführt wurden.
Die Abfrage von Reports ist nur möglich,
wenn bei der Authentifizierung nur der PSP API-Key übergeben wurde,
aber kein Shop API-Key.
Als CPSP darf ebenfalls nur der eigene API-Key übergeben worden sein, aber keine X-Auth-Merchant-Ref
.
Die Anfrage kann hierbei durch optionale from
und to
Parameter eingeschränkt werden, die den Zeitrahmen des Reports angeben.
Bei Weglassen der Werte wird to
auf den aktuellen Zeitpunkt gesetzt; from
wird bei Nicht-Angabe auf 30 Tage vor to
gesetzt.
Der Report kann maximal 180 Tage oder 50.000 Transaktionen umfassen. Wird einer der beiden Werte überschritten, wird ein Fehler zurückgeliefert. In diesem Fall muss ein kleinerer Zeitrahmen gewählt werden.
Durch die Angabe des Accept-Headers wird das Format des Reports gewählt. Valide Werte sind application/json
und text/csv
.
Query-Parameter
Name | Constraints | Description |
---|---|---|
|
Optional. |
Zeitstempel im ISO-8601-Format, ab dem Transaktionen berücksichtigt werden. Falls nicht angegeben, werden die 30 Tage seit dem |
|
Optional. |
Zeitstempel im ISO-8601-Format, bis zu dem Transaktionen berücksichtigt werden. Falls nicht angegeben, wird bis zum aktuellen Zeitpunkt abgefragt. |
|
Optional. Mögliche Feldbezeichner sind case-sensitive und unter Transaktionen aufgezählt. |
Eine Liste mit Feldbezeichnern für Transaktionen. Für den Transaktionsreport im CSV-Format bestimmt |
Response-Felder
Feld | Typ | Eigenschaften | Beschreibung |
---|---|---|---|
|
Array |
Immer vorhanden. Kann eine leere Liste sein. |
Liste von Transaktionen, die den angeforderten Report darstellen. |
Transaction
Jeder Reporting-Datensatz repräsentiert eine Transaktion. Die Datensätze sind aufsteigend nach transactionDate
sortiert.
Feld | Typ | Eigenschaften | Beschreibung |
---|---|---|---|
|
String |
UUID aus 36 Zeichen. |
Die Vorgangsnummer des Checkouts, um eine eindeutige Zuordnung zu ermöglichen. |
|
String |
UUID aus 32 Zeichen plus Präfix |
End-zu-End-Referenznummer des Checkouts. |
|
String |
|
Kennziffer des Transaktionstyps. |
|
String |
Zeitstempel nach ISO8601. |
Zeitpunkt der Transaktion. |
|
String |
Datum nach ISO8601. |
Valuta-Datum der Transaktion. |
|
String |
UUID aus 36 Zeichen. |
ID des Händler-Vertrages. |
|
String |
UUID aus 36 Zeichen. |
ID des Händlers. |
|
String |
Maximal 100 Zeichen. |
Name des Händlers. |
|
String |
Maximal 34 Stellen, i.d.R. 22. |
IBAN des Händlerkontos. |
|
String |
Maximal 20 Zeichen. Nur SEPA-konforme Zeichen. |
Händler-interne, eindeutige Bestellnummer für diesen Kaufvorgang. Entspricht der bei Anlage des Checkouts übergebenen |
|
String |
Händler-interne Referenznummer für diesen Capture- oder Refundvorgang. Entspricht je nach Transaktionstyp der bei Anlage übergebenen |
|
|
String |
UUID aus 36 Zeichen. |
ID des Checkouts. |
|
String |
Maximal 20 Zeichen. |
Die bei Anlage des Checkouts vom PSP übergebene |
|
String |
UUID aus 36 Zeichen. |
ID der Bank des Händlers. |
|
String |
UUID aus 36 Zeichen. |
ID der Bank des Käufers. |
|
String |
Maximal 100 Zeichen. |
Kurzname der Bank des Käufers. |
|
Number |
Zwischen 0.01 und 50000.00, zwei Nachkommastellen. |
Der Transaktionsbetrag. |
|
String |
Derzeit immer |
Währung der Transaktion. |
|
String |
UUID aus 36 Zeichen. |
ID des Händlerkonzentrators. |
|
String |
Maximal 100 Zeichen. |
Name des Händlerkonzentrators. |
|
String |
UUID aus 36 Zeichen. |
ID des Konzentrators des Käufers. |
|
String |
Maximal 100 Zeichen. |
Name des Konzentrators des Käufers. |
|
String |
UUID aus 36 Zeichen. |
ID des Shops. |
|
String |
Maximal 100 Zeichen. |
Name des Shops. |
|
String |
|
Ergebnis der Altersprüfung. |
|
String |
|
Gibt an, ob es sich um einen Express-Checkout handelt. |
|
String |
UUID aus 36 Zeichen. |
Eindeutige Payment-Information-ID der SEPA-Transaktion. |
|
String |
Vierstellige Zahl. |
MCC (Merchant Category Code) des Händlers. |
|
String |
Vierstellige Zahl. |
DBI (Details Business Indicator) des Händlers. |
|
String |
|
Der bei der Refundanlage angegebene |
|
String |
Maximal 20 Zeichen. |
Die bei Anlage des Captures vom PSP übergebene |
Return Codes
Status Code | Message Code | Beschreibung |
---|---|---|
200 (Ok) |
Die Anfrage wurde korrekt verarbeitet. |
|
401 (Unauthorized) |
|
Siehe Resource Access. |
404 (Not Found) |
Sie haben keinen Zugriff auf diese Ressource. Möglicherweise fehlt die Authentifizierung. |
|
422 (Unprocessable Entity) |
|
Mindestens einer der über |
422 (Unprocessable Entity) |
|
Der angefragte Report war zu groß. Entweder überschritt er die 180-Tage-Grenze oder enthielt mehr als 50.000 Elemente. |
Beispiel
GET /api/reporting/v1/reports/transactions?from=2021-07-16T12:10:54.966Z&to=2021-07-21T12:10:54.966Z&fields= HTTP/1.1
Content-Type: application/json;charset=utf-8
Accept: application/json
Authorization: Bearer <access_token>
HTTP/1.1 200 OK
Content-Type: application/json;charset=utf-8
{
"transactions" : [ {
"correlationId" : "2619a4ed-342a-4299-917e-19f9e8c60fee",
"endToEndReferenceNumber" : "0b60c9c4-1682-4030-b3de-d4f2c1ce9f60",
"transactionTypeId" : "1",
"transactionDate" : "2021-07-21T12:10:54.933Z",
"valueDate" : "2021-07-21",
"contractId" : "a9793641-a6b8-4b17-a20b-064cdc533fb6",
"merchantId" : "606e0cca-8ecf-416c-b635-91ca9abda080",
"merchantName" : "Some merchant name",
"merchantIban" : "DE12500105170648489890",
"merchantReference" : "db9c80d4-7dc8-431f-af72-c1ce335b6890",
"checkoutId" : "ced0fef3-8256-41eb-a4f5-b6b55fcead4f",
"checkoutInvoiceNr" : "44c49fee-3b7a-4e48-97ea-9a3a9d62e5d5",
"merchantTransactionReferenceNumber" : "ebf7237c-2dfd-41ef-a14e-edea32634c99",
"merchantBankId" : "370885c4-30cb-49c0-83a0-a948a91fa64a",
"buyerBankId" : "1834b4ba-7c5e-42e1-8db5-d1b56e9ad817",
"buyerBankName" : "Buyer Bank Name",
"transactionAmount" : "1.00",
"transactionCurrency" : "EUR",
"merchantAgentId" : "5c11c60c-dfa8-4efb-bda7-99f022af1be7",
"merchantAgentName" : "Merchant Broker Name",
"concentratorId" : "980a2d95-a5f6-4836-a87e-a49a78503f1b",
"concentratorName" : "Buyer Bank Concentrator",
"shopId" : "440c9255-e8e7-4c28-9f3e-57554510713a",
"shopName" : "Some shop name",
"ageVerificationStatus" : "1",
"paydirektExpress" : "n",
"paymentInformationId" : "a119017a-a0e7-4ceb-bff2-82a1227ad308",
"refundReason" : "TECHNICAL_PROBLEM",
"captureInvoiceNr" : "8e36c89e-17a0-4213-8837-93e1c1730dec",
"validityDate" : "2021-07-26",
"MCC" : "742",
"DBI" : "743"
}, {
"correlationId" : "2619a4ed-342a-4299-917e-19f9e8c60fee",
"endToEndReferenceNumber" : "0b60c9c4-1682-4030-b3de-d4f2c1ce9f60",
"transactionTypeId" : "1",
"transactionDate" : "2021-07-21T12:10:54.933Z",
"valueDate" : "2021-07-21",
"contractId" : "a9793641-a6b8-4b17-a20b-064cdc533fb6",
"merchantId" : "606e0cca-8ecf-416c-b635-91ca9abda080",
"merchantName" : "Some merchant name",
"merchantIban" : "DE12500105170648489890",
"merchantReference" : "db9c80d4-7dc8-431f-af72-c1ce335b6890",
"checkoutId" : "ced0fef3-8256-41eb-a4f5-b6b55fcead4f",
"checkoutInvoiceNr" : "44c49fee-3b7a-4e48-97ea-9a3a9d62e5d5",
"merchantTransactionReferenceNumber" : "ebf7237c-2dfd-41ef-a14e-edea32634c99",
"merchantBankId" : "370885c4-30cb-49c0-83a0-a948a91fa64a",
"buyerBankId" : "1834b4ba-7c5e-42e1-8db5-d1b56e9ad817",
"buyerBankName" : "Buyer Bank Name",
"transactionAmount" : "1.00",
"transactionCurrency" : "EUR",
"merchantAgentId" : "5c11c60c-dfa8-4efb-bda7-99f022af1be7",
"merchantAgentName" : "Merchant Broker Name",
"concentratorId" : "980a2d95-a5f6-4836-a87e-a49a78503f1b",
"concentratorName" : "Buyer Bank Concentrator",
"shopId" : "440c9255-e8e7-4c28-9f3e-57554510713a",
"shopName" : "Some shop name",
"ageVerificationStatus" : "1",
"paydirektExpress" : "n",
"paymentInformationId" : "a119017a-a0e7-4ceb-bff2-82a1227ad308",
"refundReason" : "TECHNICAL_PROBLEM",
"captureInvoiceNr" : "8e36c89e-17a0-4213-8837-93e1c1730dec",
"validityDate" : "2021-07-26",
"MCC" : "742",
"DBI" : "743"
}, {
"correlationId" : "2619a4ed-342a-4299-917e-19f9e8c60fee",
"endToEndReferenceNumber" : "0b60c9c4-1682-4030-b3de-d4f2c1ce9f60",
"transactionTypeId" : "1",
"transactionDate" : "2021-07-21T12:10:54.933Z",
"valueDate" : "2021-07-21",
"contractId" : "a9793641-a6b8-4b17-a20b-064cdc533fb6",
"merchantId" : "606e0cca-8ecf-416c-b635-91ca9abda080",
"merchantName" : "Some merchant name",
"merchantIban" : "DE12500105170648489890",
"merchantReference" : "db9c80d4-7dc8-431f-af72-c1ce335b6890",
"checkoutId" : "ced0fef3-8256-41eb-a4f5-b6b55fcead4f",
"checkoutInvoiceNr" : "44c49fee-3b7a-4e48-97ea-9a3a9d62e5d5",
"merchantTransactionReferenceNumber" : "ebf7237c-2dfd-41ef-a14e-edea32634c99",
"merchantBankId" : "370885c4-30cb-49c0-83a0-a948a91fa64a",
"buyerBankId" : "1834b4ba-7c5e-42e1-8db5-d1b56e9ad817",
"buyerBankName" : "Buyer Bank Name",
"transactionAmount" : "1.00",
"transactionCurrency" : "EUR",
"merchantAgentId" : "5c11c60c-dfa8-4efb-bda7-99f022af1be7",
"merchantAgentName" : "Merchant Broker Name",
"concentratorId" : "980a2d95-a5f6-4836-a87e-a49a78503f1b",
"concentratorName" : "Buyer Bank Concentrator",
"shopId" : "440c9255-e8e7-4c28-9f3e-57554510713a",
"shopName" : "Some shop name",
"ageVerificationStatus" : "1",
"paydirektExpress" : "n",
"paymentInformationId" : "a119017a-a0e7-4ceb-bff2-82a1227ad308",
"refundReason" : "TECHNICAL_PROBLEM",
"captureInvoiceNr" : "8e36c89e-17a0-4213-8837-93e1c1730dec",
"validityDate" : "2021-07-26",
"MCC" : "742",
"DBI" : "743"
}, {
"correlationId" : "2619a4ed-342a-4299-917e-19f9e8c60fee",
"endToEndReferenceNumber" : "0b60c9c4-1682-4030-b3de-d4f2c1ce9f60",
"transactionTypeId" : "1",
"transactionDate" : "2021-07-21T12:10:54.933Z",
"valueDate" : "2021-07-21",
"contractId" : "a9793641-a6b8-4b17-a20b-064cdc533fb6",
"merchantId" : "606e0cca-8ecf-416c-b635-91ca9abda080",
"merchantName" : "Some merchant name",
"merchantIban" : "DE12500105170648489890",
"merchantReference" : "db9c80d4-7dc8-431f-af72-c1ce335b6890",
"checkoutId" : "ced0fef3-8256-41eb-a4f5-b6b55fcead4f",
"checkoutInvoiceNr" : "44c49fee-3b7a-4e48-97ea-9a3a9d62e5d5",
"merchantTransactionReferenceNumber" : "ebf7237c-2dfd-41ef-a14e-edea32634c99",
"merchantBankId" : "370885c4-30cb-49c0-83a0-a948a91fa64a",
"buyerBankId" : "1834b4ba-7c5e-42e1-8db5-d1b56e9ad817",
"buyerBankName" : "Buyer Bank Name",
"transactionAmount" : "1.00",
"transactionCurrency" : "EUR",
"merchantAgentId" : "5c11c60c-dfa8-4efb-bda7-99f022af1be7",
"merchantAgentName" : "Merchant Broker Name",
"concentratorId" : "980a2d95-a5f6-4836-a87e-a49a78503f1b",
"concentratorName" : "Buyer Bank Concentrator",
"shopId" : "440c9255-e8e7-4c28-9f3e-57554510713a",
"shopName" : "Some shop name",
"ageVerificationStatus" : "1",
"paydirektExpress" : "n",
"paymentInformationId" : "a119017a-a0e7-4ceb-bff2-82a1227ad308",
"refundReason" : "TECHNICAL_PROBLEM",
"captureInvoiceNr" : "8e36c89e-17a0-4213-8837-93e1c1730dec",
"validityDate" : "2021-07-26",
"MCC" : "742",
"DBI" : "743"
}, {
"correlationId" : "2619a4ed-342a-4299-917e-19f9e8c60fee",
"endToEndReferenceNumber" : "0b60c9c4-1682-4030-b3de-d4f2c1ce9f60",
"transactionTypeId" : "1",
"transactionDate" : "2021-07-21T12:10:54.933Z",
"valueDate" : "2021-07-21",
"contractId" : "a9793641-a6b8-4b17-a20b-064cdc533fb6",
"merchantId" : "606e0cca-8ecf-416c-b635-91ca9abda080",
"merchantName" : "Some merchant name",
"merchantIban" : "DE12500105170648489890",
"merchantReference" : "db9c80d4-7dc8-431f-af72-c1ce335b6890",
"checkoutId" : "ced0fef3-8256-41eb-a4f5-b6b55fcead4f",
"checkoutInvoiceNr" : "44c49fee-3b7a-4e48-97ea-9a3a9d62e5d5",
"merchantTransactionReferenceNumber" : "ebf7237c-2dfd-41ef-a14e-edea32634c99",
"merchantBankId" : "370885c4-30cb-49c0-83a0-a948a91fa64a",
"buyerBankId" : "1834b4ba-7c5e-42e1-8db5-d1b56e9ad817",
"buyerBankName" : "Buyer Bank Name",
"transactionAmount" : "1.00",
"transactionCurrency" : "EUR",
"merchantAgentId" : "5c11c60c-dfa8-4efb-bda7-99f022af1be7",
"merchantAgentName" : "Merchant Broker Name",
"concentratorId" : "980a2d95-a5f6-4836-a87e-a49a78503f1b",
"concentratorName" : "Buyer Bank Concentrator",
"shopId" : "440c9255-e8e7-4c28-9f3e-57554510713a",
"shopName" : "Some shop name",
"ageVerificationStatus" : "1",
"paydirektExpress" : "n",
"paymentInformationId" : "a119017a-a0e7-4ceb-bff2-82a1227ad308",
"refundReason" : "TECHNICAL_PROBLEM",
"captureInvoiceNr" : "8e36c89e-17a0-4213-8837-93e1c1730dec",
"validityDate" : "2021-07-26",
"MCC" : "742",
"DBI" : "743"
} ]
}
Allgemeine Datentypen
Neben den Standard JSON-Datentypen gibt es komplexe Datentypen, die für einen ordentlichen Request benötigt werden.
ShippingAddress
Datentyp für Liefer- und Rechnungsadressen.
Feld | Typ | Eigenschaften | Beschreibung |
---|---|---|---|
|
String |
Optional bei als |
Vorname. |
|
String |
Optional bei als |
Nachname. |
|
String |
Optional. |
Firmenname. |
|
String |
Optional. |
Adresszusatz. |
|
String |
Optional. |
Der Name der Straße, ohne Hausnummer. |
|
String |
Optional. |
Die Hausnummer. |
|
String |
Optional bei als |
Die Postleitzahl. |
|
String |
Optional bei als |
Die Stadt. |
|
String |
Optional bei als |
Der Ländercode im ISO 3166-1 Format. |
|
String |
Optional |
Bundesland oder Bundesstaat. Kann zum Beispiel bei Auslandsadressen verwendet werden. |
|
String |
Pflichtfeld bei als |
Die Email-Adresse des Käufers. |
{
"addresseeGivenName" : "Hermann",
"addresseeLastName" : "Meyer",
"street" : "Wieseneckstraße",
"streetNr" : "26",
"zip" : "90571",
"city" : "Schwaig bei Nürnberg",
"countryCode" : "DE",
}
Beispiel mit internationaler Adresse mit Bundesland
{
"addresseeGivenName" : "John",
"addresseeLastName" : "Smith",
"street" : "Main St",
"streetNr" : "799 E",
"zip" : "85705",
"city" : "Tucson",
"countryCode" : "US",
"state" : " AZ
}
Item
Ein Item ist eine Warenkorbposition.
Feld | Typ | Eigenschaften | Beschreibung |
---|---|---|---|
|
Number |
Pflichtfeld. |
Die Anzahl der Positionen für diesen Artikel. |
|
String |
Pflichtfeld. |
Die Bezeichnung des Artikel. |
|
String |
Optional. |
Die International Article Number (EAN bzw. GTIN) des Artikels. |
|
Number |
Pflichtfeld. |
Der Einzelpreis eines Artikels, inkl. Steuern. Bei Gutschriften (z. B. in Form vom Gutscheinen) kann der Betrag auch negativ sein. |
{
"quantity" : 3,
"name" : "Bobbycar",
"ean" : "800001303",
"price" : 25.99
}
Message
Meldungen und insbesondere Fehlermeldungen. Details zur Fehlerbehandlung siehe Error Messages.
Feld | Typ | Eigenschaften | Beschreibung |
---|---|---|---|
|
String |
Pflichtfeld. |
Der eindeutige Fehlercode zu diesem Fehler. |
|
String |
Pflichtfeld. |
Die Fehlerstufe. Die möglichen Werte sind: ERROR, WARN und INFO. |
|
String |
Optional. |
Das Feld zu dem dieser Fehler erzeugt wurde. Dieses Feld wird bei einem |
|
String |
Optional. |
Der Grund für diesen Fehler als eindeutiger Code, sofern dies aus dem Feld |
|
String |
Optional. |
Eine paydirekt-interne Referenznummer zu dieser Fehlermeldung. Bitte geben Sie immer diese Referenznummer bei Support-Anfragen an. |
|
String |
Optional. |
Der ungültige Inhalt bei einem CONVERSION_ERROR. |
{
"code" : "VALIDATION_ERROR",
"severity" : "ERROR",
"path" : "currency",
"reasonCode" : "INVALID_FORMAT",
"logref" : "934180ed-ef93-4af1-835a-3071714fdce5:8t1ph9gFha1"
}
Page
Beschreibt die Segmentierung großer Resourcen in Abschnitte, die einzeln abgerufen und angezeigt werden können.
Feld | Typ | Eigenschaften | Beschreibung |
---|---|---|---|
|
Integer |
Immer vorhanden. |
Die maximale Anzahl der Elemente in dieser Page. |
|
Integer |
Immer vorhanden. |
Die Gesamtanzahl der Elemente über alle Pages. |
|
Integer |
Immer vorhanden. |
Die Gesamtanzahl der Pages. |
|
Integer |
Immer vorhanden. |
Der Index der aktuellen Page. |
Zeichensatz
Grundsätzlich gilt, dass die per HTTP-Request übergebenen Daten UTF-8 encodiert sein müssen.
Sofern nicht anders vermerkt, werden nur folgende Zeichen in Feldern vom Typ String
akzeptiert:
-
Alle Buchstaben in der Unicode-Kategorie
Letter
-
Alle Zahlen in der Unicode-Kategorie
Number
-
Folgende Sonderzeichen: .-!#$%&'*+/=?^_’`´{|}~"(),:;<>@[]
-
Leerzeichen und geschütztes Leerzeichen
-
Linebreak und Linefeed
Auch paydirekt liefert sämtliche Responses in UTF-8. Allgemein ist dabei zu beachten, dass nicht garantiert ist, dass nicht-SEPA-konforme Zeichen in allen Systemen (insbesondere auf Bankenseite, z. B. auf Kontoauszügen) korrekt, bzw. überhaupt, angezeigt werden.
SEPA-konforme Zeichen
In SEPA-Zahlungen sind gemäß Anlage 3 des DFÜ-Abkommens nur Zeichen des eingeschränkten SWIFT Latin Character Set zugelassen:
-
a b c d e f g h i j k l m n o p q r s t u v w x y z
-
A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
-
0 1 2 3 4 5 6 7 8 9
-
' : ? , - ( + . ) /
In dem eingeschränkten Zeichensatz sind somit insbesondere nicht enthalten: Umlaute, das €-Symbol, bestimmte Sonderzeichen wie der Unterstrich, das Leerzeichen oder eckige Klammern.
Damit es im Zahlungsverkehr zu keinen Störungen kommt, dürfen für entsprechend gekennzeichnete Attribute nur die zugelassenen Zeichen verwendet werden.
Changelog
Die folgende Tabelle fasst alle Änderungen an diesem Dokument seit April 2016 zusammen.
Datum | Art | Beschreibung | Abschnitt |
---|---|---|---|
09.04.2020 |
NEW INFO |
Informationen über den Standardwert von |
|
09.04.2020 |
NEW INFO |
Dokumentation des Feldes |
|
08.04.2020 |
NEW FEATURE |
Statusupdates werden nun immer – auch bei wiederholten Versuchen nach Fehlschlägen – in der Reihenfolge versendet, in der die Statusänderungen am Checkout stattgefunden haben. Die Statusupdates enthalten zudem nun einen Timestamp und eine Sequenznummer. |
|
11.12.2019 |
CHANGE |
Limit-Erhöhung für Transaktionsreports |
|
04.04.2019 |
CHANGE |
Umbenennung Vermittler in Händlerkonzentrator |
|
04.04.2019 |
NEW INFO |
Authentifizierung als Collecting PSP |
|
02.01.2019 |
CHANGE |
Händler bekommen eine explizite Fehlermeldung, falls der Kunde zwischenzeitlich nicht mehr an paydirekt teilnimmt. |
|
12.11.2018 |
NEW INFO |
Dokumentation der in String-Feldern akzeptierten Zeichen |
|
31.10.2018 |
CHANGE |
Der Inhalt des Checkout |
|
28.08.2018 |
NEW FEATURE |
Es kann nun optional die Gültigkeitsdauer von Checkouts konfiguriert werden. |
|
31.07.2018 |
NEW FEATURE |
Bei Express-Checkouts ist die Angabe eines Endpunkts zur Validierung von Lieferadressen nun optional. |
|
28.05.2018 |
NEW INFO |
Dokumentation des Fehlercodes |
|
22.12.2017 |
NEW INFO |
Angaben zum Vorhandensein aller Response-Felder |
|
29.11.2017 |
CHANGE |
Der Service zum Abruf von Bankenlogos steht nicht mehr zur Verfügung. |
|
29.11.2017 |
NEW FEATURE |
Versandbedingungen und Rechnungsreferenz können nachträglich geändert werden. |
Checkout - Aktualisierung Versandbedingungen Checkout - Aktualisierung Rechnungsreferenz |
06.09.2017 |
NEW FEATURE |
Bei der Checkoutanlage kann jetzt das für diesen geltende maximale Refundlimit gesetzt werden. |
|
09.08.2017 |
NEW FEATURE |
Beschreibung der gesicherten Vorbestellung |
|
04.04.2017 |
NEW FEATURE |
Übermittlung der E-Mail-Adresse des Käufers an den Händler/PSP bei Express |
|
22.02.2017 |
NEW FEATURE |
Statusupdates werden bei Fehlschlägen erneut gesendet. |
|
08.02.2017 |
CHANGE |
Der Checkoutstatus CANCELED ist jetzt final. |
|
11.01.2017 |
NEW FEATURE |
Erweiterung der Rechnungs- und Lieferadresse um ein Feld für das Bundesland. |
|
11.01.2017 |
NEW FEATURE |
Der PSP-Transaktionsreport enthält jetzt die |
|
11.01.2017 |
NEW INFO |
Angabe der statischen IP-Adressen, von denen Callback URLs aufgerufen werden |
|
14.12.2016 |
NEW FEATURE |
Neue Warenkorbtypen, bei denen die Übergabe der Lieferadresse optional ist. |
|
30.11.2016 |
FIX |
Die maximale Zeichenzahl für |
|
30.11.2016 |
FIX |
Die Transaktionstypen für Overcaptures und stornierte Vorbestellungen ist nun in der Beschreibung der Reports enthalten. |
|
30.11.2016 |
NEW FEATURE |
Händler/PSP können Callbacks einrichten, um bei Statusänderungen von Refunds benachrichtigt zu werden. |
|
16.11.2016 |
NEW FEATURE |
In den Reports ist nun der Grund für Refunds enthalten. |
|
16.11.2016 |
NEW INFO |
Weitere Angaben zum Format paydirekt-seitig generierter Felder |
|
02.11.2016 |
NEW FEATURE |
Händler können ihre API-Reporte nun durch zusätzliche Filter einschränken. |
|
02.11.2016 |
NEW FEATURE |
Händler können nun in Checkouts und Captures Lieferinformationen mitgeben. |
|
19.10.2016 |
FIX |
Checkout-Status |
|
19.10.2016 |
NEW FEATURE |
Refunds können um eine |
|
05.10.2016 |
NEW FEATURE |
Verwendungszwecke können um eine |
|
05.10.2016 |
NEW FEATURE |
Händler/PSP können Callbacks einrichten, um bei Statusänderungen von Checkouts und Captures benachrichtigt zu werden. |
|
21.09.2016 |
NEW FEATURE |
Angabe des Typs der Lieferadresse |
|
21.09.2016 |
NEW FEATURE |
Neue Felder |
|
10.08.2016 |
NEW INFO |
Angabe der statischen IP-Adressen der Endpunkte |
|
10.08.2016 |
FIX |
"overcapture" und andere fehlende Felder sind nun in allen betroffenen Request- und Responsebeschreibungen enthalten. |
|
27.07.2016 |
NEW FEATURE |
Bei digitalen Warenkörben sind einige Adressfelder optional, dafür neues Feld "emailAddress" |
|
27.07.2016 |
NEW FEATURE |
Anlage von Checkouts auch ohne orderAmount und shippingAmount |
|
27.07.2016 |
NEW INFO |
Beschreibung der möglichen Refundstatus |
|
27.07.2016 |
NEW INFO |
Angabe der Constraints für die Express-Callback Response |
|
13.07.2016 |
FIX |
Fehlende Feldbeschreibungen des Overcapture-Flags |
|
13.07.2016 |
NEW FEATURE |
Warenkorbkennzeichnungen |
|
13.07.2016 |
NEW FEATURE |
Update paydirekt-Express Callback |
|
13.07.2016 |
FIX |
Fehlende Feldbeschreibungen der Rechnungsnummern im PSP-Report |
|
29.06.2016 |
FIX |
paymentInformationId ist keine Liste |
|
29.06.2016 |
NEW INFO |
Hinweis auf die Beispielimplementierungen auf GitHub |
|
29.06.2016 |
CHANGE |
Zahlreiche Rechtschreibungs- und Formulierungsverbesserungen |
|
29.06.2016 |
FIX |
Fehlende Feldbeschreibungen zur Altersverifikation im Express-Checkout |
|
29.06.2016 |
CHANGE |
Beschreibung des API-Authentifizierungsprozesses |
|
29.06.2016 |
NEW FEATURE |
Auswahl der Felder für API-Reports |
|
18.05.2016 |
NEW FEATURE |
Refund-Abfrage liefert nun auch den aktuellen Status |
|
18.05.2016 |
NEW FEATURE |
Beschreibung der zum Overcapture gehörenden Felder |
|
18.05.2016 |
NEW FEATURE |
MerchantOrderReferenceNumber optional bei Express-Checkout-Anlage |
|
04.05.2016 |
NEW FEATURE |
Markierung der Sandbox API Keys |
|
04.05.2016 |
NEW FEATURE |
Händler Reports über API |
|
20.04.2016 |
NEW FEATURE |
PSP Reports über API |
|
20.04.2016 |
NEW INFO |
Beschreibung des SEPA-konformen Zeichensatzes |
|
20.04.2016 |
NEW INFO |
Erklärung des Status PENDING |
|
20.04.2016 |
NEW INFO |
Mehr Informationen zu TLS |