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 in Webshop-Systeme.

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.

Ablauf
Figure 1. Ablauf eines Bestellprozesses bei einer Direktbestellung

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

GET

Query

Liefert die Repräsentation eines oder mehrerer Geschäftsobjekte zurück. Es werden keine Veränderungen auf dieser Ressource durchgeführt.

POST

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

Authorization

Access-Token aus dem OAuth2-Aufruf

Bearer <accessTokenValue>

X-Request-ID

Eindeutige Request-ID, wird zur Protokollierung verwendet. Wenn im Request keine gesetzt ist, wird serverseitig eine erzeugt und in der HTTP Response zurückgegeben.
Wenn clientseitig eine Request-ID angegeben wird, sollte das Format UUID Typ 4 Random verwendet werden.
Optional.

 8eb5d811-ad7f-4e08-94e4-5dcfa03a4b15

Content-Type

Der Internet Media Type des Request Body. Es wird nur application/hal+json unterstützt.
Pflichtfeld bei Command-Methoden.

application/hal+json

Accept

Die akzeptierten und erwarteten Internet Media Types der Response. Es wird nur application/hal+json unterstützt.
Pflichtfeld bei Aufrufen mit Response-Body.

application/hal+json

Date

Datum und Zeit zum Sendezeitpunkt der Anfrage. Format nach [RFC 7231] IMF-fixdate.
Pflichtfeld.

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 Location zu erreichen.
Dieser Status Code kommt nach einem bestimmten erfolgreichen POST auf eine Ressourcen-URL.

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

messages

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

INVALID_FORMAT

Der Wert entspricht nicht den Formatvorgaben.

MANDATORY_VALUE_MISSING

Ein Pflichtfeld ist nicht angegeben.

INVALID_ENUM_VALUE

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
  } ],
  "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/json;charset=UTF-8
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
Content-Length: 220

{
  "messages" : [ {
    "severity" : "ERROR",
    "code" : "VALIDATION_ERROR",
    "path" : "shippingAmount",
    "reasonCode" : "INVALID_FORMAT",
    "logref" : "2acbe6f2-51fe-4ad1-9b90-692f16cbabad:wOM5bt8rqF"
  } ]
}

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

Zur Authentifizierung eines Shops wird ein API-Key Verfahren in Verbindung mit OAuth2 verwendet.

Um Anfragen an das paydirekt-System zu tätigen, wird zunächst für einen API-Key ein gültiges Access Token benötigt. Um dieses zu erhalten, muss der Händler über einen gültigen API-Key und das dazugehörige API-Secret des Shops verfügen.

API-Key

API-Key

Der API-Key dient der Identifikation eines bestimmten Shops eines Händlers. Ein API-Key kann im Händler-Portal 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

API-Secret

Das API-Secret dient der Authentifizierung des Shops. Es wird verwendet, um eine Signatur 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]
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 Token Obtain-Endpoints durch Angabe des Grant Type api_key erzeugt und wird bei allen folgenden Requests im Request Header Authorization als Bearer angegeben:

Authorization: Bearer <accessToken>

Der Access Token hat eine begrenzte Gültigkeitsdauer von derzeit 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.

In GitHub findet sich 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

Die Signatur (Auth-Code) bestätigt, dass der Händler im Besitz des API-Secrets ist und gültige Anfragen im Namen des Shops 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 X-Request-ID

UUID Type 4 Random [RFC 4122]

ec85749b-aa36-412a-a397-2b40200c119c

2.

Datum

Request Header X-Date. Wichtig: Die Zeit muss der Zeitzone UTC entsprechen!

yyyyMMddHHmmss

20141231235859

3.

API-Key

Request Header X-Auth-Key

UUID Type 4 Random [RFC 4122]

4c15310a-7936-4a19-8d80-f2b7bd95dc9b

4.

Random Nonce

Request Body-Feld randomNonce

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

Token Obtain

POST /api/merchantintegration/v1/token/obtain

Über diesen Endpoint wird ein Access Token ausgestellt, das anschließend für einen oder mehrere Zugriffe verwendet werden kann.

Request

Feld Typ Eigenschaften Beschreibung

Header-Felder

X-Auth-Key

String

Pflichtfeld.
36 Zeichen.

API-Key des Shops
Zweck: Identifizierung
Format: UUID Typ 4 Random [RFC 4122]
´Beispiel: 4c15310a-7936-4a19-8d80-f2b7bd95dc9b

X-Auth-Code

String

Pflichtfeld.
Maximal 44 Zeichen.

Signatur der Anfrage
Zweck: Authentifizierung
Kodierung: Base64 URL Encoding [RFC 4648 Section 5]
Beispiel: Im6MZB4ht8Dp8mXIBzPjqdgaQSZVl5CzoVzmoCnQAfk=

X-Request-ID

String

Pflichtfeld.
36 Zeichen.

Zufällig erzeugte UUID der Anfrage
Zweck: Protokollierung, Log-Statement Korrelation und Debugging
Format: UUID Typ 4 Random
Beispiel: ec85749b-aa36-412a-a397-2b40200c119c

X-Date

String

Pflichtfeld.

Datum und Zeit zum Sendezeitpunkt der Anfrage
Format: [RFC 7231] IMF-fixdate
Beispiel: Fri, 30 May 2014 09:46:48 GMT

Content-Type

String

Pflichtfeld.

Immer application/hal+json;charset=utf-8

Body-Felder

grantType

String

Pflichtfeld.

Immer api_key

randomNonce

String

Pflichtfeld.
Maximal 64 Zeichen.

Zufällige Zeichenkette zur Diversifizierung der Request Body Inhalte
Zweck: Erhöhung der Sicherheit des Verfahrens
Kodierung: Base64 URL Encoding [RFC 4648 Section 5]
Beispiel: Ns0WLCI3qA2AMH98wUYyhqALy VlzS0q7nHh7NdeMyvUgKJoyF0rNXkgq5fq2VNJs

Response

Feld

Typ

Eigenschaften

Beschreibung

access_token

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.

token_type

String

Immer vorhanden.

Immer bearer.

expires_in

Number

Immer vorhanden.

Gültigkeitsdauer des Access Tokens in Sekunden zur Information.

scope

String

Immer vorhanden.

Gültigkeitsbereich des Access Tokens zur Information.

aid

String

Immer vorhanden.

UUID aus 36 Zeichen zur eindeutigen Identifikation des Tokens.

jti

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

Der X-Auth-Key bzw. X-Auth-Code fehlt oder ist ungültig.

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 X-Auth-Key.

401 (Unauthorized)

API_KEY_IN_REQUEST_INACTIVE

Der API-Key ist deaktiviert.

401 (Unauthorized)

API_KEY_REQUEST_SIGNATURE_INVALID

Der X-Auth-Code ist falsch oder leer

Beispiel

POST /api/merchantintegration/v1/token/obtain HTTP/1.1
Content-Type: application/hal+json;charset=utf-8
X-Request-ID: 1bd961bf-d395-45e9-9c6e-c50e1bd9a561
Accept: application/hal+json
X-Auth-Key: 5907218c-bb96-402b-b372-ec959f62b239
X-Auth-Code: 2GhoOEF5lWYEBPSGGM1B2Lx39XCORP7hop7DrUk6pSE=
Host: api.paydirekt.de
Content-Length: 115
X-Date: Thu, 30 Aug 2018 12:45:27 GMT

{
  "grantType" : "api_key",
  "randomNonce" : "e7PPzZma-xZXEmQ20Mlqm3AWuWLbGAtYTimx-dQRkkEBvKP56nQWZXWD77UhRSiP"
}
HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 2119

{
  "access_token" : "dxAKtkQHaEIfwb7TBi7AHPGa9QGY8hU1C-fmpojc-FK813df9z_XAKiKGDoCSsAb1SPiQWOgwVGF1pamFbwm9yeZb_UtC-V0S8golWmGcspa0DR8zHCEipzjZVLhyXS6iNDGzvTE51YQ2iV17m9mqYXEvpps5esS5prFkQXriMkIVmpa0wGxcjZ4nXxJ2zjyCwhUmehjBzUBOlIVwU9e0Nko1rWriAbyBv9jOboqmyQpVnqFaHYGZn61fAt0GKlgjuLB6eruE4VjjVlDwdjkZtpELxOvlV374jsgyVL6F7GQ2_XBj-GXwnjM0XyvDv8wndA67W_SfExqEoPo4u7z90TNBxlBLyrZwiA71Cyej2DRrFmfGIeUzVL6fl6RFzka11gBfTaTOJwv80ALPQoyEnB6YGFbz-VYKd2ztjNjL3prEor4Mgm6txJY-UK_enF6mmUPSelq-vwnlwJpQfxf-JIrTxSaspBFHFr8yQI-cDzZDr8BAAkVWmjw1stDxuayEA13WwyVpgKH0fbDKdTNmg3LodvPHZPQYL5wLTvLsMwgkoEAFcJngMt1WrSvLa90mKJro3nhyXEWfpM0D34HqWKP9ylSQkuSfh9XgQvoZ42NgDwJiB35t6Afygp9_YDOnub4r88Uj237ZKHl-AdqPGvpvR0bJ9EkhpBamhpj-37hVIQotW_mJ_tO05cAMrIN66rP7yOfok4KEhGOu2dYiFYdnY0z0SXo8PAvy6jC52WfefFmRTQaKWO8l0YzP9eUgUBmM2p7wdWRBCrZ3B7y7vbV6tog_cv2hemoa1_dIx1l6LN1S7gzfJLkzPSmLaCJExlOZcZ7pgOyxkUcL_lY6nc_kRVgr95ha_R-GhleFX7loTmEFAO7fn1P3yvSypz-tItLw_ULKJ5YQvtrJKTofcTn2oPT7WhfdLkMhhp86jUBy1JOUthzKsP41ZGTM-XccjpFIsElZdUIrhnj5Qym4L1ESKC434CADysc8Ath2B-bHKt-XoBMm0_ns1kLuFK80GPByIvKzX74V8XB6WLBOdT90lgjnNU_ntf-cRL7kyWfCMN4Sfb-N-HVe2Ooeh_JGnXAIOOOmA56CxCAxFvbxA4JwPAXidq0HmJbIEe1q85vXPNePNKAb2Ui8n6f7UQqWyWUSbH6Wn7Z-EHDN5mq3TkobUL1rkAon4NHrkzhFoKvjnXQDkYbmw8gcxG0hm6BTNWv6RgLSHL9LZQsV_RUmn7PRaTCxq6NpfcPlkQCrfqW7IuwZV_B2-HNo9cbKZuCWnJLuuWWZKCpm7HFjo4tMs0S1H41Ppnzq4Q8KhssdLLN_kWhQXAaSP2_RvNT_8-gU4S_ZtbeSBQWmwYQYwk6zYMEF-CTfI_LFRdDJ5xXL4vaIm_Rrl6ZQ6ygZKsI3hOG9pqsivi829RmOBKia05blzv87-twllWv0IgNUgj79Z8xw3I1N1fKhvKppp1lArMkGDXLFiPm0yfuuWGsjJrXmv31PcTsi1HqgVREIZGE-d5YmRzZHgw9w2wa3wV6rkZQO8SOJBtYbqgLa4y_2AWUw3iWmiVhjQ8MHaLR7-pZSoxkoFaRg3Zzzm8zKiARw1IQfwBqk46RjCmFn1DgUVLJTapnt_KhNslkom-yVIvakgB7ZomMKTq9aKBU6UBnCHKLbMLpdnrhPJVkPt2c2zf_C0WJmldPF0-NA_tRYHYeujdEnuvkj4MXWGoX-fE5ig4iUprrqC7w8q7c1bgxQa39iQHYAdsdhWFoKif1LYzCl4kFRjU_BMvC_ZWe-kXQqT0Fc",
  "token_type" : "bearer",
  "expires_in" : 3599,
  "scope" : "account accountsummary checkout credit reporting thirdparty thirdpartycustomerauthorization thirdpartymerchantauthorization transaction",
  "aid" : "e73cbf65-ae03-4e86-bebd-f30619dab139",
  "jti" : "66ec0f09-4293-43d3-852c-c5fdb5429b8e"
}

Beispiel (Falscher Auth-Code)

POST /api/merchantintegration/v1/token/obtain HTTP/1.1
Content-Type: application/json;charset=utf-8
X-Request-ID: 69354396-337d-45d7-840b-603e0ab4f063
X-Auth-Key: 6ba613f9-3f01-4043-875b-1a792d2f811f
X-Auth-Code: nqNm4sglI06fNZTG66vFGV5DJNIjTo_n96ev-Sd92Z4=
Host: api.paydirekt.de
Content-Length: 115
X-Date: Thu, 30 Aug 2018 12:45:27 GMT

{
  "grantType" : "api_key",
  "randomNonce" : "xLZrCNl87uP6tTcV0HptOlWqSL-UbSvo1xFdUt4oi5IBgePYdSR3m6b5Bs7uhkBh"
}
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" : "69354396-337d-45d7-840b-603e0ab4f063:6stGGOrjEQP"
  } ]
}

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: Thu Aug 30 14:45:19 CEST 2018
Authorization: Bearer F1ELsSCDbx_8lGmQddb-XIRwZhb_ac_SZync_RNPFT8ds7l-2gJzLjilWIsfYkHp43lG74HPBzF6SNLJJhLb6YauZXrLEhwmhIq4v_jpcYpTK_UIueTUDHMos9SMNIxwmPxq8nIqFDbRAModzYPLLXisrAmm3TeBRaLjB3aX_-qnCInMQaTsG3U0sHvezt5O9pUWoGsUp-ujJ2BvzcjFK94t9phIQn4cspW237UcFr7ZQm6q7EYeCJ2UuLWM5A95eRHWX2-yhdfWZgjKqeL5eFXY4YOc6M9K3fsTSnkPiXIMYxiJP0BjeX2riYeWSKVRBGF6ytjUMmnyjO0SkUqjiQS1GsKLRveaTwMVPTZ7ZqdvM_vgAHgeenxzywStmVfH8CrxR5u96GxuYQwFFMTog1U0efqJPlJl8yyuzrddJ1nQy655XEhyHVvNrQ0fBc06h4f-OUDLafvAhN-deweT7wv49U3oOpfe6FyxFFB7Z70zpNwZBpzVFYlzhCS-QgUj3hJxR65GJpxNRxsbHqzgAbYDR7-tyG-YHC14jOa96prQjLgjA9M0GkPFi8bwfOiCBF1BhAeQBTHJ52cEQBKj-yM_t3QjgggMsV9iCFSlQyNiPhHNat_5GmwEEOr9zdgRmVbnaht3Wo6vhUsmlv2h0LFr1VthvGMVOyUtaxnHRGRjo7ehsJL5bacuxfQC7Y8r6FD5KRDWjLmfr2MHeGyDyrNlWaMtkGqdpm-t02w5ruLCv5jKSU9K-Cmuvqfk6q2wKe7dkPxVPGPg17lT2oWPGCB77O9MoOTXj5R6mFtFdpzLt3SQuad1LPg8RACBkcQauuh7JyQ8RuBkxkezHyss6uWZrEd5eXCWmQgM97HBpZhA9AktBwmH-BNzQXIL3qnyP33JErOrwexMgbmDmZZCQjAK-hTpQBa9_Ma8XyyYJBYJt1zAoE35hjUylFwnMCX5-oUOITh9naLPG1LTHrRI2PNxaalNmQ-SYXGkC3pCGdsDt-8_PlkO_B2R4vwdS7RbJx1DFZkDs6e5dctloIj9AyBDrRgoC9VDdGO9RVSURlEqRwsPeUwIZgXxOanwdglJqWjN5_p06DaLMey7AoDJQ02WNoNbjxSOUH3DAkZOPkwb0FNTZCrwC5i387grX_zEiSUPs_LpJhEnwM0wZnaYnilpAqrviFnCWuwsniBUOBYR7OOn7pt4qUDi1fEEz1GhnmcLb-UtsolPct9oiad_mNp74gCUlrCSiz1gXOHljQmyT80wFoc3-57gE_q6WnsdTfx3eDiV3aN4GhITwIZ9qVupZ0jU5VaqGJ5rkv0cVtdDdyx-2EIt1MTr_8njHuNgnCxjxRuOoqVANrxGDbN2i3ZYOIibHttyOY71aH37IkOEekxQ1BcsrCkxlCQcFj_jDYbczOgoPWZm_SW-TSgulDXdlkjeuxgwjFwm0gTioHJDLN3eZJc5kxrLLKC-GfMkpXR4aFZQbSF_5r71lwn_6602dPLo8ciL9QKVgt8bRd1qE2EgD_Ka1n8XX0stunHTlfxIphOWXbmksK7SVR3SdQMJa7HnrWeKbcv7wxqgdwqDjFVDIjVUd1lTGo9aoDVZFppcb1A0hF264ylLHmDkqD-iKVEpHc69FsvBFqq7ypU9yePehJYgTD9NkGNNZuZ1mtPVdwJUiToYH-ODMbZqYtEcGhi_j5DaCV0_ApYqYCOIuqtDn6xFPHy-UWYG2DuimQ7DsqHo_bO5WEqgdNNuLQ90EVXw0pSoTLvn_jXF2lDjkqZCApD9cXmOkJNYkgkgo
Host: api.paydirekt.de
HTTP/1.1 401 Unauthorized
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 2029

