Kartenangaben an API-Endpoints von Drittanbietern weiterleiten

Verwenden Sie die Vault and Forward API, um Kartendaten sicher für mehrere Abwickler auszutauschen.

Mit der Vault and Forward API können Sie Kartendaten im PCI-konformen Tresor von Stripe tokenisieren und speichern und diese Daten an zugelassene Zahlungsabwickler oder Endpoints weiterleiten. Mit der API können Sie:

Verwenden Sie das Payment Element für mehrere Zahlungsabwickler.
Verwenden Sie Stripe als Ihren primären Tresor für Kartendaten bei allen Abwicklern.
Geben Sie Kartendaten an Ihren eigenen PCI-konformen Token-Tresor weiter.

Zugriff anfordern

Um Zugriff auf den Weiterleitungsdienst von Stripe zu erhalten, wenden Sie sich an den Stripe-Support.

Weiterleitung von Anfragen an Ziel-Endpoints und Auffüllen der Kartendaten aus dem Tresor von Stripe

Kartenangaben erfassen und eine PaymentMethod erstellen

Zum Erfassen von Kartendaten verwenden Sie das Payment Element. Mit diesem können Sie eine PaymentMethod erstellen. Nach der Erstellung speichern wir die Kartendaten automatisch im PCI-konformen Tresor von Stripe. Wenn Sie über ein eigenes Frontend verfügen, können Sie die Vault and Forward API verwenden, indem Sie direkt eine PaymentMethod erstellen.

In der Regel können Sie PaymentMethods nur wiederverwenden, indem Sie sie an eine Kundin/einen Kunden anhängen. Die Vault und Forward API akzeptiert jedoch alle PaymentMethod-Objekte, einschließlich derjenigen, die nicht mit einer Kundin/einem Kunden verknüpft sind.

Ebenso bestätigt oder erfasst die Vault and Forward API keine PaymentIntents. Infolgedessen können Sie sie unbeabsichtigt verwenden, um eine Zahlung auf Stripe zu erfassen, die bereits von einem anderen Verarbeiter erfasst wurde.

Prüfziffern/CVCs verfallen automatisch nach einem bestimmten Zeitraum und auch dann, wenn sie mit der Vault and Forward API verwendet werden. Wenn Sie einen CVC benötigen, nachdem eine dieser Bedingungen erfüllt ist, müssen Sie die Kartenangaben erneut erfassen.

ForwardingRequest erstellen

Um Kartendaten aus dem Stripe-Tresor zu senden, müssen Sie eine ForwardingRequest erstellen und die folgenden Parameter angeben:

payment_method: Objekt mit dem Stripe die Kartendaten Ihrer Kundinnen und Kunden im Tresor von Stripe identifizieren und diese Daten in den Anfragetext einfügen kann.
url: Der genaue Ziel-Endpoint Ihrer Anfrage.
request.body: Der Anfragetext der API-Anfrage, die Sie an den Ziel-Endpoint senden möchten (zum Beispiel die Zahlungsanfrage, die Sie an einen anderen Zahlungsabwickler senden). Lassen Sie jedes Feld leer, in das Sie normalerweise Kartendaten Ihrer Kundin/Ihres Kunden eingeben.
replacements: Felder, die Stripe im request.body ersetzen soll. Die verfügbaren Felder, die unserer Empfehlung zufolge, immer festgelegt werden sollten, sind card_number, card_expiry, card_cvc und cardholder_name. Wenn Sie beispielsweise card_number in das Array replacements aufnehmen, wird das entsprechende Kartennummernfeld für Ihren Ziel-Endpoint im request.body ersetzt.

Vorsicht

