REST-API für PSP

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 (entspricht dem Standardwert, sofern nicht befüllt).

Gewünschter Garantiezeitraum (maximal 15 Kalendertage) für eine gesicherte Vorbestellung (ORDER_SECURED).

Response

In der Response wird der angelegte Checkout zurückgegeben. Die Struktur ist identisch mit dem Checkout Endpoint GET-Aufruf.

Im HTTP Header-Feld Location ist die URL der angelegten Checkout-Ressource, inkl. Checkout-ID enthalten. Die Checkout-ID wird im Response Body ebenfalls zurückgegeben.

Links

Relation Description

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. Der Aufbau bzw. die Parameter des Links können sich aufgrund von internen Weiterentwicklungen verändern. Verwenden Sie daher ausschließlich den von unserem System zur Laufzeit zurückgelieferten Link.
`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.

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. Der Aufbau bzw. die Parameter des Links können sich aufgrund von internen Weiterentwicklungen verändern. Verwenden Sie daher ausschließlich den von unserem System zur Laufzeit zurückgelieferten Link.

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

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.

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
  } ],
  "shoppingCartType" : "MIXED",
  "currency" : "EUR",
  "overcapture" : false,
  "shippingAddress" : {
    "addresseeGivenName" : "Marie",
    "addresseeLastName" : "Mustermann",
    "company" : "Musterbau GmbH & Co KG",
    "street" : "Kastanienallee",
    "streetNr" : "999",
    "additionalAddressInformation" : "Im Rückgebäude",
    "zip" : "90402",
    "city" : "Schwaig",
    "countryCode" : "DE",
    "state" : "Bayern"
  },
  "deliveryInformation" : {
    "expectedShippingDate" : "2016-10-19T12:00:00.000Z",
    "logisticsProvider" : "DHL",
    "trackingNumber" : "1234567890"
  },
  "merchantCustomerNumber" : "cust-732477",
  "merchantOrderReferenceNumber" : "order-A12223412",
  "merchantReconciliationReferenceNumber" : "recon-A12223412",
  "merchantInvoiceReferenceNumber" : "20150112334345",
  "note" : "Ihr Einkauf bei Spielauto-Versand.",
  "sha256hashedEmailAddress" : "fxP4R-IxH1Eaxpb0f_i5Shc8-FrYrtmx5lx35f9Xzgg",
  "minimumAge" : 18,
  "expiryTime" : 1800,
  "redirectUrlAfterSuccess" : "https://spielauto-versand.de/order/123/success",
  "redirectUrlAfterCancellation" : "https://spielauto-versand.de/order/123/cancellation",
  "redirectUrlAfterAgeVerificationFailure" : "https://spielauto-versand.de/order/123/ageverificationfailed",
  "redirectUrlAfterRejection" : "https://spielauto-versand.de/order/123/rejection",
  "callbackUrlStatusUpdates" : "https://spielauto-versand.de/callback/status"
}

HTTP/1.1 201 Created
Location: https://api.paydirekt.de/api/checkout/v1/checkouts/d091ffc7-3655-489f-aed2-9c4b3a4735cd
Content-Type: application/hal+json;charset=utf-8

{
  "checkoutId" : "d091ffc7-3655-489f-aed2-9c4b3a4735cd",
  "type" : "DIRECT_SALE",
  "status" : "OPEN",
  "creationTimestamp" : "2021-08-03T12:21:11.764Z",
  "totalAmount" : 100.0,
  "shippingAmount" : 3.5,
  "orderAmount" : 96.5,
  "refundLimit" : 200,
  "currency" : "EUR",
  "items" : [ {
    "quantity" : 3,
    "name" : "Bobbycar",
    "ean" : "800001303",
    "price" : 25.99
  }, {
    "quantity" : 1,
    "name" : "Helm",
    "price" : 18.53
  } ],
  "shoppingCartType" : "MIXED",
  "deliveryType" : "STANDARD",
  "shippingAddress" : {
    "addresseeGivenName" : "Marie",
    "addresseeLastName" : "Mustermann",
    "company" : "Musterbau GmbH & Co KG",
    "street" : "Kastanienallee",
    "streetNr" : "999",
    "additionalAddressInformation" : "Im Rückgebäude",
    "zip" : "90402",
    "city" : "Schwaig",
    "countryCode" : "DE",
    "state" : "Bayern"
  },
  "merchantOrderReferenceNumber" : "order-A12223412",
  "merchantCustomerNumber" : "cust-732477",
  "merchantInvoiceReferenceNumber" : "20150112334345",
  "merchantReconciliationReferenceNumber" : "recon-A12223412",
  "note" : "Ihr Einkauf bei Spielauto-Versand.",
  "minimumAge" : 18,
  "redirectUrlAfterSuccess" : "https://spielauto-versand.de/order/123/success",
  "redirectUrlAfterCancellation" : "https://spielauto-versand.de/order/123/cancellation",
  "redirectUrlAfterAgeVerificationFailure" : "https://spielauto-versand.de/order/123/ageverificationfailed",
  "redirectUrlAfterRejection" : "https://spielauto-versand.de/order/123/rejection",
  "callbackUrlStatusUpdates" : "https://spielauto-versand.de/callback/status",
  "deliveryInformation" : {
    "expectedShippingDate" : "2016-10-19T12:00:00.000Z",
    "logisticsProvider" : "DHL",
    "trackingNumber" : "1234567890"
  },
  "expiryTimestamp" : "2021-08-03T12:51:11.764Z",
  "_links" : {
    "approve" : {
      "href" : "https://localhost/checkout/?p=d091ffc7-3655-489f-aed2-9c4b3a4735cd#/checkout/d091ffc7-3655-489f-aed2-9c4b3a4735cd"
    },
    "updateDeliveryInformation" : {
      "href" : "https://api.paydirekt.de/api/checkout/v1/checkouts/d091ffc7-3655-489f-aed2-9c4b3a4735cd/deliveryInformation"
    },
    "updateMerchantInvoiceReferenceNumber" : {
      "href" : "https://api.paydirekt.de/api/checkout/v1/checkouts/d091ffc7-3655-489f-aed2-9c4b3a4735cd/merchantInvoiceReferenceNumber"
    },
    "self" : {
      "href" : "https://api.paydirekt.de/api/checkout/v1/checkouts/d091ffc7-3655-489f-aed2-9c4b3a4735cd"
    }
  }
}

Beispiel (Order)

POST /api/checkout/v1/checkouts HTTP/1.1
Content-Type: application/json;charset=utf-8
Authorization: Bearer <access_token>

{
  "type" : "ORDER",
  "totalAmount" : 100.0,
  "shippingAmount" : 3.5,
  "orderAmount" : 96.5,
  "refundLimit" : 200,
  "items" : [ {
    "quantity" : 3,
    "name" : "Bobbycar",
    "ean" : "800001303",
    "price" : 25.99
  }, {
    "quantity" : 1,
    "name" : "Helm",
    "price" : 18.53
  } ],
  "shoppingCartType" : "PHYSICAL",
  "deliveryType" : "STANDARD",
  "currency" : "EUR",
  "shippingAddress" : {
    "addresseeGivenName" : "Marie",
    "addresseeLastName" : "Mustermann",
    "company" : "Musterbau GmbH & Co KG",
    "street" : "Kastanienallee",
    "streetNr" : "999",
    "additionalAddressInformation" : "Im Rückgebäude",
    "zip" : "90402",
    "city" : "Schwaig",
    "countryCode" : "DE",
    "state" : "Bayern"
  },
  "merchantCustomerNumber" : "cust-732477",
  "merchantOrderReferenceNumber" : "order-A12223412",
  "merchantInvoiceReferenceNumber" : "20150112334345",
  "expiryTime" : 1800,
  "redirectUrlAfterSuccess" : "https://spielauto-versand.de/order/123/success",
  "redirectUrlAfterCancellation" : "https://spielauto-versand.de/order/123/cancellation",
  "redirectUrlAfterRejection" : "https://spielauto-versand.de/order/123/rejection",
  "callbackUrlStatusUpdates" : "https://spielauto-versand.de/callback/status"
}

HTTP/1.1 201 Created
Location: https://api.paydirekt.de/api/checkout/v1/checkouts/cb5d2624-3f2e-4aed-b546-fb5dd73f04f9
Content-Type: application/hal+json;charset=utf-8

{
  "checkoutId" : "cb5d2624-3f2e-4aed-b546-fb5dd73f04f9",
  "type" : "ORDER",
  "status" : "OPEN",
  "creationTimestamp" : "2021-08-03T12:22:10.282Z",
  "totalAmount" : 100.0,
  "shippingAmount" : 3.5,
  "orderAmount" : 96.5,
  "refundLimit" : 200,
  "currency" : "EUR",
  "items" : [ {
    "quantity" : 3,
    "name" : "Bobbycar",
    "ean" : "800001303",
    "price" : 25.99
  }, {
    "quantity" : 1,
    "name" : "Helm",
    "price" : 18.53
  } ],
  "shoppingCartType" : "PHYSICAL",
  "deliveryType" : "STANDARD",
  "shippingAddress" : {
    "addresseeGivenName" : "Marie",
    "addresseeLastName" : "Mustermann",
    "company" : "Musterbau GmbH & Co KG",
    "street" : "Kastanienallee",
    "streetNr" : "999",
    "additionalAddressInformation" : "Im Rückgebäude",
    "zip" : "90402",
    "city" : "Schwaig",
    "countryCode" : "DE",
    "state" : "Bayern"
  },
  "merchantOrderReferenceNumber" : "order-A12223412",
  "merchantCustomerNumber" : "cust-732477",
  "merchantInvoiceReferenceNumber" : "20150112334345",
  "redirectUrlAfterSuccess" : "https://spielauto-versand.de/order/123/success",
  "redirectUrlAfterCancellation" : "https://spielauto-versand.de/order/123/cancellation",
  "redirectUrlAfterRejection" : "https://spielauto-versand.de/order/123/rejection",
  "callbackUrlStatusUpdates" : "https://spielauto-versand.de/callback/status",
  "expiryTimestamp" : "2021-08-03T12:52:10.282Z",
  "_links" : {
    "approve" : {
      "href" : "https://localhost/checkout/?p=cb5d2624-3f2e-4aed-b546-fb5dd73f04f9#/checkout/cb5d2624-3f2e-4aed-b546-fb5dd73f04f9"
    },
    "updateDeliveryInformation" : {
      "href" : "https://api.paydirekt.de/api/checkout/v1/checkouts/cb5d2624-3f2e-4aed-b546-fb5dd73f04f9/deliveryInformation"
    },
    "updateMerchantInvoiceReferenceNumber" : {
      "href" : "https://api.paydirekt.de/api/checkout/v1/checkouts/cb5d2624-3f2e-4aed-b546-fb5dd73f04f9/merchantInvoiceReferenceNumber"
    },
    "self" : {
      "href" : "https://api.paydirekt.de/api/checkout/v1/checkouts/cb5d2624-3f2e-4aed-b546-fb5dd73f04f9"
    }
  }
}

Beispiel (Order Secured)

POST /api/checkout/v1/checkouts HTTP/1.1
Content-Type: application/json;charset=utf-8
Authorization: Bearer <access_token>

{
  "type" : "ORDER_SECURED",
  "totalAmount" : 100.0,
  "shippingAmount" : 3.5,
  "orderAmount" : 96.5,
  "refundLimit" : 200,
  "items" : [ {
    "quantity" : 3,
    "name" : "Bobbycar",
    "ean" : "800001303",
    "price" : 25.99
  }, {
    "quantity" : 1,
    "name" : "Helm",
    "price" : 18.53
  } ],
  "shoppingCartType" : "PHYSICAL",
  "deliveryType" : "STANDARD",
  "currency" : "EUR",
  "shippingAddress" : {
    "addresseeGivenName" : "Marie",
    "addresseeLastName" : "Mustermann",
    "company" : "Musterbau GmbH & Co KG",
    "street" : "Kastanienallee",
    "streetNr" : "999",
    "additionalAddressInformation" : "Im Rückgebäude",
    "zip" : "90402",
    "city" : "Schwaig",
    "countryCode" : "DE",
    "state" : "Bayern"
  },
  "merchantCustomerNumber" : "cust-732477",
  "merchantOrderReferenceNumber" : "order-A12223412",
  "merchantInvoiceReferenceNumber" : "20150112334345",
  "expiryTime" : 1800,
  "redirectUrlAfterSuccess" : "https://spielauto-versand.de/order/123/success",
  "redirectUrlAfterCancellation" : "https://spielauto-versand.de/order/123/cancellation",
  "redirectUrlAfterRejection" : "https://spielauto-versand.de/order/123/rejection",
  "callbackUrlStatusUpdates" : "https://spielauto-versand.de/callback/status",
  "requestedPreauthorizationValidity" : "2021-08-06"
}

HTTP/1.1 201 Created
Location: https://api.paydirekt.de/api/checkout/v1/checkouts/bf7ae4e9-512a-4b75-a9a9-f9c3e08a8c8a
Content-Type: application/hal+json;charset=utf-8

{
  "checkoutId" : "bf7ae4e9-512a-4b75-a9a9-f9c3e08a8c8a",
  "type" : "ORDER_SECURED",
  "status" : "OPEN",
  "creationTimestamp" : "2021-08-03T12:23:37.566Z",
  "totalAmount" : 100.0,
  "shippingAmount" : 3.5,
  "orderAmount" : 96.5,
  "refundLimit" : 200,
  "currency" : "EUR",
  "items" : [ {
    "quantity" : 3,
    "name" : "Bobbycar",
    "ean" : "800001303",
    "price" : 25.99
  }, {
    "quantity" : 1,
    "name" : "Helm",
    "price" : 18.53
  } ],
  "shoppingCartType" : "PHYSICAL",
  "deliveryType" : "STANDARD",
  "shippingAddress" : {
    "addresseeGivenName" : "Marie",
    "addresseeLastName" : "Mustermann",
    "company" : "Musterbau GmbH & Co KG",
    "street" : "Kastanienallee",
    "streetNr" : "999",
    "additionalAddressInformation" : "Im Rückgebäude",
    "zip" : "90402",
    "city" : "Schwaig",
    "countryCode" : "DE",
    "state" : "Bayern"
  },
  "merchantOrderReferenceNumber" : "order-A12223412",
  "merchantCustomerNumber" : "cust-732477",
  "merchantInvoiceReferenceNumber" : "20150112334345",
  "redirectUrlAfterSuccess" : "https://spielauto-versand.de/order/123/success",
  "redirectUrlAfterCancellation" : "https://spielauto-versand.de/order/123/cancellation",
  "redirectUrlAfterRejection" : "https://spielauto-versand.de/order/123/rejection",
  "callbackUrlStatusUpdates" : "https://spielauto-versand.de/callback/status",
  "expiryTimestamp" : "2021-08-03T12:53:37.566Z",
  "_links" : {
    "approve" : {
      "href" : "https://localhost/checkout/?p=bf7ae4e9-512a-4b75-a9a9-f9c3e08a8c8a#/checkout/bf7ae4e9-512a-4b75-a9a9-f9c3e08a8c8a"
    },
    "updateDeliveryInformation" : {
      "href" : "https://api.paydirekt.de/api/checkout/v1/checkouts/bf7ae4e9-512a-4b75-a9a9-f9c3e08a8c8a/deliveryInformation"
    },
    "updateMerchantInvoiceReferenceNumber" : {
      "href" : "https://api.paydirekt.de/api/checkout/v1/checkouts/bf7ae4e9-512a-4b75-a9a9-f9c3e08a8c8a/merchantInvoiceReferenceNumber"
    },
    "self" : {
      "href" : "https://api.paydirekt.de/api/checkout/v1/checkouts/bf7ae4e9-512a-4b75-a9a9-f9c3e08a8c8a"
    }
  }
}

Beispiel (Validierungsfehler)

POST /api/checkout/v1/checkouts HTTP/1.1
Content-Type: application/json;charset=utf-8
Authorization: Bearer <access_token>

{
  "type" : "DIRECT_SALE",
  "totalAmount" : 100.0,
  "shippingAmount" : 5.999,
  "orderAmount" : 96.5,
  "refundLimit" : 200,
  "items" : [ {
    "quantity" : 3,
    "name" : "Bobbycar",
    "ean" : "800001303",
    "price" : 25.99
  }, {
    "quantity" : 1,
    "name" : "Helm",
    "price" : 18.53
  } ],
  "shoppingCartType" : "MIXED",
  "currency" : "EUR",
  "overcapture" : false,
  "shippingAddress" : {
    "addresseeGivenName" : "Marie",
    "addresseeLastName" : "Mustermann",
    "company" : "Musterbau GmbH & Co KG",
    "street" : "Kastanienallee",
    "streetNr" : "999",
    "additionalAddressInformation" : "Im Rückgebäude",
    "zip" : "90402",
    "city" : "Schwaig",
    "countryCode" : "DE",
    "state" : "Bayern"
  },
  "merchantCustomerNumber" : "cust-732477",
  "merchantOrderReferenceNumber" : "order-A12223412",
  "merchantReconciliationReferenceNumber" : "recon-A12223412",
  "merchantInvoiceReferenceNumber" : "20150112334345",
  "note" : "Ihr Einkauf bei Spielauto-Versand.",
  "sha256hashedEmailAddress" : "fxP4R-IxH1Eaxpb0f_i5Shc8-FrYrtmx5lx35f9Xzgg",
  "expiryTime" : 1800,
  "redirectUrlAfterSuccess" : "https://spielauto-versand.de/order/123/success",
  "redirectUrlAfterCancellation" : "https://spielauto-versand.de/order/123/cancellation",
  "redirectUrlAfterAgeVerificationFailure" : "https://spielauto-versand.de/order/123/underAge",
  "redirectUrlAfterRejection" : "https://spielauto-versand.de/order/123/rejection",
  "callbackUrlStatusUpdates" : "https://spielauto-versand.de/callback/status"
}

HTTP/1.1 400 Bad Request
Content-Type: application/hal+json;charset=utf-8

{
  "messages" : [ {
    "severity" : "ERROR",
    "code" : "VALIDATION_ERROR",
    "path" : "shippingAmount",
    "reasonCode" : "INVALID_FORMAT",
    "logref" : "bddc9682-574a-4913-a743-9ae9d78b2690:7yk5DGxxCfL"
  } ]
}

Beispiel (Fachlicher Fehler)

POST /api/checkout/v1/checkouts HTTP/1.1
Content-Type: application/json;charset=utf-8
Authorization: Bearer <access_token>

{
  "type" : "DIRECT_SALE",
  "totalAmount" : 100.0,
  "shippingAmount" : 3.5,
  "orderAmount" : 96.5,
  "refundLimit" : 200,
  "items" : [ {
    "quantity" : 3,
    "name" : "Bobbycar",
    "ean" : "800001303",
    "price" : 25.99
  }, {
    "quantity" : 1,
    "name" : "Helm",
    "price" : 18.53
  } ],
  "shoppingCartType" : "MIXED",
  "currency" : "EUR",
  "overcapture" : false,
  "shippingAddress" : {
    "addresseeGivenName" : "Marie",
    "addresseeLastName" : "Mustermann",
    "company" : "Musterbau GmbH & Co KG",
    "street" : "Kastanienallee",
    "streetNr" : "999",
    "additionalAddressInformation" : "Im Rückgebäude",
    "zip" : "90402",
    "city" : "Schwaig",
    "countryCode" : "DE",
    "state" : "Bayern"
  },
  "merchantCustomerNumber" : "cust-732477",
  "merchantOrderReferenceNumber" : "order-A12223412",
  "merchantReconciliationReferenceNumber" : "recon-A12223412",
  "merchantInvoiceReferenceNumber" : "20150112334345",
  "note" : "Ihr Einkauf bei Spielauto-Versand.",
  "sha256hashedEmailAddress" : "fxP4R-IxH1Eaxpb0f_i5Shc8-FrYrtmx5lx35f9Xzgg",
  "expiryTime" : 1800,
  "redirectUrlAfterSuccess" : "https://spielauto-versand.de/order/123/success",
  "redirectUrlAfterCancellation" : "https://spielauto-versand.de/order/123/cancellation",
  "redirectUrlAfterAgeVerificationFailure" : "https://spielauto-versand.de/order/123/underAge",
  "redirectUrlAfterRejection" : "https://spielauto-versand.de/order/123/rejection",
  "callbackUrlStatusUpdates" : "https://spielauto-versand.de/callback/status"
}

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/hal+json;charset=utf-8

{
  "messages" : [ {
    "severity" : "ERROR",
    "code" : "MERCHANT_BANKACCOUNT_LOCKED",
    "logref" : "1e04ae2b-7c53-470f-8274-814be0015609:4fPGWU2EkIk"
  } ]
}

Beispiel (Konvertierungsfehler)

POST /api/checkout/v1/checkouts HTTP/1.1
Content-Type: application/json;charset=utf-8
Authorization: Bearer <access_token>

{
  "type" : "DIRECT_SALE",
  "totalAmount" : 100.0,
  "shippingAmount" : 3.5,
  "orderAmount" : 96.5,
  "refundLimit" : 200,
  "items" : [ {
    "quantity" : 3,
    "name" : "Bobbycar",
    "ean" : "800001303",
    "price" : 25.99
  }, {
    "quantity" : 1,
    "name" : "Helm",
    "price" : 18.53
  } ],
  "shoppingCartType" : "MIXED",
  "currency" : "EUR",
  "overcapture" : false,
  "shippingAddress" : {
    "addresseeGivenName" : "Marie",
    "addresseeLastName" : "Mustermann",
    "company" : "ungültige Zeichen sind z.B.: €¥£˚\\˙¯⁀",
    "street" : "Kastanienallee",
    "streetNr" : "999",
    "additionalAddressInformation" : "Im Rückgebäude",
    "zip" : "90402",
    "city" : "Schwaig",
    "countryCode" : "DE",
    "state" : "Bayern"
  },
  "merchantCustomerNumber" : "cust-732477",
  "merchantOrderReferenceNumber" : "order-A12223412",
  "merchantReconciliationReferenceNumber" : "recon-A12223412",
  "merchantInvoiceReferenceNumber" : "20150112334345",
  "note" : "Ihr Einkauf bei Spielauto-Versand.",
  "sha256hashedEmailAddress" : "fxP4R-IxH1Eaxpb0f_i5Shc8-FrYrtmx5lx35f9Xzgg",
  "expiryTime" : 1800,
  "redirectUrlAfterSuccess" : "https://spielauto-versand.de/order/123/success",
  "redirectUrlAfterCancellation" : "https://spielauto-versand.de/order/123/cancellation",
  "redirectUrlAfterAgeVerificationFailure" : "https://spielauto-versand.de/order/123/underAge",
  "redirectUrlAfterRejection" : "https://spielauto-versand.de/order/123/rejection",
  "callbackUrlStatusUpdates" : "https://spielauto-versand.de/callback/status"
}

HTTP/1.1 400 Bad Request
Content-Type: application/hal+json;charset=utf-8

{
  "messages" : [ {
    "severity" : "ERROR",
    "code" : "CONVERSION_ERROR",
    "path" : "shippingAddress.company",
    "reasonCode" : "HTTP_MESSAGE_NOT_READABLE",
    "logref" : "bb985f88-9675-497f-ba5e-5fb8ecf26084:48E4SG4I57m",
    "content" : "ungültige Zeichen sind z.B.: €¥£˚\\˙¯⁀"
  } ]
}

Abfrage

GET /api/checkout/v1/checkouts/{checkoutId}

Ein zuvor angelegter Checkout kann über die GET-Methode aufgerufen werden, um den Status der Zahlung und andere Eigenschaften abzufragen, sowie um die Links zu weiteren Ressourcen, z. B. Captures und Refunds, zu ermitteln.

Response

Feld Typ Eigenschaften Beschreibung

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.
`_embedded`	Object		Embedded Ressourcen

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

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.

_embedded

Object

Embedded Ressourcen

Links

Relation Description

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. Der Aufbau bzw. die Parameter des Links können sich aufgrund von internen Weiterentwicklungen verändern. Verwenden Sie daher ausschließlich den von unserem System zur Laufzeit zurückgelieferten Link.
`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.

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. Der Aufbau bzw. die Parameter des Links können sich aufgrund von internen Weiterentwicklungen verändern. Verwenden Sie daher ausschließlich den von unserem System zur Laufzeit zurückgelieferten Link.

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

