Details für zukünftige Zahlungen per ACH-Lastschrift speichern

Serverseitig

Diese Integration erfordert Endpoints auf Ihrem Server, die mit der Stripe-API kommunizieren können. Nutzen Sie unsere offiziellen Bibliotheken für den Zugriff auf die Stripe-API von Ihrem Server aus:

# Available as a gem
sudo gem install stripe

# If you use bundler, you can add this line to your Gemfile
gem 'stripe'

Clientseitig

Das React Native SDK ist Open Source und vollständig dokumentiert. Intern werden native iOS und Android SDKs verwendet. Um das React Native SDK von Stripe zu installieren, führen Sie einen der folgenden Befehle im Verzeichnis Ihres Projekts aus (je nachdem, welchen Paket-Manager Sie verwenden):

yarn add @stripe/stripe-react-native

Installieren Sie als Nächstes einige weitere erforderliche Abhängigkeiten:

• Navigieren Sie für iOS zum Verzeichnis ios und führen Sie pod install aus, um sicherzustellen, dass Sie auch die erforderlichen nativen Abhängigkeiten installieren.
• Für Android müssen keine Abhängigkeiten mehr installiert werden.

Stripe Initialisierung

Um Stripe in Ihrer React Native-App zu initialisieren, umschließen Sie entweder Ihren Zahlungsbildschirm mit der Komponente StripeProvider oder verwenden Sie die Initialisierungsmethode initStripe. Nur der veröffentlichbare API-Schlüssel in publishableKey ist erforderlich. Das folgende Beispiel zeigt, wie Stripe mithilfe der Komponente StripeProvider initialisiert wird.

import { useState, useEffect } from 'react';
import { StripeProvider } from '@stripe/stripe-react-native';

function App() {
  const [publishableKey, setPublishableKey] = useState('');

  const fetchPublishableKey = async () => {
    const key = await fetchKey(); // fetch key from your server here
    setPublishableKey(key);
  };

  useEffect(() => {
    fetchPublishableKey();
  }, []);

  return (
    <StripeProvider
      publishableKey={publishableKey}
      merchantIdentifier="merchant.identifier" // required for Apple Pay
      urlScheme="your-url-scheme" // required for 3D Secure and bank redirects
    >
      {/* Your app code here */}
    </StripeProvider>
  );
}

Erstellen Sie ein Kundenobjekt, wenn Ihr/e Nutzer/in ein Konto bei Ihrem Unternehmen erstellt, oder rufen Sie einen bestehenden Kunden/eine bestehende Kundin ab, der/die diesem Nutzer/dieser Nutzerin zugeordnet ist. Wenn Sie die ID des Kundenobjekts mit Ihrer eigenen Darstellung eines Kunden/einer Kundin verknüpfen, können Sie die gespeicherten Angaben zur Zahlungsmethode später abrufen und verwenden. Geben Sie eine E-Mail-Adresse an, um die Optimierung für wiederkehrende Nutzer/innen von Financial Connections zu aktivieren.

curl https://api.stripe.com/v1/customers \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d email={{CUSTOMER_EMAIL}}

Ein SetupIntent ist ein Objekt, mit dem Sie eine Zahlungsmethode eines Kunden/einer Kundin für zukünftige Zahlungen einrichten können. Der SetupIntent verfolgt die Schritte dieses Einrichtungsvorgangs.

Erstellen Sie einen SetupIntent auf Ihrem Server. Setzen Sie dabei payment_method_types auf us_bank_account und geben Sie die id der Kundin/des Kunden an.

Serverseitig

Erstellen Sie einen SetupIntent auf Ihrem Server. Setzen Sie dabei payment_method_types auf us_bank_account und geben Sie die id der Kundin/des Kunden an.

