Aller au contenu

PaymentSheet

PaymentSheet recueille les informations de paiement et confirme l’Intent en une seule présentation. Pour obtenir une carte en attente avec une confirmation ultérieure, utilisez PaymentFlow.

Image provenant de Gyazo

Utilisez un PaymentIntent pour débiter immédiatement, ou un SetupIntent pour enregistrer un moyen de paiement pour plus tard. Créez ces objets sur votre serveur. Consultez Intégration serveur.

Prise en charge des plateformes

Plateforme PaymentSheet
iOS PaymentSheet natif de Stripe
Android PaymentSheet natif de Stripe
Web Modale de saisie de carte stripe-pwa-elements

Le Web n’affiche pas le PaymentSheet natif. Sur le Web, createPaymentSheet utilise paymentIntentClientSecret et l’option facultative withZipCode ; l’implémentation Web actuelle ne prend pas en charge les SetupIntents. Les options réservées au natif, comme defaultBillingDetails, shippingDetails, billingDetailsCollectionConfiguration, enableApplePay, enableGooglePay, style et returnURL, sont ignorées.

1. createPaymentSheet

Récupérez les secrets utilisables côté client depuis votre backend, puis appelez createPaymentSheet. Le plugin ne communique pas avec l’API secrète de Stripe. Utilisez HttpClient, fetch ou tout autre client HTTP.

Sur iOS et Android, fournissez soit paymentIntentClientSecret, soit setupIntentClientSecret. Sur le Web, fournissez paymentIntentClientSecret. customerId et customerEphemeralKeySecret sont facultatifs ensemble. Si vous définissez customerId, vous devez également définir customerEphemeralKeySecret. Un PaymentIntent sans Customer est valide ; consultez la structure de démonstration intent/without-customer dans Intégration serveur.

import { firstValueFrom } from 'rxjs';
import { PaymentSheetEventsEnum, Stripe } from '@capacitor-community/stripe';

const { paymentIntent, ephemeralKey, customer } = await firstValueFrom(
  this.http.post<{
    paymentIntent: string;
    ephemeralKey: string;
    customer: string;
  }>(environment.api + 'intent', {}),
);

await Stripe.createPaymentSheet({
  paymentIntentClientSecret: paymentIntent,
  customerId: customer,
  customerEphemeralKeySecret: ephemeralKey,
  merchantDisplayName: 'rdlabo',
});

method createPaymentSheet(...)

Crée et configure une instance de PaymentSheet. Attendez la résolution de cette Promise ou l’événement Loaded avant d’appeler presentPaymentSheet().

createPaymentSheet(options: CreatePaymentSheetOption) => Promise<void>

interface CreatePaymentSheetOption

Propriété Type Description Valeur par défaut Depuis
paymentIntentClientSecret string Secret client du PaymentIntent à confirmer. Fournissez exactement l’un des deux paramètres : paymentIntentClientSecret ou setupIntentClientSecret. 3.0.0
setupIntentClientSecret string Secret client du SetupIntent utilisé pour enregistrer un moyen de paiement. Fournissez exactement l’un des deux paramètres : paymentIntentClientSecret ou setupIntentClientSecret. 3.0.0
defaultBillingDetails DefaultBillingDetails Coordonnées de facturation utilisées pour préremplir PaymentSheet. iOS et Android uniquement. https://docs.stripe.com/payments/mobile/collect-addresses?payment-ui=mobile&platform=ios#set-default-billing-details 7.2.0
shippingDetails AddressDetails Coordonnées de livraison utilisées pour préremplir PaymentSheet. Android uniquement ; sur iOS, utilisez plutôt l’élément d’adresse de Stripe. https://docs.stripe.com/payments/mobile/collect-addresses?payment-ui=mobile&platform=android#prefill-addresses 7.2.0
billingDetailsCollectionConfiguration BillingDetailsCollectionConfiguration Détermine les coordonnées de facturation recueillies par PaymentSheet. iOS et Android uniquement. https://docs.stripe.com/payments/mobile/collect-addresses?payment-ui=mobile&platform=ios#customize-billing-details-collection 7.2.0
customerEphemeralKeySecret string Secret de clé éphémère du client renvoyé par votre serveur. Utilisez-le avec customerId ; ne fournissez jamais un seul de ces deux paramètres. 3.0.0
customerId string Identifiant Stripe Customer associé à customerEphemeralKeySecret. 3.0.0
enableApplePay boolean Active Apple Pay dans le PaymentSheet natif. iOS uniquement. false 3.3.0
applePayMerchantId string Identifiant de commerçant Apple configuré pour l’application. Obligatoire lorsque enableApplePay vaut true ; ignoré sinon. 3.3.0
enableGooglePay boolean Active Google Pay dans le PaymentSheet natif. Android uniquement. false 3.2.0
GooglePayIsTesting boolean Utilise l’environnement de test Google Pay. Android uniquement. false 3.2.0
countryCode string Code de pays ISO 3166-1 à deux lettres utilisé par Apple Pay ou Google Pay. Ignoré si aucun des deux portefeuilles n’est activé. "US" 3.2.0
merchantDisplayName string Nom du commerçant affiché dans le PaymentSheet natif. "App Name" 3.0.0
returnURL string Schéma d’URL personnalisé utilisé pour revenir à l’application après une authentification par redirection. iOS uniquement. Sans cette configuration, Stripe ne propose pas les moyens de paiement par redirection qui seraient autrement admissibles. Transmettez l’URL de retour à handleURLCallback depuis le gestionnaire d’URL de l’application. "" 3.0.0
paymentMethodLayout 'automatic' | 'horizontal' | 'vertical' Disposition des moyens de paiement dans PaymentSheet sur iOS et Android. "automatic" 7.2.2
allowsDelayedPaymentMethods boolean Affiche les moyens de paiement différés, tels que les comptes bancaires américains (ACH) et SEPA Debit, dans PaymentSheet sur iOS et Android. PaymentSheet les masque par défaut, car le règlement des fonds prend du temps. false 8.3.0
style 'alwaysLight' | 'alwaysDark' Personnalisation de l’apparence du PaymentSheet natif. iOS uniquement. undefined 3.0.0
withZipCode boolean Affiche le champ de code postal dans le formulaire Web de carte bancaire. Web uniquement. true 3.6.0
currencyCode string Code de devise ISO 4217 à trois lettres utilisé par Google Pay. Obligatoire lorsque Google Pay est activé pour un SetupIntent. "USD" 7.1.0