Resource	Beschreibung
`captures`	Array von Captures, sofern Captures zu diesem Checkout vorhanden sind.
`refunds`	Array von Refunds, sofern Refunds zu diesem Checkout vorhanden sind.

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

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

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/d091ffc7-3655-489f-aed2-9c4b3a4735cd HTTP/1.1
Content-Type: application/json;charset=utf-8
Authorization: Bearer <access_token>

HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=utf-8

{
  "checkoutId" : "d091ffc7-3655-489f-aed2-9c4b3a4735cd",
  "type" : "DIRECT_SALE",
  "status" : "OPEN",
  "creationTimestamp" : "2021-08-03T12:21:11.764Z",
  "totalAmount" : 100.0,
  "shippingAmount" : 3.5,
  "orderAmount" : 96.5,
  "refundLimit" : 200,
  "currency" : "EUR",
  "items" : [ {
    "quantity" : 3,
    "name" : "Bobbycar",
    "ean" : "800001303",
    "price" : 25.99
  }, {
    "quantity" : 1,
    "name" : "Helm",
    "price" : 18.53
  } ],
  "shoppingCartType" : "MIXED",
  "deliveryType" : "STANDARD",
  "shippingAddress" : {
    "addresseeGivenName" : "Marie",
    "addresseeLastName" : "Mustermann",
    "company" : "Musterbau GmbH & Co KG",
    "street" : "Kastanienallee",
    "streetNr" : "999",
    "additionalAddressInformation" : "Im Rückgebäude",
    "zip" : "90402",
    "city" : "Schwaig",
    "countryCode" : "DE",
    "state" : "Bayern"
  },
  "merchantOrderReferenceNumber" : "order-A12223412",
  "merchantCustomerNumber" : "cust-732477",
  "merchantInvoiceReferenceNumber" : "20150112334345",
  "merchantReconciliationReferenceNumber" : "recon-A12223412",
  "note" : "Ihr Einkauf bei Spielauto-Versand.",
  "minimumAge" : 18,
  "redirectUrlAfterSuccess" : "https://spielauto-versand.de/order/123/success",
  "redirectUrlAfterCancellation" : "https://spielauto-versand.de/order/123/cancellation",
  "redirectUrlAfterAgeVerificationFailure" : "https://spielauto-versand.de/order/123/ageverificationfailed",
  "redirectUrlAfterRejection" : "https://spielauto-versand.de/order/123/rejection",
  "callbackUrlStatusUpdates" : "https://spielauto-versand.de/callback/status",
  "deliveryInformation" : {
    "expectedShippingDate" : "2016-10-19T12:00:00.000Z",
    "logisticsProvider" : "DHL",
    "trackingNumber" : "1234567890"
  },
  "expiryTimestamp" : "2021-08-03T12:51:11.764Z",
  "_links" : {
    "approve" : {
      "href" : "https://localhost/checkout/?p=d091ffc7-3655-489f-aed2-9c4b3a4735cd#/checkout/d091ffc7-3655-489f-aed2-9c4b3a4735cd"
    },
    "updateDeliveryInformation" : {
      "href" : "https://api.paydirekt.de/api/checkout/v1/checkouts/d091ffc7-3655-489f-aed2-9c4b3a4735cd/deliveryInformation"
    },
    "updateMerchantInvoiceReferenceNumber" : {
      "href" : "https://api.paydirekt.de/api/checkout/v1/checkouts/d091ffc7-3655-489f-aed2-9c4b3a4735cd/merchantInvoiceReferenceNumber"
    },
    "self" : {
      "href" : "https://api.paydirekt.de/api/checkout/v1/checkouts/d091ffc7-3655-489f-aed2-9c4b3a4735cd"
    }
  }
}

