Zum Inhalt springen

PaymentSheet

PaymentSheet erfasst Zahlungsdetails und bestätigt den Intent in einer einzigen Darstellung. Wenn Sie eine zunächst vorgemerkte Karte und einen späteren Bestätigungsschritt benötigen, verwenden Sie PaymentFlow.

Bild von Gyazo

Verwenden Sie einen PaymentIntent für eine sofortige Zahlung oder einen SetupIntent, um eine Zahlungsmethode für später zu speichern. Erstellen Sie diese Objekte auf Ihrem Server. Siehe Serverintegration.

Plattformunterstützung

Plattform PaymentSheet
iOS Natives Stripe-PaymentSheet
Android Natives Stripe-PaymentSheet
Web Karten-Modal von stripe-pwa-elements

Das Web rendert kein natives PaymentSheet. Im Web verwendet createPaymentSheet paymentIntentClientSecret und das optionale withZipCode. Die aktuelle Web-Implementierung unterstützt keine SetupIntents. Ausschließlich native Optionen wie defaultBillingDetails, shippingDetails, billingDetailsCollectionConfiguration, enableApplePay, enableGooglePay, style und returnURL werden ignoriert.

1. createPaymentSheet

Rufen Sie für den Client sichere Secrets von Ihrem Backend ab und rufen Sie anschließend createPaymentSheet auf. Das Plugin kommuniziert nicht mit der geheimen Stripe-API. Verwenden Sie HttpClient, fetch oder einen anderen HTTP-Client.

Übergeben Sie unter iOS und Android entweder paymentIntentClientSecret oder setupIntentClientSecret. Übergeben Sie im Web paymentIntentClientSecret. customerId und customerEphemeralKeySecret sind gemeinsam optional. Wenn Sie customerId setzen, müssen Sie auch customerEphemeralKeySecret setzen. Ein PaymentIntent ohne Customer ist gültig. Siehe die Demo-Struktur intent/without-customer unter Serverintegration.

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

Erstellt und konfiguriert eine PaymentSheet-Instanz. Vor
presentPaymentSheet() dieses Promise oder das Ereignis Loaded abwarten.

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

interface CreatePaymentSheetOption

Eigenschaft Typ Beschreibung Standard Seit
paymentIntentClientSecret string Client Secret des zu bestätigenden PaymentIntent. Genau einen der Werte paymentIntentClientSecret oder setupIntentClientSecret angeben. 3.0.0
setupIntentClientSecret string Client Secret des SetupIntent zum Speichern einer Zahlungsmethode. Genau einen der Werte paymentIntentClientSecret oder setupIntentClientSecret angeben. 3.0.0
defaultBillingDetails DefaultBillingDetails Rechnungsdaten zur Vorbelegung von PaymentSheet. Nur iOS und Android. https://docs.stripe.com/payments/mobile/collect-addresses?payment-ui=mobile&platform=ios#set-default-billing-details 7.2.0
shippingDetails AddressDetails Versanddaten zur Vorbelegung von PaymentSheet. Nur Android; unter iOS stattdessen das Adresselement von Stripe verwenden. https://docs.stripe.com/payments/mobile/collect-addresses?payment-ui=mobile&platform=android#prefill-addresses 7.2.0
billingDetailsCollectionConfiguration BillingDetailsCollectionConfiguration Legt fest, welche Rechnungsdaten PaymentSheet erfasst. Nur iOS und Android. https://docs.stripe.com/payments/mobile/collect-addresses?payment-ui=mobile&platform=ios#customize-billing-details-collection 7.2.0
customerEphemeralKeySecret string Vom Server zurückgegebenes Secret des temporären Kundenschlüssels. Zusammen mit customerId verwenden; nicht nur einen der beiden Werte angeben. 3.0.0
customerId string Dem customerEphemeralKeySecret zugeordnete Stripe-Kundenkennung. 3.0.0
enableApplePay boolean Aktiviert Apple Pay im nativen PaymentSheet. Nur iOS. false 3.3.0
applePayMerchantId string Für die App konfigurierte Apple-Händlerkennung. Erforderlich, wenn enableApplePay true ist; andernfalls wird sie ignoriert. 3.3.0
enableGooglePay boolean Aktiviert Google Pay im nativen PaymentSheet. Nur Android. false 3.2.0
GooglePayIsTesting boolean Verwendet die Google-Pay-Testumgebung. Nur Android. false 3.2.0
countryCode string Von Apple Pay oder Google Pay verwendeter zweibuchstabiger ISO-3166-1-Ländercode. Wird ignoriert, wenn keine der beiden Wallets aktiviert ist. "US" 3.2.0
merchantDisplayName string Im nativen PaymentSheet angezeigter Händlername. "App Name" 3.0.0
returnURL string Benutzerdefiniertes URL-Schema für die Rückkehr zur App nach einer Authentifizierung per Weiterleitung. Nur iOS. Ohne diese Konfiguration bietet Stripe ansonsten geeignete Zahlungsmethoden mit Weiterleitung nicht an. Übergeben Sie die Rückkehr-URL aus dem URL-Handler der App an handleURLCallback. "" 3.0.0
paymentMethodLayout 'automatic' | 'horizontal' | 'vertical' Layout für die Anzeige von Zahlungsmethoden in PaymentSheet auf iOS und Android. "automatic" 7.2.2
allowsDelayedPaymentMethods boolean Zeigt verzögerte Zahlungsmethoden wie US-Bankkonten (ACH) und SEPA Debit in PaymentSheet unter iOS und Android an. PaymentSheet blendet diese standardmäßig aus, da die Abwicklung der Zahlungen Zeit benötigt. false 8.3.0
style 'alwaysLight' | 'alwaysDark' Abweichende Darstellungseinstellungen für das native PaymentSheet. Nur iOS. undefined 3.0.0
withZipCode boolean Zeigt im Web-Kartenformular das Postleitzahlfeld an. Nur Web. true 3.6.0
currencyCode string Von Google Pay verwendeter dreibuchstabiger ISO-4217-Währungscode. Erforderlich, wenn Google Pay für einen SetupIntent aktiviert ist. "USD" 7.1.0