Bei der Erfassung von Zahlungsinformationen für Bankkonten wird standardmäßig Financial Connections verwendet, um das Konto Ihres Kunden/Ihrer Kundin sofort zu verifizieren, mit einer Ausweichoption für die manuelle Eingabe der Kontonummer und die Verifizierung von Testeinzahlungen. In der Financial Connections-Dokumentation erfahren Sie, wie Sie Financial Connections konfigurieren und auf zusätzliche Kontodaten zugreifen, um Ihre ACH-Integration zu optimieren. Beispielsweise können Sie Financial Connections verwenden, um den Kontostand zu prüfen, bevor Sie die ACH-Zahlung veranlassen.

curl https://api.stripe.com/v1/setup_intents \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d customer={{CUSTOMER_ID}} \
  -d "payment_method_types[]"=us_bank_account \
  -d "payment_method_options[us_bank_account][financial_connections][permissions][]"=payment_method \
  -d "payment_method_options[us_bank_account][financial_connections][permissions][]"=balances

Clientseitig

Ein SetupIntent enthält ein Client-Geheimnis. Sie können das Client-Geheimnis in Ihrer React Native-App verwenden, um den Zahlungsvorgang sicher abzuschließen, anstatt das gesamte SetupIntent-Objekt zurückzugeben. Fordern Sie in Ihrer App einen SetupIntent von Ihrem Server an und speichern Sie dessen Client-Geheimnis.

function PaymentScreen() {
  // ...

  const fetchIntentClientSecret = async () => {
    const response = await fetch(`${API_URL}/create-intent`, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        // This is an example request body, the parameters you pass are up to you
        customer: '<CUSTOMER_ID>',
      }),
    });
    const {clientSecret} = await response.json();

    return clientSecret;
  };

  return <View>...</View>;
}

Anstatt das gesamte SetupIntent-Objekt an den Client zu übermitteln, verwenden Sie dessen Client-Geheimnis aus dem vorherigen Schritt. Dieses unterscheidet sich von Ihren API-Schlüsseln, mit denen Anfragen der Stripe API authentifiziert werden.

Gehen Sie sorgfältig mit dem Client-Geheimnis um, denn es kann die Zahlung abschließen. Protokollieren Sie es nicht, betten Sie es nicht in URLs ein und geben Sie es nur dem/der Kund/in preis.

Verwenden Sie collectBankAccountForSetup, um Bankkontodaten zu erfassen, eine PaymentMethod zu erstellen und diese PaymentMethod dem SetupIntent hinzuzufügen. Sie müssen den Namen des Kontoinhabers/der Kontoinhaberin im Parameter billingDetails angeben, um eine PaymentMethod vom Typ ACH Direct Debit zu erstellen.

import {collectBankAccountForSetup} from '@stripe/stripe-react-native';

export default function MyPaymentScreen() {
  const [name, setName] = useState('');

  const handleCollectBankAccountPress = async () => {
    // Fetch the intent client secret from the backend.
    // See `fetchIntentClientSecret()`'s implementation above.
    const {clientSecret} = await fetchIntentClientSecret();

    const {setupIntent, error} = await collectBankAccountForSetup(
      clientSecret,
      {
        paymentMethodType: 'USBankAccount',
        paymentMethodData: {
          billingDetails: {
            name: "John Doe",
          },
        },
      },
    );

    if (error) {
      Alert.alert(`Error code: ${error.code}`, error.message);
    } else if (setupIntent) {
      Alert.alert('Setup status:', setupIntent.status);
      if (setupIntent.status === SetupIntents.Status.RequiresConfirmation) {
        // The next step is to call `confirmSetup`
      } else if (setupIntent.status === SetupIntents.Status.RequiresAction) {
        // The next step is to call `verifyMicrodepositsForSetup`
      }
    }
  };

  return (
    <PaymentScreen>
      <TextInput
        placeholder="Name"
        onChange={(value) => setName(value.nativeEvent.text)}
      />
      <Button
        onPress={handleCollectBankAccountPress}
        title="Collect bank account"
      />
    </PaymentScreen>
  );
}

Dadurch wird ein Nutzeroberflächen-Modal geladen, das die Erfassung und Überprüfung der Bankkontodaten abwickelt. Wenn dies abgeschlossen ist, wird die PaymentMethod automatisch an den SetupIntent angehängt.

