ACH-Lastschriftzahlungen annehmen

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 PaymentIntent ist ein Objekt, das Ihre Absicht darstellt, eine Zahlung von einer Kundin/einem Kunden einzuziehen, und das den Lebenszyklus des Zahlungsprozesses in jeder Phase verfolgt.

Serverseitig

Erstellen Sie zunächst einen PaymentIntent auf Ihrem Server und geben Sie den einzuziehenden Betrag und die Währung usd an. Falls Sie bereits über eine Integration verfügen, die die Payment Intents API verwendet, fügen Sie der Liste der Zahlungsmethoden für Ihren PaymentIntent us_bank_account hinzu. Geben Sie optional die ID der Kundin/des Kunden an.

Falls Sie die Zahlungsmethode künftig wiederverwenden möchten, geben Sie den Parameter setup_future_usage mit dem Wert off_session 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/payment_intents \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d amount=1099 \
  -d currency=usd \
  -d setup_future_usage=off_session \
  -d customer={{CUSTOMER_ID}} \
  -d "payment_method_types[]"=us_bank_account

Clientseitig

Im zurückgegebenen PaymentIntent ist ein Client-Geheimnis enthalten, mit dem der Client den Zahlungsvorgang sicher abschließen kann, anstatt das gesamte PaymentIntent-Objekt zu übergeben. Fordern Sie auf dem Client einen PaymentIntent von Ihrem Server an und speichern Sie dessen Client-Geheimnis.

import UIKit
import StripePayments