Stripe kann bei der Validierung des Namensfelds des Karteninhabers/der Karteninhaberin nachsichtiger sein als andere Zahlungsabwickler. Wenn Sie das Ersetzungsfeld cardholder_name verwenden, sind Sie dafür verantwortlich, dass die von Ihnen verwendeten Namen die vom Ziel-Endpoint erzwungene Validierung bestehen. Wenn der Ziel-Endpoint beispielsweise erwartet, dass alle Namen nur die Buchstaben A–Z ohne Akzentzeichen oder andere Schriftsysteme enthalten, müssen Sie sicherstellen, dass die von Ihnen weitergeleiteten Kartendaten diese Anforderung erfüllen. Eine Alternative besteht darin, das Ersetzungsfeld cardholder_name nicht zu verwenden und den Namen des Karteninhabers/der Karteninhaberin in Ihrem Anfragetext direkt in Ihrer Anfrage anzugeben.

Sie müssen Ihre Anfrage basierend auf den Daten formatieren, die der Ziel-Endpoint erwartet. Im folgenden Beispiel erwartet der Ziel-Endpoint einen Idempotency-Key-Header und akzeptiert einen JSON-Text mit den Zahlungsdetails.

Sicherheitshinweis

Sie müssen bei jeder API-Anfrage API-Schlüssel für den Ziel-Endpoint übergeben. Stripe leitet die Anfrage mit den Ihnen bereitgestellten API-Schlüsseln weiter und speichert nur gehashte und verschlüsselte Versionen der API-Schlüssel des Ziel-Endpoints.

Vorsicht

Sie können einen Idempotency-Key angeben, um sicherzustellen, dass Anfragen mit demselben Schlüssel nur zu einer einzigen ausgehenden Anfrage führen. Verwenden Sie einen anderen und eindeutigen Schlüssel für Stripe und alle Idempotenz-Schlüssel, die Sie in der zugrunde liegenden Drittanbieteranfrage angeben.

Verwenden Sie jedes Mal, wenn Sie eine Aktualisierung am Feld request.body oder request.header vornehmen, einen neuen Idempotency-Key. Die Übergabe des älteren Idempotenz-Schlüssels führt dazu, dass die API ältere Antworten wiedergibt, einschließlich aller früheren Validierungsfehler oder Fehler im Zusammenhang mit Ziel-Endpoints. Wir empfehlen die Verwendung eines neuen Idempotenz-Schlüssels bei der Wiederholung von Anfragen, bei denen beim Erreichen des Ziel-Endpoints ein Fehler aufgetreten ist. So stellen Sie sicher, dass die Anfrage am Ziel wiederholt wird.

Anfrage mit Kartendaten weiterleiten

Stripe stellt in Ihrem Namen eine Anfrage an den Ziel-Endpoint, indem die Kartendaten aus der PaymentMethod in den request.body eingefügt werden. Wenn diese Option aktiviert und verfügbar ist, versucht der Card Account Updater (CAU) automatisch, die neuesten verfügbaren Kartendaten für Anfragen zu aktualisieren und bereitzustellen.

Stripe leitet die Anfrage dann an den Ziel-Endpoint weiter. Beispiel:

Stripe stellt eine POST-Anfrage an den Endpoint:

POST /v1/payments HTTP/1.1
User-Agent: Stripe
Accept: */*
Host: endpoint-url
Content-Type: application/json
Content-Length: 321

Stripe gliedert sich in folgende Kopfzeilen

Destination-API-Key: {{DESTINATION_API_KEY}}
Destination-Idempotency-Key: {{DESTINATION_IDEMPOTENCY_KEY}}

Stripe nimmt den folgenden JSON-Text in die Anfrage auf:

{
  amount: {
    value: 1000,
    currency: 'usd'
  },
  paymentMethod: {
    number: '4242424242424242',
    expiryMonth: '03',
    expiryYear: '2030',
    cvc: '123',
    holderName: 'First Last',
  },
  reference: '{{REFERENCE_ID}}'
}

Notiz

Wenn Sie die Vault und die Forward API verwenden, um eine Autorisierungsanfrage zu stellen, müssen Sie alle Aktionen nach der Transaktion, wie Rückerstattungen oder Zahlungsanfechtungen, direkt mit dem Drittanbieter abwickeln. Wenden Sie sich an den Stripe-Support, wenn Sie eine 3DS-Authentifizierung für Ihre Einrichtung mit mehreren Zahlungsabwicklern benötigen.

Antwort vom Ziel-Endpoint verarbeiten

Wenn Sie die Vault and Forward API verwenden, um Kartendetails an einen Drittanbieter weiterzuleiten, wartet Stripe synchron auf eine Antwort vom Ziel-Endpoint. Das Zeitlimit für diese Antwort beträgt weniger als eine Minute. Stripe entfernt erkannte PCI-sensible Daten, speichert die entfernte Antwort des Ziel-Endpoints und gibt ein ForwardingRequest-Objekt zurück, das Daten über die Anfrage und die Antwort enthält.

Vorsicht

Wenn Sie die Vault and Forward API zur Weiterleitung von Kartendaten an einen Drittanbieter-Zahlungsabwickler verwenden, kann Stripe nicht garantieren, dass der Abwickler eine bestimmte Antwort auf Ihre weitergeleiteten API-Anfragen geben wird. Wenn der Drittanbieter-Zahlungsabwickler nicht reagiert, müssen Sie sich zur Behebung des Problems direkt an diesen Abwickler wenden.

{
  id: "fwdreq_123",
  object: "forwarding.request",
  payment_method: "{{PAYMENT_METHOD}}",
  request_details: {
    body: '{
      "amount": {
        "value": 1000,
        "currency": "usd"
      },
      "paymentMethod": {
        "number": "424242******4242",
        "expiryMonth": "03",
        "expiryYear": "2030",
        "cvc": "***",
        "holderName": "First Last",
      },
      "reference": "{{REFERENCE_ID}}"
    }',
    headers: [
      {
        name: "Content-Type",
        value: "application/json",
      },
      {
        name: "Destination-API-Key",
        value: "{{DESTINATION_API_KEY}}",
      },
      {
        name: "Destination-Idempotency-Key",
        value: "{{DESTINATION_IDEMPOTENCY_KEY}}",
      },
      ...
    ]
  },
  request_context: {
      "destination_duration": 234,
      "destination_ip_address": "35.190.113.80"
  },
  response_details: {
    body: '{
      // Response from the third-party endpoint goes here
      ...
    }',
    headers: [
      ...
    ],
    status: 200,
  },
  replacements: [
    "card_number",
    "card_expiry",
    "card_cvc",
    "cardholder_name"
  ]
  ...
}

Ihren Vault and Forward API-Endpoint konfigurieren

Um Ihren Vault and Forward API-Endpoint einzurichten, müssen Sie wie folgt vorgehen:

Bestätigung, dass wir den Ziel-Endpoint unterstützen.
Stellen Sie ein Test- und ein Produktionskonto für den Stripe-Support bereit.
Geben Sie die Produktionsdetails für den Ziel-Endpoint an den Stripe-Support weiter.

Bestätigung, dass wir den Ziel-Endpoint unterstützen

Stripe unterstützt die Weiterleitung von API-Anfragen an die folgenden Endpoints:

Adyen:
- [prefix]-checkout-live.adyenpayments.com/checkout/v68/payments
- [prefix]-checkout-live.adyenpayments.com/checkout/v68/storedPaymentMethods
- [prefix]-checkout-live.adyenpayments.com/checkout/v69/payments
- [prefix]-checkout-live.adyenpayments.com/checkout/v69/storedPaymentMethods
- [prefix]-checkout-live.adyenpayments.com/checkout/v70/payments
- [prefix]-checkout-live.adyenpayments.com/checkout/v70/storedPaymentMethods
- [prefix]-checkout-live.adyenpayments.com/checkout/v71/payments
- [prefix]-checkout-live.adyenpayments.com/checkout/v71/storedPaymentMethods
Braintree:
- payments.braintree-api.com/graphql
Checkout:
- api.checkout.com/tokens
- api.checkout.com/payments
Fat Zebra:
- gateway.pmnts.io/v1.0/credit_cards
FlexPay:
- api.flexpay.io/v1/gateways/charge
GMO-Zahlungs-Gateway:
- p01.mul-pay.jp/payment/ExecTran.json
PaymentsOS:
- api.paymentsos.com/tokens
SoftBank:
- stbfep.sps-system.com/api/xmlapi.do
Spreedly:
- core.spreedly.com/v1/payment_methods.json
TabaPay:
- [prefix]/v1/clients/[ClientID]/accounts
Worldpay:
- access.worldpay.com/api/payments
- access.worldpay.com/cardPayments/customerInitiatedTransactions
- access.worldpay.com/tokens
- secure.worldpay.com/jsp/merchant/xml/paymentService
Ihr eigener PCI-konformer Token-Tresor

Stripe unterstützt HTTPS-basierte APIs, die JSON/XML-Anfragen akzeptieren und JSON/XML-Antworten zurückgeben. Wenn Ihr Ziel-Endpoint nicht unterstützt wird oder Sie ein anderes API-Format benötigen, teilen Sie die Endpoint-Details mit dem Stripe-Support, um Unterstützung für Ihre spezifischen Anforderungen zu erhalten.

Unterstützte Länder

Die Vault and Forward API kann nur Anfragen an die folgenden Länder weiterleiten:

Länder, die für die Weiterleitung von Anfragen in Frage kommen

Stellen Sie außerdem sicher, dass Ihr Stripe-Konto in einem dieser Länder registriert ist:

Länder, die für die Vault and Forward API berechtigt sind

Testkonten für den Stripe-Support bereitstellen

Um auf die Vault and Forward API zuzugreifen, geben Sie die Konto-IDs (acct_xxxx) für Ihre Testkonten an den Stripe-Support weiter.

Geben Sie die Produktionsdetails für den Ziel-Endpoint an den Stripe-Support weiter. Dazu gehören die folgenden Angaben für den Ziel-Endpoint: URL, HTTP-Methode, Dokumentation, Felder, Anfrage-Header und Verschlüsselungsschlüssel. Stripe richtet dann den Ziel-Endpoint für die Verwendung mit der Vault and Forward API im Live-Modus ein.

Um API-Schlüssel von Drittanbietern zu teilen, müssen Sie sie mit dem öffentlichen Schlüssel von Stripe, der speziell für die Vault and Forward API gilt, verschlüssen. Beginnen Sie, indem Sie mit dem GNU Privacy Guard (PGP) einen öffentlichen Schlüssel importieren. Nachdem Sie sich mit den Grundlagen von PGP vertraut gemacht haben, verwenden Sie den folgenden PGP-Schlüssel zum Verschlüsseln Ihrer Drittanbieter-API-Schlüssel:

PGP-Schlüssel der Vault and Forward API

So verschlüsseln Sie Ihre API-Schlüssel von Drittanbietern mit dem PGP-Schlüssel der Vault and Forward API:

Erstellen Sie eine Datei mit dem Namen hash_encrypt_key.sh mit dem folgenden Inhalt. Das Skript generiert einen SHA256-Hash Ihres API-Schlüssels, verschlüsselt ihn mit dem öffentlichen Schlüssel von Stripe und codiert ihn dann mit Base64.

Erforderliche Dienstprogramme

Um das Skript ausführen zu können, müssen Sie zuerst die Dienstprogramme sha256sum, gpg und base64 installieren.

Command Line
#!/bin/sh
set -euo pipefail
fail () { printf "Error: $1\n" >&2 && exit 1; }

STRIPE_PUBLIC_KEY=AE863ADA1603150856C0A853A7B203177D034588
API_KEY=$(printf "$1" | tr -d '\n' | sed 's/^[[:space:]]*//; s/[[:space:]]*$//')

