Ajouter des moyens de paiement personnalisés

Utilisez le composant Payment Element avec l’API Checkout Sessions pour activer les paiements initiés par le commerçant.

Stripe inclut un moyen de paiement personnalisé PayPal préconfiguré qui utilise un adaptateur Stripe que vous pouvez héberger dans votre environnement et intégrer nativement avec Checkout.

Effectuez les étapes nécessaires au déploiement de l’adaptateur PayPal et configurez votre intégration avant de continuer.

// Set your secret key. Remember to switch to your live secret key in production.
// See your keys here: https://dashboard.stripe.com/apikeys
const stripe = require('stripe')('sk_test_...', {
  apiVersion: '2025-03-31.basil; checkout_merchant_instructed_orchestration_preview=v1;',
});

Configurer la Checkout Session

Transmettez custom_payment_method_types=['cpmt_...'] lorsque vous créez la session Checkout pour afficher votre moyen de paiement PayPal. Vous pouvez consulter vos moyens de paiement et identifiants personnalisés sur la page Moyens de paiement personnalisés du Dashboard.

const stripe = require('stripe')('sk_test_...', {
  apiVersion: '2025-03-31.basil; checkout_merchant_instructed_orchestration_preview=v1;',
});

const session = await stripe.checkout.sessions.create({
  ui_mode: 'custom',
  // 'setup' mode isn't available for this private preview.
  mode: 'payment' | 'subscription',
  custom_payment_method_types: ['cpmt_1RyfcvBYVDeTVJWf0MxpDkkf'],

  // You can still pass payment_method_types to indicate
  // which Stripe-supported payment methods this Checkout Session accepts.
  payment_method_types: ['card', ...],

  // Or, if using dynamic payment methods, you can continue using
  // payment method configurations.
  payment_method_configuration: 'pmc_123',
  ...
});

Les moyens de paiement dynamiques n’affichent pas de moyens de paiement personnalisés, mais vous pouvez utiliser les deux dans votre intégration. Le composant Element Payment ajoute des moyens de paiement personnalisés spécifiés après avoir appliqué la logique pour afficher les moyens de paiement pris en charge par Stripe.

Moyens de paiement Stripe

Moyen de paiement personnalisé

Changements côté client

Suivez le guide Elements avec Checkout Sessions pour les modifications côté client lorsque vous créez une page avec Stripe Elements utilisant l’API Checkout Sessions. Pour soumettre le paiement, affichez un bouton « Payer » qui appelle confirm depuis useCheckoutElements.

Limitations pour la version bêta privée

L’adaptateur PayPal est en version bêta privée et est soumis aux limitations suivantes.

Exigence de version d’API

Vous devez utiliser la version de l’API 2025-03-31.basil ou une version ultérieure. Consultez le journal des modifications de basil pour en savoir plus.

Prise en charge des fonctionnalités PayPal

• Conversion de devises : PayPal peut convertir automatiquement les paiements entrants dans la devise de votre choix. Stripe ne prend pas en charge ces transactions converties. Pour accepter les devises converties par PayPal, modifiez les paramètres de votre compte PayPal afin d’accepter chaque devise utilisée par vos clients pour le paiement et de conserver un solde dans cette devise.

Considérations relatives à la facturation

• Portail client : les clients peuvent gérer les abonnements en utilisant les moyens de paiement personnalisés existants dans le portail client, mais ne peuvent pas mettre à jour le moyen de paiement de l’abonnement vers un moyen de paiement personnalisé.
• Essais gratuits : les clients qui bénéficient d’essais gratuits dans le cadre de leur abonnement initial ne peuvent pas effectuer la transaction avec un moyen de paiement personnalisé.
• Recouvrement de revenus : Stripe tente de relancer les paiements échoués via l’adaptateur de moyens de paiement personnalisés, mais les paiements hors Stripe offrent une prise en charge limitée pour le recouvrement de revenus. Cette prise en charge permet les automatisations et les relances planifiées en cas d’échec de paiements, et est inclue dans l’analyse du recouvrement de revenus. Ne sont pris en charge ni les e-mails de recouvrement de revenus ni les Smart Retries, mais vous pouvez configurer les relances personnalisées. Vous pouvez également écouter des webhooks et envoyer des e-mails par voie programmatique aux clients.

