Capturer un paiement en plusieurs fois

Capturez un PaymentIntent en plusieurs fois, dans la limite du montant autorisé.

La multicapture vous permet de capturer plusieurs fois un PaymentIntent créé lors de l’étape de confirmation d’une CheckoutSession pour une seule transaction, dans la limite du montant total du PaymentIntent. Vous pouvez l’utiliser lorsque vous avez des commandes comportant plusieurs envois et que vous souhaitez capturer des fonds au fur et à mesure que vous traitez certaines parties de la commande.

Fonctionnalité IC+

La multicapture fait partie des fonctionnalités que nous proposons aux utilisateurs utilisant la tarification IC+. Si vous bénéficiez d’une tarification Stripe mixte et souhaitez accéder à cette fonctionnalité, contactez le support de Stripe.

Disponibilité

Lorsque vous utilisez la multicapture, tenez compte des restrictions suivantes :

Seuls les paiements par carte en ligne sont prise en charge
Elle est disponible avec Amex, Visa, Discover, Mastercard, Cartes Bancaires, Diners Club, China UnionPay (CUP) et Japan Credit Bureau (JCB)
Les flux de paiements et transferts distincts utilisant source_transaction ne sont pas pris en charge
Stripe vous permet d’effectuer jusqu’à 50 captures par PaymentIntent
mode est défini sur payment et capture_method est défini sur manual pour la CheckoutSession

Prise en charge de CUP et JCB

La multicapture CUP n’est disponible qu’aux États-Unis. La multicapture JCB n’est disponible qu’aux États-Unis, au Canada, en Australie et en Nouvelle-Zélande.

Bonnes pratiques

Lorsque vous effectuez plusieurs envois pour une même commande, communiquez à votre client final des informations sur chaque expédition de produits, et ce de manière proactive. Cela permet d’éviter les demandes d’informations et les contestations de paiement de la part de clients qui ne comprendraient pas pourquoi leur relevé bancaire affiche plusieurs transactions. Respectez les bonnes pratiques suivantes lorsque vous informez vos clients :

Juste avant l’achat, communiquez-leur la date de livraison estimée et le montant de chaque livraison.
Informez-les de chaque expédition en précisant le montant de la transaction.
Présentez à votre clientèle une politique de remboursement et d’annulation complète.

Vous pouvez utiliser le champ custom_text lorsque vous créez une nouvelle CheckoutSession pour afficher du texte supplémentaire sur la page de paiement afin de respecter les exigences de conformité.

Conformité

Lorsque vous utilisez la multicapture, vous êtes responsable du respect de l’ensemble des lois, réglementations et règles de réseau en vigueur. Consultez les règles des réseaux de cartes bancaires avec lesquels vous souhaitez utiliser cette fonctionnalité pour vous assurer que vos ventes sont conformes à toutes les règles applicables, qui varient d’un réseau à l’autre. Par exemple, la plupart des réseaux de cartes limitent l’utilisation de la multicapture aux transactions sans carte pour la vente de biens expédiés séparément. Certains réseaux de cartes autorisent la multicapture pour les entreprises en fonction de leur secteur d’activité (par exemple, le tourisme), tandis que d’autres ne l’autorisent pas pour les workflows de dépôt ou de paiement échelonné.

Les informations fournies sur cette page traitant de votre conformité à ces exigences le sont uniquement à titre indicatif, et ne constituent en rien des conseils juridiques, fiscaux, comptables ou autres. Si vous ne savez pas quelles obligations vous devez respecter, consultez un professionnel.

Créer une session Checkout

Sur votre serveur, créez une session Checkout et attribuez la valeur embedded au paramètre ui_mode. Vous pouvez configurer la session Checkout pour qu’elle inclue les postes de facture et d’autres options, par exemple la devise.

Pour rediriger vos clients vers une page personnalisée hébergée sur votre site Web, spécifiez l’URL de cette page dans le paramètre return_url. Incluez la variable de modèle {CHECKOUT_SESSION_ID} dans l’URL pour récupérer l’état de la session sur la page de retour. Checkout remplace automatiquement la variable par l’ID de session Checkout avant la redirection.