{
  "messages" : [ {
    "severity" : "ERROR",
    "code" : "ACCESS_TOKEN_EXPIRED",
    "logref" : "11bf9777-d427-492c-b402-f548e67ab4eb:1HQuq9kqYXX"
  } ],
  "error" : "invalid_token",
  "error_description" : "Access token expired: F1ELsSCDbx_8lGmQddb-XIRwZhb_ac_SZync_RNPFT8ds7l-2gJzLjilWIsfYkHp43lG74HPBzF6SNLJJhLb6YauZXrLEhwmhIq4v_jpcYpTK_UIueTUDHMos9SMNIxwmPxq8nIqFDbRAModzYPLLXisrAmm3TeBRaLjB3aX_-qnCInMQaTsG3U0sHvezt5O9pUWoGsUp-ujJ2BvzcjFK94t9phIQn4cspW237UcFr7ZQm6q7EYeCJ2UuLWM5A95eRHWX2-yhdfWZgjKqeL5eFXY4YOc6M9K3fsTSnkPiXIMYxiJP0BjeX2riYeWSKVRBGF6ytjUMmnyjO0SkUqjiQS1GsKLRveaTwMVPTZ7ZqdvM_vgAHgeenxzywStmVfH8CrxR5u96GxuYQwFFMTog1U0efqJPlJl8yyuzrddJ1nQy655XEhyHVvNrQ0fBc06h4f-OUDLafvAhN-deweT7wv49U3oOpfe6FyxFFB7Z70zpNwZBpzVFYlzhCS-QgUj3hJxR65GJpxNRxsbHqzgAbYDR7-tyG-YHC14jOa96prQjLgjA9M0GkPFi8bwfOiCBF1BhAeQBTHJ52cEQBKj-yM_t3QjgggMsV9iCFSlQyNiPhHNat_5GmwEEOr9zdgRmVbnaht3Wo6vhUsmlv2h0LFr1VthvGMVOyUtaxnHRGRjo7ehsJL5bacuxfQC7Y8r6FD5KRDWjLmfr2MHeGyDyrNlWaMtkGqdpm-t02w5ruLCv5jKSU9K-Cmuvqfk6q2wKe7dkPxVPGPg17lT2oWPGCB77O9MoOTXj5R6mFtFdpzLt3SQuad1LPg8RACBkcQauuh7JyQ8RuBkxkezHyss6uWZrEd5eXCWmQgM97HBpZhA9AktBwmH-BNzQXIL3qnyP33JErOrwexMgbmDmZZCQjAK-hTpQBa9_Ma8XyyYJBYJt1zAoE35hjUylFwnMCX5-oUOITh9naLPG1LTHrRI2PNxaalNmQ-SYXGkC3pCGdsDt-8_PlkO_B2R4vwdS7RbJx1DFZkDs6e5dctloIj9AyBDrRgoC9VDdGO9RVSURlEqRwsPeUwIZgXxOanwdglJqWjN5_p06DaLMey7AoDJQ02WNoNbjxSOUH3DAkZOPkwb0FNTZCrwC5i387grX_zEiSUPs_LpJhEnwM0wZnaYnilpAqrviFnCWuwsniBUOBYR7OOn7pt4qUDi1fEEz1GhnmcLb-UtsolPct9oiad_mNp74gCUlrCSiz1gXOHljQmyT80wFoc3-57gE_q6WnsdTfx3eDiV3aN4GhITwIZ9qVupZ0jU5VaqGJ5rkv0cVtdDdyx-2EIt1MTr_8njHuNgnCxjxRuOoqVANrxGDbN2i3ZYOIibHttyOY71aH37IkOEekxQ1BcsrCkxlCQcFj_jDYbczOgoPWZm_SW-TSgulDXdlkjeuxgwjFwm0gTioHJDLN3eZJc5kxrLLKC-GfMkpXR4aFZQbSF_5r71lwn_6602dPLo8ciL9QKVgt8bRd1qE2EgD_Ka1n8XX0stunHTlfxIphOWXbmksK7SVR3SdQMJa7HnrWeKbcv7wxqgdwqDjFVDIjVUd1lTGo9aoDVZFppcb1A0hF264ylLHmDkqD-iKVEpHc69FsvBFqq7ypU9yePehJYgTD9NkGNNZuZ1mtPVdwJUiToYH-ODMbZqYtEcGhi_j5DaCV0_ApYqYCOIuqtDn6xFPHy-UWYG2DuimQ7DsqHo_bO5WEqgdNNuLQ90EVXw0pSoTLvn_jXF2lDjkqZCApD9cXmOkJNYkgkgo"
}

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 muss als Funktion explizit für Ihren Händleraccount freigeschaltet werden. Bitte wenden Sie sich hierzu an haendler@paydirekt.de.
Die gesicherte Vorbestellung ORDER_SECURED ist momentan in Entwicklung und kann noch nicht produktiv verwendet werden.

Request

Feld Typ Eigenschaften Beschreibung

type

String

Pflichtfeld.

Die Art der Bestellung: DIRECT_SALE, ORDER oder ORDER_SECURED.
Im Falle eines DIRECT_SALE (Direktbestellung mit Einmalzahlung) wird automatisch eine Zahlungsautorisierung erzeugt. Der Händler erhält sofort eine Zahlungsgarantie.
Zu einer ORDER (Vorbestellung oder Bestellung mit Teilzahlungen) können direkt im Anschluss oder später ein oder mehrere Captures angestoßen werden. Für eine Order wird keine Zahlungsgarantie an den Händler ausgesprochen. Die Garantie wird erst mit dem Capture gegeben.
Zu einer ORDER_SECURED (gesicherte Vorbestellung oder Bestellung mit Teilzahlungen) können direkt im Anschluss oder später ein oder mehrere Captures angestoßen werden. Für eine gesicherte Vorbestellung wird eine Zahlungsgarantie für den gewählten Zeitraum (maximal 15 Kalendertage) an den Händler ausgesprochen. Captures (Teilzahlungen) werden innerhalb des Garantiezeitraums immer ausgeführt. Weitere Informationen zu Order und Capture finden Sie im Kapitel Capture.

totalAmount

Number

Pflichtfeld.
Zwischen 0.01 und 50000.
Maximal zwei Nachkommastellen.

Der Gesamtbetrag der Bestellung, inkl. aller Lieferkosten. Es werden maximal 2 Nachkommastellen unterstützt.
Im Falle eines DIRECT_SALE wird eine Zahlung für diesen Betrag initiiert.
Im Falle einer ORDER können Captures bis maximal zu diesem Betrag angestoßen werden.

shippingAmount

Number

Optional. Mindestens 0.00.
Maximal zwei Nachkommastellen.

Die Versandkosten der Bestellung. Dieser Wert wird nicht für Berechnungen verwendet, sondern dient nur zur Information.

orderAmount

Number

Optional.
Zwischen 0.01 und 50000.
Maximal zwei Nachkommastellen.

Der Warenwert der Bestellung, ohne Versandkosten. Dieser Wert wird nicht für Berechnungen verwendet, sondern dient nur zur Information.

refundLimit

Number

Optional.
Zwischen 100 und 200.
Wird bei Nichtangabe auf 200 gesetzt, das heißt maximal das Zweifache des Bestellwertes kann zurückgezahlt werden.

Maximal zurückzahlbarer Betrag als Prozentwert des Gesamtwertes der Bestellung.

overcapture

Boolean

Optional.
(Standard: false)

Flag für Overcapture-Checkouts.
Bei einem Overcapture-Checkout darf die Summe der Captures den Warenwert der Bestellung um bis zu 10% übersteigen.
Bei aktiviertem Flag muss das finalCapture-Feld des letzten Captures auf true gesetzt sein.
overcapture darf nur aktiviert sein, wenn es sich um einen Checkout des Typs ORDER handelt.
Kann nur von Händlern verwendet werden, die für dieses Feature freigeschaltet wurden.

currency

String

Pflichtfeld.

Die Währung des Gesamtbetrags. Derzeit wird nur EUR unterstützt.

items

Array von Items

Optional.

Die einzelnen Positionen des Warenkorbs.
Es wird empfohlen, diese Werte zu übergeben. Dies verbessert die Erkennung von fraudulenten Vorgängen und hilft, Disputes zu vermeiden.

shoppingCartType

String

Optional.

Kategorisiert den Warenkorb eines Checkouts anhand der Eigenschaften der enthaltenen Güter: Der Standardwert ist MIXED.
PHYSICAL: Der Warenkorb enthält ausschließlich physische Güter.
DIGITAL: Der Warenkorb enthält ausschließlich digitale Güter.
MIXED: Der Warenkorb enthält sowohl phyische als auch digitale Güter.
ANONYMOUS_DONATION: Beim Warenkorb handelt es sich ausschließlich um eine anonyme Spende.
AUTHORITIES_PAYMENT: Beim Warenkorb handelt es sich ausschließlich um Behördenzahlungen.

deliveryType

String

Optional.

Der Bestimmungsort einer Lieferung: STANDARD, PACKSTATION oder STORE_PICKUP. Der Standardwert ist STANDARD.
STANDARD: Die Güter werden an eine gewöhnliche Postadresse geliefert.
PACKSTATION: Die Güter werden an eine Packstation geliefert.
STORE_PICKUP: Die Güter werden in der Filiale abgeholt.
Dieses Feld enthält bei Express-Checkouts immer den Wert STANDARD und wird nicht anhand der gewählten Lieferoption aktualisiert.

shippingAddress

ShippingAddress

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.

merchantCustomerNumber

String

Optional.
Maximal 50 Zeichen.

Händler-interne Kundennummer des Käufers. Wird dem Kunden in der Transaktionsübersicht angezeigt. Wird dem Händler in der Transaktionsübersicht angezeigt.

merchantOrderReferenceNumber

String

Pflichtfeld.
Maximal 20 Zeichen. Nur SEPA-konforme Zeichen.

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 instructionId und im Verwendungszweck bei Händler und Käufer verwendet.

merchantInvoiceReferenceNumber

String

Optional.
Maximal 100 Zeichen.

Händler-interne, eindeutige Rechnungsnummer für diesen Kauf- bzw. Zahlvorgang. Wird dem Händler in der Transaktionsübersicht angezeigt.

merchantReconciliationReferenceNumber

String

Optional.
Maximal 30 Zeichen.

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 merchantReconciliationReferenceNumber verwendet.

sha256hashedEmailAddress

String

Optional.
Maximal 64 Zeichen.

Die E-Mail Adresse des Käufers als Base-64 encodierter SHA-256 Hash-Wert ohne Padding, sofern vorhanden. Pseudo-Code: sha256hashedEmailAddress = toStringUTF8(base64(sha256(toBytesUTF8(emailAddress)))). Beispiel: Aus der E-Mail-Adresse max@muster.de muss sich exakt der folgende HashWert ergeben (ohne Anführungszeichen): "6JL4VUgVxkq2m+a9I6ScfW2ofJP5y6wsvSaHIsX+iLs=". Diese Information wird zur Fraud Prevention verwendet.

redirectUrlAfterSuccess

String

Pflichtfeld, außer bei oneKlick-Checkouts.
Maximal 2000 Zeichen.

Die Rücksprung-Adresse des Webshops (inkl. Referenz auf die Bestellung), die nach erfolgreicher Bezahlung aufgerufen wird.

redirectUrlAfterCancellation

String

Pflichtfeld, außer bei oneKlick-Checkouts.
Maximal 2000 Zeichen.

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.

redirectUrlAfterRejection

String

Pflichtfeld, außer bei oneKlick-Checkouts.
Maximal 2000 Zeichen.

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.

callbackUrlStatusUpdates

String

Optional.
Maximal 2000 Zeichen.

URL des Endpoints, der Mitteilungen zu Statusänderungen des Checkouts empfangen soll.

minimumAge

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 redirectUrlAfterAgeVerificationFailure (siehe unten). Bei Nicht-Angabe dieses Wertes erfolgt keine Altersverifkation.

redirectUrlAfterAgeVerificationFailure

String

Pflichtfeld, wenn minimumAge gesetzt ist.
Maximal 2000 Zeichen.

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 minimumAge, zum Pflichtfeld. Ist keine Altersverifikation erforderlich, ist dieses Feld wegzulassen.

note

String

Optional.
Maximal 37 Zeichen.

Freitextfeld, das auf dem Kontoauszug im Feld Verwendungzweck erscheint (nur DIRECT_SALE).

expiryTime

Number

Optional.
Minimal 120. Maximal 1800.

Zahl, die die Gültigkeit des Checkouts ab Anlage in Sekunden angibt. Bei Nicht-Angabe werden 1800 Sekunden angenommen.

deliveryInformation

Object

Optional.

Enthält Informationen über die Lieferung.

deliveryInformation.expectedShippingDate

String

Optional.
Zeitstempel im ISO-8601-Format.

Erwartetes Versanddatum.

deliveryInformation.logisticsProvider

String

Optional.

Paket-Dienstleister.

deliveryInformation.trackingNumber

String

Optional.

Sendungsnummer.

requestedPreauthorizationValidity

String

Optional.
Datum im Format yyyy-mm-dd.
Maximal 15 Kalendertage in der Zukunft.

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.

Relation Description

self

Link zu dieser Ressource.

approve

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 approve Links im action Attribute des form Tags) erfolgen. Die Bestätigung durch den Kunden muss innerhalb von 30 Minuten erfolgen. Dieser Link ist nur vorhanden, wenn der Checkout vom Kunden noch nicht autorisiert wurde.

updateDeliveryInformation

Link zum Update der Lieferinformation. Dieser Link ist nur vorhanden, wenn die Update Frist für diesen Checkout noch nicht überschritten ist.

updateMerchantInvoiceReferenceNumber

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)

VALIDATION_ERROR

Der Request ist syntaktisch ungültig.

400 (Bad Request)

CONVERSION_ERROR

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 path genannt und der ungültige Wert im Feld content übermittelt.

401 (Unauthorized)

ACCESS_TOKEN_EXPIRED

Siehe Resource Access.

401 (Unauthorized)

UNAUTHORIZED

Der Zugriff wurde verweigert. Bitte wenden Sie sich an den paydirekt-Support.

422 (Unprocessable Entity)

MERCHANT_BANKACCOUNT_LOCKED

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)

PSP_LOCKED

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
  } ],
  "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/67403284-0171-4ada-a8d3-5e0fa79a3164
Content-Type: application/hal+json;charset=UTF-8
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
Content-Length: 2445

{
  "checkoutId" : "67403284-0171-4ada-a8d3-5e0fa79a3164",
  "type" : "DIRECT_SALE",
  "status" : "OPEN",
  "creationTimestamp" : "2018-10-23T09:39:19.590Z",
  "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
  } ],
  "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" : "2018-10-23T10:09:19.590Z",
  "_links" : {
    "approve" : {
      "href" : "https://paydirekt.de/checkout/?p=67403284-0171-4ada-a8d3-5e0fa79a3164#/checkout/67403284-0171-4ada-a8d3-5e0fa79a3164"
    },
    "updateDeliveryInformation" : {
      "href" : "https://api.paydirekt.de/api/checkout/v1/checkouts/67403284-0171-4ada-a8d3-5e0fa79a3164/deliveryInformation"
    },
    "updateMerchantInvoiceReferenceNumber" : {
      "href" : "https://api.paydirekt.de/api/checkout/v1/checkouts/67403284-0171-4ada-a8d3-5e0fa79a3164/merchantInvoiceReferenceNumber"
    },
    "self" : {
      "href" : "https://api.paydirekt.de/api/checkout/v1/checkouts/67403284-0171-4ada-a8d3-5e0fa79a3164"
    }
  }
}

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/1a809e6e-6095-4cdb-99b1-36352152abbb
Content-Type: application/hal+json;charset=UTF-8
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
Content-Length: 2073

