Commercetools – payever

1.) Konto-Konfiguration

Schritt 1: Konto registrieren

Erstellen Sie Ihr kostenloses payever-Konto hier oder loggen Sie sich ein, falls Sie bereits ein Konto haben.

Schritt 2: Zahlungsarten konfigurieren

Um Ihre Zahlungsarten zu konfigurieren, öffnen Sie zunächst die Checkout-App. Klicken Sie dazu entweder in den Business Apps auf das Checkout-Symbol oder auf die Schaltfläche Verwalten oder Öffnen im Bereich Checkout.

Den Reiter Zahlungsarten finden Sie in der Navigationsleiste auf der linken Seite.

Klicken Sie anschließend auf + Hinzufügen.

Es erscheint nun eine Liste verschiedener Zahlungsarten, aus denen Sie nach Bedarf auswählen können. Klicken Sie hierzu auf Installieren.

Sobald Sie den jeweiligen Zahlungskanal installiert haben, klicken Sie auf Öffnen. Es öffnet sich eine neue Seite, deren Aufbau je nach gewählter Zahlungsart unterschiedlich ist.

Bei den Zahlungsarten Kreditkarte, Lastschrift und PayPal klicken Sie einfach auf die Schaltfläche Verbinden. Sie werden dann zum jeweiligen Zahlungsanbieter weitergeleitet. Dort verbinden Sie Ihr bestehendes Konto oder legen ein neues an.

Für die Zahlungsarten Ratenzahlung, Rechnung, Factoring und Direkte Banküberweisung müssen Sie die Zugangsdaten eingeben, die Sie von Santander erhalten haben, und anschließend auf Verbinden klicken (falls Sie bisher keinen Kontakt zu Santander hatten, wenden Sie sich bitte an support@payever.de).

Unabhängig von der Zahlungsart stellen Sie bitte sicher, dass Sie Ihre Zugangsdaten immer im Reiter Standard eintragen.

Screenshot_2022-11-21_at_16.20.06.png Nachdem Sie die Zahlungsarten verbunden haben, können Sie die Einstellungen der jeweiligen Zahlungsart anpassen. Weitere Informationen zu den einzelnen Zahlungsarten finden Sie in der entsprechenden Dokumentation, die Sie hier einsehen können.

Schritt 3: Channels konfigurieren

Wählen Sie in der Checkout-App den Reiter Channels.

Klicken Sie auf + Hinzufügen.

Wählen Sie commercetools aus der nun angezeigten Liste aus und klicken Sie auf Installieren.

Klicken Sie nun auf Öffnen, damit Sie im nächsten Schritt die API-Keys erzeugen können.

Wählen Sie API keys aus und klicken Sie auf + Hinzufügen. Geben Sie einen Namen Ihrer Wahl ein und klicken Sie auf Generieren. Klicken Sie anschließend auf das Plus- Symbol (+), um die Zugangsdaten anzuzeigen, die Sie in die angelegte Verbindung für Ihr Online-Geschäft eintragen müssen (d. h. Client Id, Client secret, Business UUID). Kopieren Sie diese Werte in Ihre Zwischenablage.

Wählen Sie Credentials aus und klicken Sie auf Verbindung hinzufügen (Add Connection). Vergeben Sie erneut einen Namen Ihrer Wahl und tragen Sie Ihren commercetools Project Key, Client Id und Secret ein. Die kopierten Werte Client Id, Secret und Business UUID aus dem vorherigen Schritt können Sie in die entsprechenden payever-Felder einfügen. Wählen Sie Ihre Callback-URLs, um festzulegen, auf welche Seiten Ihre Kunden in bestimmten Zahlungsszenarien zurückgeleitet werden, und bestimmen Sie, wann eine Bestellung in commercetools angelegt werden soll. Klicken Sie anschließend auf Verbinden (Connect), woraufhin Sie Ihre hinzugefügte Verbindung sehen.

2.) Integrationsleitfaden

Um die payever-Gateway-Integration mit commercetools zu nutzen, folgen Sie bitte diesem Integrationsleitfaden, um sicherzustellen, dass Ihre Implementierung und Ihr Prozess wie vorgesehen funktionieren.

Begriffe, die in diesem Leitfaden verwendet werden:

Shopper – eine Person, die den Shop nutzt
Browser – der Frontend-Teil der Checkout-Oberfläche (Webshop)
Merchant-Server – der Backend-Teil des Checkouts

So funktioniert es:

Schritt 1: Erforderliche Checkout-Validierungen ausführen.
Schritt 2: Das commercetools-Payment-Objekt erstellen.
Schritt 3 – optional: Das Custom Field getPaymentMethodsRequest am commercetools-Payment setzen, um die Liste der für den Checkout verfügbaren Zahlungsarten zu erhalten.
Schritt 4: Eine payever-Zahlung erstellen.
Schritt 5: Waren versenden (Shipping goods)
Schritt 6: Eine Zahlung erstatten (Refund)
Schritt 7: Eine Zahlung stornieren
Schritt 8: Subscriptions

Schritt 1: commercetools Checkout-Validierungen

Der Merchant-Server sollte die folgenden Validierungen durchführen:

In jedem Checkout-Schritt den Warenkorb-Status validieren
Bevor ein neuer Zahlungsvorgang gestartet wird, sicherstellen, dass sich im Warenkorb noch keine bezahlten Zahlungen befinden:
- Warenkorb neu berechnen
- Zahlung validieren
- Zahlungstransaktion validieren

Wenn alle oben genannten Validierungen erfolgreich sind, kann die Bestellung sofort erstellt und die Bestätigungsseite angezeigt werden.
Andernfalls kann der Shopper mit weiteren Zahlungsschritten fortfahren.

Warenkorbstatus validieren – Prüfen Sie, ob der aktuelle Warenkorb bereits bestellt wurde (`Cart.cartState = Ordered`).
In diesem Fall laden Sie die Bestellung über die ID des bestellten Warenkorbs und zeigen die Bestellbestätigungsseite an.
Dies kann passieren, wenn der Warenkorb in einem anderen Tab bereits bestellt wurde (Edge Case)
oder durch einen optionalen asynchronen Prozess wie den commercetools-payment-to-order-processor Job.

Warenkorb neu berechnen – Führen Sie eine Warenkorb-Neuberechnung aus, um sicherzustellen:

- dass die Warenkorb-Summen stets aktuell sind
- dass zeitlich befristete Rabatte ggf. entfernt werden (Rabatte werden nur bei der Neuberechnung und bei der Auftragserstellung validiert).

Zahlung validieren – Es muss mindestens ein commercetools-Payment-Objekt vom Typ payever existieren (`Payment.paymentMethodInfo.paymentInterface = ctp-payever-integration`).

Zahlungstransaktion validieren – Eine Warenkorb-Zahlung gilt als erfolgreich, wenn es mindestens ein Payment-Objekt mit einem erfolgreichen Transaktionsstatus (`Payment.Transaction.state = Success`)
und dem Transaktionstyp `Authorization` oder `Charge` gibt.

Schritt 2: Ein commercetools-Payment erstellen

Vor dem eigentlichen Zahlungsvorgang muss das commercetools-Payment-Objekt vom Merchant-Server erstellt werden.

Auf der commercetools-Plattform stellt ein Payment lediglich einen Container für den aktuellen Status von eingehenden und/oder erstatteten Zahlungen dar.
Der eigentliche finanzielle Prozess wird im Hintergrund durch das Extension-Modul ausgeführt, das das vom Merchant-Server übergebene commercetools-Payment verarbeitet und mit der payever API kommuniziert.

Das commercetools Payment enthält standardmäßig nicht alle payever-spezifischen Felder. Diese müssen daher als Custom Fields über einen zahlungsart-spezifischen Payment-Typ gesetzt werden.