Optionale native Einstellungen umfassen style (alwaysLight oder alwaysDark, nur iOS), enableApplePay mit applePayMerchantId, enableGooglePay und Optionen zur Erfassung von Rechnungsdaten. Konfigurieren Sie unter iOS returnURL und handleURLCallback für PayPal, 3D Secure und andere weiterleitungsbasierte Zahlungsmethoden. Ohne Rückkehr-URL bietet Stripe ansonsten geeignete weiterleitungsbasierte Methoden nicht an. Siehe Weiterleitungsbasierte Zahlungsmethoden unter iOS. withZipCode ist ausschließlich für das Web bestimmt. currencyCode ist erforderlich, wenn enableGooglePay bei einem SetupIntent aktiviert ist.

Seit v8.3.0 können Sie in den Erstellungsoptionen allowsDelayedPaymentMethods: true setzen, um geeignete verzögerte Zahlungsmethoden wie ACH und SEPA Debit unter iOS und Android zuzulassen. Der Standardwert ist false; diese Option hat keine Auswirkung auf das Web. Aktivieren Sie die Methoden in Stripe und konfigurieren Sie den Intent entsprechend. Ein Ergebnis Completed kann bedeuten, dass die Zahlung noch verarbeitet wird: Warten Sie vor der Erfüllung der Bestellung auf einen Webhook, der die erfolgreiche Zahlung bestätigt. Siehe die Stripe-Anleitung zu verzögerten Zahlungsmethoden.

2. presentPaymentSheet

Rufen Sie presentPaymentSheet erst nach einem erfolgreichen createPaymentSheet auf.

const result = await Stripe.presentPaymentSheet();
if (result.paymentResult === PaymentSheetEventsEnum.Completed) {
  // Nur die UI aktualisieren. Vor der Leistungserbringung den Zahlungserfolg auf Ihrem Server per Webhook überprüfen.
}

Im Web wird das Promise bei einem Abbruch mit paymentResult: PaymentSheetEventsEnum.Canceled aufgelöst. Verarbeiten Sie dieses Ergebnis, statt sich ausschließlich auf catch zu verlassen. Behandeln Sie Canceled als Schließen des Sheets durch den Kunden. Behandeln Sie Failed als Fehler. Keines der Ergebnisse autorisiert allein die Erfüllung einer Bestellung.

method presentPaymentSheet()

Zeigt das mit createPaymentSheet() erstellte PaymentSheet an und wird
mit dem Ergebnis für Abschluss, Abbruch oder Fehlschlag aufgelöst.

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

type alias PaymentSheetResultInterface

PaymentSheetEventsEnum.Completed | PaymentSheetEventsEnum.Canceled | PaymentSheetEventsEnum.Failed

3. addListener

Registrieren Sie Ergebnis-Listener einmal beim Anwendungsstart, bevor Sie das Sheet anzeigen. Bevorzugen Sie nach der Neuerstellung einer Android-Activity Ereignisse gegenüber dem Promise. Siehe Ereignis-Listener.

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

Mitglied Wert
Loaded 'paymentSheetLoaded'
FailedToLoad 'paymentSheetFailedToLoad'
Completed 'paymentSheetCompleted'
Canceled 'paymentSheetCanceled'
Failed 'paymentSheetFailed'

Referenz

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