{
  "checkoutId" : "1a809e6e-6095-4cdb-99b1-36352152abbb",
  "type" : "ORDER",
  "status" : "OPEN",
  "creationTimestamp" : "2018-10-23T09:40:24.373Z",
  "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" : "2018-10-23T10:10:24.373Z",
  "_links" : {
    "approve" : {
      "href" : "https://paydirekt.de/checkout/?p=1a809e6e-6095-4cdb-99b1-36352152abbb#/checkout/1a809e6e-6095-4cdb-99b1-36352152abbb"
    },
    "updateDeliveryInformation" : {
      "href" : "https://api.paydirekt.de/api/checkout/v1/checkouts/1a809e6e-6095-4cdb-99b1-36352152abbb/deliveryInformation"
    },
    "updateMerchantInvoiceReferenceNumber" : {
      "href" : "https://api.paydirekt.de/api/checkout/v1/checkouts/1a809e6e-6095-4cdb-99b1-36352152abbb/merchantInvoiceReferenceNumber"
    },
    "self" : {
      "href" : "https://api.paydirekt.de/api/checkout/v1/checkouts/1a809e6e-6095-4cdb-99b1-36352152abbb"
    }
  }
}

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" : "2018-10-26"
}
HTTP/1.1 201 Created
Location: https://api.paydirekt.de/api/checkout/v1/checkouts/a754f8d9-76c6-4a4e-926f-00db2dc22628
Content-Type: application/hal+json;charset=UTF-8
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
Content-Length: 2081

{
  "checkoutId" : "a754f8d9-76c6-4a4e-926f-00db2dc22628",
  "type" : "ORDER_SECURED",
  "status" : "OPEN",
  "creationTimestamp" : "2018-10-23T09:42:48.891Z",
  "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" : "2018-10-23T10:12:48.891Z",
  "_links" : {
    "approve" : {
      "href" : "https://paydirekt.de/checkout/?p=a754f8d9-76c6-4a4e-926f-00db2dc22628#/checkout/a754f8d9-76c6-4a4e-926f-00db2dc22628"
    },
    "updateDeliveryInformation" : {
      "href" : "https://api.paydirekt.de/api/checkout/v1/checkouts/a754f8d9-76c6-4a4e-926f-00db2dc22628/deliveryInformation"
    },
    "updateMerchantInvoiceReferenceNumber" : {
      "href" : "https://api.paydirekt.de/api/checkout/v1/checkouts/a754f8d9-76c6-4a4e-926f-00db2dc22628/merchantInvoiceReferenceNumber"
    },
    "self" : {
      "href" : "https://api.paydirekt.de/api/checkout/v1/checkouts/a754f8d9-76c6-4a4e-926f-00db2dc22628"
    }
  }
}

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
  } ],
  "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/json;charset=UTF-8
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
Content-Length: 220

{
  "messages" : [ {
    "severity" : "ERROR",
    "code" : "VALIDATION_ERROR",
    "path" : "shippingAmount",
    "reasonCode" : "INVALID_FORMAT",
    "logref" : "2acbe6f2-51fe-4ad1-9b90-692f16cbabad:wOM5bt8rqF"
  } ]
}

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
  } ],
  "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/json;charset=UTF-8
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
Content-Length: 163

{
  "messages" : [ {
    "severity" : "ERROR",
    "code" : "MERCHANT_BANKACCOUNT_LOCKED",
    "logref" : "f41a1cab-344f-435f-9217-9b902a48a6f3:Sj1zlXhGAT"
  } ]
}

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
  } ],
  "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/json;charset=UTF-8
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
Content-Length: 309

{
  "messages" : [ {
    "severity" : "ERROR",
    "code" : "CONVERSION_ERROR",
    "path" : "shippingAddress.company",
    "reasonCode" : "HTTP_MESSAGE_NOT_READABLE",
    "logref" : "5dc462b0-b858-453e-a427-6e79afc75d61:3wnoU3dA6yz",
    "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

checkoutId

String

Immer vorhanden.

Eindeutige UUID aus 36 Zeichen für diesen Checkout-Vorgang. Wird vom paydirekt-System vergeben.

type

String

Immer vorhanden.

Die Art der Bestellung: DIRECT_SALE, ORDER oder ORDER_SECURED.
Im Falle eines DIRECT_SALE (Direktbestellung mit Einmalzahlung) wird automatisch eine Zahlungsautorisierung erzeugt. Der Händler erhält sofort eine Zahlungsgarantie.
Zu einer ORDER (Vorbestellung oder Bestellung mit Teilzahlungen) können direkt im Anschluss oder später ein oder mehrere Captures angestoßen werden. Für eine Order wird keine Zahlungsgarantie an den Händler ausgesprochen. Die Garantie wird erst mit dem Capture gegeben.
Zu einer ORDER_SECURED (gesicherte Vorbestellung oder Bestellung mit Teilzahlungen) können direkt im Anschluss oder später ein oder mehrere Captures angestoßen werden. Für eine gesicherte Vorbestellung wird eine Zahlungsgarantie für den gewählten Zeitraum (maximal 15 Kalendertage) an den Händler ausgesprochen. Captures (Teilzahlungen) werden innerhalb des Garantiezeitraums immer ausgeführt. Weitere Informationen zu Order und Capture finden Sie im Kapitel Capture.

status

String

Immer vorhanden.

Status des Checkouts: OPEN, PENDING, APPROVED, REJECTED, CANCELED, CLOSED oder EXPIRED.
OPEN: Der Checkout wurde neu angelegt und vom Benutzer noch nicht bestätigt.
PENDING: Der Checkout wurde vom Kunden bestätigt, aber noch nicht per execute aktiviert (derzeit nur paydirekt Express)
APPROVED: Der Checkout wurde vom Kunden bestätigt und vom System genehmigt. Im Falle einer ORDER können jetzt Captures angelegt werden.
REJECTED: Der Checkout wurde vom System abgelehnt. Die Zahlung war nicht erfolgreich. Es ist nicht zu erwarten, dass die Zahlung bei erneutem Versuch mit diesem Benutzer erfolgreich sein wird.
CANCELED: Der Checkout wurde vom Kunden abgebrochen oder es kam zu einem technischen Fehler. Der Checkout kann nicht weiter bearbeitet werden.
CLOSED: Nur ORDER: Die Bestellung ist geschlossen, es können keine weiteren Captures durchgeführt werden. Refunds sind weiter möglich.
EXPIRED: Der Checkout ist abgelaufen und kann nicht weiter verwendet werden. Der Benutzer hat den Checkout nicht innerhalb von 30 Minuten bestätigt.

correlationId

String

Vorhanden, sobald sich ein Kunde eingeloggt hat. UUID aus 36 Zeichen.

Die eindeutige Identifikation des Checkouts und aller dazugehöriger Transaktionen.

creationTimestamp

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.

expiryTimestamp

String

Immer vorhanden.

Der Ablaufzeitpunkt dieses Checkouts. Kann über das Feld expiryTime bei Anlage angepasst werden, ansonsten wird vom paydirekt-System als Standardwert 30 Minuten ab Erzeugung vergeben. Formatierung entsprechend ISO-8601 durch den Standard Java DateTimeFormatter. Abweichend davon werden immer drei Nachkommastellen für die Millisekunden ausgegeben.

totalAmount

Number

Immer vorhanden.

Der Gesamtbetrag der Bestellung, inkl. aller Lieferkosten. Es werden maximal 2 Nachkommastellen unterstützt.
Im Falle eines DIRECT_SALE wird eine Zahlung für diesen Betrag initiiert.
Im Falle einer ORDER können Captures bis maximal zu diesem Betrag angestoßen werden.

shippingAmount

Number

Vorhanden, falls bei Anlage übergeben.

Die Versandkosten der Bestellung. Dieser Wert wird nicht für Berechnungen verwendet, sondern dient nur zur Information.

orderAmount

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.

refundLimit

Number

Vorhanden, falls bei Anlage übergeben.

Maximal zurückzahlbarer Betrag als Prozentwert des Gesamtwertes der Bestellung.

overcapture

Boolean

Vorhanden, falls bei Anlage übergeben.

Flag für Overcapture-Checkouts.
Bei einem Overcapture-Checkout darf die Summe der Captures den Warenwert der Bestellung um bis zu 10% übersteigen.
Bei aktiviertem Flag muss das finalCapture-Feld des letzten Captures auf true gesetzt sein.
overcapture darf nur aktiviert sein, wenn es sich um einen Checkout des Typs ORDER handelt.
Kann nur von Händlern verwendet werden, die für dieses Feature freigeschaltet wurden.

maxCapturableAmount

Number

Vorhanden, falls Overcapture-Flag gesetzt.

Bei gesetztem Overcapture-Flag enthält dieses Feld den maximalen Betrag, der insgesamt abgerufen werden kann.

maxOvercaptureDifference

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.

currency

String

Immer vorhanden.

Die Währung des Gesamtbetrags. Derzeit wird nur EUR unterstützt.

items

Array von Items

Vorhanden, falls bei Anlage übergeben.

Die einzelnen Positionen des Warenkorbs.
Es wird empfohlen, diese Werte zu übergeben. Dies verbessert die Erkennung von fraudulenten Vorgängen und hilft, Disputes zu vermeiden.

shoppingCartType

String

Vorhanden, falls bei Anlage übergeben.

Kategorisiert den Warenkorb eines Checkouts anhand der Eigenschaften der enthaltenen Güter: Der Standardwert ist MIXED.
PHYSICAL: Der Warenkorb enthält ausschließlich physische Güter.
DIGITAL: Der Warenkorb enthält ausschließlich digitale Güter.
MIXED: Der Warenkorb enthält sowohl phyische als auch digitale Güter.
ANONYMOUS_DONATION: Beim Warenkorb handelt es sich ausschließlich um eine anonyme Spende.
AUTHORITIES_PAYMENT: Beim Warenkorb handelt es sich ausschließlich um Behördenzahlungen.

deliveryType

String

Vorhanden, falls bei Anlage übergeben.

Der Bestimmungsort einer Lieferung: STANDARD, PACKSTATION oder STORE_PICKUP. Der Standardwert ist STANDARD.
STANDARD: Die Güter werden an eine gewöhnliche Postadresse geliefert.
PACKSTATION: Die Güter werden an eine Packstation geliefert.
STORE_PICKUP: Die Güter werden in der Filiale abgeholt.
Dieses Feld enthält bei Express-Checkouts immer den Wert STANDARD und wird nicht anhand der gewählten Lieferoption aktualisiert.

shippingAddress

ShippingAddress

Vorhanden, falls bei Anlage übergeben.

Die Lieferanschrift des Empfängers. Diese Adresse wird dem Kunden nach dem Login im paydirekt-System zur Kontrolle angezeigt.

merchantCustomerNumber

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.

merchantOrderReferenceNumber

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 instructionId und im Verwendungszweck bei Händler und Käufer verwendet.

merchantInvoiceReferenceNumber

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.

merchantReconciliationReferenceNumber

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 merchantReconciliationReferenceNumber verwendet.

redirectUrlAfterSuccess

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.

redirectUrlAfterCancellation

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.

redirectUrlAfterRejection

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.

callbackUrlStatusUpdates

String

Vorhanden, falls bei Anlage übergeben.

URL des Endpoints, der Mitteilungen zu Statusänderungen des Checkouts empfangen soll.

minimumAge

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 redirectUrlAfterAgeVerificationFailure (siehe unten). Bei Nicht-Angabe dieses Wertes erfolgt keine Altersverifkation.

redirectUrlAfterAgeVerificationFailure

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 minimumAge, zum Pflichtfeld. Ist keine Altersverifikation erforderlich, ist dieses Feld wegzulassen.

note

String

Vorhanden, falls bei Anlage übergeben.

Freitextfeld, das auf dem Kontoauszug im Feld Verwendungzweck erscheint (nur DIRECT_SALE).

deliveryInformation

Object

Optional.

Enthält Informationen über die Lieferung.

deliveryInformation.expectedShippingDate

String

Optional.

Erwartetes Versanddatum.

deliveryInformation.logisticsProvider

String

Optional.

Paket-Dienstleister.

deliveryInformation.trackingNumber

String

Optional.

Sendungsnummer.

preauthorizationValidity

String

Optional.

Garantiezeitraum für die gesicherte Vorbestellung (ORDER_SECURED). Captures innerhalb dieses Zeitraums sind für den Händler garantiert.

_links

Object

Links zu Ressourcen und verfügbaren Aktionen des Checkouts.

_embedded

Object

Embedded Ressourcen

Relation Description

self

Link zu dieser Ressource.

approve

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 approve Links im action Attribute des form Tags) erfolgen. Die Bestätigung durch den Kunden muss innerhalb von 30 Minuten erfolgen. Dieser Link ist nur vorhanden, wenn der Checkout vom Kunden noch nicht autorisiert wurde.

close

Link zum Endpoint, über den die Order geschlossen werden kann. Dieser Link ist nur vorhanden, wenn es sich um einen Checkout vom Typ order handelt und er im Status APPROVED ist.

captures

Link zu Captures. Dieser Link ist nur vorhanden, wenn für diese Bestellung ein Capture möglich ist.

refunds

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 SUCCESSFUL vorhanden ist. Wenn der Link nicht vorhanden ist, sind keine Rückzahlungen möglich.

updateDeliveryInformation

Link zum Update der Lieferinformation. Dieser Link ist nur vorhanden, wenn die Update Frist für diesen Checkout noch nicht überschritten ist.

updateMerchantInvoiceReferenceNumber

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

captures

Array von Captures, sofern Captures zu diesem Checkout vorhanden sind.

refunds

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)

ACCESS_TOKEN_EXPIRED

Siehe Resource Access.

404 (Not Found)

CHECKOUT_NOT_FOUND

Der angefragte Checkout existiert nicht

Beispiel (Direct Sale nach der Anlage)

GET /api/checkout/v1/checkouts/67403284-0171-4ada-a8d3-5e0fa79a3164 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
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
Content-Length: 2445

{
  "checkoutId" : "67403284-0171-4ada-a8d3-5e0fa79a3164",
  "type" : "DIRECT_SALE",
  "status" : "OPEN",
  "creationTimestamp" : "2018-10-23T09:39:19.590Z",
  "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
  } ],
  "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" : "2018-10-23T10:09:19.590Z",
  "_links" : {
    "approve" : {
      "href" : "https://paydirekt.de/checkout/?p=67403284-0171-4ada-a8d3-5e0fa79a3164#/checkout/67403284-0171-4ada-a8d3-5e0fa79a3164"
    },
    "updateDeliveryInformation" : {
      "href" : "https://api.paydirekt.de/api/checkout/v1/checkouts/67403284-0171-4ada-a8d3-5e0fa79a3164/deliveryInformation"
    },
    "updateMerchantInvoiceReferenceNumber" : {
      "href" : "https://api.paydirekt.de/api/checkout/v1/checkouts/67403284-0171-4ada-a8d3-5e0fa79a3164/merchantInvoiceReferenceNumber"
    },
    "self" : {
      "href" : "https://api.paydirekt.de/api/checkout/v1/checkouts/67403284-0171-4ada-a8d3-5e0fa79a3164"
    }
  }
}

Beispiel (Direct Sale nach Approval durch Kunden)

GET /api/checkout/v1/checkouts/67403284-0171-4ada-a8d3-5e0fa79a3164 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
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
Content-Length: 3067

{
  "checkoutId" : "67403284-0171-4ada-a8d3-5e0fa79a3164",
  "type" : "DIRECT_SALE",
  "status" : "APPROVED",
  "correlationId" : "ext0815-00000001",
  "creationTimestamp" : "2018-10-23T09:39:19.590Z",
  "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
  } ],
  "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" : "2018-10-23T10:09:19.590Z",
  "_links" : {
    "refunds" : {
      "href" : "https://api.paydirekt.de/api/checkout/v1/checkouts/67403284-0171-4ada-a8d3-5e0fa79a3164/refunds"
    },
    "updateDeliveryInformation" : {
      "href" : "https://api.paydirekt.de/api/checkout/v1/checkouts/67403284-0171-4ada-a8d3-5e0fa79a3164/deliveryInformation"
    },
    "updateMerchantInvoiceReferenceNumber" : {
      "href" : "https://api.paydirekt.de/api/checkout/v1/checkouts/67403284-0171-4ada-a8d3-5e0fa79a3164/merchantInvoiceReferenceNumber"
    },
    "self" : {
      "href" : "https://api.paydirekt.de/api/checkout/v1/checkouts/67403284-0171-4ada-a8d3-5e0fa79a3164"
    }
  },
  "_embedded" : {
    "captures" : [ {
      "type" : "CAPTURE_DIRECT_SALE",
      "transactionId" : "41dfee54-996b-45a7-a6e3-69c734b970b5",
      "amount" : 100.0,
      "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/67403284-0171-4ada-a8d3-5e0fa79a3164/captures/41dfee54-996b-45a7-a6e3-69c734b970b5"
        }
      }
    } ]
  }
}

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 20 Minuten bis zu 5 Mal wiederholen.