Feldname	Wert
amountPlanned	Betrag, den diese Zahlung vom Kunden erhalten soll. Der Wert entspricht in der Regel dem Bruttobetrag des Warenkorbs oder der Bestellung.
paymentMethodInfo.paymentInterface	`ctp-payever-integration`
custom.type.key	`ctp-payever-integration-payment-type`
custom.fields.payeverBusinessUuid	payever Business UUID als Custom Field `payeverBusinessUuid`.
custom.fields.commercetoolsProjectKey	Commercetools-Projekt-Key als Custom Field `commercetoolsProjectKey`

Falls eines der erforderlichen Felder oben fehlt, wird die Zahlungserstellung abgelehnt.

Hier ein Beispiel, wie ein commercetools Payment Draft von Grund auf erstellt wird:

{
  "amountPlanned": {
    "currencyCode": "EUR",
    "centAmount": 10000
  },
  "paymentMethodInfo": {
    "paymentInterface": "ctp-payever-integration"
  },
  "custom": {
    "type": {
      "typeId": "type",
      "key": "ctp-payever-integration-payment-type"
    },
    "fields": {
      "payeverBusinessUuid": "YOUR_PAYEVER_BUSINESS_UUID",
      "commercetoolsProjectKey": "YOUR_COMMERCETOOLS_PROJECT_KEY"
    }
  }
}

{
  "countryCode": "DE",
  "currencyCode": "EUR",
  "amount": 10000
}

Siehe auch die payever-Dokumentation zu List Payment Options, um ein Beispiel der Response zu prüfen.

Nachfolgend ein Beispiel für die commercetools-Payment-Repräsentation mit getPaymentMethodsRequest:

{
  "amountPlanned": {
    "currencyCode": "EUR",
    "centAmount": 10000
  },
  "paymentMethodInfo": {
    "paymentInterface": "ctp-payever-integration"
  },
  "custom": {
    "type": {
      "typeId": "type",
      "key": "ctp-payever-integration-payment-type"
    },
    "fields": {
      "payeverBusinessUuid": "YOUR_PAYEVER_BUSINESS_UUID",
      "commercetoolsProjectKey": "YOUR_COMMERCETOOLS_PROJECT_KEY"
      "getPaymentMethodsRequest": "{\"countryCode\":\"DE\", \"currencyCode\":\"EUR\", \"amount\": 100}"
    }
  }
}

Übergeben Sie den Wert des Custom Fields getPaymentMethodsResponse an Ihr Frontend. Dieses können Sie im nächsten Schritt verwenden, um anzuzeigen, welche Zahlungsarten dem Shopper zur Verfügung stehen.

Beispiel einer commercetools-Payment-Repräsentation mit Response:

{
  "amountPlanned": {
    "currencyCode": "EUR",
    "centAmount": 10000
  },
  "paymentMethodInfo": {
    "paymentInterface": "ctp-payever-integration"
  },
  "custom": {
    "type": {
      "typeId": "type",
      "key": "ctp-payever-integration-payment-type"
    },
    "fields": {
      "payeverBusinessUuid": "YOUR_PAYEVER_BUSINESS_UUID",
      "commercetoolsProjectKey": "YOUR_COMMERCETOOLS_PROJECT_KEY",
      "getPaymentMethodsRequest": "{\"countryCode\":\"DE\", \"currencyCode\":\"EUR\", \"amount\": 100}"
      "getPaymentMethodsResponse": "[{\"name\":\"Credit Card\",\"fixed_fee\":0.25,\"variable_fee\":2.9,\"accept_fee\":true,\"payment_method\":\"stripe\",\"description_offer\":\"Accept all Credit Card payments with Stripe.\",\"description_fee\":\"<p>Credit card fees are only 2.9% + 0.25\u20ac per successful transaction.<\/p>\",\"status\":\"active\",\"is_redirect_method\":false,\"merchant_allowed_countries\":[],\"instruction_text\":\"Simply connect your Stripe and payever accounts, or create a new Stripe account.\",\"thumbnail1\":\"https:\/\/payeverproduction.blob.core.windows.net\/miscellaneous\/456863ab-2a66-4552-bfd7-828dcba8b15d-CARDS.png\",\"thumbnail2\":\"https:\/\/payeverproduction.blob.core.windows.net\/miscellaneous\/456863ab-2a66-4552-bfd7-828dcba8b15d-CARDS.png\",\"options\":{\"currencies\":[\"AUD\",\"CAD\",\"CZK\"],\"countries\":[\"DE\",\"BE\",\"FR\"]},\"max\":100000,\"min\":0.5},{\"name\":\"Stripe DirectDebit\",\"fixed_fee\":0.25,\"variable_fee\":2.9,\"accept_fee\":true,\"payment_method\":\"stripe_directdebit\",\"description_offer\":\"Accept SEPA Direct Debit Payments with Stripe.\",\"description_fee\":\"<p>DirectDebit fees are only 2.9% + 0.25\u20ac per successful transaction.<\/p>\",\"status\":\"active\",\"is_redirect_method\":false,\"merchant_allowed_countries\":[],\"instruction_text\":\"Simply connect your Stripe and payever accounts, or create a new Stripe account.\",\"thumbnail1\":\"https:\/\/payeverproduction.blob.core.windows.net\/miscellaneous\/5a8aa19a-fd16-47df-8fdc-53e9d62af2d2-EC.png\",\"thumbnail2\":\"https:\/\/payeverproduction.blob.core.windows.net\/miscellaneous\/5a8aa19a-fd16-47df-8fdc-53e9d62af2d2-EC.png\",\"options\":{\"currencies\":[\"AUD\",\"CAD\",\"CZK\"],\"countries\":[\"DE\",\"BE\",\"FR\"]},\"max\":100000,\"min\":0}]"
    }
  }
}

Request/Response zwischen payever und dem Extension-Modul werden im Feld interfaceInteraction des Payments mit dem Typ refund gespeichert.

Beispiel einer commercetools-Payment-Repräsentation nach einer erfolgreichen Erstattung (siehe weiter unten).

Schritt 4: Eine payever-Zahlung erstellen

Wenn ein Shopper eine Zahlungsart auswählt, gibt payever eine redirect_url zurück, zu der der Merchant-Server den Kunden umleiten oder die er innerhalb eines iFrames auf seiner Seite öffnen muss, damit der Kunde seine Zahlung dort abschließen kann.

Details finden Sie in der payever API V1 Dokumentation sowie in der payever API V2 Dokumentation.

Um eine Zahlung über unsere Integration zu erstellen, setzen Sie das Custom Field createPaymentRequest am bestehenden commercetools-Payment mit den erforderlichen Parametern.

Wenn Sie noch kein Payment-Objekt haben, sehen Sie im Abschnitt „neues commercetools-Payment erstellen“ nach und setzen Sie das Custom Field createPaymentRequest gemeinsam mit den anderen erforderlichen Feldern.

Voraussetzungen – `payment.amountPlanned` darf nicht geändert werden, wenn bereits eine `createPayment`-Interface-Interaction im commercetools-Payment vorhanden ist. Der Wert `amount` im Custom Field `createPaymentRequest` muss identisch zu `payment.amountPlanned` sein. Dies stellt sicher, dass etwaige spätere Anpassungen des Zahlungsbetrags (z. B. bei Nutzung von my-payments) für eine bereits initiierte Zahlung korrekt behandelt werden.

Wichtig – In diesem Integrationsdokument sind die Beispiele für die payever-Payment-Requests auf das Nötigste gekürzt.
Eine vollständige Liste aller Parameter finden Sie in der payever API V1 Dokumentation und in der payever API V2 Dokumentation.

Hier ein Beispiel für den Wert des Custom Fields createPaymentRequest für die Zahlungsart Santander Rechnung DE:

{
  "amount": 100,
  "fee": 0,
  "order_id": "000001",
  "currency": "EUR",
  "payment_method": "santander_invoice_de",
  "first_name": "Stub",
  "last_name": "Accepted",
  "country": "DE",
  "city": "Berlin",
  "street": "Test 1",
  "email": "test@test.de",
  "phone": "98749874",
  "zip": "12345"
}

Beispiel für eine Payment- setCustomField- Aktion mit den oben generierten Daten.