class CheckoutViewController: UIViewController {
  var paymentIntentClientSecret: String?

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

Der Kunde/Die Kundin verlässt ggf. Ihre App, um sich zu authentifizieren (z. B. in Safari oder einer Banking-App). Damit sie nach der Authentifizierung automatisch zu Ihrer App zurückkehren können, konfigurieren Sie ein benutzerdefiniertes URL-Schema und richten Sie Ihren App-Delegate so ein, dass die URL an das SDK weitergeleitet wird. Stripe unterstützt keine universellen Links.

// This method handles opening custom URL schemes (for example, "your-app://stripe-redirect")
func scene(_ scene: UIScene, openURLContexts URLContexts: Set<UIOpenURLContext>) {
    guard let url = URLContexts.first?.url else {
        return
    }
    let stripeHandled = StripeAPI.handleURLCallback(with: url)
    if (!stripeHandled) {
        // This was not a Stripe url – handle the URL normally as you would
    }
}

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

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

Verwenden Sie die Klassenfunktion collectUSBankAccountParams in STPCollectBankAccountParams, um Ihre Parameter zu erstellen, die zum Aufrufen von collectBankAccountForPayment erforderlich sind. Um die PaymentMethod „ACH Direct Debit“ zu erstellen, muss der Name des Kontoinhabers/der Kontoinhaberin im Parameter billing_details enthalten sein.

Erstellen Sie eine Instanz von STPBankAccountCollector, um collectBankAccountForPayment aufzurufen und Bankkontodetails zu erfassen, eine PaymentMethod zu erstellen und diese PaymentMethod an den PaymentIntent anzuhängen.

// Build params
let collectParams = STPCollectBankAccountParams.collectUSBankAccountParams(with: name, email: email)

// (optional) Configure the style
let style: STPBankAccountCollectorUserInterfaceStyle = .alwaysLight
let bankAccountCollector = STPBankAccountCollector(style: style)

// Calling this method will display a modal for collecting bank account information
bankAccountCollector.collectBankAccountForPayment(clientSecret: clientSecret,
                                                  returnURL: "https://your-app-domain.com/stripe-redirect",
                                                  params: collectParams,
                                                  from: self) { intent, error in
    guard let intent = intent else {
        // handle error
        return
    }
    if case .requiresPaymentMethod = intent.status {
        // Customer canceled the Financial Connections modal. Present them with other
        // payment method type options.
    } else if case .requiresConfirmation = intent.status {
        // 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.
    }
}

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 PaymentIntent angehängt.

Bevor Sie die Zahlung veranlassen können, müssen Sie eine Zahlungsautorisierung von Ihrem/Ihrer Kund/in 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]](/payments/ach-direct-debit#mandates).

Wenn der/die Kund/in den Mandatskonditionen zustimmt, müssen Sie den PaymentIntent bestätigen. Verwenden Sie confirmPayment, um die Zahlung abzuschließen, wenn der/die Kund/in das Formular absendet.

let paymentIntentParams = STPPaymentIntentParams(clientSecret: clientSecret,
                                            paymentMethodType: .USBankAccount)

STPPaymentHandler.shared().confirmPayment(
    paymentIntentParams, with: self
) { (status, intent, error) in
    switch status {
    case .failed:
        // Payment failed
    case .canceled:
        // Payment was canceled
    case .succeeded:
        // Payment succeeded
    @unknown default:
        fatalError()
    }
}

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

Nach erfolgreicher Bestätigung des PaymentIntent 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 das Bankkonto sofort verifizieren. Dieser Schritt wird nur ausgeführt, wenn Ihre Kundin/Ihr Kunde 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 Kunden/der Kundin erscheinen

• Code der Zahlungsbeschreibung. Stripe sendet eine einzelne Mikroeinzahlung ü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 confirmPayment im vorhergehenden Schritt ist ein PaymentIntent mit dem Status requires_action. Der PaymentIntent 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-Mails-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 iOS-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 einstellen, dass der Parameter amounts verarbeitet wird, da einige der von Ihren Kund/innen verwenden Banken dies möglicherweise erfordern.

  Integrationen übergeben nur den descriptor_code oder amounts. Um festzustellen, welches 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
STPAPIClient.shared.verifyPaymentIntentWithMicrodeposits(clientSecret: clientSecret,
                                                         descriptorCode: descriptorCode,
                                                         completion: { intent, error in
})

// Use if you are using amounts, do not use if you are using descriptor code
STPAPIClient.shared.verifyPaymentIntentWithMicrodeposits(clientSecret: clientSecret,
                                                         firstAmount: firstAmount,
                                                         secondAmount: secondAmount,
                                                         completion: { intent, error in
})

Wenn das Bankkonto erfolgreich verifiziert wurde, gibt Stripe das PaymentIntent-Objekt mit dem status processing 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"
  }
}

Bei ACH Direct Debit handelt es sich um eine Zahlungsmethode mit verzögerter Benachrichtigung. Das bedeutet, dass es bis zu vier Werktage dauern kann, bis Sie nach Initiierung einer Lastschrift für das Kundenkonto eine Mitteilung über die erfolgreiche oder fehlgeschlagene Zahlung erhalten.

Der von Ihnen erstellte PaymentIntent hat zunächst den Status processing. Wenn die Zahlung erfolgreich war, wird der PaymentIntent-Status von processing in succeeded geändert.

Wir empfehlen die Verwendung von Webhooks, um die erfolgreiche Zahlung zu bestätigen und die Kundinnen/Kunden zu informieren, dass die Zahlung abgeschlossen ist. Sie können sich Ereignisse auch im Stripe-Dashboard anzeigen lassen.

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.

Wenn Ihre Domain {domain} und Ihr Nutzername {username} ist, verwenden Sie das folgende E-Mail-Format, um E-Mails für Testtransaktionen zu senden: {username}+test_email@{domain}.

Wenn Ihre Domain beispielsweise example.com und Ihr Nutzername Info lautet, verwenden Sie zum Testen von ACH Direct Debit-Zahlungen das Format info+test_email@example.com. Dieses Format stellt sicher, dass E-Mails korrekt weitergeleitet werden. Wenn Sie das Suffix +test_email nicht angeben, senden wir die E-Mail nicht.

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.