POST callbackUrlStatusUpdates

Request

Feld Typ Eigenschaften Beschreibung

checkoutId

String

Immer vorhanden.

Eindeutige UUID aus 36 Zeichen für diesen Checkout-Vorgang. Wird vom paydirekt-System vergeben.

merchantOrderReferenceNumber

String

Pflichtfeld.
Maximal 20 Zeichen. Nur SEPA-konforme Zeichen.

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 instructionId und im Verwendungszweck bei Händler und Käufer verwendet.

checkoutStatus

String

Immer vorhanden.

Status des Checkouts: OPEN, PENDING, APPROVED, REJECTED, CANCELED, CLOSED oder EXPIRED.
OPEN: Der Checkout wurde neu angelegt und vom Benutzer noch nicht bestätigt.
PENDING: Der Checkout wurde vom Kunden bestätigt, aber noch nicht per execute aktiviert (derzeit nur paydirekt Express)
APPROVED: Der Checkout wurde vom Kunden bestätigt und vom System genehmigt. Im Falle einer ORDER können jetzt Captures angelegt werden.
REJECTED: Der Checkout wurde vom System abgelehnt. Die Zahlung war nicht erfolgreich. Es ist nicht zu erwarten, dass die Zahlung bei erneutem Versuch mit diesem Benutzer erfolgreich sein wird.
CANCELED: Der Checkout wurde vom Kunden abgebrochen oder es kam zu einem technischen Fehler. Der Checkout kann nicht weiter bearbeitet werden.
CLOSED: Nur ORDER: Die Bestellung ist geschlossen, es können keine weiteren Captures durchgeführt werden. Refunds sind weiter möglich.
EXPIRED: Der Checkout ist abgelaufen und kann nicht weiter verwendet werden. Der Benutzer hat den Checkout nicht innerhalb von 30 Minuten bestätigt.

Beispiel
POST /themerchant/update/order-A12223412/status HTTP/1.1
Content-Type: application/json;charset=utf-8

{
  "checkoutId" : "20812bb9-a46f-4fe3-88b9-741602cfc977",
  "merchantOrderReferenceNumber" : "order-A12223412",
  "checkoutStatus" : "APPROVED"
}

Response

Die Response enthält keinen Body und wird vom paydirekt-System nicht weiter verarbeitet. Der HTTP-Statuscode sollte dennoch für etwaige Serviceanfragen Rückschlüsse auf die Verarbeitung der Status-Benachrichtigung zulassen.

Beispiel
HTTP/1.1 200 OK

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

expectedShippingDate

String

Optional.
Zeitstempel im ISO-8601-Format.

Erwartetes Versanddatum.

logisticsProvider

String

Optional.

Paket-Dienstleister.

trackingNumber

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)

ACCESS_TOKEN_EXPIRED

Siehe Resource Access.

404 (Not Found)

CHECKOUT_NOT_FOUND

Der zu aktualisierende Checkout existiert nicht.

422 (Unprocessable Entity)

CHECKOUT_UPDATE_TIMEFRAME_EXPIRED

Der Checkout kann nicht mehr aktualisiert werden, da mehr als 25 Tage seit dem letzten Capture verstrichen sind.

Beispielrequest

PUT /api/checkout/v1/checkouts/2a7f8093-073e-4951-98fc-96d4591a637d/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

merchantInvoiceReferenceNumber

String

Optional.
Maximal 100 Zeichen.

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)

ACCESS_TOKEN_EXPIRED

Siehe Resource Access.

404 (Not Found)

CHECKOUT_NOT_FOUND

Der zu aktualisierende Checkout existiert nicht.

422 (Unprocessable Entity)

CHECKOUT_UPDATE_TIMEFRAME_EXPIRED

Der Checkout kann nicht mehr aktualisiert werden, da mehr als 25 Tage seit dem letzten Capture verstrichen sind.

Beispielrequest

PUT /api/checkout/v1/checkouts/eba794bd-335a-409f-bc71-3bd0dd3394d1/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 Typ CAPTURE_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 Flag finalCapture 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

amount

Number

Pflichtfeld.
Zwischen 0.01 und 50000.
Maximal zwei Nachkommastellen.

Der Betrag der Zahlung in Währung der ursprünglichen Order. Der Maximalbetrag liegt bei 50 000,00 EUR.

finalCapture

Boolean

Optional.
Flag muss bei dem letzten Capture eines Checkouts mit aktiviertem overcapture-Flag true sein.

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.

note

String

Optional.
Maximal 37 Zeichen.

Ein Freitext für den Kunden. Der Freitext wird dem Kunden für diese Zahlung im Verwendungszweck angezeigt.

merchantCaptureReferenceNumber

String

Optional.
Maximal 30 Zeichen.

Händler-interne Referenznummer für diesen Capture-Vorgang.

merchantReconciliationReferenceNumber

String

Optional.
Maximal 30 Zeichen.

Reconciliation-Nummer. Diese wird in den Verwendungszweck der Händlerzahlung eingefügt.

captureInvoiceReferenceNumber

String

Optional.
Maximal 100 Zeichen.

Händler-interne, eindeutige Rechnungsnummer für diesen Capture-Vorgang.

callbackUrlStatusUpdates

String

Optional.
Maximal 2000 Zeichen.

URL des Endpoints, der Mitteilungen zu Statusänderungen des Captures empfangen soll.

deliveryInformation

Object

Optional.

Enthält Informationen über die Lieferung.

deliveryInformation.expectedShippingDate

String

Optional.

Erwartetes Versanddatum.

deliveryInformation.logisticsProvider

String

Optional.

Paket-Dienstleister.

deliveryInformation.trackingNumber

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)

VALIDATION_ERROR

Der Request ist syntaktisch ungültig.

401 (Unauthorized)

ACCESS_TOKEN_EXPIRED

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.

422 (Unprocessable Entity)

CAPTURE_AMOUNT_EXCEEDED

Die Summe aller Captures übersteigt den Gesamtbetrag des Checkouts.

422 (Unprocessable Entity)

CAPTURE_CHECKOUT_WRONG_TYPE

Für diesen Checkout-Typ kann kein Capture angelegt werden.

422 (Unprocessable Entity)

CAPTURE_ORDER_CLOSED

Es wurde versucht, ein Capture für einen bereits geschlossenen Checkout anzulegen.

422 (Unprocessable Entity)

CAPTURE_ORDER_NOT_APPROVED

Es wurde versucht, einen Capture für eine Order anzulegen, die vom Kunden nicht bestätigt wurde.

422 (Unprocessable Entity)

CAPTURE_NOT_AUTHORIZED

Der Capture-Betrag wurde von der Käuferbank nicht autorisiert.

422 (Unprocessable Entity)

MERCHANT_BANKACCOUNT_LOCKED

Ihr Händlerkonto ist gesperrt. Bitte wenden Sie sich an den paydirekt Support.

422 (Unprocessable Entity)

CHECKOUT_REJECTED

Der Checkout wurde abgelehnt. Es kann kein Capture angelegt werden.

Beispiel

POST /api/checkout/v1/checkouts/a754f8d9-76c6-4a4e-926f-00db2dc22628/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/a754f8d9-76c6-4a4e-926f-00db2dc22628/captures/f5ea68ba-120e-4db4-b7ad-f47bdf20379b
Content-Type: application/hal+json;charset=UTF-8
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
Content-Length: 754

{
  "type" : "CAPTURE_ORDER",
  "transactionId" : "f5ea68ba-120e-4db4-b7ad-f47bdf20379b",
  "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/a754f8d9-76c6-4a4e-926f-00db2dc22628/captures/f5ea68ba-120e-4db4-b7ad-f47bdf20379b"
    }
  }
}

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

type

String

Immer vorhanden.

Typ der Capture-Transaktion. Entweder CAPTURE_DIRECT_SALE oder CAPTURE_ORDER. Der Wert wird automatisch durch den Typ des Checkouts ermittelt.

transactionId

String

Immer vorhanden.

Eindeutige Transaktions-ID dieses Captures (UUID aus 36 Zeichen). Der Wert wird durch das paydirekt-System vergeben.

amount

Number

Immer vorhanden.

Der Betrag der Zahlung in Währung der ursprünglichen Order. Der Maximalbetrag liegt bei 50 000,00 EUR.

finalCapture

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.

merchantCaptureReferenceNumber

String

Vorhanden, falls bei Anlage übergeben.

Händler-interne Referenznummer für diesen Capture-Vorgang.

merchantReconciliationReferenceNumber

String

Vorhanden, falls bei Anlage übergeben.

Reconciliation-Nummer. Diese wird in den Verwendungszweck der Händlerzahlung eingefügt.

captureInvoiceReferenceNumber

String

Vorhanden, falls bei Anlage übergeben.

Händler-interne, eindeutige Rechnungsnummer für diesen Capture-Vorgang.

callbackUrlStatusUpdates

String

Vorhanden, falls bei Anlage übergeben.

URL des Endpoints, der Mitteilungen zu Statusänderungen des Checkouts empfangen soll.

paymentInformationId

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.
UUID aus 36 Zeichen.

status

String

Immer vorhanden.

Gibt an, ob die Autorisierung durch die Bank noch aussteht (PENDING), erfolgreich war (SUCCESSFUL) oder abgelehnt wurde (REJECTED). Im Falle von SUCCESSFUL ist die Zahlungsgarantie für diese Transaktion gegeben.

deliveryInformation

Object

Vorhanden, falls bei Anlage übergeben.

Enthält Informationen über die Lieferung.

deliveryInformation.expectedShippingDate

String

Vorhanden, falls bei Anlage übergeben.

Erwartetes Versanddatum.

deliveryInformation.logisticsProvider

String

Vorhanden, falls bei Anlage übergeben.

Paket-Dienstleister.

deliveryInformation.trackingNumber

String

Vorhanden, falls bei Anlage übergeben.

Paketnummer.

_links

Object

Links zu Ressourcen und verfügbaren Aktionen.

Return Codes

Status Code Message Code Beschreibung

200 (Ok)

Der Capture wurde erfolgreich gesendet.

401 (Unauthorized)

ACCESS_TOKEN_EXPIRED

Siehe Resource Access.

404 (Not Found)

CHECKOUT_NOT_FOUND

Der Checkout wurde nicht gefunden.

404 (Not Found)

TRANSACTION_NOT_FOUND

Die Transaktion wurde nicht gefunden.

Beispiel

GET /api/checkout/v1/checkouts/a754f8d9-76c6-4a4e-926f-00db2dc22628/captures/f5ea68ba-120e-4db4-b7ad-f47bdf20379b 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
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
Content-Length: 820

{
  "type" : "CAPTURE_ORDER",
  "transactionId" : "f5ea68ba-120e-4db4-b7ad-f47bdf20379b",
  "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/a754f8d9-76c6-4a4e-926f-00db2dc22628/captures/f5ea68ba-120e-4db4-b7ad-f47bdf20379b"
    }
  }
}

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 20 Minuten bis zu 5 Mal wiederholen.

POST callbackUrlStatusUpdates

Request

Feld Typ Eigenschaften Beschreibung

checkoutId

String

Immer vorhanden.

Eindeutige UUID aus 36 Zeichen für diesen Checkout-Vorgang. Wird vom paydirekt-System vergeben.

merchantOrderReferenceNumber

String

Pflichtfeld.
Maximal 20 Zeichen. Nur SEPA-konforme Zeichen.

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 instructionId und im Verwendungszweck bei Händler und Käufer verwendet.

transactionId

String

Immer vorhanden.

Eindeutige Transaktions-ID dieses Captures (UUID aus 36 Zeichen). Der Wert wird durch das paydirekt-System vergeben.

merchantCaptureReferenceNumber

String

Optional.
Maximal 30 Zeichen.

Händler-interne Referenznummer für diesen Capture-Vorgang.

captureStatus

String

Immer vorhanden.

Gibt an, ob die Autorisierung durch die Bank noch aussteht (PENDING), erfolgreich war (SUCCESSFUL) oder abgelehnt wurde (REJECTED). Im Falle von SUCCESSFUL ist die Zahlungsgarantie für diese Transaktion gegeben.

Beispiel
POST /themerchant/update/order-A12223412/status HTTP/1.1
Content-Type: application/json;charset=utf-8

{
  "checkoutId" : "8a96df68-846a-4a74-8126-10c66d26ae45",
  "merchantOrderReferenceNumber" : "order-A12223412",
  "merchantCaptureReferenceNumber" : "capture-21323",
  "captureStatus" : "SUCCESSFUL",
  "transactionId" : "a07b1feb-ca7c-46b5-8dc2-51ff09832822"
}

Response

Die Response enthält keinen Body und wird vom paydirekt-System nicht weiter verarbeitet. Der HTTP-Statuscode sollte dennoch für etwaige Serviceanfragen Rückschlüsse auf die Verarbeitung der Status-Benachrichtigung zulassen.

Beispiel
HTTP/1.1 200 OK

Order schließen

POST /api/checkout/v1/checkouts/{checkoutId}/close

Bestellungen vom Typ ORDER 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)

ACCESS_TOKEN_EXPIRED

Siehe Resource Access.

422 (Unprocessable Entity)

ORDER_NOT_APPROVED

Die Bestellung ist vom Kunden nicht bestätigt worden. Unbestätigte Bestellungen können nicht geschlossen werden.

422 (Unprocessable Entity)

ORDER_ALREADY_CLOSED

Die Bestellung ist bereits geschlossen.

422 (Unprocessable Entity)

NOT_AN_ORDER

Dieser Checkout ist nicht vom Typ ORDER.

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ückzahung 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

amount

Number

Pflichtfeld.
Zwischen 0.01 und 100000.
Maximal zwei Nachkommastellen.

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.

note

String

Optional.
Maximal 37 Zeichen.

Ein Freitext für den Kunden. Der Freitext wird dem Kunden im Verwendungszweck angezeigt.

reason

String

Optional.

Grund des Refunds
MERCHANT_TECHNICAL_PROBLEM: Technisches Problem bei Abwicklung.
MERCHANT_CAN_NOT_DELIVER_GOODS: Händler kann Ware nicht liefern.
REFUND_OBLIGINGNESS: Rücküberweisung wegen Kulanz.
CUSTOMER_RETURN_GOODS: Rücküberweisung wegen Warenrücksendung.

merchantRefundReferenceNumber

String

Optional.
Maximal 30 Zeichen.

Händler-interne Referenznummer für diesen Refund-Vorgang.

merchantReconciliationReferenceNumber

String

Optional.
Maximal 30 Zeichen.

Reconciliation-Nummer. Diese wird in den Verwendungszweck der Händlerzahlung eingefügt.

callbackUrlStatusUpdates

String

Optional.
Maximal 2000 Zeichen.

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

400 (Bad Request)

VALIDATION_ERROR

Der Request ist syntaktisch ungültig.

401 (Unauthorized)

ACCESS_TOKEN_EXPIRED

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/1a809e6e-6095-4cdb-99b1-36352152abbb/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/1a809e6e-6095-4cdb-99b1-36352152abbb/refunds/9e66993a-f4e4-44c2-b3dd-d194a5ca55bd
Content-Type: application/hal+json;charset=UTF-8
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
Content-Length: 596

{
  "type" : "REFUND",
  "transactionId" : "9e66993a-f4e4-44c2-b3dd-d194a5ca55bd",
  "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/1a809e6e-6095-4cdb-99b1-36352152abbb/refunds/9e66993a-f4e4-44c2-b3dd-d194a5ca55bd"
    }
  }
}

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

type

String

Immer vorhanden.

Typ der Transaktion. Hier immer REFUND.

transactionId

String

Immer vorhanden.

Eindeutige Transaktions-ID dieses Refunds (UUID aus 36 Zeichen). Der Wert wird durch das paydirekt-System vergeben.

amount

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.

note

String

Vorhanden, falls bei Anlage übergeben.

Ein Freitext für den Kunden. Der Freitext wird dem Kunden im Verwendungszweck angezeigt.

reason

String

Optional.

Grund des Refunds
MERCHANT_TECHNICAL_PROBLEM: Technisches Problem bei Abwicklung.
MERCHANT_CAN_NOT_DELIVER_GOODS: Händler kann Ware nicht liefern.
REFUND_OBLIGINGNESS: Rücküberweisung wegen Kulanz.
CUSTOMER_RETURN_GOODS: Rücküberweisung wegen Warenrücksendung.
TECHNICAL_PROBLEM: Technisches Problem bei Abwicklung/Rückabwicklung.
MERCHANT_CAN_NOT_PROOF_SHIPMENT: Händler kann Versandbeleg nicht vorweisen (Dispute).
REFUND_ON_BEHALF_OF_MERCHANT: Rückabwicklung im Auftrag des Händlers.
REFUND_NOT_ON_BEHALF_OF_MERCHANT: Rückabwicklung ohne Auftrag des Händlers.
REFUND_MERCHANT_FRAUD: Rückabwicklung wegen Händlerfraud.

