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.
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
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.
}
})();