En savoir plus sur la configuration de la page de retour et d’autres options pour personnaliser le comportement de redirection.

Après avoir créé la session Checkout, utilisez la client_secret renvoyée dans la réponse pour monter Checkout.

Pour activer la fonctionnalité de multicapture, définissez request_multicapture sur if_available.

Moyens de paiement

Par défaut, Stripe active les cartes bancaires et autres moyens de paiement courants. Vous avez la possibilité d’activer ou de désactiver des moyens de paiement directement depuis le Dashboard Stripe. Dans Checkout, Stripe évalue la devise et les restrictions éventuelles, puis présente dynamiquement au client les moyens de paiement pris en charge.

Pour visualiser l’affichage des moyens de paiement pour les clients, saisissez un ID de transaction ou définissez le montant et la devise d’une commande dans le Dashboard.

Vous pouvez activer Apple Pay et Google Pay dans vos paramètres des moyens de paiement. Par défaut, Apple Pay est activé et Google Pay est désactivé. Cependant, dans certains cas, Stripe les filtre même lorsqu’ils sont activés. Nous filtrons Google Pay si vous activez les taxes automatiques sans collecter d’adresse de livraison.

Aucune modification de l’intégration n’est requise pour activer Apple Pay ou Google Pay dans les pages hébergées par Stripe de Checkout. Stripe gère ces paiements de la même manière que les autres paiements par carte bancaire.

Monter Checkout

Checkout est disponible dans Stripe.js. Intégrez le script Stripe.js à votre page en l’ajoutant à l’en-tête de votre fichier HTML. Ensuite, créez un nœud DOM vide (conteneur) à utiliser pour le montage.

index.html
<head>
  <script src="https://js.stripe.com/basil/stripe.js"></script>
</head>
<body>
  <div id="checkout">
    <!-- Checkout will insert the payment form here -->
  </div>
</body>

Initialisez Stripe.js avec votre clé API publique.

Créez une fonction fetchClientSecret asynchrone qui demande à votre serveur de créer la session Checkout et de récupérer la clé secrète du client. Transmettez cette fonction dans la propriété options lorsque vous créez l’instance Checkout :

index.js
// Initialize Stripe.js
const stripe = Stripe('pk_test_TYooMQauvdEDq54NiTphI7jx'
);

initialize();

// Fetch Checkout Session and retrieve the client secret
async function initialize() {
  const fetchClientSecret = async () => {
    const response = await fetch("/create-checkout-session", {
      method: "POST",
    });
    const { clientSecret } = await response.json();
    return clientSecret;
  };

  // Initialize Checkout
  const checkout = await stripe.initEmbeddedCheckout({
    fetchClientSecret,
  });

  // Mount Checkout
  checkout.mount('#checkout');
}

Checkout s’affiche dans un iframe qui envoie de manière sécurisée les informations de paiement à Stripe via une connexion HTTPS.

Erreur fréquente

Évitez de placer Checkout dans un autre iframe, car certains moyens de paiement nécessitent une redirection vers une autre page pour la confirmation du paiement.

Personnaliser l’apparence

Personnalisez Checkout pour qu’il corresponde au design de votre site en définissant la couleur d’arrière-plan, la couleur des boutons, le rayon de la bordure et les polices dans les paramètres de marque de votre compte.

Par défaut, Checkout s’affiche sans espacement externe ni marge. Nous vous recommandons d’utiliser un élément de conteneur tel qu’un espace div pour appliquer la marge souhaitée (par exemple, 16 px sur tous les côtés).

Afficher une page de retour

Une fois que votre client a effectué une tentative de paiement, Stripe le redirige vers une page de retour que vous hébergez sur votre site. Lors de la création de la session Checkout, vous avez renseigné l’URL de la page de retour dans le paramètre return_url. En savoir plus sur les autres options de personnalisation du comportement de redirection.