{
  "version": "PAYMENT_VERSION",
  "actions": [
    {
      "action": "setCustomField",
      "name": "createPaymentRequest",
      "value": "{\"amount\": 100, \"fee\": 0, \"order_id\": \"000001\", \"currency\": \"EUR\", \"payment_method\": \"santander_invoice_de\", \"first_name\" : \"Stub\", \"last_name\" : \"Accepted\", \"country\" : \"DE\", \"city\" : \"berlin\", \"street\" : \"Test 1\" ,  \"email\" : \"test@test.de\", \"phone\" : \"98749874\", \"zip\": \"12345\" }"
    }
  ]
}

Beispiel einer commercetools-Payment-Repräsentation mit createPaymentRequest:

{
  "amountPlanned": {
    "currencyCode": "EUR",
    "centAmount": 10000
  },
  "paymentMethodInfo": {
    "paymentInterface": "ctp-payever-integration"
  },
  "custom": {
    "type": {
      "typeId": "type",
      "key": "ctp-payever-integration-payment-type"
    },
    "fields": {
      "payeverBusinessUuid": "YOUR_PAYEVER_BUSINESS_UUID",
      "commercetoolsProjectKey": "YOUR_COMMERCETOOLS_PROJECT_KEY",
      "createPaymentRequest": "{\"amount\": 100, \"fee\": 0, \"order_id\": \"000001\", \"currency\": \"EUR\", \"payment_method\": \"santander_invoice_de\", \"first_name\" : \"Stub\", \"last_name\" : \"Accepted\", \"country\" : \"DE\", \"city\" : \"berlin\", \"street\" : \"Test 1\" ,  \"email\" : \"test@test.de\", \"phone\" : \"98749874\", \"zip\": \"12345\" }"
    }
  }
}

Die Payment-Response enthält eine Redirect-URL, und die Antwort von payever wird im Custom Field createPaymentResponse gespeichert.
Der Kunde muss über diese redirect_url weitergeleitet werden (oder sie wird in einem iFrame geöffnet), um die Zahlung abzuschließen.

Im Folgenden ein Beispiel eines commercetools-Payments mit gesetztem Feld createPaymentResponse für die oben dargestellte Response.

{
    "amountPlanned": {
      "type": "centPrecision",
      "currencyCode": "EUR",
      "centAmount": 10000,
      "fractionDigits": 2
    },
    "paymentMethodInfo": {
      "paymentInterface": "ctp-payever-integration"
    },
    "custom": {
      "type": {
          "typeId": "type",
          "id": "9798d6a3-13e1-4c4c-a868-7048cffeae8b"
      },
      "fields": {
          "payeverBusinessUuid": "815c5953-6881-11e7-9835-52540073a0b6",
          "commercetoolsProjectKey": "test121",
          "createPaymentV2Request": "{\"amount\": 100, \"fee\": 0, \"order_id\": \"000001\", \"currency\": \"EUR\", \"payment_method\": \"zinia_bnpl_de\", \"cart\": [{\"name\": \"Product name\", \"price\": 100, \"quantity\": 1, \"description\": \"Product description\", \"sku\": \"4550330381882\", \"identifier\": \"4550330381882\"}],\"billing_address\": {\"salutation\": \"mr\", \"first_name\": \"Payever\", \"last_name\": \"Test\", \"street\": \"On Campus 5\", \"zip\": \"48712\", \"country\": \"DE\", \"city\": \"Gescher\"}, \"email\": \"test@test.de\", \"phone\": \"+4940912345678\", \"payment_data\": {\"force_redirect\": true }}",
          "createPaymentResponse": "https://linkup.demo.cf.zinia.com/03c7xxxx-9721-42c1-843d-1905d518732b?documentCountry=DE"
      }
    },
}

Zahlung mit Splits über API v3 erstellen: Siehe payever API V3 Dokumentation

Es besteht die Möglichkeit, Splits zu verwenden, wenn die Zahlung auf mehrere Business-Konten aufgeteilt werden soll.
Hier ein Beispiel für den Wert des Custom Fields createPaymentV3Request für Kreditkarten mit Payment Splits:

{
  "purchase": {
    "amount": 210,
    "currency": "EUR",
    "country": "DE",
    "delivery_fee": 10
  },
  "reference": "000001",
  "payment_issuer": "verifone",
  "payment_method": "credit_card",
  "customer": {
    "type": "person",
    "gender": "male",
    "birthdate": "1990-01-30",
    "phone": "+4940912345678",
    "email": "test@test.com",
    "social_security_number": "12345678"
  },
  "cart": [
    {
      "name": "Product name",
      "unit_price": 100,
      "total_amount": 200,
      "quantity": 2,
      "description": "Product description",
      "sku": "4550330381882",
      "identifier": "4550330381882"
    }
  ],
  "shipping_option": {
    "name": "Free",
    "carrier": "DHL",
    "category": "pickup",
    "price": 0,
    "tax_rate": 0,
    "tax_amount": 0,
    "details": {
      "timeslot": "2023-02-30",
      "pickup_location": {
        "id": "12345",
        "name": "of3",
        "address": {
          "first_name": "Grün",
          "last_name": "Ampel",
          "street": "Test 12",
          "street_number": "12",
          "salutation": "mr",
          "zip": "38889",
          "country": "DE",
          "city": "Elbingerode (Harz)",
          "organization_name": "Test",
          "street_line_2": "Test line 2",
          "street_name": "Test",
          "house_extension": "A"
        }
      }
    }
  },
  "billing_address": {
    "first_name": "Grün",
    "last_name": "Ampel",
    "street": "Test 12",
    "street_number": "12",
    "salutation": "mr",
    "zip": "38889",
    "country": "DE",
    "city": "Elbingerode (Harz)",
    "organization_name": "Test",
    "street_line_2": "Test line 2",
    "street_name": "Test",
    "house_extension": "A"
  },
  "splits": [
    {
      "type": "marketplace",
      "identifier": "{{business_uuid1}}",
      "amount": {
        "value": 150,
        "currency": "EUR"
      },
      "surcharges": {
        "delivery_fee": 10
      },
      "reference": "{{unique-split-reference1}}",
      "description": "{{split_description1}}"
    },
    {
      "type": "marketplace",
      "identifier": "{{business_uuid2}}",
      "amount": {
        "value": 50,
        "currency": "EUR"
      },
      "reference": "{{unique-split-reference2}}",
      "description": "{{split_description2}}"
    }
  ]
}

Wichtig – "purchase.delivery_fee": "10" muss der Summe aller Werte splits.surcharges.delivery_fee entsprechen oder kann ganz weggelassen werden;
"reference": "000001" wird als reference_extra jeder Zahlungssplit verwendet.
"splits.identifier": "{{business_uuid1}}" sind die Business-Account-UUIDs, zwischen denen die Zahlung aufgeteilt werden soll.
"splits.reference": "{{unique-split-reference}}" ist die eindeutige Referenz des Zahlungssplits zur späteren Verwendung bei Capture/Refund/Cancel.

Beispiel einer Payment- setCustomField- Aktion mit den oben dargestellten Daten.

