Accéder directement au contenu
Créez un compte
 ou
connecter-vous
Logo de la documentation Stripe
/
Créez un compte
Connectez-vous
AperçuMettre votre intégration à niveau
Paiements en ligne
PrésentationTrouver votre cas d'usageManaged Payments
Moyens de paiement
Interfaces de paiement
Scénarios de paiement
Paiements par TPE
Au-delà des paiements

Transfert des informations de carte vers des endpoints d'API tiers

Comment utiliser l'API Vault and Forward pour partager en toute sécurité des informations de carte avec différents prestataires.

L’API Vault and Forward vous permet de tokeniser et de stocker les informations de carte bancaire sur Stripe, une solution sécurisée conforme à la norme PCI, puis d’acheminer ces données vers des endpoints ou prestataires autorisés. Avec l’API, vous pouvez :

Demander un accès

Pour obtenir un accès au service de transfert de Stripe, contactez le service Support de Stripe.

Transmettre les demandes aux endpoints de destination et renseigner les informations de carte à partir du système de stockage sécurisé de Stripe

Collecter des informations de carte et créer un PaymentMethod

Pour collecter les informations de carte, utilisez le Payment Element afin de créer un PaymentMethod. Une fois que vous avez créé un PaymentMethod, nous stockons automatiquement les informations de la carte dans le système sécurisé de Stripe, conforme aux normes PCI. Si vous avez votre propre front-end, vous pouvez toujours utiliser l’API Vault and Forward en créant directement un PaymentMethod.

En règle générale, vous ne pouvez réutiliser les PaymentMethods qu’en les associant à un objet Customer. Cependant, l’API Vault and Forward accepte tous les objets PaymentMethod, y compris ceux qui ne sont pas rattachés à un client.

De même, l’API Vault and Forward ne confirme ni ne capture les PaymentIntents. De ce fait, il est possible que vous les utilisiez par erreur pour capturer sur Stripe un paiement déjà capturé sur un autre prestataire de services de paiement.

Les CVC expirent automatiquement après une certaine période et expirent également lorsqu’ils sont utilisés avec l’API Vault and Forward. Si vous avez besoin d’un CVC après que l’une ou l’autre de ces conditions a été remplie, vous devez recollecter les informations de la carte.

Créer une ForwardingRequest

Pour envoyer des informations de carte depuis le système sécurisé de Stripe, vous devez créer une ForwardingRequest et y inclure les paramètres suivants :

  • payment_method : objet qui permet à Stripe de trouver les informations de carte bancaire de votre client dans ses données et de les insérer dans le corps de la requête.
  • url : le endpoint de destination exact de votre requête.
  • request.body : le corps de la requête API que vous souhaitez envoyer au endpoint de destination (par exemple, l’envoi d’une demande de paiement à un autre prestataire de services de paiement). Le champ dans lequel vous saisissez habituellement les informations de carte bancaire de votre client doit rester vide.
  • replacements : les champs que vous souhaitez que Stripe remplace dans le request.body. Les champs disponibles que nous recommandons de toujours définir sont card_number, card_expiry, card_cvc, et cardholder_name. Par exemple, l’inclusion de card_number dans le tableau replacements remplace le champ de numéro de carte approprié pour votre endpoint de destination dans le request.body.

Mise en garde

Stripe peut être plus indulgent que d’autres sous-traitants dans la validation du champ du nom du titulaire de la carte. Si vous utilisez le champ de remplacement cardholder_name, vous devez vous assurer que les noms que vous utilisez passent la validation imposée par l’endpoint de destination. Par exemple, si l’endpoint de destination s’attend à ce que tous les noms ne contiennent que les lettres A à Z, sans accent ou autre système d’écriture, vous devez vérifier que les informations bancaires que vous transmettez répondent à cette exigence. Une autre solution consiste à ne pas utiliser le champ de remplacement cardholder_name et à préciser le nom du titulaire de la carte directement dans le corps de votre demande.

Vous devez formater votre requête en fonction des données attendues par l’endpoint de destination. Dans l’exemple ci-dessous, l’endpoint de destination attend un en-tête Idempotency-Key et accepte un corps de requête JSON contenant les informations de paiement.