Lors de l’affichage de votre page de retour, récupérez l’état de la session Checkout à l’aide de l’ID de session Checkout dans l’URL. Traitez le résultat en fonction de l’état de la session comme suit :

complete : Le paiement a abouti. Utilisez les informations de la session Checkout pour afficher une page de confirmation.
open : Le paiement a échoué ou a été annulé. Montez à nouveau Checkout pour que votre client puisse effectuer une nouvelle tentative.

client.js
const session = await fetch(`/session_status?session_id=${session_id}`)
if (session.status == 'open') {
  // Remount embedded Checkout
} else if (session.status == 'complete') {
  // Show success page
  // Optionally use session.payment_status or session.customer_email
  // to customize the success page
}

Moyens de paiement avec redirection

Lors du paiement, certains moyens de paiement redirigent le client vers une page intermédiaire, comme la page d’autorisation de sa banque. Une fois qu’il a renseigné cette page, Stripe le redirige vers votre page de retour.

En savoir plus sur les moyens de paiement avec redirection et le comportement de redirection.

Capturer le PaymentIntent

Pour un PaymentIntent à l’état requires_capture pour lequel la multicapture est available, la configuration du paramètre facultatif final_capture sur false indique à Stripe de ne pas débloquer les fonds non capturés restants lors de l’appel de l’API de capture. Par exemple, si vous confirmez une intention de paiement de 10 USD, la capture de 7 USD avec l’attribut final_capture=false conserve l’autorisation pour les 3 USD restants.

Dans la réponse de capture du PI, les champs amount_capturable et amount_received sont mis à jour en conséquence.

// PaymentIntent Response
{
  "id": "pi_ANipwO3zNfjeWODtRPIg",
  "object": "payment_intent",
  "amount": 1000,
  "amount_capturable": 300, // 1000 - 700 = 300
  "amount_received": 700,
  // if latest_charge is expanded
  "latest_charge": {
      "id": "ch_xxx",
      "object": "charge",
      "amount": 1000,
      "amount_captured": 700,
      "amount_refunded": 0,
      ...
    }
  ...
}

Capture finale

Le PaymentIntent reste à l’état requires_capture jusqu’à ce que vous effectuiez l’une des actions suivantes :

Définissez final_capture sur true.
Effectuez une capture sans le paramètre final_capture (car final_capture est défini par défaut sur true).
La fenêtre d’autorisation expire.

À ce stade, Stripe libère les fonds restants et fait passer le PaymentIntent à l’état succeeded.

Dans la réponse de capture du PI, les champs amount_capturable et amount_received seront mis à jour en conséquence.

// PaymentIntent Response
{
  "id": "pi_ANipwO3zNfjeWODtRPIg",
  "object": "payment_intent",
  "amount": 1000,
  "amount_capturable": 0, // not 100 due to final_capture=true
  "amount_received": 900, // 700 + 200 = 900
  // if latest_charge is expanded
  "latest_charge": {
      "id": "ch_xxx",
      "object": "charge",
      "amount": 1000,
      "amount_captured": 900,
      "amount_refunded": 0,
      ...
    }
  ...
}

Les PaymentIntents non capturés passent à l’état canceled, tandis que les PaymentIntents partiellement capturés passent à succeeded.

FacultatifDébloquer les fonds non capturés

Tester votre intégration

Utilisez une carte de test Stripe avec n’importe quel CVC, code postal et date d’expiration postérieure à la date du jour pour tester les paiements multicapture.

Numéro	Moyen de paiement	Description
	`pm_card_visa`	Cette carte de test prend en charge la multicapture.
	`pm_card_visa_cartesBancaires`	Carte de test Cartes Bancaires ou Visa prenant en charge la multicapture.

Remboursements

Pour un PaymentIntent à l’état requires_capture, vous pouvez effectuer autant de remboursements que vous le souhaitez, dans la limite du montant total capturé moins le montant total remboursé, c’est-à-dire le montant amount_received-amount_refunded. Le champ charge.refunded ne passe à la valeur true que lorsque la capture finale est effectuée et que l’intégralité du amount_received est remboursée.