[ -x "$(command -v sha256sum)" ]                    || fail "sha256sum is not installed."
[ -x "$(command -v gpg)" ]                          || fail "gpg is not installed."
[ -x "$(command -v base64)" ]                       || fail "base64 is not installed."
[ ! -z "$API_KEY" ]                                 || fail "Please pass in an API key."
grep -iqv "Basic \|Bearer " <<< "$API_KEY"          || fail "Please omit the Basic/Bearer prefix."
gpg --list-keys $STRIPE_PUBLIC_KEY > /dev/null 2>&1 || fail "Stripe public key not imported."

printf "$API_KEY" | sha256sum | cut -d " " -f 1 | tr -d '\n' | gpg -e -r $STRIPE_PUBLIC_KEY --always-trust | base64 > encrypted_hashed_key.txt
printf "Successfully generated encrypted_hashed_key.txt\n"

Führen Sie das Skript aus, indem Sie Ihren Drittanbieter-API Schlüssel in einfachen Anführungszeichen übergeben und dabei das Präfix Bearer oder Basic weglassen. Der Schlüssel muss exakt der Schlüssel sein, den Sie für tatsächliche Anforderungen an den Ziel-Endpoint verwenden, ohne Präfix.
Das Skript erzeugt eine Datei mit dem Namen encrypted_hashed_key.txt.
Command Line
```
sh hash_encrypt_key.sh '<THIRD_PARTY_API_KEY>'
```