Remarques relatives à Connect

• Paiements directs uniquement : l’adaptateur prend actuellement en charge les paiements directs, le type de paiement Connect avec lequel les clients effectuent des transactions directement avec le compte connecté.
• Aucuns frais d’application : vous ne pouvez pas collecter de frais d’application sur les paiements PayPal traités par l’adaptateur pendant la version bêta privée.
• Le compte traitant les paiements héberge l’adaptateur : le compte qui crée la transaction (par exemple, un compte connecté avec des paiements directs) doit déployer et héberger l’adaptateur dans son propre environnement. Vous ne pouvez pas partager l’adaptateur entre plusieurs comptes.
• Prise en charge plus large de Connect : les types de paiements supplémentaires (paiements indirects, paiements et transferts distincts) et les frais d’application ne sont pas pris en charge pendant la version bêta privée. Contactez votre représentant Stripe pour en savoir plus.

Prise en charge des paiements hors Stripe

• Remboursements : Stripe ne peut pas déclencher de remboursements pour les paiements hors Stripe. Vous devez rembourser directement les clients et signaler le remboursement à Stripe.

• Litiges : Stripe ne gère pas les litiges relatifs aux moyens de paiement personnalisés. Vous devez répondre aux litiges des prestataires tiers. Vous ne pouvez pas signaler les litiges sur les enregistrements de paiement pour le moment.
• Paiements échoués : l’enregistrement du paiement indique les échecs de paiement pour maintenir le fonctionnement des produits dépendants.
• Fraude : Radar ne prend pas en charge les moyens de paiement personnalisés hors Stripe. Checkout ne prend pas en charge l’intégration tierce de bibliothèques de fraude lors de la version bêta privée.
• Enregistrements des paiements : les transactions hors Stripe génèrent un objet Payment Record plutôt qu’un objet Payment Intent. L’enregistrement des paiements d’un moyen de paiement personnalisé affiche les états succès, échec et annulé.
• Reporting sur les paiements et les revenus unifié : certains graphiques du Dashboard ou certaines ressources Stripe (comme Balance Transactions) ne prennent pas en compte l’activité liée aux Payment Records. Dans certains cas, vous devrez peut-être joindre les données de l’API Payment Records pour obtenir un ensemble de données complet.

Remarques relatives à Checkout

• Flux avec redirection uniquement : les paiements PayPal effectués via l’adaptateur nécessitent actuellement une redirection pleine page vers PayPal pour obtenir l’autorisation du client. Cela s’applique à toute la page Checkout, aux composants Element Checkout et au formulaire intégré.

• Autres flux en cours : les flux PayPal modaux (fenêtres contextuelles) et du composant Element Express Checkout ne sont pas pris en charge pendant la version bêta privée.

• Disponibilité des moyens de paiement : lorsque vous ajoutez le moyen de paiement personnalisé PayPal à une Checkout Session, les moyens de paiement suivants ne sont pas disponibles :

  • Alipay
  • Prélèvement ACSS
  • BLIK
  • US bank account
    (uniquement disponible avec le composant Element Payment)

  Avec les moyens de paiement dynamiques, ces moyens de paiement n’apparaissent pas dans Checkout. Si vous les incluez dans payment_method_types, Stripe renvoie une erreur.

Adaptive Pricing

Adaptive Pricing ne fonctionne pas avec les moyens de paiement personnalisés. S’il est activé, Checkout présente aux clients soit des devises localisées, soit des moyens de paiement personnalisés.

Par exemple, Checkout montre à un client dans une région possédant une devise localisée, comme l’EUR, le sélecteur de devise pour lequel l’EUR est présélectionné, et le moyen de paiement PayPal personnalisé est masqué. Si le client sélectionne plutôt l’USD, il voit le moyen de paiement PayPal personnalisé. Les clients dans une région possédant une intégration de devise voient le moyen de paiement PayPal personnalisé et le sélecteur de devise est masqué.