Beispiel (Direct Sale nach Approval durch Kunden)

GET /api/checkout/v1/checkouts/d091ffc7-3655-489f-aed2-9c4b3a4735cd HTTP/1.1
Content-Type: application/json;charset=utf-8
Authorization: Bearer <access_token>

HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=utf-8

{
  "checkoutId" : "d091ffc7-3655-489f-aed2-9c4b3a4735cd",
  "type" : "DIRECT_SALE",
  "status" : "APPROVED",
  "correlationId" : "ext0815-00000015",
  "creationTimestamp" : "2021-08-03T12:21:11.764Z",
  "totalAmount" : 100.0,
  "shippingAmount" : 3.5,
  "orderAmount" : 96.5,
  "refundLimit" : 200,
  "currency" : "EUR",
  "items" : [ {
    "quantity" : 3,
    "name" : "Bobbycar",
    "ean" : "800001303",
    "price" : 25.99
  }, {
    "quantity" : 1,
    "name" : "Helm",
    "price" : 18.53
  } ],
  "shoppingCartType" : "MIXED",
  "deliveryType" : "STANDARD",
  "shippingAddress" : {
    "addresseeGivenName" : "Marie",
    "addresseeLastName" : "Mustermann",
    "company" : "Musterbau GmbH & Co KG",
    "street" : "Kastanienallee",
    "streetNr" : "999",
    "additionalAddressInformation" : "Im Rückgebäude",
    "zip" : "90402",
    "city" : "Schwaig",
    "countryCode" : "DE",
    "state" : "Bayern"
  },
  "merchantOrderReferenceNumber" : "order-A12223412",
  "merchantCustomerNumber" : "cust-732477",
  "merchantInvoiceReferenceNumber" : "20150112334345",
  "merchantReconciliationReferenceNumber" : "recon-A12223412",
  "note" : "Ihr Einkauf bei Spielauto-Versand.",
  "minimumAge" : 18,
  "redirectUrlAfterSuccess" : "https://spielauto-versand.de/order/123/success",
  "redirectUrlAfterCancellation" : "https://spielauto-versand.de/order/123/cancellation",
  "redirectUrlAfterAgeVerificationFailure" : "https://spielauto-versand.de/order/123/ageverificationfailed",
  "redirectUrlAfterRejection" : "https://spielauto-versand.de/order/123/rejection",
  "callbackUrlStatusUpdates" : "https://spielauto-versand.de/callback/status",
  "deliveryInformation" : {
    "expectedShippingDate" : "2016-10-19T12:00:00.000Z",
    "logisticsProvider" : "DHL",
    "trackingNumber" : "1234567890"
  },
  "expiryTimestamp" : "2021-08-03T12:51:11.764Z",
  "_links" : {
    "refunds" : {
      "href" : "https://api.paydirekt.de/api/checkout/v1/checkouts/d091ffc7-3655-489f-aed2-9c4b3a4735cd/refunds"
    },
    "updateDeliveryInformation" : {
      "href" : "https://api.paydirekt.de/api/checkout/v1/checkouts/d091ffc7-3655-489f-aed2-9c4b3a4735cd/deliveryInformation"
    },
    "updateMerchantInvoiceReferenceNumber" : {
      "href" : "https://api.paydirekt.de/api/checkout/v1/checkouts/d091ffc7-3655-489f-aed2-9c4b3a4735cd/merchantInvoiceReferenceNumber"
    },
    "self" : {
      "href" : "https://api.paydirekt.de/api/checkout/v1/checkouts/d091ffc7-3655-489f-aed2-9c4b3a4735cd"
    }
  },
  "_embedded" : {
    "captures" : [ {
      "type" : "CAPTURE_DIRECT_SALE",
      "transactionId" : "2a45ea30-b467-4a88-a1f3-6275e9d5e0a0",
      "amount" : 100.0,
      "callbackUrlStatusUpdates" : "https://spielauto-versand.de/callback/status",
      "deliveryInformation" : {
        "expectedShippingDate" : "2016-10-19T12:00:00.000Z",
        "logisticsProvider" : "DHL",
        "trackingNumber" : "1234567890"
      },
      "status" : "SUCCESSFUL",
      "_links" : {
        "self" : {
          "href" : "https://api.paydirekt.de/api/checkout/v1/checkouts/d091ffc7-3655-489f-aed2-9c4b3a4735cd/captures/2a45ea30-b467-4a88-a1f3-6275e9d5e0a0"
        }
      }
    } ]
  }
}