merchantRefundReferenceNumber

String

Vorhanden, falls bei Anlage übergeben.

Händler-interne Referenznummer für diesen Refund-Vorgang.

merchantReconciliationReferenceNumber

String

Vorhanden, falls bei Anlage übergeben.

Reconciliation-Nummer. Diese wird in den Verwendungszweck der Händlerzahlung eingefügt.

paymentInformationId

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.
UUID aus 36 Zeichen.

callbackUrlStatusUpdates

String

Vorhanden, falls bei Anlage übergeben.

URL des Endpoints, der Mitteilungen zu Statusänderungen des Refunds empfangen soll.

status

String

Immer vorhanden.

Status des Refunds
PENDING: Initialer Status. Der Refund wird im Zahlungsverkehr bearbeitet.
ERROR: Der Rückzahlungsvorgang ist aus technischen Gründen temporär unterbrochen.
SUCCESSFUL: Der Refund war erfolgreich. Der Betrag ist bereits auf dem Käuferkonto verbucht oder wird gerade von der Käuferbank verarbeitet.
FAILED: Der Refund konnte im Zahlungsverkehr endgültig nicht verarbeitet werden und muss neu initiiert werden.

_links

Object

Links zu Ressourcen und verfügbaren Aktionen.

Return Codes

Status Code Message Code Beschreibung

200 (Ok)

Die Anfrage wurde korrekt verarbeitet.

401 (Unauthorized)

ACCESS_TOKEN_EXPIRED

Siehe Resource Access.

404 (Not Found)

CHECKOUT_NOT_FOUND

Der Checkout wurde nicht gefunden, oder Sie haben keine Zugriff auf diesen Checkout.

404 (Not Found)

TRANSACTION_NOT_FOUND

Die Rückzahlung mit der angegebenen refundId wurde nicht gefunden.

Beispiel

GET /api/checkout/v1/checkouts/1a809e6e-6095-4cdb-99b1-36352152abbb/refunds/9e66993a-f4e4-44c2-b3dd-d194a5ca55bd 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
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
Content-Length: 662

{
  "type" : "REFUND",
  "transactionId" : "9e66993a-f4e4-44c2-b3dd-d194a5ca55bd",
  "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/1a809e6e-6095-4cdb-99b1-36352152abbb/refunds/9e66993a-f4e4-44c2-b3dd-d194a5ca55bd"
    }
  }
}

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 20 Minuten bis zu 5 Mal wiederholen.

POST callbackUrlStatusUpdates

Request

Feld Typ Eigenschaften Beschreibung

checkoutId

String

Immer vorhanden.

Eindeutige UUID aus 36 Zeichen für diesen Checkout-Vorgang. Wird vom paydirekt-System vergeben.

transactionId

String

Immer vorhanden.

Eindeutige Transaktions-ID dieses Refunds (UUID aus 36 Zeichen). Der Wert wird durch das paydirekt-System vergeben.

merchantRefundReferenceNumber

String

Optional.
Maximal 30 Zeichen.

Händler-interne Referenznummer für diesen Refund-Vorgang.

merchantReconciliationReferenceNumber

String

Optional.
Maximal 30 Zeichen.

Reconciliation-Nummer. Diese wird in den Verwendungszweck der Händlerzahlung eingefügt.

refundStatus

String

Status des Refunds
PENDING: Initialer Status. Der Refund wird im Zahlungsverkehr bearbeitet.
ERROR: Der Rückzahlungsvorgang ist aus technischen Gründen temporär unterbrochen.
SUCCESSFUL: Der Refund war erfolgreich. Der Betrag ist bereits auf dem Käuferkonto verbucht oder wird gerade von der Käuferbank verarbeitet.
FAILED: Der Refund konnte im Zahlungsverkehr endgültig nicht verarbeitet werden und muss neu initiiert werden.

Beispiel
POST /themerchant/update/refund-12345/status HTTP/1.1
Content-Type: application/json;charset=utf-8

{
  "checkoutId" : "452ed6f6-6457-43e7-a650-f5131832ec09",
  "transactionId" : "47eaf56e-84f7-46ba-b350-0391617ce982",
  "merchantRefundReferenceNumber" : "refund-12345",
  "merchantReconciliationReferenceNumber" : "reconciliation-12345",
  "refundStatus" : "SUCCESSFUL"
}

Response

Die Response enthält keinen Body und wird vom paydirekt-System nicht weiter verarbeitet. Der HTTP-Statuscode sollte dennoch für etwaige Serviceanfragen Rückschlüsse auf die Verarbeitung der Status-Benachrichtigung zulassen.

Beispiel
HTTP/1.1 200 OK

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.
Ablauf Express-Checkout
Figure 2. Ablauf eines Bestellprozesses bei einem Express-Checkout

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

type

String

Pflichtfeld.

Die Art der Bestellung: DIRECT_SALE, ORDER oder ORDER_SECURED.
Im Falle eines DIRECT_SALE (Direktbestellung mit Einmalzahlung) wird automatisch eine Zahlungsautorisierung erzeugt. Der Händler erhält sofort eine Zahlungsgarantie.
Zu einer ORDER (Vorbestellung oder Bestellung mit Teilzahlungen) können direkt im Anschluss oder später ein oder mehrere Captures angestoßen werden. Für eine Order wird keine Zahlungsgarantie an den Händler ausgesprochen. Die Garantie wird erst mit dem Capture gegeben.
Zu einer ORDER_SECURED (gesicherte Vorbestellung oder Bestellung mit Teilzahlungen) können direkt im Anschluss oder später ein oder mehrere Captures angestoßen werden. Für eine gesicherte Vorbestellung wird eine Zahlungsgarantie für den gewählten Zeitraum (maximal 15 Kalendertage) an den Händler ausgesprochen. Captures (Teilzahlungen) werden innerhalb des Garantiezeitraums immer ausgeführt. Weitere Informationen zu Order und Capture finden Sie im Kapitel Capture.

express

Boolean

Pflichtfeld für Express-Checkout.

Flag, gibt an, dass es sich um einen Express-Checkout handelt. Muss true sein.

totalAmount

Number

Pflichtfeld.
Zwischen 0.01 und 50000.
Maximal zwei Nachkommastellen.

Der Gesamtbetrag der Bestellung, inkl. aller Lieferkosten. Es werden maximal 2 Nachkommastellen unterstützt.
Im Falle eines DIRECT_SALE wird eine Zahlung für diesen Betrag initiiert.
Im Falle einer ORDER können Captures bis maximal zu diesem Betrag angestoßen werden.

shippingAmount

Number

Optional.
Mindestens 0.00.
Maximal zwei Nachkommastellen.
Falls nicht übergeben, wird der Standardwert 0 gesetzt.

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 callbackUrlCheckDestinations übergeben wurde, sind die Versandkosten final.

orderAmount

Number

Optional.
Zwischen 0.01 und 50000.
Maximal zwei Nachkommastellen.
Falls nicht übergeben, wird der Wert gleich dem totalAmount gesetzt.

Der Warenwert der Bestellung, ohne Versandkosten. Dieser Wert wird nicht für Berechnungen verwendet, sondern dient nur zur Information.

refundLimit

Number

Optional.
Zwischen 100 und 200.
Wird bei Nichtangabe auf 200 gesetzt, das heißt maximal das Zweifache des Bestellwertes kann zurückgezahlt werden.

Maximal zurückzahlbarer Betrag als Prozentwert des Gesamtwertes der Bestellung.

overcapture

Boolean

Optional.
(Standard: false)

Flag für Overcapture-Checkouts.
Bei einem Overcapture-Checkout darf die Summe der Captures den Warenwert der Bestellung um bis zu 10% übersteigen.
Bei aktiviertem Flag muss das finalCapture-Feld des letzten Captures auf true gesetzt sein.
overcapture darf nur aktiviert sein, wenn es sich um einen Checkout des Typs ORDER handelt.
Kann nur von Händlern verwendet werden, die für dieses Feature freigeschaltet wurden.

currency

String

Pflichtfeld.

Die Währung des Gesamtbetrags. Derzeit wird nur EUR unterstützt.

items

Array von Items

Optional.

Die einzelnen Positionen des Warenkorbs.
Es wird empfohlen, diese Werte zu übergeben. Dies verbessert die Erkennung von fraudulenten Vorgängen und hilft, Disputes zu vermeiden.

shoppingCartType

String

Optional.

Kategorisiert den Warenkorb eines Checkouts anhand der Eigenschaften der enthaltenen Güter: Der Standardwert ist MIXED.
PHYSICAL: Der Warenkorb enthält ausschließlich physische Güter.
DIGITAL: Der Warenkorb enthält ausschließlich digitale Güter.
MIXED: Der Warenkorb enthält sowohl phyische als auch digitale Güter.
ANONYMOUS_DONATION: Beim Warenkorb handelt es sich ausschließlich um eine anonyme Spende.
AUTHORITIES_PAYMENT: Beim Warenkorb handelt es sich ausschließlich um Behördenzahlungen.

deliveryType

String

Optional.

Der Bestimmungsort einer Lieferung: STANDARD, PACKSTATION oder STORE_PICKUP. Der Standardwert ist STANDARD.
STANDARD: Die Güter werden an eine gewöhnliche Postadresse geliefert.
PACKSTATION: Die Güter werden an eine Packstation geliefert.
STORE_PICKUP: Die Güter werden in der Filiale abgeholt.
Dieses Feld enthält bei Express-Checkouts immer den Wert STANDARD und wird nicht anhand der gewählten Lieferoption aktualisiert.

merchantCustomerNumber

String

Optional.
Maximal 50 Zeichen.

Händler-interne Kundennummer des Käufers. Wird dem Kunden in der Transaktionsübersicht angezeigt. Wird dem Händler in der Transaktionsübersicht angezeigt.

merchantOrderReferenceNumber

String

Optional.
Maximal 20 Zeichen. Nur SEPA-konforme Zeichen.

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 instructionId und im Verwendungszweck bei Händler und Ku00E4ufer verwendet.
Wird bei der Ausführung überschrieben.

merchantInvoiceReferenceNumber

String

Optional.
Maximal 100 Zeichen.

Händler-interne, eindeutige Rechnungsnummer für diesen Kauf- bzw. Zahlvorgang. Wird dem Händler in der Transaktionsübersicht angezeigt.

merchantReconciliationReferenceNumber

String

Optional.
Maximal 30 Zeichen.

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 merchantReconciliationReferenceNumber verwendet.

sha256hashedEmailAddress

String

Optional.
Maximal 64 Zeichen.

Die E-Mail Adresse des Käufers als Base-64 encodierter SHA-256 Hash-Wert ohne Padding, sofern vorhanden. Pseudo-Code: sha256hashedEmailAddress = toStringUTF8(base64(sha256(toBytesUTF8(emailAddress)))). Beispiel: Aus der E-Mail-Adresse max@muster.de muss sich exakt der folgende HashWert ergeben (ohne Anführungszeichen): "6JL4VUgVxkq2m+a9I6ScfW2ofJP5y6wsvSaHIsX+iLs=". Diese Information wird zur Fraud Prevention verwendet.

redirectUrlAfterSuccess

String

Pflichtfeld, außer bei oneKlick-Checkouts.
Maximal 2000 Zeichen.

Die Rücksprung-Adresse des Webshops (inkl. Referenz auf die Bestellung), die nach erfolgreicher Bezahlung aufgerufen wird.

redirectUrlAfterCancellation

String

Pflichtfeld, außer bei oneKlick-Checkouts.
Maximal 2000 Zeichen.

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.

redirectUrlAfterRejection

String

Pflichtfeld, außer bei oneKlick-Checkouts.
Maximal 2000 Zeichen.

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.

callbackUrlStatusUpdates

String

Optional.
Maximal 2000 Zeichen.

URL des Endpoints, der Mitteilungen zu Statusänderungen des Checkouts empfangen soll.

minimumAge

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 redirectUrlAfterAgeVerificationFailure (siehe unten). Bei Nicht-Angabe dieses Wertes erfolgt keine Altersverifkation.

redirectUrlAfterAgeVerificationFailure

String

Pflichtfeld, wenn minimumAge gesetzt ist.
Maximal 2000 Zeichen.

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 minimumAge, zum Pflichtfeld. Ist keine Altersverifikation erforderlich, ist dieses Feld wegzulassen.

note

String

Optional.
Maximal 37 Zeichen.

Freitextfeld, das auf dem Kontoauszug im Feld Verwendungzweck erscheint (nur DIRECT_SALE).

expiryTime

Number

Optional.
Minimal 120. Maximal 1800.

Zahl, die die Gültigkeit des Checkouts ab Anlage in Sekunden angibt. Bei Nicht-Angabe werden 1800 Sekunden angenommen.

callbackUrlCheckDestinations

String

Optional für Express-Checkouts.
Maximal 2000 Zeichen.

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.

webUrlShippingTerms

String

Pflichtfeld für Express-Checkouts.
Maximal 2000 Zeichen.

Link zu einer Webseite mit den Versandbedingungen des Händlers.

Response

Feld Typ Eigenschaften Beschreibung

checkoutId

String

Immer vorhanden.

Eindeutige UUID aus 36 Zeichen für diesen Checkout-Vorgang. Wird vom paydirekt-System vergeben.

type

String

Immer vorhanden.

Die Art der Bestellung: DIRECT_SALE, ORDER oder ORDER_SECURED.
Im Falle eines DIRECT_SALE (Direktbestellung mit Einmalzahlung) wird automatisch eine Zahlungsautorisierung erzeugt. Der Händler erhält sofort eine Zahlungsgarantie.
Zu einer ORDER (Vorbestellung oder Bestellung mit Teilzahlungen) können direkt im Anschluss oder später ein oder mehrere Captures angestoßen werden. Für eine Order wird keine Zahlungsgarantie an den Händler ausgesprochen. Die Garantie wird erst mit dem Capture gegeben.
Zu einer ORDER_SECURED (gesicherte Vorbestellung oder Bestellung mit Teilzahlungen) können direkt im Anschluss oder später ein oder mehrere Captures angestoßen werden. Für eine gesicherte Vorbestellung wird eine Zahlungsgarantie für den gewählten Zeitraum (maximal 15 Kalendertage) an den Händler ausgesprochen. Captures (Teilzahlungen) werden innerhalb des Garantiezeitraums immer ausgeführt. Weitere Informationen zu Order und Capture finden Sie im Kapitel Capture.

express

Boolean

Immer vorhanden bei Express-Checkouts.

Flag, gibt an, dass es sich um einen Express-Checkout handelt. Muss true sein.

status

String

Immer vorhanden.

Status des Checkouts: OPEN, PENDING, APPROVED, REJECTED, CANCELED, CLOSED oder EXPIRED.
OPEN: Der Checkout wurde neu angelegt und vom Benutzer noch nicht bestätigt.
PENDING: Der Checkout wurde vom Kunden bestätigt, aber noch nicht per execute aktiviert (derzeit nur paydirekt Express)
APPROVED: Der Checkout wurde vom Kunden bestätigt und vom System genehmigt. Im Falle einer ORDER können jetzt Captures angelegt werden.
REJECTED: Der Checkout wurde vom System abgelehnt. Die Zahlung war nicht erfolgreich. Es ist nicht zu erwarten, dass die Zahlung bei erneutem Versuch mit diesem Benutzer erfolgreich sein wird.
CANCELED: Der Checkout wurde vom Kunden abgebrochen oder es kam zu einem technischen Fehler. Der Checkout kann nicht weiter bearbeitet werden.
CLOSED: Nur ORDER: Die Bestellung ist geschlossen, es können keine weiteren Captures durchgeführt werden. Refunds sind weiter möglich.
EXPIRED: Der Checkout ist abgelaufen und kann nicht weiter verwendet werden. Der Benutzer hat den Checkout nicht innerhalb von 30 Minuten bestätigt.

creationTimestamp

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.

expiryTimestamp

String

Immer vorhanden.

Der Ablaufzeitpunkt dieses Checkouts. Kann über das Feld expiryTime bei Anlage angepasst werden, ansonsten wird vom paydirekt-System als Standardwert 30 Minuten ab Erzeugung vergeben. Formatierung entsprechend ISO-8601 durch den Standard Java DateTimeFormatter. Abweichend davon werden immer drei Nachkommastellen für die Millisekunden ausgegeben.

totalAmount

Number

Immer vorhanden.