{
  "version": "PAYMENT_VERSION",
  "actions": [
    {
      "action": "setCustomField",
      "name": "createPaymentV3Request",
      "value": "{ \"purchase\": { \"amount\": 210, \"currency\": \"EUR\", \"country\": \"DE\", \"delivery_fee\": 10 }, \"reference\": \"000001\", \"payment_method\": \"zinia_bnpl_de\", \"customer\": { \"type\": \"person\", \"gender\": \"male\", \"birthdate\": \"1990-01-30\", \"phone\": \"+4940912345678\", \"email\": \"test@test.com\", \"social_security_number\": \"12345678\" }, \"cart\": [ { \"name\": \"Product name\", \"unit_price\": 100, \"total_amount\": 200, \"quantity\": 2, \"description\": \"Product description\", \"sku\": \"4550330381882\", \"identifier\": \"4550330381882\" } ], \"shipping_option\": { \"name\": \"Free\", \"carrier\": \"DHL\", \"category\": \"pickup\", \"price\": 0, \"tax_rate\": 0, \"tax_amount\": 0, \"details\": { \"timeslot\": \"2023-02-30\", \"pickup_location\": { \"id\": \"12345\", \"name\": \"of3\", \"address\": { \"first_name\": \"Grün\", \"last_name\": \"Ampel\", \"street\": \"Test 12\", \"street_number\": \"12\", \"salutation\": \"mr\", \"zip\": \"38889\", \"country\": \"DE\", \"city\": \"Elbingerode (Harz)\", \"organization_name\": \"Test\", \"street_line_2\": \"Test line 2\", \"street_name\": \"Test\", \"house_extension\": \"A\" } } } }, \"billing_address\": { \"first_name\": \"Grün\", \"last_name\": \"Ampel\", \"street\": \"Test 12\", \"street_number\": \"12\", \"salutation\": \"mr\", \"zip\": \"38889\", \"country\": \"DE\", \"city\": \"Elbingerode (Harz)\", \"organization_name\": \"Test\", \"street_line_2\": \"Test line 2\", \"street_name\": \"Test\", \"house_extension\": \"A\" },\"splits\": [{\"type\": \"marketplace\",\"identifier\": \"{{business_uuid1}}\",\"amount\": {\"value\": 150,\"currency\": \"EUR\"},\"reference\": \"{{unique-split-reference1}}\",\"description\": \"{{split_description1}}\"},{\"type\": \"marketplace\",\"identifier\": \"{{business_uuid2}}\",\"amount\": {\"value\": 50,\"currency\": \"EUR\"},\"reference\": \"{{unique-split-reference2}}\",\"description\": \"{{split_description2}}\"}]}"
    }
  ]
}

Beispiel einer commercetools-Payment-Repräsentation mit createPaymentV3Request:

{
  "amountPlanned": {
    "currencyCode": "EUR",
    "centAmount": 21000
  },
  "paymentMethodInfo": {
    "paymentInterface": "ctp-payever-integration"
  },
  "custom": {
    "type": {
      "typeId": "type",
      "key": "ctp-payever-integration-payment-type"
    },
    "fields": {
      "payeverBusinessUuid": "{{business_uuid1}}",
      "commercetoolsProjectKey": "YOUR_COMMERCETOOLS_PROJECT_KEY",
      "createPaymentV3Request": "{ \"purchase\": { \"amount\": 210, \"currency\": \"EUR\", \"country\": \"DE\", \"delivery_fee\": 10 }, \"reference\": \"000001\", \"payment_method\": \"zinia_bnpl_de\", \"customer\": { \"type\": \"person\", \"gender\": \"male\", \"birthdate\": \"1990-01-30\", \"phone\": \"+4940912345678\", \"email\": \"test@test.com\", \"social_security_number\": \"12345678\" }, \"cart\": [ { \"name\": \"Product name\", \"unit_price\": 100, \"total_amount\": 200, \"quantity\": 2, \"description\": \"Product description\", \"sku\": \"4550330381882\", \"identifier\": \"4550330381882\" } ], \"shipping_option\": { \"name\": \"Free\", \"carrier\": \"DHL\", \"category\": \"pickup\", \"price\": 0, \"tax_rate\": 0, \"tax_amount\": 0, \"details\": { \"timeslot\": \"2023-02-30\", \"pickup_location\": { \"id\": \"12345\", \"name\": \"of3\", \"address\": { \"first_name\": \"Grün\", \"last_name\": \"Ampel\", \"street\": \"Test 12\", \"street_number\": \"12\", \"salutation\": \"mr\", \"zip\": \"38889\", \"country\": \"DE\", \"city\": \"Elbingerode (Harz)\", \"organization_name\": \"Test\", \"street_line_2\": \"Test line 2\", \"street_name\": \"Test\", \"house_extension\": \"A\" } } } }, \"billing_address\": { \"first_name\": \"Grün\", \"last_name\": \"Ampel\", \"street\": \"Test 12\", \"street_number\": \"12\", \"salutation\": \"mr\", \"zip\": \"38889\", \"country\": \"DE\", \"city\": \"Elbingerode (Harz)\", \"organization_name\": \"Test\", \"street_line_2\": \"Test line 2\", \"street_name\": \"Test\", \"house_extension\": \"A\" },\"splits\": [{\"type\": \"marketplace\",\"identifier\": \"{{business_uuid1}}\",\"amount\": {\"value\": 150,\"currency\": \"EUR\"},\"reference\": \"{{unique-split-reference1}}\",\"description\": \"{{split_description1}}\"},{\"type\": \"marketplace\",\"identifier\": \"{{business_uuid2}}\",\"amount\": {\"value\": 50,\"currency\": \"EUR\"},\"reference\": \"{{unique-split-reference2}}\",\"description\": \"{{split_description2}}\"}]}"
    }
  }
}

Response:

Ein Beispiel für ein commercetools-Payment mit Feld createPaymentResponse. (Details siehe Originaldokumentation.)

Die oben gezeigte commercetools-Payment-Repräsentation mit createPaymentV3Request ist damit vollständig.

Schritt 5: Waren versenden (Shipping goods)

Manuelles Versenden der Waren

Für Zahlungsarten, die eine getrennte Autorisierung und Belastung (Capture) unterstützen, können Sie die Zahlung auch zu einem späteren Zeitpunkt erfassen – etwa erst dann, wenn die Ware tatsächlich versendet wurde. Dies ermöglicht Ihnen, die Zahlung bzw. Autorisierung bei Bedarf auch zu stornieren.

API-Aufruf zum Erfassen einer Zahlung (Shipping goods):

Um eine Zahlung manuell zu erfassen, fügen Sie eine Transaktion mit dem Typ Charge und dem Status Initial zum commercetools-Payment hinzu.

{
  "action": "addTransaction",
  "transaction": {
    "type": "Charge",
    "amount": {
      "currencyCode": "EUR",
      "centAmount": 1000
    },
    "state": "Initial"
  }
}

Das Extension-Modul aktualisiert diese Transaktion mit dem Transaktionsstatus Success und dem Feld interactionId, das die Payment-ID aus der payever-Response enthält:

{
  "id": "a2904b53-d79a-484e-8954-ee4c3b6de1a2",
  "type": "Charge",
  "amount": {
    "type": "centPrecision",
    "currencyCode": "EUR",
    "centAmount": 1000,
    "fractionDigits": 2
  },
  "interactionId": "79bd18b5-6531-499b-a6df-4e841ad80b50",
  "state": "Success"
}

Request und Response zwischen payever und dem Extension-Modul werden im Feld interfaceInteraction des Payments mit dem Typ shippingGoodsPayment gespeichert. Die commercetools-Payment- Repräsentation nach einem erfolgreichen Shipping-goods-Aufruf sieht beispielsweise so aus:

{
  "transactions": [
    {
      "id": "f91e1fd9-cf08-41f8-9785-ed4b76658e39",
      "type": "Authorization",
      "amount": {
        "type": "centPrecision",
        "currencyCode": "EUR",
        "centAmount": 1000,
        "fractionDigits": 2
      },
      "interactionId": "79bd18b5-6531-499b-a6df-4e841ad80b50",
      "state": "Success"
    },
    {
      "id": "a2904b53-d79a-484e-8954-ee4c3b6de1a2",
      "type": "Charge",
      "amount": {
        "type": "centPrecision",
        "currencyCode": "EUR",
        "centAmount": 1000,
        "fractionDigits": 2
      },
      "interactionId": "79bd18b5-6531-499b-a6df-4e841ad80b50",
      "state": "Success"
    }
  ],
  "interfaceInteractions": [
    {
      "type": {
        "typeId": "type",
        "id": "e6a36f88-58a4-46f5-998b-214973b0427b"
      },
      "fields": {
        "type": "shippingGoodsPayment",
        "request":"{\"paymentId\":\"e6a36f88-58a4-46f5-998b-214973b0427b\",\"amount\":\"10\"}",
        "response":"{\"id\":\"e6a36f88-58a4-46f5-998b-214973b0427b\",\"status\":\"STATUS_PAID\",\"specific_status\":\"ORDER_SHIPPED\",\"merchant_name\":\"ANWR Media GmbH\",\"customer_name\":\"Thu Nguyen\",\"payment_type\":\"zinia_bnpl_de\",\"customer_email\":\"ndtthu@gmail.com\",\"created_at\":\"2023-06-16T07:09:32.000Z\",\"updated_at\":\"2023-06-16T07:16:33.000Z\",\"channel\":\"commercetools\",\"channel_type\":null,\"channel_source\":null,\"reference\":\"2f80c7e2\",\"amount\":10.00,\"total\":10.00,\"currency\":\"EUR\",\"delivery_fee\":0,\"payment_fee\":0,\"down_payment\":0,\"payment_details\":{\"birthday\":null,\"order_id\":\"0946b9f4-4ac5-470e-963d-8504c7ef8faf\",\"otp_id\":null,\"redirect_url\":\"https://linkup.demo.cf.zinia.com/0946b9f4-4ac5-470e-963d-8504c7ef8faf?documentCountry=DE\",\"expiration_time\":\"2023-06-16T07:19:33.633Z\",\"advertising_accepted\":true,\"conditions_accepted\":true,\"finalize_unique_id\":\"0946b9f4-4ac5-470e-963d-8504c7ef8faf\",\"receipt_unique_id\":null,\"reservation_unique_id\":\"0946b9f4-4ac5-470e-963d-8504c7ef8faf\",\"usage_text\":\"\",\"shop_user_session\":null},\"payment_details_array\":{\"birthday\":null,\"order_id\":\"0946b9f4-4ac5-470e-963d-8504c7ef8faf\",\"otp_id\":null,\"redirect_url\":\"https://linkup.demo.cf.zinia.com/0946b9f4-4ac5-470e-963d-8504c7ef8faf?documentCountry=DE\",\"expiration_time\":\"2023-06-16T07:19:33.633Z\",\"advertising_accepted\":true,\"conditions_accepted\":true,\"finalize_unique_id\":\"0946b9f4-4ac5-470e-963d-8504c7ef8faf\",\"receipt_unique_id\":null,\"reservation_unique_id\":\"0946b9f4-4ac5-470e-963d-8504c7ef8faf\",\"usage_text\":\"\",\"shop_user_session\":null},\"address\":{\"city\":\"Gescher\",\"country\":\"DE\",\"country_name\":\"DE\",\"email\":\"ndtthu@gmail.com\",\"first_name\":\"Thu\",\"last_name\":\"Nguyen\",\"phone\":\"+4915212341234\",\"salutation\":\"\",\"street\":\"On Campus 5\",\"zip_code\":\"48712\"},\"shipping_address\":{\"city\":\"Gescher\",\"country\":\"DE\",\"country_name\":\"DE\",\"first_name\":\"Thu\",\"last_name\":\"Nguyen\",\"salutation\":\"\",\"street\":\"On Campus 5\",\"zip_code\":\"48712\"}}",
        "createdAt": "2023-06-23T14:22:02.668Z"
      }
    }
  ]
}

Shipping-goods-Anfragen erneut senden (Retry)

Um Shipping-goods-Anfragen im Fehlerfall erneut senden zu können, fügen Sie dem Custom Type mit dem Schlüssel ctp-payever-integration-transaction-payment-type ein Transaktions-Custom-Field mit dem Schlüssel idempotencyKey hinzu. Die addTransaction-Aktion sieht dann wie folgt aus:

{
  "action": "addTransaction",
  "transaction": {
    "type": "Charge",
    "amount": {
      "currencyCode": "EUR",
      "centAmount": 500
    },
    "state": "Initial",
    "custom": {
      "type": {
        "typeId": "type",
        "key": "ctp-payever-integration-transaction-payment-type"
      },
      "fields": {
        "idempotencyKey": "your-unique-idempotency-key"
      }
    }
  }
}

Wenn kein Custom Field idempotencyKey gesetzt ist, wird standardmäßig die Transaktions-ID als Idempotency Key verwendet.

Beachten Sie folgende Empfehlungen bei der Verwendung des Idempotency Keys:

idempotencyKey muss pro Anfrage eindeutig sein, damit eine fehlgeschlagene Anfrage mit demselben Schlüssel erneut durchgeführt werden kann.
Generieren Sie Idempotency Keys mit UUID Version 4 (random), damit nicht zwei API-Credentials innerhalb desselben Accounts auf die Responses des jeweils anderen zugreifen können.
Verwenden Sie beim Wiederholen von Requests Exponentielles Backoff.

Benutzerdefinierte Referenz für manuelles Shipping goods

Wenn Sie den Referenzwert für das manuelle Erfassen (Shipping goods) anpassen möchten, fügen Sie ein Transaktions-Custom-Field mit dem Schlüssel reference zum Custom Type ctp-payever-integration-transaction-payment-type hinzu. Die addTransaction-Aktion sieht dann wie folgt aus:

{
  "action": "addTransaction",
  "transaction": {
    "type": "Charge",
    "amount": {
      "currencyCode": "EUR",
      "centAmount": 500
    },
    "state": "Initial",
    "custom": {
      "type": {
        "typeId": "type",
        "key": "ctp-payever-integration-transaction-payment-type"
      },
      "fields": {
        "reference": "your-custom-manual-capture-reference"
      }
    }
  }
}

Shipping-goods-Anfragen für Payment Splits

Um eine Shipping-goods-Anfrage für eine Zahlung auszulösen, die mit Splits erstellt wurde, fügen Sie ein Transaktions-Custom-Field mit dem Schlüssel splitReference zum Custom Type ctp-payever-integration-transaction-payment-type hinzu. Die addTransaction-Aktion sieht dann wie folgt aus:

{
  "action": "addTransaction",
  "transaction": {
    "type": "Charge",
    "amount": {
      "currencyCode": "EUR",
      "centAmount": 16000
    },
    "state": "Initial",
    "custom": {
      "type": {
        "typeId": "type",
        "key": "ctp-payever-integration-transaction-payment-type"
      },
      "fields": {
        "splitReference": {{unique-split-reference1}}
      }
    }
  }
}

Beachten Sie dabei:

splitReference muss identisch zu einem der in createPaymentV3Request gesendeten Split-Referenzen sein.

Weitere Informationen zu Shipping goods

Aus Sicht von payever finden Sie weitere Details in folgender Dokumentation:

Schritt 6: Erstattung (Refund)

Erstattung

Wenn Sie Ihrem Shopper Gelder zurückzahlen möchten, z. B. weil er einen Artikel zurückgesendet hat, müssen Sie eine Refund-Anfrage durchführen.

API-Aufruf zum Erstatten einer Zahlung

Voraussetzungen

Es ist erforderlich, dass das Payment eine Transaktion mit Typ Authorization und Status Success besitzt.
Aus dieser autorisierten Transaktion wird das Feld interactionId als paymentId für die payever-Refund-Anfrage verwendet.

Schritte

Um eine (teilweise) Erstattung durchzuführen, fügen Sie mindestens eine Transaktion mit Typ Refund und Status Initial zum commercetools-Payment hinzu.
Es ist möglich, mehrere Refund-Transaktionen hinzuzufügen – alle werden parallel verarbeitet.

{
  "action": "addTransaction",
  "transaction": {
    "type": "Refund",
    "amount": {
      "currencyCode": "EUR",
      "centAmount": 1000
    },
    "state": "Initial"
  }
}

Das Extension-Modul aktualisiert die Transaktion mit dem Status Success und dem Feld interactionId, das die Payment-ID aus der payever-Response enthält:

{
  "id": "a4504b99-d46e-484e-1344-ee4c3b6de1a2",
  "type": "Refund",
  "amount": {
    "type": "centPrecision",
    "currencyCode": "EUR",
    "centAmount": 1000,
    "fractionDigits": 2
  },
  "interactionId": "77bd18b5-6531-499b-a6df-4e841ad80b50",
  "state": "Pending"
}

Request/Response zwischen payever und dem Extension-Modul werden im Feld interfaceInteraction des Payments mit dem Typ refund gespeichert.