Callback für Statusupdates

Wenn Händler/PSPs bei Anlage von Checkouts eine Callback URL callbackUrlStatusUpdates übergeben, sendet das paydirekt-System bei Statusänderungen des Checkouts an diese URL einen HTTP-Request. Bei DIRECT_SALE werden für den eingebetteten Capture ebenfalls Statusupdates versendet. Bei Verbindungsfehlern oder Responses mit einem HTTP-Statuscode von 5xx wird das paydirekt-System die Übermittlung der Statusänderung in einem Zeitfenster von 24 Stunden bis zu 5 Mal wiederholen. Statusänderungen werden dabei immer in der Reihenfolge übermittelt, in der sie am Checkout aufgetreten sind. Kann eine Statusänderung nicht übermittelt werden, so werden auch alle nachfolgenden Statusänderungen nicht übermittelt, bis entweder die fehlgeschlagene Übermittlung nachgeholt werden konnte oder alle wiederholten Versuche fehlgeschlagen sind.

POST callbackUrlStatusUpdates

Request

Feld Typ Eigenschaften Beschreibung

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.
`statusUpdateTimestamp`	String	Immer vorhanden.	Zeitstempel der Statusänderung.
`sequenceNumber`	Number	Immer vorhanden.	Sequenznummer der Statusänderung. Anhand der Sequenznummer kann ein Shop die Reihenfolge der Statusänderungen nachvollziehen und gegebenenfalls fehlende Statusänderungen erkennen.

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.

statusUpdateTimestamp

String

Immer vorhanden.

Zeitstempel der Statusänderung.

sequenceNumber

Number

Immer vorhanden.

Sequenznummer der Statusänderung. Anhand der Sequenznummer kann ein Shop die Reihenfolge der Statusänderungen nachvollziehen und gegebenenfalls fehlende Statusänderungen erkennen.

Beispiel

POST /webhooktest/v1/checkout/status HTTP/1.1
Content-Type: application/json;charset=utf-8

{
  "checkoutId" : "a563306c-dff8-4eb5-bf89-3369a6377715",
  "checkoutStatus" : "APPROVED",
  "merchantOrderReferenceNumber" : "order-A12223412",
  "statusUpdateTimestamp" : "2020-01-01T12:00:00.000Z",
  "sequenceNumber" : 4
}

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

Feld	Typ	Eigenschaften	Beschreibung
`expectedShippingDate`	String	Optional. Zeitstempel im ISO-8601-Format.	Erwartetes Versanddatum.
`logisticsProvider`	String	Optional.	Paket-Dienstleister.
`trackingNumber`	String	Optional.	Sendungsnummer.

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

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.

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/2deac850-363f-4171-8691-49b2db659566/deliveryInformation HTTP/1.1
Content-Type: application/json;charset=utf-8
Authorization: Bearer <access_token>

{
  "expectedShippingDate" : "2016-10-19T12:00:00Z",
  "logisticsProvider" : "DHL",
  "trackingNumber" : "1234567890"
}

Aktualisierung der Rechnungsreferenz

PUT /api/checkout/v1/checkouts/{checkoutId}/merchantInvoiceReferenceNumber

Über diesen Endpoint kann die Rechnungsreferenz eines bereits angelegten Checkouts aktualisiert werden. Die aktuelle Rechnungsreferenz des Checkouts ist für Käufer nicht einsehbar. Aktualisierungen sind nur bis 25 Tage nach dem letzten Capture auf den Checkout gestattet.

Request

Feld Typ Eigenschaften Beschreibung

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.

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

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.

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/2685d7ef-9b85-4bfc-ae24-e81e575a9501/merchantInvoiceReferenceNumber HTTP/1.1
Content-Type: application/json;charset=utf-8
Authorization: Bearer <access_token>

{
  "merchantInvoiceReferenceNumber" : "12345678"
}

Capture

Durch ein Capture wird das Konto des Käufers um einen bestimmten Betrag belastet und dem Händler eine Zahlungsgarantie ausgesprochen.

Jedes Capture wird von der Käuferbank autorisiert. Eine erfolgreiche Bank-Autorisierung führt zu einer Zahlungsgarantie über den angefragten Betrag und einer entsprechenden Buchung auf dem Konto. Dies führt je nach Ergebnis zu einem finalen Status SUCCESSFUL oder REJECTED.

Es gibt folgende Typen von Captures:

CAPTURE_DIRECT_SALE: Wird automatisch erzeugt, wenn der Käufer einen Checkout vom Typ DIRECT_SALE bestätigt und die Autorisierung durch die Käuferbank erfolgreich war.
CAPTURE_ORDER: Nach erfolgreicher Anlage eines Checkouts vom Typ ORDER kann der Händler bis maximal 182 Tage nach Erstellung der Order einen oder mehrere Capture(s) vom 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

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.

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

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.
422 (Unprocessable Entity)	`ACCOUNT_DEBOARDED`	Es wurde versucht, einen Capture für einen Kunden anzulegen, welcher nicht mehr bei paydirekt teilnimmt.

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.

422 (Unprocessable Entity)

ACCOUNT_DEBOARDED

Es wurde versucht, einen Capture für einen Kunden anzulegen, welcher nicht mehr bei paydirekt teilnimmt.

Beispiel

POST /api/checkout/v1/checkouts/bf7ae4e9-512a-4b75-a9a9-f9c3e08a8c8a/captures HTTP/1.1
Content-Type: application/json;charset=utf-8
Authorization: Bearer <access_token>

{
  "amount" : 10,
  "finalCapture" : false,
  "note" : "Thanks for shopping.",
  "merchantCaptureReferenceNumber" : "capture-21323",
  "merchantReconciliationReferenceNumber" : "recon-1234",
  "captureInvoiceReferenceNumber" : "invoice-1234",
  "callbackUrlStatusUpdates" : "https://spielauto-versand.de/callback/status",
  "deliveryInformation" : {
    "expectedShippingDate" : "2016-10-19T12:00:00.000Z",
    "logisticsProvider" : "DHL",
    "trackingNumber" : "1234567890"
  }
}

HTTP/1.1 201 Created
Location: https://api.paydirekt.de/api/checkout/v1/checkouts/bf7ae4e9-512a-4b75-a9a9-f9c3e08a8c8a/captures/8978dc99-f4b0-499e-bc7e-64a12772d4fc
Content-Type: application/hal+json;charset=utf-8

{
  "type" : "CAPTURE_ORDER",
  "transactionId" : "8978dc99-f4b0-499e-bc7e-64a12772d4fc",
  "amount" : 10,
  "merchantReconciliationReferenceNumber" : "recon-1234",
  "finalCapture" : false,
  "merchantCaptureReferenceNumber" : "capture-21323",
  "captureInvoiceReferenceNumber" : "invoice-1234",
  "callbackUrlStatusUpdates" : "https://spielauto-versand.de/callback/status",
  "deliveryInformation" : {
    "expectedShippingDate" : "2016-10-19T12:00:00.000Z",
    "logisticsProvider" : "DHL",
    "trackingNumber" : "1234567890"
  },
  "status" : "SUCCESSFUL",
  "_links" : {
    "self" : {
      "href" : "https://api.paydirekt.de/api/checkout/v1/checkouts/bf7ae4e9-512a-4b75-a9a9-f9c3e08a8c8a/captures/8978dc99-f4b0-499e-bc7e-64a12772d4fc"
    }
  }
}

Abfrage

GET /api/checkout/v1/checkouts/{checkoutId}/captures/{captureId}

Die Abfrage liefert die Daten eines spezifischen Captures. Die Capture-Transaktionen sind in der Checkout-Resource eingebettet. Eine explizite Abfrage einer Capture-Transaktion ist im Allgemeinen nicht notwendig.

Response

Feld Typ Eigenschaften Beschreibung

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.

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

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.

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/bf7ae4e9-512a-4b75-a9a9-f9c3e08a8c8a/captures/8978dc99-f4b0-499e-bc7e-64a12772d4fc HTTP/1.1
Content-Type: application/json;charset=utf-8
Authorization: Bearer <access_token>

HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=utf-8

{
  "type" : "CAPTURE_ORDER",
  "transactionId" : "8978dc99-f4b0-499e-bc7e-64a12772d4fc",
  "amount" : 10,
  "merchantReconciliationReferenceNumber" : "recon-1234",
  "finalCapture" : false,
  "merchantCaptureReferenceNumber" : "capture-21323",
  "captureInvoiceReferenceNumber" : "invoice-1234",
  "callbackUrlStatusUpdates" : "https://spielauto-versand.de/callback/status",
  "deliveryInformation" : {
    "expectedShippingDate" : "2016-10-19T12:00:00.000Z",
    "logisticsProvider" : "DHL",
    "trackingNumber" : "1234567890"
  },
  "status" : "SUCCESSFUL",
  "paymentInformationId" : "0000000-1111-2222-3333-444444444444",
  "_links" : {
    "self" : {
      "href" : "https://api.paydirekt.de/api/checkout/v1/checkouts/bf7ae4e9-512a-4b75-a9a9-f9c3e08a8c8a/captures/8978dc99-f4b0-499e-bc7e-64a12772d4fc"
    }
  }
}