Der Gesamtbetrag der Bestellung, inkl. aller Lieferkosten. Es werden maximal 2 Nachkommastellen unterstützt.
Im Falle eines DIRECT_SALE wird eine Zahlung für diesen Betrag initiiert.
Im Falle einer ORDER können Captures bis maximal zu diesem Betrag angestoßen werden.

shippingAmount

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 callbackUrlCheckDestinations übergeben wurde, sind die Versandkosten final.

orderAmount

Number

Immer vorhanden.

Der Warenwert der Bestellung, ohne Versandkosten. Dieser Wert wird nicht für Berechnungen verwendet, sondern dient nur zur Information.

refundLimit

Number

Vorhanden, falls bei Anlage übergeben.

Maximal zurückzahlbarer Betrag als Prozentwert des Gesamtwertes der Bestellung.

currency

String

Immer vorhanden.

Die Währung des Gesamtbetrags. Derzeit wird nur EUR unterstützt.

items

Array von Items

Vorhanden, falls bei Anlage übergeben.

Die einzelnen Positionen des Warenkorbs.
Es wird empfohlen, diese Werte zu übergeben. Dies verbessert die Erkennung von fraudulenten Vorgängen und hilft, Disputes zu vermeiden.

overcapture

Boolean

Vorhanden, falls bei Anlage übergeben.

Flag für Overcapture-Checkouts.
Bei einem Overcapture-Checkout darf die Summe der Captures den Warenwert der Bestellung um bis zu 10% übersteigen.
Bei aktiviertem Flag muss das finalCapture-Feld des letzten Captures auf true gesetzt sein.
overcapture darf nur aktiviert sein, wenn es sich um einen Checkout des Typs ORDER handelt.
Kann nur von Händlern verwendet werden, die für dieses Feature freigeschaltet wurden.

maxCapturableAmount

Number

Vorhanden, falls Overcapture-Flag gesetzt.

Bei gesetztem Overcapture-Flag enthält dieses Feld den maximalen Betrag, der insgesamt abgerufen werden kann.

maxOvercaptureDifference

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.

shoppingCartType

String

Vorhanden, falls bei Anlage übergeben.

Kategorisiert den Warenkorb eines Checkouts anhand der Eigenschaften der enthaltenen Güter: Der Standardwert ist MIXED.
PHYSICAL: Der Warenkorb enthält ausschließlich physische Güter.
DIGITAL: Der Warenkorb enthält ausschließlich digitale Güter.
MIXED: Der Warenkorb enthält sowohl phyische als auch digitale Güter.
ANONYMOUS_DONATION: Beim Warenkorb handelt es sich ausschließlich um eine anonyme Spende.
AUTHORITIES_PAYMENT: Beim Warenkorb handelt es sich ausschließlich um Behördenzahlungen.

deliveryType

String

Vorhanden, falls bei Anlage übergeben.

Der Bestimmungsort einer Lieferung: STANDARD, PACKSTATION oder STORE_PICKUP. Der Standardwert ist STANDARD.
STANDARD: Die Güter werden an eine gewöhnliche Postadresse geliefert.
PACKSTATION: Die Güter werden an eine Packstation geliefert.
STORE_PICKUP: Die Güter werden in der Filiale abgeholt.
Dieses Feld enthält bei Express-Checkouts immer den Wert STANDARD und wird nicht anhand der gewählten Lieferoption aktualisiert.

merchantCustomerNumber

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.

merchantOrderReferenceNumber

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 instructionId und im Verwendungszweck bei Händler und Käufer verwendet.

merchantInvoiceReferenceNumber

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.

merchantReconciliationReferenceNumber

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 merchantReconciliationReferenceNumber verwendet.

redirectUrlAfterSuccess

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.

redirectUrlAfterCancellation

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.

redirectUrlAfterRejection

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.

callbackUrlStatusUpdates

String

Vorhanden, falls bei Anlage übergeben.

URL des Endpoints, der Mitteilungen zu Statusänderungen des Checkouts empfangen soll.

callbackUrlCheckDestinations

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.

webUrlShippingTerms

String

Immer vorhanden bei Express-Checkouts.

Link zu einer Webseite mit den Versandbedingungen des Händlers.

minimumAge

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 redirectUrlAfterAgeVerificationFailure (siehe unten). Bei Nicht-Angabe dieses Wertes erfolgt keine Altersverifkation.

redirectUrlAfterAgeVerificationFailure

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 minimumAge, zum Pflichtfeld. Ist keine Altersverifikation erforderlich, ist dieses Feld wegzulassen.

note

String

Vorhanden, falls bei Anlage übergeben.

Freitextfeld, das auf dem Kontoauszug im Feld Verwendungzweck erscheint (nur DIRECT_SALE).

_links

Object

Links zu Ressourcen und verfügbaren Aktionen des Checkouts.

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/e2528839-ee25-4f9c-bbf7-c06c3c4ea7e3
Content-Type: application/hal+json;charset=UTF-8
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
Content-Length: 2139

{
  "checkoutId" : "e2528839-ee25-4f9c-bbf7-c06c3c4ea7e3",
  "type" : "DIRECT_SALE",
  "express" : true,
  "status" : "OPEN",
  "creationTimestamp" : "2018-10-23T09:36:43.984Z",
  "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" : "2018-10-23T10:06:43.984Z",
  "_links" : {
    "approve" : {
      "href" : "https://paydirekt.de/checkout/?p=e2528839-ee25-4f9c-bbf7-c06c3c4ea7e3#/checkout/e2528839-ee25-4f9c-bbf7-c06c3c4ea7e3"
    },
    "updateDeliveryInformation" : {
      "href" : "https://api.paydirekt.de/api/checkout/v1/checkouts/e2528839-ee25-4f9c-bbf7-c06c3c4ea7e3/deliveryInformation"
    },
    "updateMerchantInvoiceReferenceNumber" : {
      "href" : "https://api.paydirekt.de/api/checkout/v1/checkouts/e2528839-ee25-4f9c-bbf7-c06c3c4ea7e3/merchantInvoiceReferenceNumber"
    },
    "self" : {
      "href" : "https://api.paydirekt.de/api/checkout/v1/checkouts/e2528839-ee25-4f9c-bbf7-c06c3c4ea7e3"
    }
  }
}

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

checkoutId

String

Immer vorhanden.

Eindeutige UUID aus 36 Zeichen für diesen Checkout-Vorgang. Wird vom paydirekt-System vergeben.

type

String

Immer vorhanden.

Die Art der Bestellung: DIRECT_SALE, ORDER oder ORDER_SECURED.
Im Falle eines DIRECT_SALE (Direktbestellung mit Einmalzahlung) wird automatisch eine Zahlungsautorisierung erzeugt. Der Händler erhält sofort eine Zahlungsgarantie.
Zu einer ORDER (Vorbestellung oder Bestellung mit Teilzahlungen) können direkt im Anschluss oder später ein oder mehrere Captures angestoßen werden. Für eine Order wird keine Zahlungsgarantie an den Händler ausgesprochen. Die Garantie wird erst mit dem Capture gegeben.
Zu einer ORDER_SECURED (gesicherte Vorbestellung oder Bestellung mit Teilzahlungen) können direkt im Anschluss oder später ein oder mehrere Captures angestoßen werden. Für eine gesicherte Vorbestellung wird eine Zahlungsgarantie für den gewählten Zeitraum (maximal 15 Kalendertage) an den Händler ausgesprochen. Captures (Teilzahlungen) werden innerhalb des Garantiezeitraums immer ausgeführt. Weitere Informationen zu Order und Capture finden Sie im Kapitel Capture.

express

Boolean

Immer vorhanden bei Express-Checkouts.

Flag, gibt an, dass es sich um einen Express-Checkout handelt. Muss true sein.

status

String

Immer vorhanden.

Status des Checkouts: OPEN, PENDING, APPROVED, REJECTED, CANCELED, CLOSED oder EXPIRED.
OPEN: Der Checkout wurde neu angelegt und vom Benutzer noch nicht bestätigt.
PENDING: Der Checkout wurde vom Kunden bestätigt, aber noch nicht per execute aktiviert (derzeit nur paydirekt Express)
APPROVED: Der Checkout wurde vom Kunden bestätigt und vom System genehmigt. Im Falle einer ORDER können jetzt Captures angelegt werden.
REJECTED: Der Checkout wurde vom System abgelehnt. Die Zahlung war nicht erfolgreich. Es ist nicht zu erwarten, dass die Zahlung bei erneutem Versuch mit diesem Benutzer erfolgreich sein wird.
CANCELED: Der Checkout wurde vom Kunden abgebrochen oder es kam zu einem technischen Fehler. Der Checkout kann nicht weiter bearbeitet werden.
CLOSED: Nur ORDER: Die Bestellung ist geschlossen, es können keine weiteren Captures durchgeführt werden. Refunds sind weiter möglich.
EXPIRED: Der Checkout ist abgelaufen und kann nicht weiter verwendet werden. Der Benutzer hat den Checkout nicht innerhalb von 30 Minuten bestätigt.

creationTimestamp

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.

expiryTimestamp

String

Immer vorhanden.

Der Ablaufzeitpunkt dieses Checkouts. Kann über das Feld expiryTime bei Anlage angepasst werden, ansonsten wird vom paydirekt-System als Standardwert 30 Minuten ab Erzeugung vergeben. Formatierung entsprechend ISO-8601 durch den Standard Java DateTimeFormatter. Abweichend davon werden immer drei Nachkommastellen für die Millisekunden ausgegeben.

totalAmount

Number

Immer vorhanden.

Der Gesamtbetrag der Bestellung, inkl. aller Lieferkosten. Es werden maximal 2 Nachkommastellen unterstützt.
Im Falle eines DIRECT_SALE wird eine Zahlung für diesen Betrag initiiert.
Im Falle einer ORDER können Captures bis maximal zu diesem Betrag angestoßen werden.

shippingAmount

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 callbackUrlCheckDestinations übergeben wurde, sind die Versandkosten final.

items

Array von Items

Vorhanden, falls bei Anlage übergeben.

Die einzelnen Positionen des Warenkorbs.
Es wird empfohlen, diese Werte zu übergeben. Dies verbessert die Erkennung von fraudulenten Vorgängen und hilft, Disputes zu vermeiden.

shoppingCartType

String

Vorhanden, falls bei Anlage übergeben.

Kategorisiert den Warenkorb eines Checkouts anhand der Eigenschaften der enthaltenen Güter: Der Standardwert ist MIXED.
PHYSICAL: Der Warenkorb enthält ausschließlich physische Güter.
DIGITAL: Der Warenkorb enthält ausschließlich digitale Güter.
MIXED: Der Warenkorb enthält sowohl phyische als auch digitale Güter.
ANONYMOUS_DONATION: Beim Warenkorb handelt es sich ausschließlich um eine anonyme Spende.
AUTHORITIES_PAYMENT: Beim Warenkorb handelt es sich ausschließlich um Behördenzahlungen.

deliveryType

String

Vorhanden, falls bei Anlage übergeben.

Der Bestimmungsort einer Lieferung: STANDARD, PACKSTATION oder STORE_PICKUP. Der Standardwert ist STANDARD.
STANDARD: Die Güter werden an eine gewöhnliche Postadresse geliefert.
PACKSTATION: Die Güter werden an eine Packstation geliefert.
STORE_PICKUP: Die Güter werden in der Filiale abgeholt.
Dieses Feld enthält bei Express-Checkouts immer den Wert STANDARD und wird nicht anhand der gewählten Lieferoption aktualisiert.

orderAmount

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.

refundLimit

Number

Vorhanden, falls bei Anlage übergeben.

Maximal zurückzahlbarer Betrag als Prozentwert des Gesamtwertes der Bestellung.

currency

String

Immer vorhanden.

Die Währung des Gesamtbetrags. Derzeit wird nur EUR unterstützt.

overcapture

Boolean

Vorhanden, falls bei Anlage übergeben.

Flag für Overcapture-Checkouts.
Bei einem Overcapture-Checkout darf die Summe der Captures den Warenwert der Bestellung um bis zu 10% übersteigen.
Bei aktiviertem Flag muss das finalCapture-Feld des letzten Captures auf true gesetzt sein.
overcapture darf nur aktiviert sein, wenn es sich um einen Checkout des Typs ORDER handelt.
Kann nur von Händlern verwendet werden, die für dieses Feature freigeschaltet wurden.

maxCapturableAmount

Number

Vorhanden, falls Overcapture-Flag gesetzt.

Bei gesetztem Overcapture-Flag enthält dieses Feld den maximalen Betrag, der insgesamt abgerufen werden kann.

maxOvercaptureDifference

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.

correlationId

String

Vorhanden, sobald sich ein Kunde eingeloggt hat. UUID aus 36 Zeichen.

Die eindeutige Identifikation des Checkouts und aller dazugehöriger Transaktionen.

note

String

Vorhanden, falls bei Anlage übergeben.

Freitextfeld, das auf dem Kontoauszug im Feld Verwendungzweck erscheint (nur DIRECT_SALE).

shippingAddress

ShippingAddress

Vorhanden bei Express-Checkouts nach dem Wechsel in den Status PENDING.

Die vom Kunden angegebene, vollständige Lieferadresse.

shippingOption

Object

Vorhanden bei Express-Checkouts nach dem Wechsel in den Status PENDING, falls eine callbackUrlCheckDestinations bei der Checkout-Anlage übergeben wurde.

Die vom Kunden ausgewählte Versandoption.

billingAddress

ShippingAddress

Vorhanden bei Express-Checkouts nach dem Wechsel in den Status PENDING.

Die vom Kunden angegebene, vollständige Rechnungsadresse.

buyerEmailAddress

String

Vorhanden bei Express-Checkouts nach dem Wechsel in den Status PENDING.

Die E-Mail Adresse des Kunden.

merchantCustomerNumber

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.

merchantOrderReferenceNumber

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 instructionId und im Verwendungszweck bei Händler und Käufer verwendet.

merchantInvoiceReferenceNumber

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.

merchantReconciliationReferenceNumber

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 merchantReconciliationReferenceNumber verwendet.

minimumAge

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 redirectUrlAfterAgeVerificationFailure (siehe unten). Bei Nicht-Angabe dieses Wertes erfolgt keine Altersverifkation.

redirectUrlAfterSuccess

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.

redirectUrlAfterCancellation

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.

redirectUrlAfterRejection

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.

redirectUrlAfterAgeVerificationFailure

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 minimumAge, zum Pflichtfeld. Ist keine Altersverifikation erforderlich, ist dieses Feld wegzulassen.

callbackUrlStatusUpdates

String

Vorhanden, falls bei Anlage übergeben.

URL des Endpoints, der Mitteilungen zu Statusänderungen des Checkouts empfangen soll.

callbackUrlCheckDestinations

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.

webUrlShippingTerms

String

Immer vorhanden bei Express-Checkouts.

Link zu einer Webseite mit den Versandbedingungen des Händlers.

_links

Object

Links zu Ressourcen und verfügbaren Aktionen des Checkouts.

Beispiel

GET /api/checkout/v1/checkouts/e2528839-ee25-4f9c-bbf7-c06c3c4ea7e3 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
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
Content-Length: 2801

{
  "checkoutId" : "e2528839-ee25-4f9c-bbf7-c06c3c4ea7e3",
  "type" : "DIRECT_SALE",
  "express" : true,
  "status" : "PENDING",
  "correlationId" : "ext0815-00000001",
  "creationTimestamp" : "2018-10-23T09:36:43.984Z",
  "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" : "2018-10-23T10:06:43.984Z",
  "_links" : {
    "execute" : {
      "href" : "https://api.paydirekt.de/api/checkout/v1/checkouts/e2528839-ee25-4f9c-bbf7-c06c3c4ea7e3/execute"
    },
    "updateDeliveryInformation" : {
      "href" : "https://api.paydirekt.de/api/checkout/v1/checkouts/e2528839-ee25-4f9c-bbf7-c06c3c4ea7e3/deliveryInformation"
    },
    "updateMerchantInvoiceReferenceNumber" : {
      "href" : "https://api.paydirekt.de/api/checkout/v1/checkouts/e2528839-ee25-4f9c-bbf7-c06c3c4ea7e3/merchantInvoiceReferenceNumber"
    },
    "self" : {
      "href" : "https://api.paydirekt.de/api/checkout/v1/checkouts/e2528839-ee25-4f9c-bbf7-c06c3c4ea7e3"
    }
  }
}

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

termsAcceptedTimestamp

String

Pflichtfeld.
Zeitstempel im ISO-8601-Format.

Zeitpunkt, an dem der Kunde die Geschäfts- und Lieferbedingungen im Webshop akzeptiert hat.

merchantOrderReferenceNumber

String