Command Line
curl https://api.stripe.com/v1/forwarding/requests \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -H "Idempotency-Key: 
{{IDEMPOTENCY_KEY}}
" \
  -d payment_method=
{{PAYMENT_METHOD_ID}}
 \
  --data-urlencode url="https://endpoint-url/v1/payments" \
  -d "request[headers][0][name]"=Destination-API-Key \
  -d "request[headers][0][value]"={{DESTINATION_API_KEY}} \
  -d "request[headers][1][name]"=Destination-Idempotency-Key \
  -d "request[headers][1][value]"={{DESTINATION_IDEMPOTENCY_KEY}} \
  --data-urlencode "request[body]"="{\"amount\":{\"value\":1000,\"currency\":\"usd\"},\"paymentMethod\":{\"number\":\"\",\"expiryMonth\":\"\",\"expiryYear\":\"\",\"cvc\":\"\",\"holderName\":\"\"},\"reference\":\"{{REFERENCE_ID}}\"}" \
  -d "replacements[0]"=card_number \
  -d "replacements[1]"=card_expiry \
  -d "replacements[2]"=card_cvc \
  -d "replacements[3]"=cardholder_name

Conseil en matière de sécurité

Nous vous demandons de transmettre les clés API pour le endpoint de destination lors de chaque demande API. Stripe transmet la demande en utilisant les clés API que vous fournissez, et ne conserve que les versions hachées et chiffrées des clés API du endpoint de destination.

Mise en garde

Vous pouvez fournir une Idempotency-Key (clé d’impotence) Stripe pour vous assurer que les requêtes utilisant la même clé n’aboutissent qu’à une seule requête sortante. Utilisez une clé différente et unique pour Stripe et toutes les clés d’idempotence que vous fournissez dans la requête tierce sous-jacente.

Utilisez un nouveau Idempotency-Key chaque fois que vous apportez des modifications aux champs request.body ou request.header. La transmission de l’ancienne clé d’idempotence entraîne la relecture par l’API des réponses plus anciennes, y compris les erreurs de validation précédentes ou les erreurs d’endpoint de destination. Nous vous recommandons d’utiliser une nouvelle clé d’idempotence lorsque vous relancez des demandes qui ont rencontré une erreur atteignant l’endpoint de destination pour vous assurer que la demande est relancée à la destination.

Transmettre la requête avec les informations de carte

Stripe envoie une requête au endpoint de destination en votre nom en insérant les informations de carte du PaymentMethod dans le champ request.body. Lorsqu’il est activé et disponible, l’outil de mise à jour de carte tente automatiquement de mettre à jour les données et de fournir les dernières informations de carte disponibles pour les requêtes.

Stripe transmet ensuite la requête à l’endpoint de destination. Par exemple :

  1. Stripe envoie une requête POST à l’endpoint :

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

  2. Stripe inclut les en-têtes suivants :

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

  3. Stripe inclut le corps JSON suivant dans la requête :

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

Remarque

Si vous utilisez l’API Vault and Forward pour effectuer une demande d’autorisation, vous devez traiter toutes les actions post-transaction éventuelles, telles que les remboursements et les litiges, directement auprès du prestataire de services de paiement tiers. Contactez le service Support de Stripe si vous avez besoin d’activer l’authentification 3DS dans une configuration à plusieurs prestataires.

Traiter la réponse du endpoint de destination

Lorsque vous utilisez l’API Vault and Forward pour transmettre les informations de carte à un prestataire de services de paiement tiers, Stripe attend une réponse synchrone de l’endpoint de destination. Le délai d’attente de cette réponse est inférieur à une minute. Stripe expurge les données sensibles PCI identifiées, stocke la réponse expurgée de l’endpoint de destination et renvoie un objet ForwardingRequest qui contient des données sur la requête et la réponse.

Mise en garde

Lorsque vous utilisez l’API Vault and Forward pour transmettre des informations de carte à un prestataire de services de paiement tiers, Stripe ne peut pas garantir la réponse fournie par le prestataire à vos requêtes API transférées. Si le prestataire ne répond pas, vous devez le contacter directement pour résoudre le problème.

{
  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"
  ]
  ...
}

Configurer votre endpoint d’API Vault and Forward

Pour configurer votre endpoint d’API Vault and Forward, vous devez :

Vérifier que nous prenons en charge l’endpoint de destination

Stripe prend en charge le transfert des requêtes API vers les endpoints suivants :

  • 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 Payment 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
  • Votre propre système de stockage des tokens, conforme à la norme PCI

Stripe prend en charge les API reposant sur le protocole HTTPS qui acceptent les requêtes JSON/XML et renvoient des réponses JSON/XML. Si votre endpoint n’est pas pris en charge ou si vous avez besoin d’un format d’API différent, communiquez les détails de l’endpoint auservice Support de Stripe afin d’obtenir de l’aide.

Pays pris en charge

L’API Vault and Forward peut uniquement transférer des requêtes vers les pays suivants :

Pays admissibles à la transmission des requêtes

En outre, assurez-vous que votre compte Stripe est établi dans l’un de ces pays :

