Diese Anleitung erklärt, wie Sie als payever Händler payever mit Ihrem SAP Commerce Cloud, Open Payment Framework (OPF) Tenant verbinden können. Dafür wird die von SAP veröffentlichte, fertige payever Postman Collection verwendet.
Schritt 1: Account anlegen
Erstellen Sie sich hier, sofern Sie das noch nicht getan haben, Ihren kostenlosen payever Account. Sollten Sie bereits einen Account haben, können Sie sich hier einloggen.
Schritt 2: Zahlarten konfigurieren
Um zu den Zahlarten zu gelangen, öffnen Sie zunächst die Checkout App. Klicken Sie dazu entweder auf das Checkout-Symbol in der Kachel Business Apps oder auf Öffnen in der Kachel Checkout.
Sie finden die Zahlkarten in der linken Navigationsleiste.
Klicken Sie auf Hinzufügen.
Nun erscheint eine Liste an verschiedenen Zahlarten, die Sie nach Bedarf auswählen können. Klicken Sie hierfür auf Installieren.
Nachdem Sie die Zahlart erfolgreich installiert haben, klicken Sie auf Öffnen, um gegebenenfalls die Zugangsdaten einzugeben. Dies können Sie auch zu einem späteren Zeitpunkt unter dem Reiter Connect > Settings konfigurieren.
Nun öffnet sich eine Schaltfläche, deren Aufbau sich je nach Zahlsart unterschiedlich gestaltet.
Für die Zahlungsmethoden Kreditkarte, Lastschrift und PayPal genügt ein Klick auf die Schaltfläche Verbinden. Sie werden daraufhin zum entsprechenden Anbieter weitergeleitet. Dort haben Sie die Möglichkeit, entweder Ihren bereits bestehenden Account zu verknüpfen oder einen neuen Account zu erstellen.
Für die Zahlungsmethoden Openbank Pay Ratenkauf, Openbank Pay BNPL und Openbank Pay Finanzierung geben Sie bitte die Zugangsdaten ein, die Sie von Openbank Pay erhalten haben, und klicken Sie anschließend auf „Verbinden“.
Falls Sie bisher noch keinen Kontakt zu Openbank Pay hatten, wenden Sie sich bitte an support@payever.de.
Die Zugangsdaten können je nach Zahlungsmethode variieren und reichen von einem einzelnen numerischen oder alphanumerischen Code bis hin zu maximal vier verschiedenen Codes.
Unabhängig von der Zahlart, achten Sie bitte darauf, Ihre Zugangsdaten stets in den Reiter Standard bzw. Default einzutragen. Klicken Sie nicht auf Hinzufügen und tragen dort die Zugangsdaten ein (dies müssen Sie nur dann, wenn Sie für einen besonderen Use Case mehrere Paare an Zugangsdaten für die gleiche Zahlsart haben - auch in diesen Fällen müssen Sie aber immer erst die Default/Standard-Variante mit Zugangsdaten befüllen, bevor Sie weitere hinzufügen können).
Nachdem Sie die Zahlarten verbunden haben, können Sie an der Zahlart noch eine oder mehrere Einstellungen treffen - welche genau das jeweils sind und was diese zu bedeuten haben, entnehmen Sie bitte ebenfalls unserer Dokumentation zu der betroffenen Zahlart, welche Sie hier finden können.
Schritt 3: Kanal/Kanäle einrichten
Wählen Sie in der Checkout App in der linken Navigationsleiste Kanäle aus.
Klicken Sie auf Hinzufügen.
Bitte wählen Sie aus Liste API aus und klicken Sie auf Installieren.
Nun müssen Sie auf Öffnen klicken, damit Sie im nächsten Schritt die API-Schlüssel generieren können.
1.Drücken Sie auf API Schlüssel und Hinzufügen
2.Geben Sie dem API Schlüssel einen beliebigen Namen und klicken Sie auf Erstellen.
3.Klicken Sie nun auf das + Plus-Symbol.
4.Sie sehen nun die Daten, die Sie später eingeben müssen (Client ID, Client Secret und Business UUID). Bitte kopieren Sie sich diese in die Zwischenablage.
Schritt 4: Integration von payever in das SAP Open Payment Framework
4.1 Einleitung
Das Open Payment Framework ermöglicht es Ihnen, Payment Service Provider (PSPs) innerhalb der SAP Commerce Cloud zu orchestrieren. payever wird als Payment Integration in Ihrem OPF Tenant integriert. Anstatt jedes Mapping manuell in der OPF Workbench zu konfigurieren, stellt SAP eine Postman Collection bereit, die die payever Integration programmatisch über die Merchant API Ihres Tenants erstellt und konfiguriert.
Die Integration basiert auf der Payments V3 REST API von payever. Der OPF Tenant ruft den create-payment Endpoint von payever auf, um eine Transaktion über eine Hosted Payment Page zu autorisieren. Anschließend werden Folgeoperationen wie Capture, Refund und Reversal ausgeführt und payever Benachrichtigungen verarbeitet.
Die Collection zeigt die folgenden Funktionen:
- Autorisierung einer Zahlung über die Hosted Payment Page von payever (Full-Page Redirect)
- Settlement (Capture)
- Refund
- Reversal (Rückabwicklung einer Autorisierung)
Außerdem konfiguriert sie die unterstützenden Bestandteile, die für eine funktionierende Integration erforderlich sind: eine ausgehende OAuth 2.0 Authentifizierung, eine HMAC-Signaturprüfung für eingehende Benachrichtigungen sowie das Capture-Verhalten auf Account-Ebene.
4.2 Voraussetzungen
Um die Integration abzuschließen, benötigen Sie die zwei Konfigurationsdateien aus dem payever PAYMENT-PAGE Sample von SAP:
| Datei | Rolle in Postman | Beschreibung |
|---|---|---|
mapping_configuration.json |
Collection | Die payever OPF Mapping Collection. Sie enthält die Requests, mit denen Variablen, Authentifizierungen und Request-Mappings (Authorization, Settlement, Refund, Reversal, Notification) auf Ihrem Tenant erstellt werden. |
environment_configuration.json |
Environment | Die Variablensammlung (Tenant URL, Integration IDs, payever Zugangsdaten, Zahlungsmethode usw.), die von der Collection zur Laufzeit ausgelesen wird. Diese Datei bearbeiten Sie vor dem Import. |
Zusätzlich benötigen Sie Zugriff auf:
- Eine OPF Workbench / ein OPF Cockpit für Ihren lizenzierten SAP Commerce Cloud, Open Payment Framework Tenant.
- Postman (Desktop- oder Webversion), um die Collection zu importieren und auszuführen.
- Einen Satz payever API-Zugangsdaten (Client ID und Client Secret). Für die Sandbox sind diese veröffentlicht; für die Produktion werden sie für Ihren payever Account ausgestellt.
4.3 Sandbox vs. Produktion
Sie können die Collection entweder gegen die offene payever Sandbox oder gegen die Produktion ausführen.
| Umgebung | payever apiDomain
|
Zugangsdaten |
|---|---|---|
| Sandbox (Test) | proxy.staging.devpayever.com |
Kein payever Account erforderlich. Verwenden Sie die veröffentlichten payever Testzugangsdaten. |
| Produktion (Live) | proxy.payever.org |
Ein payever Account ist erforderlich. Kontaktieren Sie payever, um für die Produktion eingerichtet zu werden. |
HINWEIS: Die Sandbox wird von Montag bis Freitag, 8:00 bis 18:00 Uhr CET, überwacht und unterstützt. Sie können sie auch außerhalb dieser Zeiten aufrufen, Supportanfragen werden jedoch nur innerhalb dieses Zeitfensters bearbeitet. Für Unterstützung kontaktieren Sie support@payever.de.
4.4 Unterstützte Zahlungsmethoden
Die folgenden E-Commerce-Zahlungsmethoden (und deren Anbieter) sind über die payever API verfügbar und können über die OPF Collection konfiguriert werden. Point-of-Sale-Zahlungsmethoden (POS) sind bewusst ausgeschlossen - diese Collection deckt nur E-Commerce ab. Die vollständige und stets aktuelle Liste finden Sie in der payever Payment Methods Reference.
| Zahlungsmethode | Method Code | Method Issuer | Verfügbare Länder |
|---|---|---|---|
| Openbank Pay BNPL Germany | openbank_pay_bnpl_de |
- | DE |
| Openbank Pay BNPL Netherlands | openbank_pay_bnpl |
- | NL |
| Openbank Pay BNPL Spain | openbank_pay_bnpl_es |
- | ES |
| Openbank Pay Installments Germany | openbank_pay_installment_de |
- | DE |
| Openbank Pay Installments Netherlands | openbank_pay_installment |
- | NL |
| Openbank Pay Installments Spain | openbank_pay_installment_es |
- | ES |
| Openbank Pay Lending Germany | openbank_pay_lending_de |
- | DE |
| Openbank Pay Slice-In-Three Germany | openbank_pay_slice_three_de |
- | DE |
| Openbank Pay Slice-In-Three Netherlands | openbank_pay_slice_three |
- | NL |
| Santander BNPL | santander_invoice_at |
- | AT |
| Santander Installments Austria | santander_installment_at |
- | AT |
| Santander Installments Belgium | santander_installment_be |
- | BE |
| Santander Pay by Bank | santander_instant |
- | AT |
| Resurs BNPL | resurs_bnpl |
- | DK, FI, NO, SE |
| Resurs Installments | resurs_installment |
- | DK, FI, NO, SE |
| Verifone Credit Card | credit_card |
verifone | DE, DK, ES, FI, NL, NO, PL, SE, UK, AT, BE |
| Verifone Direct Debit | direct_debit |
verifone | DE, AT, CH |
| Verifone BNPL | bnpl |
verifone | DE, AT |
| Apple Pay | apple_pay |
verifone, stripe | Alle |
| Google Pay | google_pay |
stripe, verifone | Alle |
| PayPal | paypal |
- | Alle |
| Stripe Credit Card | credit_card |
stripe | Alle |
| Stripe Direct Debit | direct_debit |
stripe | Alle |
| Pay by Bank | pay_by_bank |
- | Alle |
| Wero | wero |
ppro, stripe | Alle |
| Wiretransfer | wiretransfer |
- | Alle |
HINWEIS: Die Verfügbarkeit hängt vom Land und von Ihrem Vertrag mit payever ab. Die Bedingungen der einzelnen Zahlungsmethoden (Betragsgrenzen, Währung, Land, Adressregeln) finden Sie in der payever Zahlungsdokumentation.
4.5 Integrationsübersicht
Grundsätzlich erfolgt die Anbindung von payever an OPF in vier Schritten, die nachfolgend einzeln beschrieben werden:
- Erstellen Sie eine Payment Integration in der OPF Workbench. Dadurch erhalten Sie eine Integration ID und eine Configuration ID.
- Beschaffen Sie Ihre Zugangsdaten - ein OPF Bearer Token sowie Ihre payever Client ID und Ihr payever Client Secret.
- Konfigurieren Sie die Postman Environment-Datei mit Ihrer Tenant URL, den IDs und den payever Werten.
- Importieren Sie die Collection und führen Sie sie aus, um die payever Integration auf Ihrem Tenant bereitzustellen und anschließend zu validieren.
HINWEIS: Die Samples im SAP Repository sind Referenzimplementierungen und werden weder von SAP noch von payever offiziell unterstützt. Testen Sie die Integration immer gründlich in Ihrem OPF Tenant, bevor Sie live gehen.
Schritt 1: Payment Integration erstellen
Der erste Schritt besteht darin, eine payever Payment Integration in Ihrer OPF Workbench zu erstellen. Dadurch entstehen die beiden Identifikatoren, die die Postman Collection benötigt, um den richtigen Account anzusprechen: die Integration ID und die Configuration ID.
Für die verbindliche UI-Anleitung lesen Sie bitte die SAP Dokumentation Creating Payment Integration. Die folgenden Schritte fassen den Prozess aus Sicht eines payever Händlers zusammen.
Schritte in der OPF Workbench
- Öffnen Sie die OPF Workbench für Ihren Tenant, zum Beispiel
https://<your-tenant>.commerce.<region>.context.cloud.sap/opf-workbench. - Erstellen Sie eine neue Payment Integration für payever.
- Erstellen Sie innerhalb dieser Integration eine Payment Configuration.
- Öffnen Sie die Seite Configuration Details. Oben links auf dieser Seite finden Sie die beiden IDs, die Sie benötigen.
Erhaltene Identifikatoren
| OPF-Begriff | Postman Variable | Beschreibung |
|---|---|---|
| Integration ID | accountGroupId |
Identifiziert die payever Payment Integration, die Sie erstellt haben. |
| Configuration ID | accountId |
Identifiziert die Payment Configuration, die innerhalb der Integration erstellt wurde. |
Diese beiden Werte tragen Sie in Schritt 3 in die Postman Environment-Datei ein.
Site Assignment
Jede Payment Integration muss einer Site (Base Store) in Ihrem SAP Commerce Cloud Tenant zugewiesen werden, damit die Integration im Checkout dieses Storefronts angeboten wird. Sie setzen dies in den General Information der Integration: Öffnen Sie die Integration, klicken Sie auf das Bearbeiten-Symbol (Stift) auf der Karte General Information und setzen Sie das Feld Site Assignment (zum Beispiel electronics-spa).
Dieselbe Karte zeigt außerdem die Notification URL, die payever für Statusupdates aufruft, und ermöglicht Ihnen, die Werte Authorization Time-out Days sowie Capture & Refund Attempts anzupassen.
Merchant ID (Business UUID)
payever identifiziert Ihren Shop über eine Business UUID. In OPF wird diese als Merchant ID der Integration eingetragen.
| Umgebung | Merchant ID Wert |
|---|---|
| Sandbox | Verwenden Sie payever, wie in den Sandbox API-Zugangsdaten angegeben. |
| Produktion | Verwenden Sie die Business UUID, die für Ihren payever Account ausgestellt wurde. Sie finden diese in Ihrem payever Account unter Connect > Shopsystems > API. |
HINWEIS: Die Business UUID wird auch vom List Payment Options Endpoint von payever referenziert. Halten Sie sie daher griffbereit.
payever Domain zur Allowlist hinzufügen
Bevor die Integration payever aufrufen kann, muss die payever API-Domain zur Domain Allowlist Ihres Tenants in der OPF Workbench hinzugefügt werden. Hinweise dazu finden Sie in der SAP Dokumentation Adding Tenant-specific Domain to Allowlist.
Fügen Sie die Domain hinzu, die zu der Umgebung passt, die Sie verwenden möchten:
| Umgebung | Domain für die Allowlist |
|---|---|
| Produktion | proxy.payever.org |
| Sandbox (Test) | proxy.staging.devpayever.com |
HINWEIS: Wenn Sie diesen Schritt überspringen, kann der Authorization Request den create-payment Endpoint von payever nicht erreichen und Autorisierungsversuche schlagen fehl.
Schritt 2: Zugangsdaten beschaffen
Es werden zwei Arten von Zugangsdaten benötigt: ein OPF Bearer Token (um die Merchant API Ihres Tenants aufzurufen) und Ihre payever API Keys (damit die Integration payever aufrufen kann).
OPF Bearer Token
Die Collection authentifiziert sich gegenüber Ihrem OPF Tenant mit einem Bearer Token, das bei jedem Request im Authorization Header übergeben wird. Dieses Token ist kein payever Zugangsdatenwert. Es handelt sich um ein OAuth 2.0 Access Token (JWT) für Ihre eigene OPF Tenant API, das für eine „External Application“ ausgestellt wird, die Sie in der OPF Workbench mit dem Client Credentials Grant erstellen.
1. External Application erstellen
Erstellen Sie in der OPF Workbench eine External Application. OPF erzeugt dafür eine Client ID und ein Client Secret. Diese OPF Zugangsdaten sind getrennt von Ihrer payever Client ID und Ihrem payever Client Secret. Die UI-Schritte finden Sie in der SAP Dokumentation Creating an External Application.
2. Access Token anfordern
Tauschen Sie die Zugangsdaten der External Application über den client_credentials Grant gegen ein Access Token aus. Verwenden Sie dafür den Token Endpoint Ihres Tenants. Den exakten Endpoint Ihrer Landschaft finden Sie in der SAP Dokumentation Making Authorized API Calls.
Die Antwort enthält das JWT im Feld access_token:
curl -X POST 'https://<your-opf-tenant>/oauth/token' \ -H 'Content-Type: application/x-www-form-urlencoded' \ -u '<external_app_client_id>:<external_app_client_secret>' \ -d 'grant_type=client_credentials'
{
"access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
"token_type": "bearer",
"expires_in": 3600
}
3. Variable token setzen
Kopieren Sie den Wert access_token in die Variable token der Postman Environment. Stellen Sie dem Wert das Wort Bearer und ein Leerzeichen voran. Die Collection sendet den Header exakt als Authorization: {{token}}, daher muss das Schema Teil des Variablenwerts sein:
token = Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
WICHTIG: Das Token läuft ab (siehe expires_in, typischerweise nach etwa einer Stunde). Wenn Requests den Status 401 zurückgeben, fordern Sie ein neues Token an und aktualisieren Sie die Variable token. Ein leerer oder abgelaufener Token ist die häufigste Ursache für 401 Unauthorized bei jedem Request.
payever API Keys
Die Integration ruft payever über OAuth 2.0 auf. Daher benötigen Sie eine payever Client ID und ein payever Client Secret.
| Umgebung | Wo Sie die Keys erhalten |
|---|---|
| Sandbox | Verwenden Sie die veröffentlichten payever Test API-Zugangsdaten. Es ist kein Account erforderlich. |
| Produktion | Erstellen Sie die Keys in Ihrem payever Account unter Connect > Shopsystems > API. Neu bei payever? Registrieren Sie sich hier. |
Weitere Informationen zur payever Authentifizierung finden Sie unter Authentication.
Schritt 3: Postman Environment konfigurieren
Bevor Sie die Collection importieren, bearbeiten Sie die Datei environment_configuration.json, damit jeder Request gegen Ihren OPF Tenant und Ihren payever Account ausgeführt wird. Die Environment-Datei ist in allgemeine OPF-Variablen, payever-spezifische Variablen und ausgehende OAuth 2.0 Werte aufgeteilt, die vom Authentication Mapping verwendet werden.
Allgemeine OPF-Variablen
| Variable | Zuordnung | Beschreibung |
|---|---|---|
token |
Authorization Header | OPF Bearer Token (JWT). Muss mit Bearer beginnen. |
rootUrl |
Base URL | Die Basis-URL Ihres OPF Tenants (ohne nachfolgenden Pfad). Siehe Root URL unten. |
service |
URL-Pfadsegment | Der OPF Servicename. Standardwert ist opf. Wenn die Variable leer bleibt, entfernt die Collection das Segment /{{service}} automatisch aus der URL. |
accountGroupId |
Integration ID | Die Payment Integration ID von der Seite Configuration Details. |
accountId |
Configuration ID | Die Payment Configuration ID von der Seite Configuration Details. |
payever-spezifische Variablen
| Variable | Beschreibung |
|---|---|
clientId |
Ihre payever API Client ID. |
secret |
Ihr payever API Client Secret. |
apiDomain |
Zielumgebung: proxy.payever.org (Produktion) oder proxy.staging.devpayever.com (Sandbox). |
apiVersion |
payever API-Version. Verwenden Sie v3. |
paymentMethod |
Der zu konfigurierende Payment Method Code, z. B. santander_installment. Siehe Unterstützte Zahlungsmethoden. |
HINWEIS: Die Business UUID (Merchant ID, z. B. payever für die Sandbox) wird direkt auf der Integration in der OPF Workbench konfiguriert, wie in Schritt 1 beschrieben. Wenn Sie sie als Postman Variable (merchantId) referenzieren, fügen Sie sie ebenfalls zur Environment-Datei hinzu.
Ausgehende OAuth 2.0 Variablen
Diese Werte befüllen die OAuth 2.0 Authentifizierung, die OPF verwendet, wenn payever aufgerufen wird. Sie werden vom Oauth2 Request in der Collection referenziert.
| Variable | Beispielwert | Beschreibung |
|---|---|---|
authentication_outbound_oauth2_token_url_export_1080 |
https://proxy.staging.devpayever.com/oauth/v2/token |
payever OAuth Token Endpoint. Verwenden Sie für Live die Produktionsdomain. |
authentication_outbound_oauth2_client_id_export_1080 |
(Ihre payever Client ID) | Client ID, mit der das Token angefordert wird. Setzen Sie diesen Wert auf denselben Wert wie clientId. |
authentication_outbound_oauth2_client_secret_export_1080 |
(Ihr payever Client Secret) | Client Secret, mit dem das Token angefordert wird. Setzen Sie diesen Wert auf denselben Wert wie secret. |
authentication_outbound_oauth2_use_basic_auth_export_1080 |
false |
Gibt an, ob die Zugangsdaten über HTTP Basic Auth gesendet werden. Für payever sollte dieser Wert auf false bleiben. |
WICHTIG: In der unbearbeiteten Sample-Datei enthalten die ausgehende Client ID und das ausgehende Client Secret Platzhaltertexte (Payever oAuth2 Auth_clientId / Payever oAuth2 Auth_clientSecret). Ersetzen Sie diese durch Ihre echte payever Client ID und Ihr echtes payever Client Secret, da sonst die OAuth Token-Anfrage an payever fehlschlägt.
Variablen für das Account-Verhalten
Diese Variablen steuern, wie sich der payever Account bzw. die Konfiguration verhält. Sie werden durch die Requests Account Patch und Account Group Patch angewendet.
| Variable | Beispielwert | Beschreibung |
|---|---|---|
capturePattern |
PARTIAL_CAPTURE |
Capture-Strategie für Settlements. |
enableOverCapture |
false |
Gibt an, ob Captures den autorisierten Betrag überschreiten dürfen. |
enableCaptureReAuth |
false |
Gibt an, ob ein Capture eine erneute Autorisierung auslösen darf. |
authorizationTimeoutDays |
7 |
Anzahl der Tage, nach denen eine nicht gecapturete Autorisierung abläuft. |
Beispiel für die Environment-Datei
Nach der Bearbeitung sollte Ihre Environment-Datei ungefähr wie folgt aussehen. Ersetzen Sie jeden <...> Platzhalter durch Ihre eigenen Werte.
{
"name": "payever",
"values": [
{ "key": "token", "value": "Bearer <opf_access_token_jwt>", "enabled": true },
{ "key": "rootUrl", "value": "https://<your-tenant>.commerce.stage.context.cloud.sap", "enabled": true },
{ "key": "service", "value": "opf", "enabled": true },
{ "key": "accountGroupId", "value": "<integration_id>", "enabled": true },
{ "key": "accountId", "value": "<configuration_id>", "enabled": true },
{ "key": "clientId", "value": "<payever_client_id>", "enabled": true },
{ "key": "secret", "value": "<payever_client_secret>", "enabled": true },
{ "key": "apiDomain", "value": "proxy.staging.devpayever.com", "enabled": true },
{ "key": "apiVersion", "value": "v3", "enabled": true },
{ "key": "paymentMethod", "value": "santander_installment", "enabled": true },
{ "key": "authentication_outbound_oauth2_token_url_export_1080", "value": "https://proxy.staging.devpayever.com/oauth/v2/token", "enabled": true },
{ "key": "authentication_outbound_oauth2_client_id_export_1080", "value": "<payever_client_id>", "enabled": true },
{ "key": "authentication_outbound_oauth2_client_secret_export_1080", "value": "<payever_client_secret>", "enabled": true },
{ "key": "authentication_outbound_oauth2_use_basic_auth_export_1080", "value": "false", "enabled": true },
{ "key": "capturePattern", "value": "PARTIAL_CAPTURE", "enabled": true },
{ "key": "enableOverCapture", "value": "false", "enabled": true },
{ "key": "enableCaptureReAuth", "value": "false", "enabled": true },
{ "key": "authorizationTimeoutDays", "value": "7", "enabled": true }
],
"_postman_variable_scope": "environment"
}
Root URL
Die rootUrl ist die Basis-URL Ihres OPF Tenants - ohne Pfad. Leiten Sie sie aus Ihrer Workbench- bzw. Cockpit-URL ab, indem Sie den nachfolgenden Pfad entfernen.
Wenn Ihre Workbench-URL beispielsweise lautet:
https://opf-iss-d0.uis.commerce.stage.context.cloud.sap/opf-workbench
dann lautet die Basis-URL:
https://opf-iss-d0.uis.commerce.stage.context.cloud.sap
HINWEIS: Fügen Sie keinen abschließenden Schrägstrich hinzu. Die Collection ergänzt den Pfad /{{service}}/merchant/... selbst.
Schritt 4: Collection importieren und ausführen
Nachdem die Environment-Datei vorbereitet wurde, können Sie beide Dateien in Postman importieren und die Requests ausführen, um die payever Integration auf Ihrem OPF Tenant bereitzustellen.
Dateien importieren
- Importieren Sie
environment_configuration.jsonals Postman Environment. - Importieren Sie
mapping_configuration.jsonals Postman Collection. - Wählen Sie die importierte Environment oben rechts im Environment Selector aus, bevor Sie etwas ausführen. Wenn keine Environment ausgewählt ist, werden die
{{...}}Variablen als leere Strings aufgelöst und die Requests schlagen fehl.
Die offizielle Anleitung zum Import in einen OPF Tenant finden Sie in der SAP Dokumentation Importing a Postman Collection.
Aufbau der Collection
Jeder Request richtet sich an die Merchant API Ihres Tenants und authentifiziert sich mit dem Header Authorization: {{token}}. Der Basispfad lautet:
{{rootUrl}}/{{service}}/merchant/...
Ein Pre-request Script auf Collection-Ebene entfernt das Segment /{{service}} automatisch, wenn Sie die Variable service leer lassen:
let url = pm.request.url.toString();
if (pm.environment.get("service") == null || pm.environment.get("service") === "") {
let updateUrl = url.replace("/{{service}}", "");
pm.request.url = updateUrl;
}
Die Collection ist in die folgenden Ordner unterteilt.
| Ordner | Methode & Pfad (relativ zu merchant/) |
Zweck |
|---|---|---|
| Variable | POST accountgroups/{{accountGroupId}}/accounts/{{accountId}}/variables |
Speichert die payever Werte (apiDomain, clientId, secret, apiVersion, paymentMethod) auf der Konfiguration, damit die Mappings sie als ${vars.*} referenzieren können. |
| Account | PATCH accountgroups/{{accountGroupId}}/accounts/{{accountId}} |
Setzt das Capture-Verhalten (capturePattern, enableOverCapture, enableCaptureReAuth). |
| AccountGroup | PATCH accountgroups/{{accountGroupId}} |
Setzt Optionen auf Integrationsebene, z. B. authorizationTimeoutDays. |
| Authentications | POST authentications |
Erstellt die ausgehende OAuth 2.0 Authentifizierung und die HMAC-Signaturprüfung, die für payever Benachrichtigungen verwendet wird. |
| Authorization | PUT accountgroups/{{accountGroupId}}/accounts/{{accountId}}/authorization |
Verknüpft den Autorisierungsschritt mit dem create-payment Endpoint von payever (POST https://${vars.apiDomain}/api/${vars.apiVersion}/payment) über einen Full-Page Redirect. |
| Settlement | PUT accountgroups/{{accountGroupId}}/accounts/{{accountId}}/settlement |
Erstellt das Mapping für den Settlement- bzw. Capture-Request. |
| Refund | PUT accountgroups/{{accountGroupId}}/accounts/{{accountId}}/refund |
Erstellt das Mapping für den Refund-Request. |
| Authorization_reversal | PUT accountgroups/{{accountGroupId}}/accounts/{{accountId}}/authorization_reversal |
Erstellt das Mapping für den Reversal-Request. |
| Notification | PUT accountgroups/{{accountGroupId}}/accounts/{{accountId}}/notification |
Erstellt das Mapping für eingehende payever Benachrichtigungen, die über die HMAC-Signatur verifiziert werden. |
Empfohlene Ausführungsreihenfolge
Führen Sie die Requests so aus, dass Abhängigkeiten vorhanden sind, bevor sie referenziert werden:
- Variable - erstellt zuerst alle Variablen; die Mappings hängen davon ab.
- Authentications - erstellt die OAuth 2.0 und HMAC Authentifizierungen.
- AccountGroup und Account - wendet die Einstellungen für Integration und Konfiguration an.
- Authorization, Settlement, Refund, Authorization_reversal, Notification - erstellt die Request-Mappings.
Sie können Requests einzeln ausführen oder den Postman Collection Runner verwenden, um die gesamte Collection in der richtigen Reihenfolge gegen die ausgewählte Environment auszuführen.
4.6 Beispiel: Authorization Mapping
Der Authorization Request verknüpft einen OPF Authorize Call mit dem create-payment Endpoint von payever. Das ausgehende Mapping sieht wie folgt aus:
{
"pattern": "FULL_PAGE",
"requestType": "AUTHORIZATION",
"remoteApiOutboundMappings": [
{
"method": "POST",
"url": "https://${vars.apiDomain}/api/${vars.apiVersion}/payment",
"requestContentType": "application/json",
"authenticationIds": ["{{authentication_outbound_oauth2_1080}}"],
"requestExample": {
"channel": { "name": "api", "type": "ecommerce", "source": "1.0.0" },
"purchase": { "amount": 140, "currency": "EUR", "delivery_fee": 10 },
"reference": "900001291100",
"payment_method": "${vars.paymentMethod}",
"cart": [
{ "identifier": "123", "name": "Some Item", "total_amount": 100, "unit_price": 50, "tax_rate": 0, "quantity": 2, "sku": "123" }
]
}
}
]
}
Der an payever weitergeleitete Request Body folgt dem create-payment Schema. Daher kann jedes dort dokumentierte Feld zum Mapping hinzugefügt werden. Die vollständige Liste der mappbaren Parameter finden Sie in der Payments V3 API.
4.7 Testanforderungen
Eine Zahlungsmethode wird nur dann angezeigt bzw. ist nur dann verfügbar, wenn die Bestellung die Voraussetzungen dieser Methode erfüllt. Diese Regeln unterscheiden sich je nach Methode. Jede Methode kann eigene Bedingungen definieren:
- Betragsgrenze - ein minimaler und maximaler Transaktionsbetrag.
- Einschränkungen für Rechnungs- und Lieferadresse - beispielsweise müssen Rechnungs- und Lieferadresse übereinstimmen.
- Länderbeschränkung - die Methode wird nur in bestimmten Ländern angeboten.
- Währungsbeschränkung - die Methode unterstützt nur bestimmte Währungen.
Wenn eine Zahlungsmethode während eines Tests nicht erscheint, liegt die häufigste Ursache darin, dass die Bestellung eine dieser Regeln nicht erfüllt. Die genauen Bedingungen der einzelnen Methoden finden Sie in der payever Zahlungsdokumentation.
Verwenden Sie für Sandbox-Tests die payever Testzugangsdaten und Testdaten, um Transaktionen zu simulieren.
4.8 Troubleshooting
| Symptom | Wahrscheinliche Ursache |
|---|---|
401 Unauthorized bei jedem Request |
Das token fehlt, ist abgelaufen oder beginnt nicht mit Bearer. Erzeugen Sie ein neues OPF Token. |
Requests gehen an die falsche URL / 404
|
rootUrl enthält einen abschließenden Schrägstrich oder einen Pfad, oder es ist die falsche accountGroupId / accountId gesetzt. |
| OAuth Token Request an payever schlägt fehl | Die ausgehende OAuth 2.0 Client ID bzw. das Client Secret enthält noch Platzhaltertext statt Ihrer echten payever Keys. |
| Autorisierung ist in OPF erfolgreich, aber payever wird nie aufgerufen | Die payever Domain (apiDomain) befindet sich nicht auf der Tenant Allowlist (siehe Schritt 1). |
| Zahlungsmethode wird im Checkout nicht angeboten | Die Testbestellung erfüllt die Voraussetzungen der Methode nicht (Betrag, Währung, Land, Adresse). |
Für tenantseitige Diagnosen verwenden Sie SAPs Open Payment Framework Logging. Für payever-seitige Fehler lesen Sie bitte die payever Status Codes and Errors Reference.
4.9 Go Live
Vor dem Wechsel in die Produktion:
- Führen Sie End-to-End-Tests für jede Zahlungsmethode durch, die Sie anbieten möchten. Verwenden Sie dafür die Sandbox
apiDomainund die veröffentlichten Testzugangsdaten. - Ändern Sie
apiDomainaufproxy.payever.orgund die OAuth Token URL auf die Produktionsdomain. - Ersetzen Sie die Sandbox payever Keys durch Ihre produktive Client ID und Ihr produktives Client Secret.
- Fügen Sie
proxy.payever.orgzur Tenant Allowlist hinzu (siehe Schritt 1). - Aktualisieren Sie die Merchant ID der Integration auf Ihre produktive Business UUID.
HINWEIS: Die Staging- und Live-Umgebungen sind getrennte Systeme mit getrennten Zugangsdaten. Sandbox Keys funktionieren nicht in der Produktion und produktive Keys funktionieren nicht in der Sandbox.
4.10 Einzelne Zahlungsmethoden konfigurieren
payever bietet viele Zahlungsmethoden an (siehe Unterstützte Zahlungsmethoden). In OPF ordnet eine Payment Integration vom Typ Payment Method jeweils eine einzelne payever Zahlungsmethode zu. Wenn Sie mehrere payever Methoden in Ihrem Checkout anbieten möchten, erstellen Sie für jede Methode eine separate payever Integration (zum Beispiel Payever-01, Payever-02, Payever-03 usw.). Jede Integration enthält ihren eigenen payment_method Wert.
Sie können die Zahlungsmethode entweder über die Postman Collection setzen (über die Variable paymentMethod, siehe Schritt 3) oder direkt in der OPF Workbench UI. Die Workbench-Schritte werden unten beschrieben.
1. Payment Integration auswählen
Öffnen Sie unter Payment Integrations die payever Integration, die Sie konfigurieren möchten. Um eine Methode hinzuzufügen, klicken Sie zuerst auf Create, um eine neue payever Integration zu erstellen.
2. Details anzeigen
Klicken Sie auf der Configuration Karte der Integration auf Show Details, um die Feld-Mappings der Konfiguration zu öffnen. Von hier aus können Sie auch Export to Postman Collection auswählen.
3. Authorization Request bearbeiten
Klicken Sie im Configuration Screen unter Payment Processing auf Edit auf der Authorization Karte.
4. Zahlungsmethode setzen
Suchen Sie in den Authorization Field Mappings das Feld payment_method, setzen Sie den Mapping Type auf Manual input und tragen Sie den payever Method Code ein (zum Beispiel paypal). Verwenden Sie die Codes aus der Liste der unterstützten Zahlungsmethoden (Punkt 4.4). Klicken Sie auf Save.
5. Verfügbare Felder mit Smart Fields ermitteln
Wenn Sie unsicher sind, welche Feldnamen verfügbar sind oder welche Werte akzeptiert werden, klicken Sie im Mapping Bereich auf Open Smartfield Details, um alle Smart Fields zu durchsuchen. Sie können auch Generate fields to map from request example verwenden, um das Mapping anhand eines Beispiel-Request-Bodys zu befüllen.
HINWEIS: Wiederholen Sie diese Schritte für jede payever Zahlungsmethode, die Sie anbieten möchten. Erstellen Sie dafür jeweils eine eigene payever Integration pro Methode.
Sobald die Konfiguration korrekt abgeschlossen wurde, sind Sie fertig, und der Checkout sollte in Ihrem Frontend-Shop wie folgt aussehen.
Noch Fragen oder Probleme?
Sie erreichen unseren kostenlosen Support Montags bis Freitags zwischen 8 und 18 Uhr unter support@payever.de
Bitte teilen Sie uns in Ihrer Nachricht mit, um welchen Shop bzw. welches Business es bei Ihrer Anfrage geht und mit welcher E-Mail-Adresse Sie bei uns registriert sind. Beschreiben Sie außerdem bitte möglichst genau, welche Fehlermeldung oder Störung Sie an welcher Stelle bemerkt haben. So können wir Ihr Anliegen schneller prüfen und bearbeiten. Schicken Sie uns gerne zusätzlich Screenshots oder weitere relevante Informationen mit, die uns helfen, die Problematik besser nachzuvollziehen.