Pflichtfeld.
Maximal 20 Zeichen. Nur SEPA-konforme Zeichen.

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 instructionId und im Verwendungszweck bei Händler und Ku00E4ufer verwendet.
Überschreibt die bei Anlage des Checkouts optional übergebene merchantOrderReferenceNumber.

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)

ACCESS_TOKEN_EXPIRED

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/9cf70221-5a24-4262-88d8-e72f717ba09d/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
Strict-Transport-Security: max-age=31536000 ; includeSubDomains

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

checkoutId

String

Immer vorhanden.

Eindeutige UUID aus 36 Zeichen für diesen Checkout-Vorgang. Wird vom paydirekt-System vergeben.

merchantOrderReferenceNumber

String

Immer vorhanden.
Maximal 20 Zeichen.

Händler-interne, eindeutige Bestellnummer für diesen Kaufvorgang.

orderAmount

Number

Optional.
Zwischen 0.01 und 50000.
Maximal zwei Nachkommastellen.

Der Warenwert der Bestellung, ohne Versandkosten. Dieser Wert wird nicht für Berechnungen verwendet, sondern dient nur zur Information.

destinations

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.
Für jede Adresse muss entschieden werden, ob sie als Rechnungsadresse bzw. als Lieferadresse verwendet werden kann und welche Lieferoptionen und Kosten möglich sind.

destinations[].id

String

Immer vorhanden.
36 Zeichen.

Eindeutige ID der Destination.

destinations[].countryCode

String

Immer vorhanden.
2 Zeichen.

Der Ländercode im ISO 3166-1 Format.

destinations[].zip

String

Optional.
Zwischen 4 und 10 Zeichen.

Postleitzahl.

destinations[].dhlPackstation

Boolean

Optional.

Flag, ob es sich um eine Packstation handelt.

Response

Feld Typ Eigenschaften Beschreibung

checkedDestinations

Array

Pflichtfeld.

Ein Array von geprüften Rechnungs- und Lieferadressen des Kunden mit Angabe möglicher Lieferoptionen.

checkedDestinations[].id

String

Pflichtfeld.
36 Zeichen.

Eindeutige ID der Destination.

checkedDestinations[].countryCode

String

Pflichtfeld.
2 Zeichen.

Der Ländercode im ISO 3166-1 Format.

checkedDestinations[].zip

String

Optional.
Zwischen 4 und 10 Zeichen.

Postleitzahl.

checkedDestinations[].dhlPackstation

Boolean

Optional.

Flag, ob es sich um eine Packstation handelt.

checkedDestinations[].validBillingDestination

Boolean

Pflichtfeld.

Flag, ob die Destination als Rechnungsadresse verwendet werden kann.

checkedDestinations[].validShippingDestination

Boolean

Pflichtfeld.

Flag, ob die Destination als Lieferadresse verwendet werden kann.

checkedDestinations[].shippingOptions

Array

Pflichtfeld.

Ein Array von möglichen Versandoptionen für diese Destination. Wert ist eine Zahl zwischen 0 und 10 sein.

checkedDestinations[].shippingOptions[].code

String

Pflichtfeld.
Maximal 50 Zeichen.

Ein Händler-interner Code zur Identifizierung der Versandoption. Wird später im Checkout zurückgegeben.

checkedDestinations[].shippingOptions[].name

String

Pflichtfeld.
Maximal 50 Zeichen.

Die Bezeichnung der Versandoption (in Deutsch). Wird dem Kunden zur Auswahl angezeigt.

checkedDestinations[].shippingOptions[].description

String

Pflichtfeld.
Maximal 50 Zeichen.

Die Beschreibung der Versandoption (in Deutsch). Wird dem Kunden zur Auswahl angezeigt.

checkedDestinations[].shippingOptions[].amount

Number

Pflichtfeld.
Zwischen 0.00 und 999.

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" : "0b713e6c-5122-48ad-9eb1-c21e678e5c28",
  "merchantOrderReferenceNumber" : "order-A12223412",
  "orderAmount" : 96.5,
  "destinations" : [ {
    "id" : "96f9f094-083c-42db-8de2-c5ecab214497",
    "countryCode" : "DE",
    "zip" : "91781",
    "dhlPackstation" : false
  } ]
}
HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 414