Callback für Statusupdates

Händler/PSPs können bei Anlage des Captures eine Callback URL callbackUrlStatusUpdates übergeben. Das paydirekt-System sendet bei Statusänderungen des Captures an diese einen HTTP-Request. Bei Verbindungsfehlern oder Responses mit einem HTTP-Statuscode von 5xx wird das paydirekt-System die Übermittlung der Statusänderung in einem Zeitfenster von 24 Stunden bis zu 5 Mal wiederholen. Statusänderungen werden dabei immer in der Reihenfolge übermittelt, in der sie am Checkout aufgetreten sind. Kann eine Statusänderung nicht übermittelt werden, so werden auch alle nachfolgenden Statusänderungen nicht übermittelt, bis entweder die fehlgeschlagene Übermittlung nachgeholt werden konnte oder alle wiederholten Versuche fehlgeschlagen sind.

POST callbackUrlStatusUpdates

Request

Feld Typ Eigenschaften Beschreibung

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.
`statusUpdateTimestamp`	String	Immer vorhanden.	Zeitstempel der Statusänderung.
`sequenceNumber`	Number	Immer vorhanden.	Sequenznummer der Statusänderung. Anhand der Sequenznummer kann ein Shop die Reihenfolge der Statusänderungen nachvollziehen und gegebenenfalls fehlende Statusänderungen erkennen.

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.

statusUpdateTimestamp

String

Immer vorhanden.

Zeitstempel der Statusänderung.

sequenceNumber

Number

Immer vorhanden.

Sequenznummer der Statusänderung. Anhand der Sequenznummer kann ein Shop die Reihenfolge der Statusänderungen nachvollziehen und gegebenenfalls fehlende Statusänderungen erkennen.

Beispiel

POST /webhooktest/v1/capture/status HTTP/1.1
Content-Type: application/json;charset=utf-8

{
  "checkoutId" : "060f9016-c995-44d6-8a36-c55a34a3a4a8",
  "merchantOrderReferenceNumber" : "order-A12223412",
  "transactionId" : "8eba8017-a5da-46fd-8fc2-dd917d32865a",
  "captureStatus" : "SUCCESSFUL",
  "merchantCaptureReferenceNumber" : "3aeeea9d-713f-437f-b342-eaa29b39ac49",
  "statusUpdateTimestamp" : "2020-01-01T12:00:00.000Z",
  "sequenceNumber" : 2
}

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 (Secured) schließen

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

Bestellungen vom Typ ORDER als auch ORDER_SECURED können und sollen im paydirekt-System geschlossen werden, wenn für die Bestellung kein weiterer CAPTURE durchgeführt werden wird. Damit wird die Bestellung dem Kunden nicht weiter als offen angezeigt.

Bestellungen können nur geschlossen werden, wenn sie vorher vom Kunden durch seinen Login bestätigt worden sind.

Request

Die Anfrage benötigt keinen Request Body.

Response

In der Response wird der angelegte Checkout zurückgegeben. Die Struktur ist identisch mit dem Checkout Endpoint GET-Aufruf des Checkouts.

Return Codes

Status Code Message Code Beschreibung

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

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ückzahlung ermöglicht. Der Endpoint sollte nicht direkt aufgerufen werden. Es sollte immer der Link aus der Checkout-Ressource verwendet werden.

Mit der Erzeugung einer Refund-Ressource wird eine Rückzahlung an den Kunden initiiert.

Request

Feld Typ Eigenschaften Beschreibung

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.

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

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.

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/cb5d2624-3f2e-4aed-b546-fb5dd73f04f9/refunds HTTP/1.1
Content-Type: application/json;charset=utf-8
Authorization: Bearer <access_token>

{
  "amount" : 10,
  "note" : "Ihre Bestellung vom 31.03.2015",
  "merchantRefundReferenceNumber" : "refund-99989",
  "merchantReconciliationReferenceNumber" : "recon-1234",
  "reason" : "MERCHANT_CAN_NOT_DELIVER_GOODS",
  "callbackUrlStatusUpdates" : "https://spielauto-versand.de/callback/status"
}

HTTP/1.1 201 Created
Location: https://api.paydirekt.de/api/checkout/v1/checkouts/cb5d2624-3f2e-4aed-b546-fb5dd73f04f9/refunds/7b13f884-4833-45ab-b0aa-f074ca878239
Content-Type: application/hal+json;charset=utf-8

{
  "type" : "REFUND",
  "transactionId" : "7b13f884-4833-45ab-b0aa-f074ca878239",
  "amount" : 10,
  "merchantReconciliationReferenceNumber" : "recon-1234",
  "note" : "Ihre Bestellung vom 31.03.2015",
  "merchantRefundReferenceNumber" : "refund-99989",
  "status" : "PENDING",
  "reason" : "MERCHANT_CAN_NOT_DELIVER_GOODS",
  "callbackUrlStatusUpdates" : "https://spielauto-versand.de/callback/status",
  "_links" : {
    "self" : {
      "href" : "https://api.paydirekt.de/api/checkout/v1/checkouts/cb5d2624-3f2e-4aed-b546-fb5dd73f04f9/refunds/7b13f884-4833-45ab-b0aa-f074ca878239"
    }
  }
}

Abfrage

GET /api/checkout/v1/checkouts/{checkoutId}/refunds/{refundId}

Liefert die Daten zu einer Rückzahlung. Nach einer Initiierung eines Refunds befindet sich der Refund mindestens einen Tag im Status PENDING. Es wird empfohlen, den Status 1-2 mal pro Tag abzufragen, bis ein finaler Status (SUCCESS oder FAILED) erreicht ist.

Die Refund-Transaktionen sind in der Checkout-Ressource embedded. Refundinformationen können also auch durch Abfrage des zugehörigen Checkouts abgerufen werden.

Response

Feld Typ Eigenschaften Beschreibung

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.

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

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.

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/cb5d2624-3f2e-4aed-b546-fb5dd73f04f9/refunds/7b13f884-4833-45ab-b0aa-f074ca878239 HTTP/1.1
Content-Type: application/json;charset=utf-8
Authorization: Bearer <access_token>

HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=utf-8

{
  "type" : "REFUND",
  "transactionId" : "7b13f884-4833-45ab-b0aa-f074ca878239",
  "amount" : 10,
  "merchantReconciliationReferenceNumber" : "recon-1234",
  "note" : "Ihre Bestellung vom 31.03.2015",
  "merchantRefundReferenceNumber" : "refund-99989",
  "status" : "PENDING",
  "reason" : "MERCHANT_CAN_NOT_DELIVER_GOODS",
  "callbackUrlStatusUpdates" : "https://spielauto-versand.de/callback/status",
  "paymentInformationId" : "0000000-1111-2222-3333-444444444444",
  "_links" : {
    "self" : {
      "href" : "https://api.paydirekt.de/api/checkout/v1/checkouts/cb5d2624-3f2e-4aed-b546-fb5dd73f04f9/refunds/7b13f884-4833-45ab-b0aa-f074ca878239"
    }
  }
}

Callback für Statusupdates

Händler/PSPs können bei Anlage des Refunds eine Callback URL callbackUrlStatusUpdates übergeben. Das paydirekt-System sendet bei Statusänderungen des Refunds an diese einen HTTP-Request. Bei Verbindungsfehlern oder Responses mit einem HTTP-Statuscode von 5xx wird das paydirekt-System die Übermittlung der Statusänderung in einem Zeitfenster von 24 Stunden bis zu 5 Mal wiederholen. Statusänderungen werden dabei immer in der Reihenfolge übermittelt, in der sie am Checkout aufgetreten sind. Kann eine Statusänderung nicht übermittelt werden, so werden auch alle nachfolgenden Statusänderungen nicht übermittelt, bis entweder die fehlgeschlagene Übermittlung nachgeholt werden konnte oder alle wiederholten Versuche fehlgeschlagen sind.

POST callbackUrlStatusUpdates

Request

Feld Typ Eigenschaften Beschreibung

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.
`statusUpdateTimestamp`	String	Immer vorhanden.	Zeitstempel der Statusänderung.
`sequenceNumber`	Number	Immer vorhanden.	Sequenznummer der Statusänderung. Anhand der Sequenznummer kann ein Shop die Reihenfolge der Statusänderungen nachvollziehen und gegebenenfalls fehlende Statusänderungen erkennen.

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.

statusUpdateTimestamp

String

Immer vorhanden.

Zeitstempel der Statusänderung.

sequenceNumber

Number

Immer vorhanden.

Sequenznummer der Statusänderung. Anhand der Sequenznummer kann ein Shop die Reihenfolge der Statusänderungen nachvollziehen und gegebenenfalls fehlende Statusänderungen erkennen.

Beispiel

POST /webhooktest/v1/refund/status HTTP/1.1
Content-Type: application/json;charset=utf-8

{
  "checkoutId" : "d7ded1f3-f595-410a-82a0-03429f08a1ab",
  "transactionId" : "f75c1502-e398-46b1-b5c2-5d474b8bbf77",
  "merchantRefundReferenceNumber" : "refund-12345",
  "merchantReconciliationReferenceNumber" : "reconciliation-12345",
  "refundStatus" : "SUCCESSFUL",
  "statusUpdateTimestamp" : "2020-01-01T12:00:00.000Z",
  "sequenceNumber" : 2
}

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.

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

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.

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

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.

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.

Return Codes

siehe Return Codes.

Beispiel

POST /api/checkout/v1/checkouts HTTP/1.1
Content-Type: application/json;charset=utf-8
Authorization: Bearer <access_token>