Stripe ne prend pas en charge les remboursements partiels avec des paramètres refund_application_fee=true ou reverse_transfer=true. Vous pouvez également effectuer des remboursements partiels de frais en procédant à des remboursements et annulations de transfert manuels, à l’aide des endpoints de remboursement des commissions de la plateforme et d’annulation de transfert. Après avoir utilisé les endpoints de remboursement des commissions de la plateforme ou d’annulation de transfert, Stripe ne prend plus en charge d’autres remboursements avec reverse_transfer=true ou refund_application_fee=true respectivement.

Connect

Les captures multiples sont compatibles avec tous les cas d’usage de Connect, à l’exception des paiements et transferts distincts dotés du paramètre source_transaction. Les paramètres application_fee_amount et transfer_data[amount] font l’objet de validations supplémentaires. Tenez compte des validations suivantes lors de l’implémentation des captures multiples avec Connect :

Si vous définissez les attributs application_fee_amount ou transfer_data[amount] lors de la première capture, ils seront obligatoires pour toutes les captures suivantes. Chaque application_fee_amount et transfer_data[amount] transmis au moment de la capture remplace les valeurs transmises lors de la création, de la confirmation et de la mise à jour de PaymentIntent.
Stripe ne prend pas en charge les remboursements partiels sur les paiements multicapture dotés du paramètre « refund_application_fee=true » ou « reverse_transfer=true ». Vous pouvez effectuer des remboursements partiels de frais ou des annulations de transfert à l’aide des endpoints de remboursement des commission de la plateforme et d’annulation de transfert.

Webhooks

Débiter les webhooks mis à jour

Nous envoyons un webhook charge.updated chaque fois que vous capturez un paiement.

Par exemple, lors de la première capture d’un paiement multicapture indirect avec application_fee_amount, nous modifions ces champs, passant de valeurs vides à des valeurs non vides.

// charge.updated
{
  "data": {
    "id": "ch_xxx",
    "object": "charge",
    "amount": 1000,
    "balance_transaction": "txn_xxx", // applicable to all charges
    "transfer": "tr_xxx",             // applicable to destination charges only
    "application_fee": "fee_xxx",     // applicable to Connect only
    ...
  },
  "previous_attributes": {
    "balance_transaction": null, // applicable to all charges
    "transfer": null,            // applicable to destination charges only
    "application_fee": null,     // applicable to Connect only
  }
}

payment_intent.amount_capturable_updated

Nous envoyons le payment_intent.amount_capturable_updated à chaque capture, quelles que soient les valeurs amount_to_capture et final_capture.

Par exemple, en capturant 1 USD d’un PaymentIntent d’un montant de 10 USD, le champ amount_capturable du PaymentIntent est mis à jour à 9 USD.

// payment_intent.amount_capturable_updated
{
  "data": {
    "id": "pi_xxx",
    "object": "payment_intent",
    "amount": 1000,
    "amount_capturable": 900 // 1000 - 100 = 900
     ...
  },
  "previous_attributes": {
    "amount_capturable": 1000
  }
}

Débiter les événements capturés

Nous envoyons un événement charge.captured pour les captures finales ou à la fin de la fenêtre d’autorisation pour annuler l’autorisation du montant non capturé. Le champ captured d’un paiement ne devient true qu’après une capture finale ou une annulation d’autorisation.

Par exemple, si nous effectuons une capture avec amount=0 et final_capture=true, l’attribut captured du paiement passe de false à true.

// charge.captured
{
  "data": {
    "id": "ch_xxx",
    "object": "charge",
    "captured": true
        ...
  },
  "previous_attributes": {
    "captured": false
  }
}

Rembourser des webhooks

Les webhooks de remboursement multicapture sont similaires aux webhooks de remboursement classiques.

Lors de chaque remboursement partiel, nous envoyons un événement refund.created. Pour les comptes connectés, nous envoyons également des événements application_fee.refunded lorsque nous remboursons une commission de plateforme, et des événements transfer.reversed lorsque nous annulons des transferts.