{
  "checkedDestinations" : [ {
    "id" : "96f9f094-083c-42db-8de2-c5ecab214497",
    "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

Händler können Reports über die Transaktionen abrufen, die von den ihm zugeordneten Shops durchgeführt wurden.

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 10.000 Transaktionen umfassen. Wird einer der beiden Werte überschritten, wird ein Fehler ausgegeben. 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

from

Optional.

Zeitstempel im ISO-8601-Format, ab dem Transaktionen berücksichtigt werden. Falls nicht angegeben, werden die 30 Tage seit dem to-Zeitstempel abgefragt, d.h. der from-Zeitstempel implizit auf to-Zeitstempel minus 30 Tage gesetzt.

to

Optional.

Zeitstempel im ISO-8601-Format, bis zu dem Transaktionen berücksichtigt werden. Falls nicht angegeben, wird bis zum aktuellen Zeitpunkt abgefragt.

fields

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 fields die enthaltenen Spalten und deren Reihenfolge. Für den Transaktionsreport im JSON-Format bestimmt fields die enthaltenen Felder. Ist fields nicht angegeben, enthält der Transaktionsreport alle möglichen Felder, wie sie in Transaktionen aufgezählt sind.

reconciliationReferences

Optional.

Liste von MerchantReconciliationReferenceNumbers, nach denen Transaktionen gefiltert werden. Eine leere Liste wird ignoriert

paymentInformationIds

Optional.

Liste von PaymentInformationIds, nach denen Transaktionen gefiltert werden. Eine leere Liste wird ignoriert

merchantReferenceNumbers

Optional.

Liste von MerchantReferenceNumbers, nach denen Transaktionen gefiltert werden. Eine leere Liste wird ignoriert

checkoutInvoiceNumbers

Optional.

Liste von CheckoutInvoiceReferenceNumbers, nach denen Transaktionen gefiltert werden. Eine leere Liste wird ignoriert

captureInvoiceNumbers

Optional.

Liste von CaptureInvoiceReferenceNumbers, nach denen Transaktionen gefiltert werden. Eine leere Liste wird ignoriert

Response-Felder

Feld Typ Eigenschaften Beschreibung

transactions

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 ihrem transactionDate sortiert.

Feld Typ Eigenschaften Beschreibung

correlationId

String

UUID aus 36 Zeichen.

Die Vorgangsnummer des Checkouts, um eine eindeutige Zuordnung zu ermöglichen.

endToEndReferenceNumber

String

UUID aus 32 Zeichen plus Präfix PD.

End-zu-End-Referenznummer des Checkouts.

transactionTypeId

String

1 (Direct Sale),
2 (Refund),
3 (Vorbestellung),
4 (abgelehntes Capture),
5 (erfolgreiches Capture zu einer Order),
6 (stornierte Vorbestellung),
7 (erfolgreiches Overcapture)

Kennziffer des Transaktionstyps.

transactionDate

String

Zeitstempel nach ISO8601.

Zeitpunkt der Transaktion.

valueDate

String

Datum nach ISO8601.

Valuta-Datum der Transaktion.

contractId

String

UUID aus 36 Zeichen.

ID des Händler-Vertrages.

merchantId

String

UUID aus 36 Zeichen.

ID des Händlers.

merchantName

String

Maximal 100 Zeichen.

Name des Händlers.

merchantIban

String

Maximal 34 Stellen, i.d.R. 22.

IBAN des Händlerkontos.

merchantReference

String

Maximal 20 Zeichen. Nur SEPA-konforme Zeichen.

Händler-interne, eindeutige Bestellnummer für diesen Kaufvorgang. Entspricht der bei Anlage des Checkouts übergebenen merchantOrderReferenceNumber.

merchantTransactionReferenceNumber

String

Händler-interne Referenznummer für diesen Capture- oder Refundvorgang. Entspricht je nach Transaktionstyp der bei Anlage übergebenen merchantCaptureReferenceNumber oder der merchantRefundReferenceNumber.

merchantBankId

String

UUID aus 36 Zeichen.

ID der Bank des Händlers.

buyerBankId

String

UUID aus 36 Zeichen.

ID der Bank des Käufers.

buyerBankName

String

Maximal 100 Zeichen.

Kurzname der Bank des Käufers.

transactionAmount

Number

Zwischen 0.01 und 50000.00, zwei Nachkommastellen.

Der Transaktionsbetrag.

transactionCurrency

String

Derzeit immer EUR.

Währung der Transaktion.

bankIntermediaryId

String

UUID aus 36 Zeichen.

ID des Konzentrators der Käuferbank.

bankIntermediaryName

String

Maximal 100 Zeichen.

Name des Konzentrators der Käuferbank.

shopId

String

UUID aus 36 Zeichen.

ID des Shops.

shopName

String

Maximal 100 Zeichen.

Name des Shops.

ageVerificationStatus

String

0 (nicht geprüft),
1 (bestanden),
2 (nicht bestanden)

Ergebnis der Altersprüfung.

MCC

String

Vierstellige Zahl.

MCC (Merchant Category Code) des Händlers.

DBI

String

Vierstellige Zahl.

DBI (Details Business Indicator) des Händlers.

paydirektExpress

String

y (Express),
n (kein Express)

Gibt an, ob es sich um einen Express-Checkout handelt.

checkoutId

String

UUID aus 36 Zeichen.

ID des Checkouts.

checkoutInvoiceNr

String

Maximal 20 Zeichen.

Die bei Anlage des Checkouts vom Händler übergebene merchantInvoiceReferenceNumber.

captureInvoiceNr

String

Maximal 20 Zeichen.

Die bei Anlage des Captures vom Händler übergebene captureInvoiceReferenceNumber.

reconciliationReferenceNr

String

Maximal 30 Zeichen.

Die bei Anlage des Checkouts oder Captures vom Händler übergebene merchantReconciliationReferenceNumber.

paymentInformationId

String

UUID aus 36 Zeichen.

Eindeutige Payment-Information-ID der SEPA-Transaktion.

refundReason

String

MERCHANT_TECHNICAL_PROBLEM: Technisches Problem bei Abwicklung.
MERCHANT_CAN_NOT_DELIVER_GOODS: Händler kann Ware nicht liefern.
REFUND_OBLIGINGNESS: Rücküberweisung wegen Kulanz.
TECHNICAL_PROBLEM: Technisches Problem bei Abwicklung/Rückabwicklung.
MERCHANT_CAN_NOT_PROOF_SHIPMENT: Händler kann Versandbeleg nicht vorweisen (Dispute).
REFUND_ON_BEHALF_OF_MERCHANT: Rückabwicklung im Auftrag des Händlers.
REFUND_NOT_ON_BEHALF_OF_MERCHANT: Rückabwicklung ohne Auftrag des Händlers.
REFUND_MERCHANT_FRAUD: Rückabwicklung wegen Händlerfraud.

Der bei der Refundanlage angegebene reason.

Return Codes

Status Code Message Code Beschreibung

200 (Ok)

Die Anfrage wurde korrekt verarbeitet.

401 (Unauthorized)

ACCESS_TOKEN_EXPIRED

Siehe Resource Access.

404 (Not Found)

Sie haben keinen Zugriff auf diese Ressource. Möglicherweise fehlt die Authentifizierung.

422 (Unprocessable Entity)

INVALID_FIELD_NAME

Mindestens einer der über fields angegebenen Feldnamen konnte nicht einem Transaktionsfeld zugeordnet werden.

422 (Unprocessable Entity)

REPORT_RANGE_TOO_LARGE

Der angefragte Report war zu groß. Entweder überschritt er die 180-Tage-Grenze oder enthielt mehr als 10.000 Elemente.

Beispiel

GET /api/reporting/v1/reports/transactions?from=2018-10-04T13:29:38.342Z&to=2018-10-09T13:29:38.342Z&fields=&reconciliationReferences=&paymentInformationIds=&merchantReferenceNumbers=&checkoutInvoiceNumbers=&captureInvoiceNumbers=&fields=&reconciliationReferences=&paymentInformationIds=&merchantReferenceNumbers=&checkoutInvoiceNumbers=&captureInvoiceNumbers= HTTP/1.1
Accept: application/json
Authorization: Bearer <access_token>
HTTP/1.1 200 OK
Content-Type: application/json

{
  "transactions" : [ {
    "correlationId" : "afae5607-aafc-4ee1-865d-f5600084e483",
    "endToEndReferenceNumber" : "9da5f583-b73e-41f7-a5f8-00c942afed7d",
    "transactionTypeId" : "1",
    "transactionDate" : "2018-10-09T13:29:38.337Z",
    "valueDate" : "2018-10-09",
    "contractId" : "6c4c6f1a-bc62-4e3c-8694-207e8658085c",
    "merchantId" : "6c1cfb81-f13e-4871-8631-fead4f992e6e",
    "merchantName" : "Some merchant name",
    "merchantIban" : "DE12500105170648489890",
    "merchantReference" : "c2e17963-854f-4a64-8c74-67a69b23e246",
    "merchantTransactionReferenceNumber" : "72ebc3fc-6cf2-4e13-8f19-d4529b05cdf0",
    "checkoutId" : "481e6571-0ed6-41f8-b854-28f7119cf735",
    "merchantBankId" : "5f168889-f623-455a-9dce-03749162e914",
    "buyerBankId" : "896682e0-ef76-4169-809d-b2e2294eda17",
    "buyerBankName" : "Buyer Bank Name",
    "transactionAmount" : "1.00",
    "transactionCurrency" : "EUR",
    "bankIntermediaryId" : "d46b4a6c-2351-4d13-b603-c2d38820251d",
    "bankIntermediaryName" : "Buyer Bank Concentrator",
    "shopId" : "9133b00e-b1dd-4ee5-987a-84c4cc9a53f3",
    "shopName" : "Some shop name",
    "ageVerificationStatus" : "1",
    "paydirektExpress" : "n",
    "checkoutInvoiceNr" : "b88f10b1-c038-4b56-8ab9-188a1e9d7830",
    "captureInvoiceNr" : "3234995a-43c5-4113-ae6f-6f72baa0f0f9",
    "reconciliationReferenceNr" : "6134f210-b949-4f40-824a-20b9cff51b3b",
    "paymentInformationId" : "1db91ad8-93a6-4eb2-8c68-93c9753e2d56",
    "refundReason" : "TECHNICAL_PROBLEM",
    "validityDate" : "2018-10-14",
    "MCC" : "742",
    "DBI" : "743"
  }, {
    "correlationId" : "afae5607-aafc-4ee1-865d-f5600084e483",
    "endToEndReferenceNumber" : "9da5f583-b73e-41f7-a5f8-00c942afed7d",
    "transactionTypeId" : "1",
    "transactionDate" : "2018-10-09T13:29:38.337Z",
    "valueDate" : "2018-10-09",
    "contractId" : "6c4c6f1a-bc62-4e3c-8694-207e8658085c",
    "merchantId" : "6c1cfb81-f13e-4871-8631-fead4f992e6e",
    "merchantName" : "Some merchant name",
    "merchantIban" : "DE12500105170648489890",
    "merchantReference" : "c2e17963-854f-4a64-8c74-67a69b23e246",
    "merchantTransactionReferenceNumber" : "72ebc3fc-6cf2-4e13-8f19-d4529b05cdf0",
    "checkoutId" : "481e6571-0ed6-41f8-b854-28f7119cf735",
    "merchantBankId" : "5f168889-f623-455a-9dce-03749162e914",
    "buyerBankId" : "896682e0-ef76-4169-809d-b2e2294eda17",
    "buyerBankName" : "Buyer Bank Name",
    "transactionAmount" : "1.00",
    "transactionCurrency" : "EUR",
    "bankIntermediaryId" : "d46b4a6c-2351-4d13-b603-c2d38820251d",
    "bankIntermediaryName" : "Buyer Bank Concentrator",
    "shopId" : "9133b00e-b1dd-4ee5-987a-84c4cc9a53f3",
    "shopName" : "Some shop name",
    "ageVerificationStatus" : "1",
    "paydirektExpress" : "n",
    "checkoutInvoiceNr" : "b88f10b1-c038-4b56-8ab9-188a1e9d7830",
    "captureInvoiceNr" : "3234995a-43c5-4113-ae6f-6f72baa0f0f9",
    "reconciliationReferenceNr" : "6134f210-b949-4f40-824a-20b9cff51b3b",
    "paymentInformationId" : "1db91ad8-93a6-4eb2-8c68-93c9753e2d56",
    "refundReason" : "TECHNICAL_PROBLEM",
    "validityDate" : "2018-10-14",
    "MCC" : "742",
    "DBI" : "743"
  }, {
    "correlationId" : "afae5607-aafc-4ee1-865d-f5600084e483",
    "endToEndReferenceNumber" : "9da5f583-b73e-41f7-a5f8-00c942afed7d",
    "transactionTypeId" : "1",
    "transactionDate" : "2018-10-09T13:29:38.337Z",
    "valueDate" : "2018-10-09",
    "contractId" : "6c4c6f1a-bc62-4e3c-8694-207e8658085c",
    "merchantId" : "6c1cfb81-f13e-4871-8631-fead4f992e6e",
    "merchantName" : "Some merchant name",
    "merchantIban" : "DE12500105170648489890",
    "merchantReference" : "c2e17963-854f-4a64-8c74-67a69b23e246",
    "merchantTransactionReferenceNumber" : "72ebc3fc-6cf2-4e13-8f19-d4529b05cdf0",
    "checkoutId" : "481e6571-0ed6-41f8-b854-28f7119cf735",
    "merchantBankId" : "5f168889-f623-455a-9dce-03749162e914",
    "buyerBankId" : "896682e0-ef76-4169-809d-b2e2294eda17",
    "buyerBankName" : "Buyer Bank Name",
    "transactionAmount" : "1.00",
    "transactionCurrency" : "EUR",
    "bankIntermediaryId" : "d46b4a6c-2351-4d13-b603-c2d38820251d",
    "bankIntermediaryName" : "Buyer Bank Concentrator",
    "shopId" : "9133b00e-b1dd-4ee5-987a-84c4cc9a53f3",
    "shopName" : "Some shop name",
    "ageVerificationStatus" : "1",
    "paydirektExpress" : "n",
    "checkoutInvoiceNr" : "b88f10b1-c038-4b56-8ab9-188a1e9d7830",
    "captureInvoiceNr" : "3234995a-43c5-4113-ae6f-6f72baa0f0f9",
    "reconciliationReferenceNr" : "6134f210-b949-4f40-824a-20b9cff51b3b",
    "paymentInformationId" : "1db91ad8-93a6-4eb2-8c68-93c9753e2d56",
    "refundReason" : "TECHNICAL_PROBLEM",
    "validityDate" : "2018-10-14",
    "MCC" : "742",
    "DBI" : "743"
  }, {
    "correlationId" : "afae5607-aafc-4ee1-865d-f5600084e483",
    "endToEndReferenceNumber" : "9da5f583-b73e-41f7-a5f8-00c942afed7d",
    "transactionTypeId" : "1",
    "transactionDate" : "2018-10-09T13:29:38.337Z",
    "valueDate" : "2018-10-09",
    "contractId" : "6c4c6f1a-bc62-4e3c-8694-207e8658085c",
    "merchantId" : "6c1cfb81-f13e-4871-8631-fead4f992e6e",
    "merchantName" : "Some merchant name",
    "merchantIban" : "DE12500105170648489890",
    "merchantReference" : "c2e17963-854f-4a64-8c74-67a69b23e246",
    "merchantTransactionReferenceNumber" : "72ebc3fc-6cf2-4e13-8f19-d4529b05cdf0",
    "checkoutId" : "481e6571-0ed6-41f8-b854-28f7119cf735",
    "merchantBankId" : "5f168889-f623-455a-9dce-03749162e914",
    "buyerBankId" : "896682e0-ef76-4169-809d-b2e2294eda17",
    "buyerBankName" : "Buyer Bank Name",
    "transactionAmount" : "1.00",
    "transactionCurrency" : "EUR",
    "bankIntermediaryId" : "d46b4a6c-2351-4d13-b603-c2d38820251d",
    "bankIntermediaryName" : "Buyer Bank Concentrator",
    "shopId" : "9133b00e-b1dd-4ee5-987a-84c4cc9a53f3",
    "shopName" : "Some shop name",
    "ageVerificationStatus" : "1",
    "paydirektExpress" : "n",
    "checkoutInvoiceNr" : "b88f10b1-c038-4b56-8ab9-188a1e9d7830",
    "captureInvoiceNr" : "3234995a-43c5-4113-ae6f-6f72baa0f0f9",
    "reconciliationReferenceNr" : "6134f210-b949-4f40-824a-20b9cff51b3b",
    "paymentInformationId" : "1db91ad8-93a6-4eb2-8c68-93c9753e2d56",
    "refundReason" : "TECHNICAL_PROBLEM",
    "validityDate" : "2018-10-14",
    "MCC" : "742",
    "DBI" : "743"
  }, {
    "correlationId" : "afae5607-aafc-4ee1-865d-f5600084e483",
    "endToEndReferenceNumber" : "9da5f583-b73e-41f7-a5f8-00c942afed7d",
    "transactionTypeId" : "1",
    "transactionDate" : "2018-10-09T13:29:38.337Z",
    "valueDate" : "2018-10-09",
    "contractId" : "6c4c6f1a-bc62-4e3c-8694-207e8658085c",
    "merchantId" : "6c1cfb81-f13e-4871-8631-fead4f992e6e",
    "merchantName" : "Some merchant name",
    "merchantIban" : "DE12500105170648489890",
    "merchantReference" : "c2e17963-854f-4a64-8c74-67a69b23e246",
    "merchantTransactionReferenceNumber" : "72ebc3fc-6cf2-4e13-8f19-d4529b05cdf0",
    "checkoutId" : "481e6571-0ed6-41f8-b854-28f7119cf735",
    "merchantBankId" : "5f168889-f623-455a-9dce-03749162e914",
    "buyerBankId" : "896682e0-ef76-4169-809d-b2e2294eda17",
    "buyerBankName" : "Buyer Bank Name",
    "transactionAmount" : "1.00",
    "transactionCurrency" : "EUR",
    "bankIntermediaryId" : "d46b4a6c-2351-4d13-b603-c2d38820251d",
    "bankIntermediaryName" : "Buyer Bank Concentrator",
    "shopId" : "9133b00e-b1dd-4ee5-987a-84c4cc9a53f3",
    "shopName" : "Some shop name",
    "ageVerificationStatus" : "1",
    "paydirektExpress" : "n",
    "checkoutInvoiceNr" : "b88f10b1-c038-4b56-8ab9-188a1e9d7830",
    "captureInvoiceNr" : "3234995a-43c5-4113-ae6f-6f72baa0f0f9",
    "reconciliationReferenceNr" : "6134f210-b949-4f40-824a-20b9cff51b3b",
    "paymentInformationId" : "1db91ad8-93a6-4eb2-8c68-93c9753e2d56",
    "refundReason" : "TECHNICAL_PROBLEM",
    "validityDate" : "2018-10-14",
    "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

addresseeGivenName

String

Optional bei als AUTHORITIES_PAYMENT oder ANONYMOUS_DONATION kategorisierten Warenkörben, sonst Pflichtfeld.
Maximal 100 Zeichen.

Vorname.

addresseeLastName

String

Optional bei als AUTHORITIES_PAYMENT oder ANONYMOUS_DONATION kategorisierten Warenkörben, sonst Pflichtfeld.
Maximal 100 Zeichen.

Nachname.

company

String

Optional.
Maximal 100 Zeichen.

Firmenname.

additionalAddressInformation

String

Optional.
Maximal 100 Zeichen.

Adresszusatz.

street

String

Optional.
Maximal 100 Zeichen.

Der Name der Straße, ohne Hausnummer.

streetNr

String

Optional.
Maximal 10 Zeichen.

Die Hausnummer.

zip

String

Optional bei als DIGITAL, AUTHORITIES_PAYMENT oder ANONYMOUS_DONATION kategorisierten Warenkörben, sonst Pflichtfeld.
Maximal 10 Zeichen.

Die Postleitzahl.

city

String

Optional bei als DIGITAL, AUTHORITIES_PAYMENT oder ANONYMOUS_DONATION kategorisierten Warenkörben, sonst Pflichtfeld.
Maximal 100 Zeichen.

Die Stadt.

countryCode

String

Optional bei als DIGITAL, AUTHORITIES_PAYMENT oder ANONYMOUS_DONATION kategorisierten Warenkörben, sonst Pflichtfeld.
2 Zeichen.

Der Ländercode im ISO 3166-1 Format.

state

String

Optional
100 Zeichen.

Bundesland oder Bundesstaat. Kann zum Beispiel bei Auslandsadressen verwendet werden.

emailAddress

String

Pflichtfeld bei als DIGITAL kategorisierten Warenkörben, sonst optional.
Muss eine gültige Email-Adresse sein.

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

quantity

Number

Pflichtfeld.
Ganzzahlig.
Mindestens 1.

Die Anzahl der Positionen für diesen Artikel.

name

String

Pflichtfeld.
Maximal 100 Zeichen.

Die Bezeichnung des Artikel.

ean

String

Optional.
Maximal 100 Zeichen.

Die International Article Number (EAN bzw. GTIN) des Artikels.

price

Number

Pflichtfeld.
Positiv oder Negativ.
Maximal 2 Nachkommastellen.

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

code

String

Pflichtfeld.
Maximal 100 Zeichen.

Der eindeutige Fehlercode zu diesem Fehler.

severity

String

Pflichtfeld.

Die Fehlerstufe. Die möglichen Werte sind: ERROR, WARN und INFO.

path

String

Optional.
Maximal 1000 Zeichen.

Das Feld zu dem dieser Fehler erzeugt wurde. Dieses Feld wird bei einem VALIDATION_ERROR (Response Code 400) befüllt.

reasonCode

String

Optional.
Maximal 1000 Zeichen.

Der Grund für diesen Fehler als eindeutiger Code, sofern dies aus dem Feld code nicht eindeutig hervorgeht. Der reasonCode dient vor allem zu Debugging-Zwecken, es sollte hierauf keine Logik implementiert werden.

logref

String

Optional.
Maximal 1000 Zeichen.

Eine paydirekt-interne Referenznummer zu dieser Fehlermeldung. Bitte geben Sie immer diese Referenznummer bei Support-Anfragen an.

content

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

size

Integer

Immer vorhanden.

Die maximale Anzahl der Elemente in dieser Page.

totalElements

Integer

Immer vorhanden.

Die Gesamtanzahl der Elemente über alle Pages.

totalPages

Integer

Immer vorhanden.

Die Gesamtanzahl der Pages.

number

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

12.11.2018

NEW INFO

Dokumentation der in String-Feldern akzeptierten Zeichen

Zeichensatz

28.08.2018

NEW FEATURE

Es kann nun optional die Gültigkeitsdauer von Checkouts konfiguriert werden.

Checkout - Anlage

31.07.2018

NEW FEATURE

Bei Express-Checkouts ist die Angabe eines Endpunkts zur Validierung von Lieferadressen nun optional.

Express

28.05.2018

NEW INFO

Dokumentation des Fehlercodes ORDER_NOT_APPROVED

Capture - Order schließen

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.

Checkout - Anlage

09.08.2017

NEW FEATURE

Beschreibung der gesicherten Vorbestellung

Checkout - Anlage

04.04.2017

NEW FEATURE

Übermittlung der E-Mail-Adresse des Käufers an den Händler/PSP bei Express

Express Checkout - Abfrage

22.02.2017

NEW FEATURE

Statusupdates werden bei Fehlschlägen erneut gesendet.

Checkout - Callback Capture - Callback Refund - Callback

08.02.2017

CHANGE

Der Checkoutstatus CANCELED ist jetzt final.

Checkout - Abfrage

11.01.2017

NEW FEATURE

Erweiterung der Rechnungs- und Lieferadresse um ein Feld für das Bundesland.

ShippingAddress

11.01.2017

NEW FEATURE

Der PSP-Transaktionsreport enthält jetzt die checkoutInvoiceNr und captureInvoiceNr.

Report

11.01.2017

NEW INFO

Angabe der statischen IP-Adressen, von denen Callback URLs aufgerufen werden

Endpoint

14.12.2016

NEW FEATURE

Neue Warenkorbtypen, bei denen die Übergabe der Lieferadresse optional ist.

Checkout - Anlage

30.11.2016

FIX

Die maximale Zeichenzahl für merchantRefundReferenceNumber und merchantCaptureReferenceNumber ist 30.

Capture - Anlage Refund - Anlage

30.11.2016

FIX

Die Transaktionstypen für Overcaptures und stornierte Vorbestellungen ist nun in der Beschreibung der Reports enthalten.

Report

30.11.2016

NEW FEATURE

Händler/PSP können Callbacks einrichten, um bei Statusänderungen von Refunds benachrichtigt zu werden.

Refund - Callback

16.11.2016

NEW FEATURE

In den Reports ist nun der Grund für Refunds enthalten.

Report

16.11.2016

NEW INFO

Weitere Angaben zum Format paydirekt-seitig generierter Felder

Report Checkout - Abfrage Capture - Abfrage

02.11.2016

NEW FEATURE

Händler können ihre API-Reporte nun durch zusätzliche Filter einschränken.

Report

02.11.2016

NEW FEATURE

Händler können nun in Checkouts und Captures Lieferinformationen mitgeben.

Checkout - Anlage Capture - Anlage

19.10.2016

FIX

Checkout-Status CANCELED ist nicht final. Abgebrochene Checkouts können noch abgeschlossen werden.

Checkout - Abfrage

19.10.2016

NEW FEATURE

Refunds können um eine reason ergänzt werden.

Refund - Abfrage Refund - Anlage

05.10.2016

NEW FEATURE

Verwendungszwecke können um eine merchantReconciliationReferenceNumber ergänzt werden.

Checkout - Anlage Capture - Anlage Refund - Anlage

05.10.2016

NEW FEATURE

Händler/PSP können Callbacks einrichten, um bei Statusänderungen von Checkouts und Captures benachrichtigt zu werden.

Checkout - Callback Capture - Callback

21.09.2016

NEW FEATURE

Angabe des Typs der Lieferadresse

Checkout - Anlage

21.09.2016

NEW FEATURE

Neue Felder checkoutId und buyerBankName in den Reports

Reports

10.08.2016

NEW INFO

Angabe der statischen IP-Adressen der Endpunkte

Endpoint

10.08.2016

FIX

"overcapture" und andere fehlende Felder sind nun in allen betroffenen Request- und Responsebeschreibungen enthalten.

Checkout - Anlage Checkout - Abfrage Express - Anlage

27.07.2016

NEW FEATURE

Bei digitalen Warenkörben sind einige Adressfelder optional, dafür neues Feld "emailAddress"

Allgemeine Datentypen - ShippingAddress

27.07.2016

NEW FEATURE

Anlage von Checkouts auch ohne orderAmount und shippingAmount

Checkout - Anlage

27.07.2016

NEW INFO

Beschreibung der möglichen Refundstatus

Refund - Abfrage

27.07.2016

NEW INFO

Angabe der Constraints für die Express-Callback Response

Express Callback - Response

13.07.2016

FIX

Fehlende Feldbeschreibungen des Overcapture-Flags

Checkout - Anlage

13.07.2016

NEW FEATURE

Warenkorbkennzeichnungen

Checkout - Anlage
Express - Anlage

13.07.2016

NEW FEATURE

Update paydirekt-Express Callback

Express - Callback

13.07.2016

FIX

Fehlende Feldbeschreibungen der Rechnungsnummern im PSP-Report

Reports

29.06.2016

FIX

paymentInformationId ist keine Liste

Capture - Abfrage
Refund - Abfrage

29.06.2016

NEW INFO

Hinweis auf die Beispielimplementierungen auf GitHub

Authentifizierung

29.06.2016

CHANGE

Zahlreiche Rechtschreibungs- und Formulierungsverbesserungen

29.06.2016

FIX

Fehlende Feldbeschreibungen zur Altersverifikation im Express-Checkout

Express - Anlage

29.06.2016

CHANGE

Beschreibung des API-Authentifizierungsprozesses

Authentifizierung

29.06.2016

NEW FEATURE

Auswahl der Felder für API-Reports

Reports

18.05.2016

NEW FEATURE

Refund-Abfrage liefert nun auch den aktuellen Status

Refund - Abfrage

18.05.2016

NEW FEATURE

Beschreibung der zum Overcapture gehörenden Felder

Checkout - Anlage

18.05.2016

NEW FEATURE

MerchantOrderReferenceNumber optional bei Express-Checkout-Anlage

Express - Anlage

04.05.2016

NEW FEATURE

Markierung der Sandbox API Keys

API-Key

04.05.2016

NEW FEATURE

Händler Reports über API

Reports

20.04.2016

NEW FEATURE

PSP Reports über API

Reports

20.04.2016

NEW INFO

Beschreibung des SEPA-konformen Zeichensatzes

SEPA-konforme Zeichen

20.04.2016

NEW INFO

Erklärung des Status PENDING

Capture - Anlage

20.04.2016

NEW INFO

Mehr Informationen zu TLS

Transport Layer Security