Kartenangaben an API-Endpoints von Drittanbietern weiterleiten
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 einem Kunden/einer Kundin zuordnen. Die Vault and Forward API akzeptiert jedoch alle PaymentMethod-Objekte, auch solche, die nicht mit einem Kunden/einer Kundin verknüpft sind. Ebenso bestätigt oder erfasst die Vault und Forward API PaymentIntents nicht. Infolgedessen können Sie sie unbeabsichtigt verwenden, um eine Zahlung auf Stripe zu erfassen, die bereits von einem anderen Verarbeiter erfasst wurde.
CVCs verfallen automatisch nach einem bestimmten Zeitraum und auch dann, wenn sie mit der Vault und Forward API verwendet werden. Wenn Sie einen CVC benötigen, nachdem eine dieser Bedingungen erfüllt ist, müssen Sie sich die Kartenangaben merken.
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 imrequest.body
ersetzen soll. Die verfügbaren Felder, die unserer Empfehlung zufolge, immer festgelegt werden sollten, sindcard_number
,card_expiry
,card_cvc
undcardholder_name
. Wenn Sie beispielsweisecard_number
in das Arrayreplacements
aufnehmen, wird das entsprechende Kartennummernfeld für Ihren Ziel-Endpoint imrequest.body
ersetzt.
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 einen neuen Idempotency-Key
, wenn Sie Aktualisierungen der Felder request.body
oder request.header
vornehmen. Wenn Sie den älteren Idempotenz-Schlüssel übergeben, hat dies zur Folge, dass ältere Antworten angezeigt werden, einschließlich früherer Validierungsfehler.
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 und 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 bekannte 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/v68/payments
[prefix]-checkout-live.adyenpayments.com/v69/payments
[prefix]-checkout-live.adyenpayments.com/v70/payments
- Braintree:
payments.braintree-api.com/graphql
- Checkout:
api.checkout.com/tokens
api.checkout.com/payments
- GMO Payment Gateway:
p01.mul-pay.jp/payment/ExecTran.json
- PaymentsOS:
api.paymentsos.com/tokens
- Worldpay:
access.worldpay.com/tokens
- Ihr eigener PCI-konformer Token-Tresor
Die Vault and Forward API kann nur Anfragen an die folgenden Länder weiterleiten:
Unterstützte Länder
Wir können HTTPS-basierte APIs, die JSON-Anfragen akzeptieren und JSON-Antworten zurückgeben, unterstützen. Wenn wir den Ziel-Endpoint noch nicht unterstützen oder Sie ein anderes API-Format benötigen, geben Sie die Details des Endpoints an den Stripe-Support weiter, damit wir Ihren Ziel-Endpoint unterstützen können.
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.
Produktionsdaten teilen
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:
Berechnen Sie den Hash
SHA256
Ihres privaten Schlüssels und hexcodieren Sie den Hash. Behandeln Sie diesen Hash als Geheimschlüssel.Command Lineecho -n "{{THIRD_PARTY_SECRET_KEY}}" | sha256sum
Verschlüsseln Sie den Hash
SHA256
mit dem öffentlichen Schlüssel von Stripe, codieren Sie das Ergebnis mitBase64
und legen Sie den Stripe-Schlüssel alstrusted
fest.Command Lineecho -n "{{SHA256_HASH}}" | gpg -e -r AE863ADA1603150856C0A853A7B203177D034588 --always-trust | base64 > encrypted_base64.txt
Überprüfen Sie
encrypted_base64.txt
, indem Sie den folgenden Befehl ausführen:Command Linecat encrypted_base64.txt | base64 -d | gpg --list-only --list-packets
Stellen Sie sicher, dass die Datei encrypted_base64.txt
die folgenden Merkmale enthält:
- Schlüssel-ID:
27E4B9436302901A
- Schlüsseltyp: RSA
- Schlüsselgröße: 4.096 Bit
- Nutzer-ID:
Forward API Secret Encryption Key (Forward API Secret Encryption Key) <multiprocessor-ext@stripe.com>
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 Anfrage-Logs und Fehler im Zusammenhang mit der Vault and Forward API im Entwickler-Dashboard anzeigen. Darüber hinaus können Sie mit der List API die Logs 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.