{
  "type" : "DIRECT_SALE",
  "express" : true,
  "totalAmount" : 100.0,
  "shippingAmount" : 3.5,
  "orderAmount" : 96.5,
  "refundLimit" : 200,
  "items" : [ {
    "quantity" : 3,
    "name" : "Bobbycar",
    "ean" : "800001303",
    "price" : 25.99
  }, {
    "quantity" : 1,
    "name" : "Helm",
    "price" : 18.53
  } ],
  "shoppingCartType" : "MIXED",
  "deliveryType" : "PACKSTATION",
  "currency" : "EUR",
  "overcapture" : false,
  "merchantCustomerNumber" : "cust-732477",
  "merchantOrderReferenceNumber" : "order-A12223412",
  "merchantReconciliationReferenceNumber" : "recon-A12223412",
  "merchantInvoiceReferenceNumber" : "20150112334345",
  "note" : "Ihr Einkauf bei Spielauto-Versand.",
  "sha256hashedEmailAddress" : "fxP4R-IxH1Eaxpb0f_i5Shc8-FrYrtmx5lx35f9Xzgg",
  "minimumAge" : 18,
  "expiryTime" : 1800,
  "redirectUrlAfterSuccess" : "https://spielauto-versand.de/order/123/success",
  "redirectUrlAfterCancellation" : "https://spielauto-versand.de/order/123/cancellation",
  "redirectUrlAfterAgeVerificationFailure" : "https://spielauto-versand.de/order/123/ageverification",
  "redirectUrlAfterRejection" : "https://spielauto-versand.de/order/123/rejection",
  "callbackUrlCheckDestinations" : "https://spielauto-versand.de/destinations/check",
  "callbackUrlStatusUpdates" : "https://spielauto-versand.de/callback/status",
  "webUrlShippingTerms" : "https://spielauto-versand.de//shippingterms"
}

HTTP/1.1 201 Created
Location: https://api.paydirekt.de/api/checkout/v1/checkouts/c7ef2cd9-325a-40b4-8aa1-eee246cfd130
Content-Type: application/hal+json;charset=utf-8

{
  "checkoutId" : "c7ef2cd9-325a-40b4-8aa1-eee246cfd130",
  "type" : "DIRECT_SALE",
  "express" : true,
  "status" : "OPEN",
  "creationTimestamp" : "2021-08-03T12:24:58.310Z",
  "totalAmount" : 100.0,
  "shippingAmount" : 3.5,
  "orderAmount" : 96.5,
  "refundLimit" : 200,
  "currency" : "EUR",
  "items" : [ {
    "quantity" : 3,
    "name" : "Bobbycar",
    "ean" : "800001303",
    "price" : 25.99
  }, {
    "quantity" : 1,
    "name" : "Helm",
    "price" : 18.53
  } ],
  "shoppingCartType" : "MIXED",
  "deliveryType" : "PACKSTATION",
  "merchantOrderReferenceNumber" : "order-A12223412",
  "merchantCustomerNumber" : "cust-732477",
  "merchantInvoiceReferenceNumber" : "20150112334345",
  "merchantReconciliationReferenceNumber" : "recon-A12223412",
  "note" : "Ihr Einkauf bei Spielauto-Versand.",
  "minimumAge" : 18,
  "redirectUrlAfterSuccess" : "https://spielauto-versand.de/order/123/success",
  "redirectUrlAfterCancellation" : "https://spielauto-versand.de/order/123/cancellation",
  "redirectUrlAfterAgeVerificationFailure" : "https://spielauto-versand.de/order/123/ageverification",
  "redirectUrlAfterRejection" : "https://spielauto-versand.de/order/123/rejection",
  "callbackUrlStatusUpdates" : "https://spielauto-versand.de/callback/status",
  "callbackUrlCheckDestinations" : "https://spielauto-versand.de/destinations/check",
  "webUrlShippingTerms" : "https://spielauto-versand.de//shippingterms",
  "expiryTimestamp" : "2021-08-03T12:54:58.310Z",
  "_links" : {
    "approve" : {
      "href" : "https://localhost/checkout/?p=c7ef2cd9-325a-40b4-8aa1-eee246cfd130#/checkout/c7ef2cd9-325a-40b4-8aa1-eee246cfd130"
    },
    "updateDeliveryInformation" : {
      "href" : "https://api.paydirekt.de/api/checkout/v1/checkouts/c7ef2cd9-325a-40b4-8aa1-eee246cfd130/deliveryInformation"
    },
    "updateMerchantInvoiceReferenceNumber" : {
      "href" : "https://api.paydirekt.de/api/checkout/v1/checkouts/c7ef2cd9-325a-40b4-8aa1-eee246cfd130/merchantInvoiceReferenceNumber"
    },
    "self" : {
      "href" : "https://api.paydirekt.de/api/checkout/v1/checkouts/c7ef2cd9-325a-40b4-8aa1-eee246cfd130"
    }
  }
}

Abfrage

GET /api/checkout/v1/checkouts/{checkoutId}

Die Abfrage erfolgt analog zur regulären Checkout Endpoint GET-Abfrage.

Nach der erfolgreichen Bestätigung des Checkouts durch den Kunden werden über diesen Aufruf die vom Kunden gewählte, vollständige Rechnungsadresse, Versandadresse und Versandoption bereitgestellt, eingebettet in die regulären Daten des Checkouts.

Außerdem ist der Link zur tatsächlichen Ausführung des Checkouts enthalten.

Response

Feld Typ Eigenschaften Beschreibung

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.

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

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

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/c7ef2cd9-325a-40b4-8aa1-eee246cfd130 HTTP/1.1
Content-Type: application/json;charset=utf-8
Authorization: Bearer <access_token>

HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=utf-8

{
  "checkoutId" : "c7ef2cd9-325a-40b4-8aa1-eee246cfd130",
  "type" : "DIRECT_SALE",
  "express" : true,
  "status" : "PENDING",
  "correlationId" : "ext0815-00000003",
  "creationTimestamp" : "2021-08-03T12:24:58.310Z",
  "totalAmount" : 106.5,
  "shippingAmount" : 10.0,
  "orderAmount" : 96.5,
  "refundLimit" : 200,
  "currency" : "EUR",
  "items" : [ {
    "quantity" : 3,
    "name" : "Bobbycar",
    "ean" : "800001303",
    "price" : 25.99
  }, {
    "quantity" : 1,
    "name" : "Helm",
    "price" : 18.53
  } ],
  "shoppingCartType" : "MIXED",
  "deliveryType" : "PACKSTATION",
  "shippingAddress" : {
    "addresseeGivenName" : "Hans",
    "addresseeLastName" : "Mustermann",
    "street" : "Musterstr.",
    "streetNr" : "1",
    "zip" : "12345",
    "city" : "Musterstadt",
    "countryCode" : "DE"
  },
  "merchantOrderReferenceNumber" : "order-A12223412",
  "merchantCustomerNumber" : "cust-732477",
  "merchantInvoiceReferenceNumber" : "20150112334345",
  "merchantReconciliationReferenceNumber" : "recon-A12223412",
  "note" : "Ihr Einkauf bei Spielauto-Versand.",
  "minimumAge" : 18,
  "redirectUrlAfterSuccess" : "https://spielauto-versand.de/order/123/success",
  "redirectUrlAfterCancellation" : "https://spielauto-versand.de/order/123/cancellation",
  "redirectUrlAfterAgeVerificationFailure" : "https://spielauto-versand.de/order/123/ageverification",
  "redirectUrlAfterRejection" : "https://spielauto-versand.de/order/123/rejection",
  "callbackUrlStatusUpdates" : "https://spielauto-versand.de/callback/status",
  "callbackUrlCheckDestinations" : "https://spielauto-versand.de/destinations/check",
  "webUrlShippingTerms" : "https://spielauto-versand.de//shippingterms",
  "shippingOption" : {
    "code" : "1234",
    "name" : "DHL",
    "description" : "DHL ist toll.",
    "amount" : 10.0
  },
  "billingAddress" : {
    "addresseeGivenName" : "Hans",
    "addresseeLastName" : "Mustermann",
    "street" : "Musterstr.",
    "streetNr" : "1",
    "zip" : "12345",
    "city" : "Musterstadt",
    "countryCode" : "DE"
  },
  "buyerEmailAddress" : "hannes.schroeder@senacor.com",
  "expiryTimestamp" : "2021-08-03T12:54:58.310Z",
  "_links" : {
    "execute" : {
      "href" : "https://api.paydirekt.de/api/checkout/v1/checkouts/c7ef2cd9-325a-40b4-8aa1-eee246cfd130/execute"
    },
    "updateDeliveryInformation" : {
      "href" : "https://api.paydirekt.de/api/checkout/v1/checkouts/c7ef2cd9-325a-40b4-8aa1-eee246cfd130/deliveryInformation"
    },
    "updateMerchantInvoiceReferenceNumber" : {
      "href" : "https://api.paydirekt.de/api/checkout/v1/checkouts/c7ef2cd9-325a-40b4-8aa1-eee246cfd130/merchantInvoiceReferenceNumber"
    },
    "self" : {
      "href" : "https://api.paydirekt.de/api/checkout/v1/checkouts/c7ef2cd9-325a-40b4-8aa1-eee246cfd130"
    }
  }
}

Ausführung

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

Aus rechtlichen Gründen muss der Käufer den Kauf im Händlershop abschließen und explizit bestätigen.

Beim Klick auf den Kaufen-Button des Shops teilt der Händler dem paydirekt-System mit, ob der Kaufabschluss erfolgt ist. Im Fall Direct Sale findet zudem die Zahlungsautorisierung statt.

Der Checkout bleibt so lange im Status PENDING, bis die Bestätigung eingegangen ist. Anschließend wechselt der Checkout in den Status APPROVED, sofern die Zahlung durch die Bank erfolgreich war, sonst REJECTED. Die Bestätigung muss innerhalb von 30 Minuten nach Anlage des Checkouts erfolgen.

Request

Feld Typ Eigenschaften Beschreibung

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

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

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

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/18a2e3e6-34ab-4911-b6fe-6ab26e7dcf8f/execute HTTP/1.1
Content-Type: application/json;charset=utf-8
Authorization: Bearer <access_token>

{
  "termsAcceptedTimestamp" : "2015-09-16T16:58:37+02:00",
  "merchantOrderReferenceNumber" : "order-A12223412"
}

HTTP/1.1 200 OK

Callback für Adressprüfung

POST callbackUrlCheckDestinations