Pays éligibles à l'API Vault and Forward

Fournir des comptes de test au service Support de Stripe

Pour accéder à l’API Vault and Forward, partagez les identifiants de compte (acct_xxxx) de vos comptes de test avec le service Support de Stripe.

Partager des informations de production

Communiquez les informations de production concernant votre endpoint de destination au service Support de Stripe en précisant notamment les éléments suivants : URL, méthode HTTP, documentation, champs, en-têtes des requêtes et clés de chiffrement. Stripe configure ensuite votre endpoint de destination pour une utilisation avec l’API Vault and Forward en mode production.

Pour partager des clés API tierces, vous devez les chiffrer à l’aide de la clé publique de Stripe spécifique à l’API Vault and Forward. Commencez par importer une clé publique à l’aide du PGP GNU Privacy Guard. Familiarisez-vous avec les principes de bases de PGP, puis utilisez la clé PGP suivante pour chiffrer vos clés API tierces :

Clé PGP de l'API Vault and Forward

Pour chiffrer vos clés API tierces avec la clé PGP de l’API Vault and Forward :

  1. Créez un fichier nommé hash_encrypt_key.sh avec le contenu ci-dessous. Le script génère un hachage SHA256 pour votre clé API, le chiffre à l’aide de la clé publique de Stripe, puis l’encode en fonction de Base64.

    Utilitaires requis

    Pour exécuter le script, vous devez d’abord installer les utilitaires sha256sum, gpg et base64.

    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"

  2. Exécutez le script en transmettant votre clé API tierce entre guillemets simples, en omettant tout préfixe Bearer ou Basic. La clé doit correspondre exactement à celle que vous utilisez pour les requêtes réelles au endpoint de destination, sans inclure de préfixe.

    Le script produit un fichier nommé encrypted_hashed_key.txt.

    Command Line
    sh hash_encrypt_key.sh '<THIRD_PARTY_API_KEY>'

Tester votre intégration

Pour confirmer que votre intégration fonctionne correctement avec votre endpoint de destination, lancez une ForwardingRequest en utilisant le PaymentMethod que vous avez créé. Cet exemple utilise pm_card_visa comme moyen de paiement.

Command Line
curl https://api.stripe.com/v1/forwarding/requests \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -H "Idempotency-Key: 
{{IDEMPOTENCY_KEY}}
" \
  -d payment_method=pm_card_visa \
  -d url="{{DESTINATION ENDPOINT}}" \
  -d "request[headers][0][name]"=Destination-API-Key \
  -d "request[headers][0][value]"={{DESTINATION_API_KEY}} \
  -d "request[headers][1][name]"=Destination-Idempotency-Key \
  -d "request[headers][1][value]"={{DESTINATION_IDEMPOTENCY_KEY}} \
  --data-urlencode "request[body]"="{\"amount\":{\"value\":1000,\"currency\":\"usd\"},\"paymentMethod\":{\"number\":\"\",\"expiryMonth\":\"\",\"expiryYear\":\"\",\"cvc\":\"\",\"holderName\":\"\"},\"reference\":\"{{REFERENCE_ID}}\"}" \
  -d "replacements[0]"=card_number \
  -d "replacements[1]"=card_expiry \
  -d "replacements[2]"=card_cvc \
  -d "replacements[3]"=cardholder_name

Mise en garde

L’API Vault and Forward traite toutes les réponses de l’endpoint de destination comme une réussite (success) et renvoie un code d’état 200, ainsi que le code de réponse de l’endpoint de destination dans le fichier response.body. Par exemple, lorsque l’endpoint de destination renvoie un code d’état 400 à Stripe, l’API Vault and Forward répond avec un code d’état 200. Le fichier response.body inclut la réponse 400 de l’endpoint de destination et le message d’erreur. Testez séparément la requête API que vous envoyez à votre endpoint de destination pour vous assurer que vous n’avez pas d’erreurs.

Consulter le log des requêtes dans le Dashboard

Vous pouvez consulter le log des requêtes et les erreurs liées à l’API Vault and Forward dans Workbench. Par ailleurs, vous pouvez utiliser l’API List pour récupérer les logs depuis Stripe.

Conseil en matière de sécurité

Les paramètres request.headers et request.body de la requête entrante sont chiffrés et apparaissent comme encrypted_request dans le Dashboard.

Cette page vous a-t-elle été utile ?
OuiNon
Besoin d'aide ? Contactez le service Support.
Rejoignez notre programme d'accès anticipé.
Consultez notre log des modifications.
Des questions ? Contactez l'équipe commerciale.
LLM ? Lire llms.txt.
Propulsé par Markdoc