Die commercetools-Payment-Repräsentation nach einer erfolgreichen Erstattung könnte zum Beispiel so aussehen:

{
  "id": "ca068e31-c2f1-410a-912d-d12bf3c645b2",
  "key": "14",
  "amountPlanned": {
    "type": "centPrecision",
    "currencyCode": "EUR",
    "centAmount": 1000,
    "fractionDigits": 2
  },
  "paymentMethodInfo": {
    "paymentInterface": "ctp-payever-integration"
  },
  "transactions": [
    {
      "id": "98d62c56-9a72-4b96-8cb7-f9fe68181085",
      "type": "Authorization",
      "amount": {
        "type": "centPrecision",
        "currencyCode": "EUR",
        "centAmount": 1000,
        "fractionDigits": 2
      },
      "interactionId": "77bd18b5-6531-499b-a6df-4e841ad80b50",
      "state": "Success"
    },
    {
      "id": "5d3e8fc1-bdb7-4e34-b3e9-8b34c3f60135",
      "type": "Refund",
      "amount": {
        "type": "centPrecision",
        "currencyCode": "EUR",
        "centAmount": 1000,
        "fractionDigits": 2
      },
      "interactionId": "77bd18b5-6531-499b-a6df-4e841ad80b50",
      "state": "Success"
    }
  ],
  "interfaceInteractions": [
    {
      "type": {
        "typeId": "type",
        "id": "5d93411a-9736-43ba-9f4d-5f14158427ba"
      },
      "fields": {
        "createdAt": "2023-06-19T16:17:14.247Z",
        "request": "{\"paymentId\":\"77bd18b5-6531-499b-a6df-4e841ad80b50\",\"amount\":\"10\"}",
        "response":"{\"id\":\"77bd18b5-6531-499b-a6df-4e841ad80b50\",\"status\":\"STATUS_REFUNDED\",\"merchant_name\":\"ANWR Media GmbH\",\"customer_name\":\"Thu Nguyen\",\"payment_type\":\"zinia_bnpl_de\",\"customer_email\":\"ndtthu@gmail.com\",\"created_at\":\"2023-06-16T07:09:32.000Z\",\"updated_at\":\"2023-06-16T07:16:33.000Z\",\"channel\":\"commercetools\",\"channel_type\":null,\"channel_source\":null,\"reference\":\"2f80c7e2\",\"amount\":10.00,\"total\":10.00,\"currency\":\"EUR\",\"delivery_fee\":0,\"payment_fee\":0,\"down_payment\":0,\"payment_details\":{\"birthday\":null,\"order_id\":\"0946b9f4-4ac5-470e-963d-8504c7ef8faf\",\"otp_id\":null,\"redirect_url\":\"https://linkup.demo.cf.zinia.com/0946b9f4-4ac5-470e-963d-8504c7ef8faf?documentCountry=DE\",\"expiration_time\":\"2023-06-16T07:19:33.633Z\",\"advertising_accepted\":true,\"conditions_accepted\":true,\"finalize_unique_id\":\"0946b9f4-4ac5-470e-963d-8504c7ef8faf\",\"receipt_unique_id\":null,\"reservation_unique_id\":\"0946b9f4-4ac5-470e-963d-8504c7ef8faf\",\"usage_text\":\"\",\"shop_user_session\":null},\"payment_details_array\":{\"birthday\":null,\"order_id\":\"0946b9f4-4ac5-470e-963d-8504c7ef8faf\",\"otp_id\":null,\"redirect_url\":\"https://linkup.demo.cf.zinia.com/0946b9f4-4ac5-470e-963d-8504c7ef8faf?documentCountry=DE\",\"expiration_time\":\"2023-06-16T07:19:33.633Z\",\"advertising_accepted\":true,\"conditions_accepted\":true,\"finalize_unique_id\":\"0946b9f4-4ac5-470e-963d-8504c7ef8faf\",\"receipt_unique_id\":null,\"reservation_unique_id\":\"0946b9f4-4ac5-470e-963d-8504c7ef8faf\",\"usage_text\":\"\",\"shop_user_session\":null},\"address\":{\"city\":\"Gescher\",\"country\":\"DE\",\"country_name\":\"DE\",\"email\":\"ndtthu@gmail.com\",\"first_name\":\"Thu\",\"last_name\":\"Nguyen\",\"phone\":\"+4915212341234\",\"salutation\":\"\",\"street\":\"On Campus 5\",\"zip_code\":\"48712\"},\"shipping_address\":{\"city\":\"Gescher\",\"country\":\"DE\",\"country_name\":\"DE\",\"first_name\":\"Thu\",\"last_name\":\"Nguyen\",\"salutation\":\"\",\"street\":\"On Campus 5\",\"zip_code\":\"48712\"}}",
        "type": "refundPayment"
      }
    }
  ]
}

Refund-Anfragen erneut senden (Retry)

Um Refund-Anfragen im Fehlerfall erneut senden zu können, fügen Sie ein Transaktions-Custom-Field mit dem Schlüssel idempotencyKey zum Custom Type ctp-payever-integration-transaction-payment-type hinzu. Die addTransaction-Aktion sieht dann wie folgt aus:

{
  "action": "addTransaction",
  "transaction": {
    "type": "Refund",
    "amount": {
      "currencyCode": "EUR",
      "centAmount": 500
    },
    "state": "Initial",
    "custom": {
      "type": {
        "typeId": "type",
        "key": "ctp-payever-integration-transaction-payment-type"
      },
      "fields": {
        "idempotencyKey": "your-unique-idempotency-key"
      }
    }
  }
}

Benutzerdefinierte Refund-Referenz

Standardmäßig wird die Refund-Referenz aus der interactionId der Autorisierungstransaktion entnommen. Wenn Sie diesen Wert anpassen möchten, fügen Sie ein Transaktions-Custom-Field mit dem Schlüssel reference zum Custom Type ctp-payever-integration-transaction-payment-type hinzu. Die addTransaction-Aktion sieht dann wie folgt aus:

{
  "action": "addTransaction",
  "transaction": {
    "type": "Refund",
    "amount": {
      "currencyCode": "EUR",
      "centAmount": 500
    },
    "state": "Initial",
    "custom": {
      "type": {
        "typeId": "type",
        "key": "ctp-payever-integration-transaction-payment-type"
      },
      "fields": {
        "reference": "your-custom-refund-reference"
      }
    }
  }
}

Wenn kein Custom Field mit Schlüssel idempotencyKey angegeben ist, wird standardmäßig die Transaktions-ID als Idempotency Key verwendet.

Beachten Sie folgende Hinweise zur Nutzung des Idempotency Keys:

idempotencyKey muss pro Anfrage eindeutig sein, damit eine fehlgeschlagene Anfrage mit demselben Schlüssel erneut durchgeführt werden kann.
Generieren Sie Idempotency Keys mit UUID Version 4 (random), um zu verhindern, dass zwei API-Credentials im selben Account auf die Antworten des jeweils anderen zugreifen.
Verwenden Sie Exponentielles Backoff beim erneuten Senden.

Refund-Anfragen für Payment Splits

Um eine Refund-Anfrage für eine Zahlung auszulösen, die mit Splits erstellt wurde, fügen Sie ein Transaktions-Custom-Field mit dem Schlüssel splitReference zum Custom Type ctp-payever-integration-transaction-payment-type hinzu. Die addTransaction-Aktion sieht dann wie folgt aus:

{
  "action": "addTransaction",
  "transaction": {
    "type": "Refund",
    "amount": {
      "currencyCode": "EUR",
      "centAmount": 16000
    },
    "state": "Initial",
    "custom": {
      "type": {
        "typeId": "type",
        "key": "ctp-payever-integration-transaction-payment-type"
      },
      "fields": {
        "splitReference": {{unique-split-reference1}}
      }
    }
  }
}

Beachten Sie dabei:

splitReference muss identisch zu einem der in createPaymentV3Request gesendeten Split-Referenzen sein.

Zusätzliche Informationen