Wenn der Händler die Lieferadressen des Kunden validieren und mit Lieferoptionen versehen will, muss er einen optionalen Endpoint zur Verfügung stellen, der prüft, ob Versand- und Rechnungsadressen für eine Bestellung valide sind, welche Versandoptionen es gibt und wie hoch die Versandkosten sind.

Der Endpoint muss über HTTPS abgesichert sein.

Die URL des Endpoints kann bei der Anlage des Checkouts im Feld callbackUrlCheckDestinations angegeben werden. Hier kann auch eine ID oder ein Token zur Referenz auf die Bestellung enthalten sein, falls auf weitere Informationen zur Bestellung bzw. zu den Bestellpositionen zugegriffen werden soll (z. B. Gewicht, Gefahrgüter).

Das paydirekt-System ruft diesen Endpoint nach dem Login des Benutzers einmal oder mehrfach auf (Callback).

Aus Datenschutzgründen werden nicht die vollständigen Adressdaten übermittelt, sondern nur die relevanten Informationen des Bestimmungsorts (Destination):

Land als Ländercode im zweistelligen ISO 3166-1 Format
Postleitzahl
Flag, ob es sich um eine Packstation handelt

Die vom Benutzer ausgewählte, vollständige Liefer- und Versandadresse, sowie die gewählte Versandoption, werden im Checkout gespeichert und können später, nachdem der Kunde die Zahlung bestätigt hat, abgerufen werden.

Wenn der Endpoint nicht erreichbar ist, wird der Checkout mit einem technischen Fehler abgebrochen.

Request

Feld Typ Eigenschaften Beschreibung

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" : "4f498d16-c6ce-48f3-81ed-4e2ac32daae1",
  "merchantOrderReferenceNumber" : "order-A12223412",
  "orderAmount" : 96.5,
  "destinations" : [ {
    "id" : "f1ef551a-c380-402e-a853-b4d31740d643",
    "countryCode" : "DE",
    "zip" : "91781",
    "dhlPackstation" : false
  } ]
}

HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8

{
  "checkedDestinations" : [ {
    "id" : "f1ef551a-c380-402e-a853-b4d31740d643",
    "countryCode" : "DE",
    "zip" : "91781",
    "dhlPackstation" : false,
    "validBillingDestination" : true,
    "validShippingDestination" : true,
    "shippingOptions" : [ {
      "code" : "DHL_PAKET",
      "name" : "DHL Paket",
      "description" : "Lieferung am nächsten Werktag",
      "amount" : 6.99
    } ]
  } ]
}

Callback für Statusupdates

Händler/PSPs können auch bei der Anlage von Express-Checkouts eine Callback URL callbackUrlStatusUpdates übergeben. Das paydirekt-System versendet dann die gleichen Benachrichtigungen wie bei normalen Checkouts.

Reports

Transaktionen

GET /api/reporting/v1/reports/transactions

PSPs und CPSPs können Reports über die Transaktionen abrufen, die von den ihm zugeordneten Shops bzw. Händlern durchgeführt wurden. Die Abfrage von Reports ist nur möglich, wenn bei der Authentifizierung nur der PSP API-Key übergeben wurde, aber kein Shop API-Key. Als CPSP darf ebenfalls nur der eigene API-Key übergeben worden sein, aber keine X-Auth-Merchant-Ref.

Die Anfrage kann hierbei durch optionale from und to Parameter eingeschränkt werden, die den Zeitrahmen des Reports angeben. Bei Weglassen der Werte wird to auf den aktuellen Zeitpunkt gesetzt; from wird bei Nicht-Angabe auf 30 Tage vor to gesetzt.

Der Report kann maximal 180 Tage oder 50.000 Transaktionen umfassen. Wird einer der beiden Werte überschritten, wird ein Fehler zurückgeliefert. In diesem Fall muss ein kleinerer Zeitrahmen gewählt werden.

Durch die Angabe des Accept-Headers wird das Format des Reports gewählt. Valide Werte sind application/json und text/csv.

Query-Parameter

Name Constraints Description

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.

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

checkoutId

String

UUID aus 36 Zeichen.

ID des Checkouts.

checkoutInvoiceNr

String

Maximal 20 Zeichen.

Die bei Anlage des Checkouts vom PSP übergebene merchantInvoiceReferenceNumber.

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.

merchantAgentId

String

UUID aus 36 Zeichen.

ID des Händlerkonzentrators.

merchantAgentName

String

Maximal 100 Zeichen.

Name des Händlerkonzentrators.

concentratorId

String

UUID aus 36 Zeichen.

ID des Konzentrators des Käufers.

concentratorName

String

Maximal 100 Zeichen.

Name des Konzentrators des Käufers.

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.

paydirektExpress

String

y (Express),
n (kein Express)

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

paymentInformationId

String

UUID aus 36 Zeichen.

Eindeutige Payment-Information-ID der SEPA-Transaktion.

MCC

String

Vierstellige Zahl.

MCC (Merchant Category Code) des Händlers.

DBI

String

Vierstellige Zahl.

DBI (Details Business Indicator) des Händlers.

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.

captureInvoiceNr

String

Maximal 20 Zeichen.

Die bei Anlage des Captures vom PSP übergebene captureInvoiceReferenceNumber.

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

Beispiel

GET /api/reporting/v1/reports/transactions?from=2021-07-16T12:10:54.966Z&to=2021-07-21T12:10:54.966Z&fields= HTTP/1.1
Content-Type: application/json;charset=utf-8
Accept: application/json
Authorization: Bearer <access_token>

HTTP/1.1 200 OK
Content-Type: application/json;charset=utf-8