Les paramètres natifs facultatifs comprennent style (alwaysLight ou alwaysDark, sur iOS seulement), enableApplePay avec applePayMerchantId, enableGooglePay et les options de collecte des informations de facturation. Sur iOS, configurez returnURL et handleURLCallback pour PayPal, 3D Secure et les autres moyens de paiement avec redirection ; Stripe ne propose pas les moyens avec redirection autrement admissibles lorsqu’aucune URL de retour n’est disponible. Consultez Moyens de paiement avec redirection sur iOS. withZipCode est réservé au Web. currencyCode est obligatoire lorsque enableGooglePay est activé pour un SetupIntent.

Depuis la v8.3.0, définissez allowsDelayedPaymentMethods: true dans les options de création pour autoriser les moyens de paiement différés admissibles, comme ACH et SEPA Debit, sur iOS et Android. La valeur par défaut est false ; cette option n’a aucun effet sur le Web. Activez ces moyens de paiement dans Stripe et configurez l’Intent en conséquence. Un résultat Completed peut signifier que le paiement est encore en cours de traitement : attendez un webhook confirmant la réussite du paiement avant d’exécuter la commande. Consultez le guide Stripe sur les moyens de paiement différés.

2. presentPaymentSheet

Appelez presentPaymentSheet uniquement après la réussite de createPaymentSheet.

const result = await Stripe.presentPaymentSheet();
if (result.paymentResult === PaymentSheetEventsEnum.Completed) {
  // Mettez uniquement l’interface à jour. Vérifiez la réussite du paiement sur votre serveur par webhook avant d’exécuter la commande.
}

Sur le Web, une annulation résout la Promise avec paymentResult: PaymentSheetEventsEnum.Canceled ; traitez ce résultat sans vous appuyer uniquement sur catch. Traitez Canceled comme la fermeture de la feuille par le client et Failed comme une erreur. Aucun de ces résultats n’autorise à lui seul l’exécution d’une commande.

method presentPaymentSheet()

Présente le PaymentSheet créé par createPaymentSheet() et se résout avec son résultat : terminé, annulé ou échoué.

presentPaymentSheet() => Promise<{ paymentResult: PaymentSheetResultInterface; }>

type alias PaymentSheetResultInterface

PaymentSheetEventsEnum.Completed | PaymentSheetEventsEnum.Canceled | PaymentSheetEventsEnum.Failed

3. addListener

Enregistrez les écouteurs de résultat une seule fois au démarrage de l’application, avant de présenter la feuille. Préférez les événements à la Promise après une recréation de l’Activity Android. Consultez Écouteurs d’événements.

await Promise.all([
  Stripe.addListener(PaymentSheetEventsEnum.Completed, () => {
    console.log('PaymentSheetEventsEnum.Completed');
  }),
  Stripe.addListener(PaymentSheetEventsEnum.Canceled, () => {
    console.log('PaymentSheetEventsEnum.Canceled');
  }),
  Stripe.addListener(PaymentSheetEventsEnum.Failed, (error) => {
    console.log('PaymentSheetEventsEnum.Failed', error);
  }),
]);

enum PaymentSheetEventsEnum

Membre Valeur
Loaded 'paymentSheetLoaded'
FailedToLoad 'paymentSheetFailedToLoad'
Completed 'paymentSheetCompleted'
Canceled 'paymentSheetCanceled'
Failed 'paymentSheetFailed'

Référence

payment-sheet.ts
import { PaymentSheetEventsEnum, Stripe } from '@capacitor-community/stripe';

(async () => {
  await Stripe.addListener(PaymentSheetEventsEnum.Completed, () => {
    console.log('PaymentSheetEventsEnum.Completed');
  });

  // Replace `/your-intent-endpoint` with your backend from Server Integration.
  const response = await fetch('/your-intent-endpoint', {
    method: 'POST',
  });
  if (!response.ok) {
    throw new Error(`Intent request failed: ${response.status}`);
  }
  const { paymentIntent, ephemeralKey, customer } = (await response.json()) as {
    paymentIntent: string;
    ephemeralKey: string;
    customer: string;
  };

  // prepare PaymentSheet with CreatePaymentSheetOption.
  await Stripe.createPaymentSheet({
    paymentIntentClientSecret: paymentIntent,
    customerId: customer,
    customerEphemeralKeySecret: ephemeralKey,
  });

  // present PaymentSheet and get result.
  const result = await Stripe.presentPaymentSheet();
  if (result.paymentResult === PaymentSheetEventsEnum.Completed) {
    // Update UI only. Fulfill orders from a verified server webhook.
  }
})();