When a customer exits your app (for example to authenticate in Safari or their banking app), provide a way for them to automatically return to your app. Many payment method types require a return URL. If you don’t provide one, we can’t present payment methods that require a return URL to your users, even if you’ve enabled them.

So geben Sie eine Rückgabe-URL an:

1. Registrieren Sie eine benutzerdefinierte URL. Universelle Links werden nicht unterstützt.
2. Konfigurieren Sie Ihre benutzerdefinierte URL.
3. Richten Sie Ihre Root-Komponente so ein, dass sie die URL an das Stripe SDK weitergibt, wie unten gezeigt.

import { useEffect, useCallback } from 'react';
import { Linking } from 'react-native';
import { useStripe } from '@stripe/stripe-react-native';

export default function MyApp() {
  const { handleURLCallback } = useStripe();

  const handleDeepLink = useCallback(
    async (url: string | null) => {
      if (url) {
        const stripeHandled = await handleURLCallback(url);
        if (stripeHandled) {
          // This was a Stripe URL - you can return or add extra handling here as you see fit
        } else {
          // This was NOT a Stripe URL – handle as you normally would
        }
      }
    },
    [handleURLCallback]
  );

  useEffect(() => {
    const getUrlAsync = async () => {
      const initialUrl = await Linking.getInitialURL();
      handleDeepLink(initialUrl);
    };

    getUrlAsync();

    const deepLinkListener = Linking.addEventListener(
      'url',
      (event: { url: string }) => {
        handleDeepLink(event.url);
      }
    );

    return () => deepLinkListener.remove();
  }, [handleDeepLink]);

  return (
    <View>
      <AwesomeAppComponent />
    </View>
  );
}

Weitere Informationen zu nativen URL-Schemen finden Sie in der Dokumentation für Android und iOS.

Bevor Sie den SetupIntent abschließen und die Zahlungsmethodendetails für den/die Kund/in speichern können, müssen Sie eine Zahlungsautorisierung einholen, indem Sie Mandatsbedingungen anzeigen, denen er/sie zustimmen muss.

Um die Nacha-Regeln einzuhalten, müssen Sie eine Autorisierung von Ihrem Kunden/Ihrer Kundin einholen, bevor Sie die Zahlung veranlassen können. Dies tun Sie durch Anzeigen von Mandatskonditionen, denen der Kunde/die Kundin zustimmen muss. Weitere Informationen finden Sie unter Mandate.

Wenn der/die Kund/in den Mandatskonditionen zustimmt, müssen Sie den SetupIntent bestätigen. Verwenden Sie confirmSetup, um den Intent zu bestätigen.

import {confirmSetup} from '@stripe/stripe-react-native';

export default function MyPaymentScreen() {
  const [name, setName] = useState('');

  const handleCollectBankAccountPress = async () => {
    // See above
  };

  const handlePayPress = async () => {
    // use the same clientSecret as earlier, see above
    const {error, setupIntent} = await confirmSetup(clientSecret, {
      type: 'USBankAccount',
    });

    if (error) {
      Alert.alert(`Error code: ${error.code}`, error.message);
    } else if (setupIntent) {
      if (setupIntent.status === SetupIntents.Status.Processing) {
        // The debit has been successfully submitted and is now processing
      } else if (
        setupIntent.status === SetupIntents.Status.RequiresAction &&
        setupIntent?.nextAction?.type === 'verifyWithMicrodeposits'
      ) {
        // The payment must be verified with `verifyMicrodepositsForPayment`
      } else {
        Alert.alert('Payment status:', setupIntent.status);
      }
    }
  };

  return (
    <PaymentScreen>
      <TextInput
        placeholder="Name"
        onChange={(value) => setName(value.nativeEvent.text)}
      />
      <Button
        onPress={handleCollectBankAccountPress}
        title="Collect bank account"
      />
      <Button onPress={handlePayPress} title="Pay" />
    </PaymentScreen>
  );
}