{
  "transactions" : [ {
    "correlationId" : "2619a4ed-342a-4299-917e-19f9e8c60fee",
    "endToEndReferenceNumber" : "0b60c9c4-1682-4030-b3de-d4f2c1ce9f60",
    "transactionTypeId" : "1",
    "transactionDate" : "2021-07-21T12:10:54.933Z",
    "valueDate" : "2021-07-21",
    "contractId" : "a9793641-a6b8-4b17-a20b-064cdc533fb6",
    "merchantId" : "606e0cca-8ecf-416c-b635-91ca9abda080",
    "merchantName" : "Some merchant name",
    "merchantIban" : "DE12500105170648489890",
    "merchantReference" : "db9c80d4-7dc8-431f-af72-c1ce335b6890",
    "checkoutId" : "ced0fef3-8256-41eb-a4f5-b6b55fcead4f",
    "checkoutInvoiceNr" : "44c49fee-3b7a-4e48-97ea-9a3a9d62e5d5",
    "merchantTransactionReferenceNumber" : "ebf7237c-2dfd-41ef-a14e-edea32634c99",
    "merchantBankId" : "370885c4-30cb-49c0-83a0-a948a91fa64a",
    "buyerBankId" : "1834b4ba-7c5e-42e1-8db5-d1b56e9ad817",
    "buyerBankName" : "Buyer Bank Name",
    "transactionAmount" : "1.00",
    "transactionCurrency" : "EUR",
    "merchantAgentId" : "5c11c60c-dfa8-4efb-bda7-99f022af1be7",
    "merchantAgentName" : "Merchant Broker Name",
    "concentratorId" : "980a2d95-a5f6-4836-a87e-a49a78503f1b",
    "concentratorName" : "Buyer Bank Concentrator",
    "shopId" : "440c9255-e8e7-4c28-9f3e-57554510713a",
    "shopName" : "Some shop name",
    "ageVerificationStatus" : "1",
    "paydirektExpress" : "n",
    "paymentInformationId" : "a119017a-a0e7-4ceb-bff2-82a1227ad308",
    "refundReason" : "TECHNICAL_PROBLEM",
    "captureInvoiceNr" : "8e36c89e-17a0-4213-8837-93e1c1730dec",
    "validityDate" : "2021-07-26",
    "MCC" : "742",
    "DBI" : "743"
  }, {
    "correlationId" : "2619a4ed-342a-4299-917e-19f9e8c60fee",
    "endToEndReferenceNumber" : "0b60c9c4-1682-4030-b3de-d4f2c1ce9f60",
    "transactionTypeId" : "1",
    "transactionDate" : "2021-07-21T12:10:54.933Z",
    "valueDate" : "2021-07-21",
    "contractId" : "a9793641-a6b8-4b17-a20b-064cdc533fb6",
    "merchantId" : "606e0cca-8ecf-416c-b635-91ca9abda080",
    "merchantName" : "Some merchant name",
    "merchantIban" : "DE12500105170648489890",
    "merchantReference" : "db9c80d4-7dc8-431f-af72-c1ce335b6890",
    "checkoutId" : "ced0fef3-8256-41eb-a4f5-b6b55fcead4f",
    "checkoutInvoiceNr" : "44c49fee-3b7a-4e48-97ea-9a3a9d62e5d5",
    "merchantTransactionReferenceNumber" : "ebf7237c-2dfd-41ef-a14e-edea32634c99",
    "merchantBankId" : "370885c4-30cb-49c0-83a0-a948a91fa64a",
    "buyerBankId" : "1834b4ba-7c5e-42e1-8db5-d1b56e9ad817",
    "buyerBankName" : "Buyer Bank Name",
    "transactionAmount" : "1.00",
    "transactionCurrency" : "EUR",
    "merchantAgentId" : "5c11c60c-dfa8-4efb-bda7-99f022af1be7",
    "merchantAgentName" : "Merchant Broker Name",
    "concentratorId" : "980a2d95-a5f6-4836-a87e-a49a78503f1b",
    "concentratorName" : "Buyer Bank Concentrator",
    "shopId" : "440c9255-e8e7-4c28-9f3e-57554510713a",
    "shopName" : "Some shop name",
    "ageVerificationStatus" : "1",
    "paydirektExpress" : "n",
    "paymentInformationId" : "a119017a-a0e7-4ceb-bff2-82a1227ad308",
    "refundReason" : "TECHNICAL_PROBLEM",
    "captureInvoiceNr" : "8e36c89e-17a0-4213-8837-93e1c1730dec",
    "validityDate" : "2021-07-26",
    "MCC" : "742",
    "DBI" : "743"
  }, {
    "correlationId" : "2619a4ed-342a-4299-917e-19f9e8c60fee",
    "endToEndReferenceNumber" : "0b60c9c4-1682-4030-b3de-d4f2c1ce9f60",
    "transactionTypeId" : "1",
    "transactionDate" : "2021-07-21T12:10:54.933Z",
    "valueDate" : "2021-07-21",
    "contractId" : "a9793641-a6b8-4b17-a20b-064cdc533fb6",
    "merchantId" : "606e0cca-8ecf-416c-b635-91ca9abda080",
    "merchantName" : "Some merchant name",
    "merchantIban" : "DE12500105170648489890",
    "merchantReference" : "db9c80d4-7dc8-431f-af72-c1ce335b6890",
    "checkoutId" : "ced0fef3-8256-41eb-a4f5-b6b55fcead4f",
    "checkoutInvoiceNr" : "44c49fee-3b7a-4e48-97ea-9a3a9d62e5d5",
    "merchantTransactionReferenceNumber" : "ebf7237c-2dfd-41ef-a14e-edea32634c99",
    "merchantBankId" : "370885c4-30cb-49c0-83a0-a948a91fa64a",
    "buyerBankId" : "1834b4ba-7c5e-42e1-8db5-d1b56e9ad817",
    "buyerBankName" : "Buyer Bank Name",
    "transactionAmount" : "1.00",
    "transactionCurrency" : "EUR",
    "merchantAgentId" : "5c11c60c-dfa8-4efb-bda7-99f022af1be7",
    "merchantAgentName" : "Merchant Broker Name",
    "concentratorId" : "980a2d95-a5f6-4836-a87e-a49a78503f1b",
    "concentratorName" : "Buyer Bank Concentrator",
    "shopId" : "440c9255-e8e7-4c28-9f3e-57554510713a",
    "shopName" : "Some shop name",
    "ageVerificationStatus" : "1",
    "paydirektExpress" : "n",
    "paymentInformationId" : "a119017a-a0e7-4ceb-bff2-82a1227ad308",
    "refundReason" : "TECHNICAL_PROBLEM",
    "captureInvoiceNr" : "8e36c89e-17a0-4213-8837-93e1c1730dec",
    "validityDate" : "2021-07-26",
    "MCC" : "742",
    "DBI" : "743"
  }, {
    "correlationId" : "2619a4ed-342a-4299-917e-19f9e8c60fee",
    "endToEndReferenceNumber" : "0b60c9c4-1682-4030-b3de-d4f2c1ce9f60",
    "transactionTypeId" : "1",
    "transactionDate" : "2021-07-21T12:10:54.933Z",
    "valueDate" : "2021-07-21",
    "contractId" : "a9793641-a6b8-4b17-a20b-064cdc533fb6",
    "merchantId" : "606e0cca-8ecf-416c-b635-91ca9abda080",
    "merchantName" : "Some merchant name",
    "merchantIban" : "DE12500105170648489890",
    "merchantReference" : "db9c80d4-7dc8-431f-af72-c1ce335b6890",
    "checkoutId" : "ced0fef3-8256-41eb-a4f5-b6b55fcead4f",
    "checkoutInvoiceNr" : "44c49fee-3b7a-4e48-97ea-9a3a9d62e5d5",
    "merchantTransactionReferenceNumber" : "ebf7237c-2dfd-41ef-a14e-edea32634c99",
    "merchantBankId" : "370885c4-30cb-49c0-83a0-a948a91fa64a",
    "buyerBankId" : "1834b4ba-7c5e-42e1-8db5-d1b56e9ad817",
    "buyerBankName" : "Buyer Bank Name",
    "transactionAmount" : "1.00",
    "transactionCurrency" : "EUR",
    "merchantAgentId" : "5c11c60c-dfa8-4efb-bda7-99f022af1be7",
    "merchantAgentName" : "Merchant Broker Name",
    "concentratorId" : "980a2d95-a5f6-4836-a87e-a49a78503f1b",
    "concentratorName" : "Buyer Bank Concentrator",
    "shopId" : "440c9255-e8e7-4c28-9f3e-57554510713a",
    "shopName" : "Some shop name",
    "ageVerificationStatus" : "1",
    "paydirektExpress" : "n",
    "paymentInformationId" : "a119017a-a0e7-4ceb-bff2-82a1227ad308",
    "refundReason" : "TECHNICAL_PROBLEM",
    "captureInvoiceNr" : "8e36c89e-17a0-4213-8837-93e1c1730dec",
    "validityDate" : "2021-07-26",
    "MCC" : "742",
    "DBI" : "743"
  }, {
    "correlationId" : "2619a4ed-342a-4299-917e-19f9e8c60fee",
    "endToEndReferenceNumber" : "0b60c9c4-1682-4030-b3de-d4f2c1ce9f60",
    "transactionTypeId" : "1",
    "transactionDate" : "2021-07-21T12:10:54.933Z",
    "valueDate" : "2021-07-21",
    "contractId" : "a9793641-a6b8-4b17-a20b-064cdc533fb6",
    "merchantId" : "606e0cca-8ecf-416c-b635-91ca9abda080",
    "merchantName" : "Some merchant name",
    "merchantIban" : "DE12500105170648489890",
    "merchantReference" : "db9c80d4-7dc8-431f-af72-c1ce335b6890",
    "checkoutId" : "ced0fef3-8256-41eb-a4f5-b6b55fcead4f",
    "checkoutInvoiceNr" : "44c49fee-3b7a-4e48-97ea-9a3a9d62e5d5",
    "merchantTransactionReferenceNumber" : "ebf7237c-2dfd-41ef-a14e-edea32634c99",
    "merchantBankId" : "370885c4-30cb-49c0-83a0-a948a91fa64a",
    "buyerBankId" : "1834b4ba-7c5e-42e1-8db5-d1b56e9ad817",
    "buyerBankName" : "Buyer Bank Name",
    "transactionAmount" : "1.00",
    "transactionCurrency" : "EUR",
    "merchantAgentId" : "5c11c60c-dfa8-4efb-bda7-99f022af1be7",
    "merchantAgentName" : "Merchant Broker Name",
    "concentratorId" : "980a2d95-a5f6-4836-a87e-a49a78503f1b",
    "concentratorName" : "Buyer Bank Concentrator",
    "shopId" : "440c9255-e8e7-4c28-9f3e-57554510713a",
    "shopName" : "Some shop name",
    "ageVerificationStatus" : "1",
    "paydirektExpress" : "n",
    "paymentInformationId" : "a119017a-a0e7-4ceb-bff2-82a1227ad308",
    "refundReason" : "TECHNICAL_PROBLEM",
    "captureInvoiceNr" : "8e36c89e-17a0-4213-8837-93e1c1730dec",
    "validityDate" : "2021-07-26",
    "MCC" : "742",
    "DBI" : "743"
  } ]
}

Allgemeine Datentypen

Neben den Standard JSON-Datentypen gibt es komplexe Datentypen, die für einen ordentlichen Request benötigt werden.

ShippingAddress

Datentyp für Liefer- und Rechnungsadressen.

Feld Typ Eigenschaften Beschreibung

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

09.04.2020

NEW INFO

Informationen über den Standardwert von requestedPreauthorizationValidity ergänzt.

Checkout - Callback Capture - Callback Refund - Callback

09.04.2020

NEW INFO

Dokumentation des Feldes validityDate hinzugefügt.

Report - Transaktionen

08.04.2020

NEW FEATURE

Statusupdates werden nun immer – auch bei wiederholten Versuchen nach Fehlschlägen – in der Reihenfolge versendet, in der die Statusänderungen am Checkout stattgefunden haben. Die Statusupdates enthalten zudem nun einen Timestamp und eine Sequenznummer.

11.12.2019

CHANGE

Limit-Erhöhung für Transaktionsreports

Report - Transaktionen

04.04.2019

CHANGE

Umbenennung Vermittler in Händlerkonzentrator

04.04.2019

NEW INFO

Authentifizierung als Collecting PSP

02.01.2019

CHANGE

Händler bekommen eine explizite Fehlermeldung, falls der Kunde zwischenzeitlich nicht mehr an paydirekt teilnimmt.

Capture - Anlage

12.11.2018

NEW INFO

Dokumentation der in String-Feldern akzeptierten Zeichen

Zeichensatz

31.10.2018

CHANGE

Der Inhalt des Checkout approve Links hat sich verändert.

Checkout - Abfrage

28.08.2018

NEW FEATURE

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

Capture - Order schließen

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

22.12.2017

NEW INFO

Angaben zum Vorhandensein aller Response-Felder

29.11.2017

CHANGE

Der Service zum Abruf von Bankenlogos steht nicht mehr zur Verfügung.

29.11.2017

NEW FEATURE

Versandbedingungen und Rechnungsreferenz können nachträglich geändert werden.

Checkout - Aktualisierung Versandbedingungen Checkout - Aktualisierung Rechnungsreferenz

06.09.2017

NEW FEATURE

Bei der Checkoutanlage kann jetzt das für diesen geltende maximale Refundlimit gesetzt werden.

09.08.2017

NEW FEATURE

Beschreibung der gesicherten Vorbestellung

Express Checkout - Abfrage

04.04.2017

NEW FEATURE

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

22.02.2017

NEW FEATURE

Statusupdates werden bei Fehlschlägen erneut gesendet.

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.

11.01.2017

NEW FEATURE

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

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.

Capture - Anlage Refund - Anlage

30.11.2016

FIX

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

30.11.2016

FIX

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

30.11.2016

NEW FEATURE

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

Refund - Callback

16.11.2016

NEW FEATURE

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

Report Checkout - Abfrage Capture - Abfrage

16.11.2016

NEW INFO

Weitere Angaben zum Format paydirekt-seitig generierter Felder

02.11.2016

NEW FEATURE

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

Checkout - Anlage Capture - Anlage

02.11.2016

NEW FEATURE

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

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

21.09.2016

NEW FEATURE

Neue Felder checkoutId und buyerBankName in den Reports

Checkout - Anlage Checkout - Abfrage Express - Anlage

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.

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

Express Callback - Response

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

13.07.2016

FIX

Fehlende Feldbeschreibungen des Overcapture-Flags

Checkout - Anlage
Express - Anlage

13.07.2016

NEW FEATURE

Warenkorbkennzeichnungen

13.07.2016

NEW FEATURE

Update paydirekt-Express Callback

Express - Callback

13.07.2016

FIX

Fehlende Feldbeschreibungen der Rechnungsnummern im PSP-Report

Capture - Abfrage
Refund - Abfrage

29.06.2016

FIX

paymentInformationId ist keine Liste

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

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

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

20.04.2016

NEW FEATURE

PSP Reports über API