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

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.

Serverseitig

Erstellen Sie einen SetupIntent auf Ihrem Server, wobei payment_method_types auf us_bank_account gesetzt ist, 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

In dem zurückgegebenen SetupIntent ist ein Client-Geheimnis enthalten, das auf dem Client verwendet wird, um die Einrichtung sicher abzuschließen, ohne das gesamte SetupIntent-Objekt übergeben zu müssen. Es gibt verschiedene Möglichkeiten, das Client-Geheimnis an den Client zu übergeben.

import androidx.appcompat.app.AppCompatActivity

class CheckoutActivity : AppCompatActivity() {
    lateinit var setupIntentClientSecret: String

    fun startCheckout() {
        // Request a SetupIntent from your server and store its client secret
    }
}

Damit die Zahlung erfolgreich ist, ist bei ACH Direct Debit ein Kundenname und (optional) eine E-Mail-Adresse erforderlich. Erfassen Sie in Ihrer App die notwendigen Abrechnungsdaten von den Kund/innen:

• Den vollständigen Namen (Vor- und Nachname) des/der Kund/in
• E-Mail-Adresse

Verwenden Sie CollectBankAccountConfiguration.USBankAccount, um die Parameter zu erstellen, die für den Aufruf von presentWithSetupIntent erforderlich sind.

Initialisieren Sie eine CollectBankAccountLauncher-Instanz innerhalb von OnCreate Ihrer Checkout-Aktivität und übergeben Sie eine Methode zur Verarbeitung des Ergebnisses. Rufen Sie dann presentWithSetupIntent auf, um Bankkontodaten zu erfassen, eine PaymentMethod zu erstellen und diese PaymentMethod an den SetupIntent anzuhängen.

import androidx.appcompat.app.AppCompatActivity

class CheckoutActivity : AppCompatActivity() {
    private lateinit var setupIntentClientSecret: String
    private lateinit var collectBankAccountLauncher: CollectBankAccountLauncher

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        // Create collector
        collectBankAccountLauncher = CollectBankAccountLauncher.create(
            this
        ) { result: CollectBankAccountResult ->
            when (result) {
                is CollectBankAccountResult.Completed -> {
                    val intent = result.response.intent
                    if (intent.status === StripeIntent.Status.RequiresPaymentMethod) {
                        // Customer canceled the Financial Connections modal. Present them with other
                        // payment method type options.
                    } else if (intent.status === StripeIntent.Status.RequiresConfirmation) {
                        // We collected an account - possibly instantly verified, but possibly
                        // manually-entered. Display payment method details and mandate text
                        // to the customer and confirm the intent once they accept
                        // the mandate.
                    }
                }
                is CollectBankAccountResult.Cancelled -> {
                    // handle cancellation
                }
                is CollectBankAccountResult.Failed -> {
                    // handle error
                    print("Error: ${result.error}")
                }
            }
        }
    }

    fun startCheckout() {
        // ...

        // Build params
        val collectParams: CollectBankAccountConfiguration =
            CollectBankAccountConfiguration.USBankAccount(
                name,
                email
            )

        // Calling this method will trigger the Financial Connections modal to be displayed
        collectBankAccountLauncher.presentWithSetupIntent(
            publishableKey,
            setupIntentClientSecret,
            collectParams
        )
    }
}

Dadurch wird eine Modal-Nutzeroberfläche geladen, um die Erfassung und Überprüfung der Bankkontodaten abzuwickeln. Wenn dies abgeschlossen ist, wird die PaymentMethod automatisch an den SetupIntent angehängt.

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 erfolgt durch Anzeigen von Mandatsbedingungen, denen der Kunde/die Kundin zustimmen muss. Weitere Informationen finden Sie unter Mandate.

Wenn der/die Kund/in den Mandatsbedingungen zustimmt, müssen Sie den Setup bestätigen. Verwenden Sie confirm, um die Zahlung abzuschließen, wenn der/die Kund/in das Formular einreicht.

class CheckoutActivity : AppCompatActivity() {
    // ...
    private lateinit var setupIntentClientSecret: String
    private val paymentLauncher: PaymentLauncher by lazy {
        val paymentConfiguration = PaymentConfiguration.getInstance(applicationContext)
        PaymentLauncher.Companion.create(
            this,
            paymentConfiguration.publishableKey,
            paymentConfiguration.stripeAccountId,
            ::onPaymentResult
        )
    }

    private fun startCheckout() {
        // ...

        val confirmParams = ConfirmSetupIntentParams.create(
            clientSecret = setupIntentClientSecret,
            paymentMethodType = PaymentMethod.Type.USBankAccount
        )
        paymentLauncher.confirm(confirmParams)
    }