Bei erfolgreicher Ausführung gibt Stripe ein SetupIntent-Objekt mit einem der folgenden möglichen Status zurück:

Nach erfolgreicher Bestätigung des SetupIntent muss eine E-Mail-Bestätigung des Mandats und der erfassten Bankkontodaten an Ihren Kunden/Ihre Kundin gesendet werden. Stripe kümmert sich standardmäßig darum, aber Sie können auch nutzerdefinierte Benachrichtigungen senden, wenn Sie dies vorziehen.

Nicht alle Kund/innen können ihr Bankkonto sofort verifizieren. In diesen Fällen sendet Stripe eine Testeinzahlung an das Bankkonto. Es kann bis zu 1–2 Werktage dauern, bis diese Testeinzahlung auf dem Online-Kontoauszug des/der Kund/in angezeigt wird. Diese Einzahlung kann eine der beiden folgenden Formen haben:

• Code der Zahlungsbeschreibung. Stripe sendet eine einzelne Mikroeinzahlung über 0,01 USD an das Bankkonto des/der Kund/in mit einem einmaligen, 6-stelligen descriptorCode, der mit SM beginnt. Ihr/e Kund/in verwendet diese Zeichenfolge, um sein/ihr Bankkonto zu verifizieren.
• Betrag: Stripe sendet zwei nicht eindeutige Testeinzahlungen an das Kundenbankkonto, wobei ACCTVERIFY als Zahlungsbeschreibung in der Abrechnung angegeben ist. Ihre Kundin/Ihr Kunde verwendet die Einzahlungsbeträge zur Verifizierung des Bankkontos.

Das Ergebnis des Aufrufs der Methode confirmSetup im vorhergehenden Schritt ist ein SetupIntent mit dem Status requiresAction. Der SetupIntent enthält das Feld next_action, das einige nützliche Informationen zum Abschließen der Verifizierung enthält.

nextAction: {
  type: 'verifyWithMicrodeposits';
  redirectUrl: "https://payments.stripe.com/…",
  microdepositType: "descriptor_code";
  arrivalDate: "1647586800";
}

Wenn Sie eine E-Mail-Adresse für die Rechnungsstellungl angegeben haben, verwendet Stripe diese E-Mail-Adresse, um Ihren Kunden/Ihre Kundin zu benachrichtigen, wann wir den Eingang der Einzahlungen erwarten. Die E-Mail enthält einen Link zu einer von Stripe gehosteten Verifizierungsseite, auf der der Kunde/die Kundin die Beträge der Einzahlungen bestätigen und die Verifizierung abschließen kann.

Wenn Sie wissen, dass sich die Zahlung im Zustand requiresAction befindet und nextAction den Typ verifyWithMicrodeposits aufweist, können Sie die Verifizierung des Bankkontos auf zwei Arten abschließen:

1. Überprüfen Sie die Einzahlungen direkt in Ihrer App, indem Sie verifyMicrodepositsForSetup aufrufen, nachdem Sie entweder den Beschreibungscode oder die Beträge erfasst haben.

import { verifyMicrodepositsForSetup } from '@stripe/stripe-react-native';

export default function MyPaymentScreen() {
  const [verificationText, setVerificationText] = useState('');

  return (
    <TextInput
      placeholder="Descriptor code or comma-separated amounts"
      onChange={(value) => setVerificationText(value.nativeEvent.text)} // Validate and store your user's verification input
    />
    <Button
      title="Verify microdeposit"
      onPress={async () => {
        const { paymentIntent, error } =
          await verifyMicrodepositsForSetup(secret, {
            // Provide either the descriptorCode OR amounts, not both
            descriptorCode: verificationText,
            amounts: verificationText,
          });

        if (error) {
          Alert.alert(`Error code: ${error.code}`, error.message);
        } else if (paymentIntent) {
          Alert.alert('Payment status:', paymentIntent.status);
        }
      }}
    />
  );
}