Fügen Sie nicht zu viele Refund-Transaktionen gleichzeitig hinzu, da der API-Extension-Endpunkt ein Zeitlimit hat. Wenn zu viele Transaktionen auf einmal hinzugefügt werden, benötigt das Extension-Modul mehr Zeit zur Verarbeitung, was zu langen Requests und einem Überschreiten des Zeitlimits führen kann.

Weitere Ressourcen: payever Refund API

Schritt 7: Eine Zahlung stornieren

Zahlung stornieren

Wenn Sie eine Zahlung autorisiert haben, diese aber nicht erfassen möchten, müssen Sie eine Cancel-Anfrage durchführen, um die Gelder wieder für den Shopper freizugeben.
Wenn die Zahlung bereits erfasst wurde, müssen Sie sie stattdessen erstatten.

API-Aufruf zum Stornieren einer Zahlung.

Voraussetzungen:

Es ist erforderlich, dass das Payment eine Transaktion vom Typ Authorization mit Status Success besitzt.
Aus dieser Transaktion wird das Feld interactionId als paymentId für die payever-Cancel-Anfrage verwendet.

Schritte

Um eine Stornierung durchzuführen, fügen Sie eine Transaktion mit Typ CancelAuthorization und Status Initial zum commercetools-Payment hinzu.

{
  "action": "addTransaction",
  "transaction": {
    "type": "CancelAuthorization",
    "amount": {
      "currencyCode": "EUR",
      "centAmount": 1000
    },
    "state": "Initial"
  }
}

Das Extension-Modul aktualisiert die Transaktion mit Status Success und dem Feld interactionId, das die paymentId aus der payever-Response enthält:

{
  "id": "a4504b99-d46e-484e-1344-ee4c3b6de1a2",
  "type": "CancelAuthorization",
  "amount": {
    "type": "centPrecision",
    "currencyCode": "EUR",
    "centAmount": 1000,
    "fractionDigits": 2
  },
  "interactionId": "0946b9f4-4ac5-470e-963d-8504c7ef8faf",
  "state": "Success"
}

Request/Response zwischen payever und dem Extension-Modul werden im Feld interfaceInteraction des Payments mit Typ cancelPayment gespeichert.
Eine beispielhafte commercetools-Payment-Repräsentation nach erfolgreicher CancelAuthorization-Anfrage:

{
  "id": "ca068e31-c2f1-410a-912d-d12bf3c645b2",
  "key": "14",
  "amountPlanned": {
    "type": "centPrecision",
    "currencyCode": "EUR",
    "centAmount": 1000,
    "fractionDigits": 2
  },
  "paymentMethodInfo": {
    "paymentInterface": "ctp-payever-integration"
  },
  "transactions": [
    {
      "id": "98d62c56-9a72-4b96-8cb7-f9fe68181085",
      "type": "Authorization",
      "amount": {
        "type": "centPrecision",
        "currencyCode": "EUR",
        "centAmount": 1000,
        "fractionDigits": 2
      },
      "interactionId": "0946b9f4-4ac5-470e-963d-8504c7ef8faf",
      "state": "Success"
    },
    {
      "id": "5d3e8fc1-bdb7-4e34-b3e9-8b34c3f60135",
      "type": "CancelAuthorization",
      "amount": {
        "type": "centPrecision",
        "currencyCode": "EUR",
        "centAmount": 1000,
        "fractionDigits": 2
      },
      "interactionId": "0946b9f4-4ac5-470e-963d-8504c7ef8faf",
      "state": "Success"
    }
  ],
  "interfaceInteractions": [
    {
      "type": {
        "typeId": "type",
        "id": "5d93411a-9736-43ba-9f4d-5f14158427ba"
      },
      "fields": {
        "createdAt": "2020-11-19T16:17:14.247Z",
        "request": "{\"paymentId\":\"0946b9f4-4ac5-470e-963d-8504c7ef8faf\",\"amount\":\"10\"}",
        "response":"{\"id\":\"0946b9f4-4ac5-470e-963d-8504c7ef8faf\",\"status\":\"STATUS_CANCELLED\",\"merchant_name\":\"ANWR Media GmbH\",\"customer_name\":\"Thu Nguyen\",\"payment_type\":\"zinia_bnpl_de\",\"customer_email\":\"ndtthu@gmail.com\",\"created_at\":\"2023-06-16T07:09:32.000Z\",\"updated_at\":\"2023-06-16T07:16:33.000Z\",\"channel\":\"commercetools\",\"channel_type\":null\",\"channel_source\":null,\"reference\":\"2f80c7e2\",\"amount\":10.00,\"total\":10.00,\"currency\":\"EUR\",\"delivery_fee\":0,\"payment_fee\":0,\"down_payment\":0,\"payment_details\":{\"birthday\":null,\"order_id\":\"0946b9f4-4ac5-470e-963d-8504c7ef8faf\",\"otp_id\":null,\"redirect_url\":\"https://linkup.demo.cf.zinia.com/0946b9f4-4ac5-470e-963d-8504c7ef8faf?documentCountry=DE\",\"expiration_time\":\"2023-06-16T07:19:33.633Z\",\"advertising_accepted\":true,\"conditions_accepted\":true,\"finalize_unique_id\":\"0946b9f4-4ac5-470e-963d-8504c7ef8faf\",\"receipt_unique_id\":null,\"reservation_unique_id\":\"0946b9f4-4ac5-470e-963d-8504c7ef8faf\",\"usage_text\":\"\",\"shop_user_session\":null},\"payment_details_array\":{\"birthday\":null,\"order_id\":\"0946b9f4-4ac5-470e-963d-8504c7ef8faf\",\"otp_id\":null,\"redirect_url\":\"https://linkup.demo.cf.zinia.com/0946b9f4-4ac5-470e-963d-8504c7ef8faf?documentCountry=DE\",\"expiration_time\":\"2023-06-16T07:19:33.633Z\",\"advertising_accepted\":true,\"conditions_accepted\":true,\"finalize_unique_id\":\"0946b9f4-4ac5-470e-963d-8504c7ef8faf\",\"receipt_unique_id\":null,\"reservation_unique_id\":\"0946b9f4-4ac5-470e-963d-8504c7ef8faf\",\"usage_text\":\"\",\"shop_user_session\":null},\"address\":{\"city\":\"Gescher\",\"country\":\"DE\",\"country_name\":\"DE\",\"email\":\"ndtthu@gmail.com\",\"first_name\":\"Thu\",\"last_name\":\"Nguyen\",\"phone\":\"+4915212341234\",\"salutation\":\"\",\"street\":\"On Campus 5\",\"zip_code\":\"48712\"},\"shipping_address\":{\"city\":\"Gescher\",\"country\":\"DE\",\"country_name\":\"DE\",\"first_name\":\"Thu\",\"last_name\":\"Nguyen\",\"salutation\":\"\",\"street\":\"On Campus 5\",\"zip_code\":\"48712\"}}",
        "type": "cancelPayment"
      }
    }
  ]
}

Cancel-Anfragen erneut senden (Retry)

Um Cancel-Anfragen im Fehlerfall erneut senden zu können, fügen Sie ein Transaktions-Custom-Field mit dem Schlüssel idempotencyKey zum Custom Type ctp-payever-integration-transaction-payment-type hinzu. Die addTransaction-Aktion sieht dann wie folgt aus:

{
  "action": "addTransaction",
  "transaction": {
    "type": "CancelAuthorization",
    "amount": {
      "currencyCode": "EUR",
      "centAmount": 500
    },
    "state": "Initial",
    "custom": {
      "type": {
        "typeId": "type",
        "key": "ctp-payever-integration-transaction-payment-type"
      },
      "fields": {
        "idempotencyKey": "your-unique-idempotency-key"
      }
    }
  }
}

Benutzerdefinierte Cancel-Referenz

Standardmäßig wird die Cancel-Referenz aus der interactionId der Autorisierungstransaktion entnommen. Wenn Sie diesen Wert anpassen möchten, fügen Sie ein Transaktions- Custom-Field mit dem Schlüssel reference zum Custom Type ctp-payever-integration-transaction-payment-type hinzu. Die addTransaction-Aktion sieht dann wie folgt aus:

{
  "action": "addTransaction",
  "transaction": {
    "type": "CancelAuthorization",
    "amount": {
      "currencyCode": "EUR",
      "centAmount": 500
    },
    "state": "Initial",
    "custom": {
      "type": {
        "typeId": "type",
        "key": "ctp-payever-integration-transaction-payment-type"
      },
      "fields": {
        "reference": "your-custom-cancel-reference"
      }
    }
  }
}

Wenn kein Custom Field idempotencyKey gesetzt ist, wird standardmäßig die Transaktions-ID als Idempotency Key verwendet.

Beachten Sie dabei:

idempotencyKey muss für jede Anfrage eindeutig sein, damit eine fehlgeschlagene Anfrage mit demselben Schlüssel sicher erneut durchgeführt werden kann.
Generieren Sie Idempotency Keys mit UUID Version 4 (random), um zu verhindern, dass zwei API-Credentials im selben Account auf die Antworten des jeweils anderen zugreifen.
Verwenden Sie Exponentielles Backoff beim erneuten Senden.

Cancel-Anfragen für Payment Splits

Um eine Cancel-Anfrage für eine Zahlung auszulösen, die mit Splits erstellt wurde, fügen Sie ein Transaktions-Custom-Field mit dem Schlüssel splitReference zum Custom Type ctp-payever-integration-transaction-payment-type hinzu. Die addTransaction-Aktion sieht dann wie folgt aus:

{
  "action": "addTransaction",
  "transaction": {
    "type": "CancelAuthorization",
    "amount": {
      "currencyCode": "EUR",
      "centAmount": 16000
    },
    "state": "Initial",
    "custom": {
      "type": {
        "typeId": "type",
        "key": "ctp-payever-integration-transaction-payment-type"
      },
      "fields": {
        "splitReference": {{unique-split-reference1}}
      }
    }
  }
}

Beachten Sie dabei:

splitReference muss identisch zu einem der in createPaymentV3Request verwendeten Split-Referenzen sein.

Weitere Ressourcen: payever Cancel Dokumentation

Metadaten für commercetools-Transaktionen

Um einer commercetools-Transaktion zusätzliche Details hinzuzufügen, fügen Sie ein Transaktions-Custom-Field mit dem Schlüssel metadata für eine Transaktion mit dem Custom Type ctp-payever-integration-transaction-payment-type hinzu. Die addTransaction-Aktion sieht dann wie folgt aus:

{
  "action": "addTransaction",
  "transaction": {
    "type": "Charge",
    "amount": {
      "currencyCode": "EUR",
      "centAmount": 500
    },
    "state": "Initial",
    "custom": {
      "type": {
        "typeId": "type",
        "key": "ctp-payever-integration-transaction-payment-type"
      },
      "fields": {
        "metadata": "your-additional-payment-details-json"
      }
    }
  }
}

Schritt 8: Subscriptions

Unsere Integration verwendet Subscriptions für Messages und Benachrichtigungen. Subscriptions werden verwendet, um als Reaktion auf ein Ereignis in commercetools Composable Commerce einen asynchronen Hintergrundprozess auszulösen.

Um Subscriptions zu aktivieren, empfehlen wir, im Projekt die Messages zu aktivieren (Settings -> Developer settings -> Project messages). Unsere Integration verfügt bereits über eine Subscription mit Azure Service Bus und ist auf diese drei Order-Messages abonniert:

Order Shipment State Changed – wird ausgelöst, um eine payever-Zahlung zu erfassen (Capture)
Return Info Added – wird ausgelöst, um die payever-Zahlung zu erstatten;
Order State Changed – wird ausgelöst, um die payever-Zahlung zu stornieren;

Eine payever-Zahlung erfassen

Um eine Zahlung vollständig (oder den verbleibenden Betrag) zu erfassen, gehen Sie im Merchant Center von commercetools auf die Bestellseite und ändern den Shipment-Status auf „Shipped“ oder „Delivered“.

Die payever-Zahlung erstatten

Wenn Sie dem Shopper Gelder zurückzahlen möchten, z. B. bei einer Retoure, öffnen Sie im Merchant Center von commercetools die Bestellseite > „Returns“ und erstellen Sie eine Rücksendung. Wählen Sie die Anzahl der Artikel, die zurückgegeben werden sollen, und klicken Sie anschließend auf „Speichern“.

Die payever-Zahlung stornieren

Wenn Sie eine Zahlung autorisiert haben, diese aber nicht erfassen möchten, müssen Sie eine Cancel-Anfrage ausführen, um die Gelder wieder für den Shopper freizugeben.
Wenn die Zahlung bereits erfasst wurde, müssen Sie stattdessen eine Erstattung durchführen.

Um eine Stornierung auszulösen, gehen Sie im Merchant Center von commercetools auf die Bestellseite und ändern den Bestellstatus auf „Cancelled“.

Schritt 1: commercetools Checkout-Validierungen

Warenkorb neu berechnen – Führen Sie eine Warenkorb-Neuberechnung aus, um sicherzustellen:

Zahlung validieren – Es muss mindestens ein commercetools-Payment-Objekt vom Typ payever existieren (Payment.paymentMethodInfo.paymentInterface = ctp-payever-integration).

Zahlungstransaktion validieren – Eine Warenkorb-Zahlung gilt als erfolgreich, wenn es mindestens ein Payment-Objekt mit einem erfolgreichen Transaktionsstatus (Payment.Transaction.state = Success)und dem Transaktionstyp Authorization oder Charge gibt.

Schritt 2: Ein commercetools-Payment erstellen

Schritt 3 (optional): Verfügbare Zahlungsarten abrufen

Schritt 4: Eine payever-Zahlung erstellen

Wichtig – In diesem Integrationsdokument sind die Beispiele für die payever-Payment-Requests auf das Nötigste gekürzt.Eine vollständige Liste aller Parameter finden Sie in der payever API V1 Dokumentation und in der payever API V2 Dokumentation.

Schritt 5: Waren versenden (Shipping goods)

Manuelles Versenden der Waren

API-Aufruf zum Erfassen einer Zahlung (Shipping goods):

Shipping-goods-Anfragen erneut senden (Retry)

Benutzerdefinierte Referenz für manuelles Shipping goods

Shipping-goods-Anfragen für Payment Splits

Weitere Informationen zu Shipping goods

Schritt 6: Erstattung (Refund)

Erstattung

API-Aufruf zum Erstatten einer Zahlung

Voraussetzungen

Schritte

Refund-Anfragen erneut senden (Retry)

Benutzerdefinierte Refund-Referenz

Refund-Anfragen für Payment Splits

Zusätzliche Informationen

Weitere Ressourcen: payever Refund API

Schritt 7: Eine Zahlung stornieren

Zahlung stornieren

Schritte

Cancel-Anfragen erneut senden (Retry)

Benutzerdefinierte Cancel-Referenz

Cancel-Anfragen für Payment Splits

Metadaten für commercetools-Transaktionen

Schritt 8: Subscriptions

Eine payever-Zahlung erfassen

Die payever-Zahlung erstatten

Die payever-Zahlung stornieren

Verwandte Beiträge

Zahlung validieren – Es muss mindestens ein commercetools-Payment-Objekt vom Typ payever existieren (`Payment.paymentMethodInfo.paymentInterface = ctp-payever-integration`).

Zahlungstransaktion validieren – Eine Warenkorb-Zahlung gilt als erfolgreich, wenn es mindestens ein Payment-Objekt mit einem erfolgreichen Transaktionsstatus (`Payment.Transaction.state = Success`)
und dem Transaktionstyp `Authorization` oder `Charge` gibt.

Wichtig – In diesem Integrationsdokument sind die Beispiele für die payever-Payment-Requests auf das Nötigste gekürzt.
Eine vollständige Liste aller Parameter finden Sie in der payever API V1 Dokumentation und in der payever API V2 Dokumentation.