Ihre Integration testen

Um zu bestätigen, dass Ihre Integration mit dem Ziel-Endpoint korrekt funktioniert, initiieren Sie eine ForwardingRequest mit der von Ihnen erstellten PaymentMethod. In diesem Beispiel wird pm_card_visa als Zahlungsmethode verwendet.

Vorsicht

Die Vault and Forward API behandelt jede Antwort vom Ziel-Endpoint als success und gibt 200 sowie den Antwortcode des Ziel-Endpoints im response.body zurück. Wenn der Ziel-Endpoint beispielsweisen den Antwortcode 400 an Stripe zurückgibt, antwortet die Vault and Forward API mit den Statuscode 200. Der response.body enthält die 400-Antwort des Ziel-Endpoints und eine Fehlermeldung. Testen Sie die API-Anfrage, die Sie an Ihren Ziel-Endpoint senden, separat, um sicherzustellen, dass keine Fehler auftreten.

Ihre Anfrage-Logs im Dashboard anzeigen

Sie können Anfrageprotokolle und Fehler im Zusammenhang mit der Vault and Forward API in Workbench anzeigen. Darüber hinaus können Sie mit der List API die Protokolle von Stripe abrufen.

Sicherheitshinweis

Die Parameter request.headers und request.body in der eingehenden Anfrage sind verschlüsselt und werden im Dashboard als encrypted_request angezeigt.

Kartenangaben an API-Endpoints von Drittanbietern weiterleiten

Verwenden Sie die Vault and Forward API, um Kartendaten sicher für mehrere Abwickler auszutauschen.

Zugriff anfordern

Weiterleitung von Anfragen an Ziel-Endpoints und Auffüllen der Kartendaten aus dem Tresor von Stripe

Kartenangaben erfassen und eine PaymentMethod erstellen

ForwardingRequest erstellen

Vorsicht

Sicherheitshinweis

Vorsicht

Anfrage mit Kartendaten weiterleiten

Notiz

Antwort vom Ziel-Endpoint verarbeiten

Vorsicht

Ihren Vault and Forward API-Endpoint konfigurieren

Bestätigung, dass wir den Ziel-Endpoint unterstützen

Unterstützte Länder

Länder, die für die Weiterleitung von Anfragen in Frage kommen

Länder, die für die Vault and Forward API berechtigt sind

Testkonten für den Stripe-Support bereitstellen

Produktionsdaten teilen

PGP-Schlüssel der Vault and Forward API

Erforderliche Dienstprogramme

Ihre Integration testen

Vorsicht

Ihre Anfrage-Logs im Dashboard anzeigen

Sicherheitshinweis