1. Verwenden Sie die von Stripe gehostete Verifizierungsseite, die wir automatisch für Sie bereitstellen. Verwenden Sie dazu die URL nextAction[redirectUrl] im Objekt nextAction (siehe oben), um Ihre Kund/inn zum Abschluss des Verifizierungsprozesses zu leiten.

const {error, setupIntent} = await confirmSetup(clientSecret, {
  type: 'USBankAccount',
});

if (error) {
  Alert.alert(`Error code: ${error.code}`, error.message);
} else if (setupIntent) {
  if (
    setupIntent.status === SetupIntents.Status.RequiresAction &&
    setupIntent?.nextAction?.type === 'verifyWithMicrodeposits'
  ) {
    // Open the Stripe-hosted verification page
    Linking.openURL(setupIntent.nextAction.redirectUrl);
  } else {
    Alert.alert('Payment status:', setupIntent.status);
  }
}

Wenn das Bankkonto erfolgreich verifiziert wurde, gibt Stripe das SetupIntent-Objekt mit dem status Succeeded zurück und übermittelt das Webhook-Ereignis setup_intent.succeeded.

Die Verifizierung kann aus unterschiedlichen Gründen fehlschlagen. Der Fehler kann synchron als direkte Fehlermeldung oder asynchron über das Webhook-Ereignis setup_intent.setup_failed auftreten (wie in den folgenden Beispielen dargestellt).

{
  "error": {
    "code": "payment_method_microdeposit_verification_amounts_mismatch",
    "message": "The amounts provided do not match the amounts that were sent to the bank account. You have {attempts_remaining} verification attempts remaining.",
    "type": "invalid_request_error"
  }
}

Erfahren Sie, wie Sie Szenarien mit sofortigen Verifizierungen mithilfe von Financial Connections testen können.

Transaktions-E-Mails in einer Sandbox senden

Nachdem Sie die Bankkontodetails erfasst und ein Mandat akzeptiert haben, senden Sie die Mandatsbestätigung und die Verifizierungs-E-Mails mit Testeinzahlungen in einer Sandbox.

If your domain is {domain} and your username is {username}, use the the following email format to send test transaction emails: {username}+test_email@{domain}.

For example, if your domain is example.com and your username is info, use the format info+test_email@example.com for testing ACH Direct Debit payments. This format ensures that emails route correctly. If you don’t include the +test_email suffix, we won’t send the email.

Testkontonummern

Stripe stellt mehrere Testkontonummern und dazugehörige Token zur Verfügung, um sicherzustellen, dass Ihre Integration für Bankkonten mit manueller Eingabe für den Einsatz in einer Produktionsumgebung bereit ist.

Bevor Testtransaktionen abgeschlossen werden können, müssen Sie alle Testkonten verifizieren, auf denen die Zahlung automatisch erfolgreich war oder fehlschlagen ist. Verwenden Sie dazu die nachstehenden Test-Mikroeinzahlungsbeträge oder Beschreibungscodes.

Testen von Mikroeinzahlungen und Beschreibungscodes

Um verschiedene Szenarien zu imitieren, verwenden Sie diese Mikroeinzahlungsbeträge oder 0,01 Beschreibungscodewerte.

Abwicklungsverhalten testen

Testtransaktionen werden sofort abgewickelt und Ihrem verfügbaren Testguthaben hinzugefügt. Dieses Verhalten unterscheidet sich vom Live-Modus, bei dem es mehrere Tage dauern kann, bis Transaktionen Ihrem verfügbaren Guthaben gutgeschrieben werden.

Ist der SetupIntent erfolgreich, wird eine neue PaymentMethod erstellt, die an den/die Kunden/Kundin angehängt ist. Damit können künftige Zahlungen eingeleitet werden, ohne dass der Kunde/die Kundin das Bankkonto erneut angeben muss.

curl https://api.stripe.com/v1/payment_intents \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -d "amount"=1099 \
  -d "currency"="usd" \
  -d "customer"="{{CUSTOMER_ID}}" \
  -d "payment_method"="{{PAYMENT_METHOD_ID}}" \
  -d "payment_method_types[]"="us_bank_account" \
  -d "confirm"="true"