    private fun onPaymentResult(paymentResult: PaymentResult) {
        when (paymentResult) {
            is PaymentResult.Completed -> {
                // show success UI
            }
            is PaymentResult.Canceled -> {
                // handle cancel flow
            }
            is PaymentResult.Failed -> {
                // handle failures
                // (for example, the customer might need to choose a new payment
                // method)
            }
        }
    }
}

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

Nach erfolgreicher Bestätigung des Setup muss eine Bestätigung des Mandats und der erfassten Bankkontodaten per E-Mail an Ihre Kundinnen/Kunden 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 das Bankkonto sofort verifizieren. Dieser Schritt wird nur ausgeführt, wenn Ihr/e Kund/in die Sofortverifizierung im vorherigen Schritt deaktiviert hat.

In diesen Fällen sendet Stripe eine descriptor_code-Testeinzahlung und greift möglicherweise auf eine amount-Testeinzahlung zurück, falls weitere Probleme bei der Verifizierung des Bankkontos auftreten. Es dauert 1–2 Werktage, bis diese Einzahlungen auf der Online-Abrechnung des/der Kund/in angezeigt werden.

• Code der Zahlungsbeschreibung: Stripe sendet eine einzelne Testeinzahlung über 0,01 USD an das Bankkonto des/der Kund/in mit einem einmaligen, 6-stelligen descriptor_code, 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 confirmSetupIntent im vorhergehenden Schritt ist ein SetupIntent mit dem Status requires_action. Der SetupIntent enthält ein next_action-Feld, das einige nützliche Informationen zum Abschließen der Verifizierung enthält.

Wenn Sie eine E-Mail-Adresse für die Rechnungsstellung angegeben haben, benachrichtigt Stripe Ihre Kundinnen und Kunden über diese E-Mail-Adresse, wann die Einzahlungen voraussichtlich eingehen werden. Die E-Mail enthält einen Link zu einer von Stripe gehosteten Verifizierungsseite, auf der sie die Beträge der Einzahlungen bestätigen und die Verifizierung abschließen können.

Optional: Nutzerdefinierte E-Mail-Benachrichtigungen senden

Sie können auch personalisierte E-Mail-Benachrichtigungen an Ihren Kunden/Ihre Kundin senden. Nachdem Sie die nutzerspezifischen E-Mails eingerichtet haben, müssen Sie angeben, wie der Kunde/die Kundin auf die Verifizierungs-E-Mail antwortet. Wählen Sie dazu eine der folgenden Optionen aus:

• Verwenden Sie die von Stripe gehostete Verifizierungsseite. Verwenden Sie dazu die URL verify_with_microdeposits[hosted_verification_url] im next_action-Objekt, um Ihre Kundinnen/Kunden zum Abschluss des Verifizierungsvorgangs zu leiten.

• Wenn die von Stripe gehostete Verifizierungsseite nicht verwenden möchten, können Sie in Ihrer App ein Formular für Ihre Kund/innen zur Weiterleitung von Mikroeinzahlungen an Sie erstellen und das Bankkonto mit dem Android SDK verifizieren.

  • Richten Sie das Formular mindestens so ein, dass es den Parameter descriptor code verarbeitet, bei dem es sich um eine 6-stellige Zeichenfolge zu Verifizierungszwecken handelt.
  • Stripe empfiehlt außerdem, dass Sie Ihr Formular so konfigurieren, dass der Parameter amounts verarbeitet wird, da einige der von Ihren Kund/innen verwenden Banken dies möglicherweise verlangen.

  Integrationen übergeben nur den descriptor_code oder amounts. Um festzustellen, welchen Parameter Ihre Integration verwendet, prüfen Sie den Wert für verify_with_microdeposits[microdeposit_type] im next_action-Objekt.

// Use if you are using a descriptor code, do not use if you are using amounts
fun verifySetupIntentWithMicrodeposits(
    clientSecret: String,
    descriptorCode: String,
    callback: ApiResultCallback<PaymentIntent>
)

// Use if you are using amounts, do not use if you are using descriptor code
fun verifySetupIntentWithMicrodeposits(
    clientSecret: String,
    firstAmount: Int,
    secondAmount: Int,
    callback: ApiResultCallback<PaymentIntent>
)

Wenn das Bankkonto erfolgreich verifiziert wurde, gibt Stripe das SetupIntent-Objekt mit dem status succeeded zurück.

Die Verifizierung kann aus unterschiedlichen Gründen fehlschlagen. Der Fehler tritt synchron als direkte Fehlermeldung auf.

{
  "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 ein Kundenobjekt 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"