Geld mit Treasury mithilfe von InboundTransfer-Objekten bewegen

Erfahren Sie, wie Sie Geld von einem anderen Konto, das Sie besitzen, auf ein Treasury Finanzkonto überweisen können.

Bei eingehenden Überweisungen wird Geld mithilfe des ACH-Netzwerks von einem externen US-Bankkonto auf ein Finanzkonto übertragen. Diese Transfers werden mit InboundTransfer-Objekten initiiert.

Inbound transfers take 2-4 business days to complete unless you’re using the same-day ACH capability. For more information, see the Money movement timelines guide.

Notiz

You can use inbound transfers to move funds from a financial account owner’s bank account. To accept funds from an external party into a financial account, use an ACH Debit into the Payments balance, followed by a payout to the financial account.

Einen InboundTransfer erstellen

Verwenden Sie POST /v1/treasury/inbound_transfers, um ein InboundTransfer-Objekt zu erstellen, das Pull-basierte Überweisungen von einem externen Konto, das Sie besitzen, auf Ihr Finanzkonto darstellt. Mit anderen Worten, Sie erstellen einen InboundTransfer, um Gelder auf Ihr Finanzkonto zu überweisen, indem Sie Ihr externes US-Bankkonto belasten. Folgende Parameter müssen Sie in Ihre Anfrage aufnehmen:

amount: Der Betrag in Cent, der auf das Finanzkonto übertragen werden soll.
currency: Dreistelliger ISO-Währungscode (derzeit wird nur der Wert usd unterstützt).
financial_account: Die ID des Finanzkontos, das den Transfer empfängt.
origin_payment_method: The source of funds for the inbound transfer. You must first set up the account-attached payment method for inbound flows and verify the bank account using a SetupIntent. Alternatively, you can use an existing BankAccount previously set up as a verified ExternalAccount. Whether you use a payment method or a bank account, you need the account owner’s permission to debit the funds from the account.

Der folgende JSON zeigt die Daten, die Sie in den Text Ihrer Anfrage aufnehmen können.

{
  // The source PaymentMethod or BankAccount. Funds are pulled from this account.
  "origin_payment_method": "{{PAYMENT_METHOD_ID}}" | "{{BANK_ACCOUNT_ID}}",
  // The destination FinancialAccount. Funds arrive in this account.
  "financial_account": "{{FINANCIAL_ACCOUNT_ID}}",
  // The amount to debit. 10.00 USD in this case.
  "amount": 1000,
  "currency": "usd",
  // An optional, internal description for the InboundTransfer.
  "description": "Funds for vendor payment payment_234281",
  // An optional descriptor for the InboundTransfer to send
  // to the network with the debit request. Max 10 characters
  "statement_descriptor": "payment_1",
  // Stripe doesn't support updating InboundTransfers after creation.
  // You can only set metadata at creation time.
  "metadata": null | {{Hash}}
}

Bei der folgenden Anfrage werden 200 USD mit einer mit einem Konto verknüpften Zahlungsmethode auf das Finanzkonto mit der angegebenen ID überwiesen. Der Stripe-Account-Header-Wert gibt das verbundene Stripe-Konto an, das sowohl das Finanzkonto als auch die Zahlungsmethode enthält.

Bei Erfolg stellt die Antwort das Objekt InboundTransfer bereit. Dieses enthält eine hosted_regulatory_receipt_url, die dem Kontoinhaber/der Karteninhaberin weitere Angaben zur Transaktion auf Ihrer Plattform bereitstellt.

{
    "id": "{{INBOUND_TRANSFER_ID}}",
    "object": "inbound_transfer",
    "amount": 20000,
    "created": 1648071297,
    "currency": "usd",
    "description": "Funds for repair",
    "financial_account": "{{FINANCIAL_ACCOUNT_ID}}",
    "hosted_regulatory_receipt_url": "https://payments.stripe.com/regulatory-receipt/{{IBT_URL}}",
    "linked_flows": null,
    "livemode": false,
    "metadata": {},
    "origin_payment_method": "{{PAYMENT_METHOD_ID}}",
    ...
    "statement_descriptor": "Invoice 12",
    "status": "processing",
    ...
}

Achtung

In seltenen Fällen kann Stripe eine InboundTransfer-Anfrage aufgrund verschiedener Risikofaktoren stornieren. In diesen Szenarien fordert die API Fehler mit dem Antwortcode 402 an. Die Fehlermeldung enthält zusätzliche Details zu den Risikofaktoren, die zu der Intervention geführt haben.

ACH-Abwicklung am selben Tag

Private Vorschau

Die ACH-Abwicklung am selben Tag befindet sich derzeit in der Vorschau und hat nur eine begrenzte Verfügbarkeit. Geeignete Nutzer/innen werden von Stripe überprüft und genehmigt. Um Zugriff anzufordern, senden Sie eine E-Mail an treasury-support@stripe.com.

Wenn Sie keinen Zugriff haben, geben API-Aufrufe, die ACH-Funktionen oder -Parameter vom selben Tag enthalten, einen Fehler zurück.

Using same-day ACH enables funds to arrive in the originating financial account within the same business day if the InboundTransfer call successfully completes before the cutoff time. To use same-day ACH, set the origin_payment_method_options.us_bank_account.ach.submission parameter to same_day.

Betrugsrisiko bei taggleicher ACH-Verfügbarkeit

The fast settlement of same-day ACH inbound transfers can expose your platform to greater financial risk than from standard ACH inbound transfers. For example, a connected account can initiate an inbound transfer that gets returned due to insufficient funds in the source account. Same-day settlement leaves more time to potentially withdraw the funds from the financial account before they’re returned. If the connected account withdraws the funds, and then the return causes a negative balance in the financial account, your platform is responsible.

Wenn die Betrugspräventionssysteme von Stripe eine eingehende Überweisung als hochriskant einstufen, schlägt die Erstellungsanfrage mit einem Fehler fehl:

{
  "error": {
    "type": "invalid_request_error",
    "message_code": "inbound_transfer_not_same_day_eligible",
    "message": "This transaction is not eligible for same-day availability at this time. Please try again with `standard` ACH submission."
  }
}

Wenn der Meldungscode inbound_transfer_not_same_day_eligible fehlerhaft ist, wiederholen Sie die Anfrage mit dem als standard festgelegten Parameter origin_payment_method_options.us_bank_account.ach.submission.

Einen InboundTransfer abrufen

Verwenden Sie GET /v1/treasury/inbound_transfers/{{INBOUND_TRANSFER_ID}}, um Details für den InboundTransfer mit der zugehörigen ID abzurufen.

Der folgende JSON zeigt die Daten, die Sie in den Text Ihrer Anfrage aufnehmen können. Einige der Parameter in der Antwort enthalten zusätzliche Details, die nur zurückgegeben werden, wenn Sie sie als Werte zum expand[]-Parameter hinzufügen. Die Felder, die Sie erweitern können, haben im folgenden Antwortbeispiel den Kommentar „Erweiterbar“. Weitere Informationen zum Erweitern von Objektantworten finden Sie unter Antworten erweitern.

{
  "id": "{{INBOUND_TRANSFER_ID}}",
  "object": "inbound_transfer",
  "livemode": false,
  "created": "{{Timestamp}}",
  "financial_account": "{{FINANCIAL_ACCOUNT_ID}}", // Expandable
  "amount": 1000,
  "currency": "usd",
  // The only current valid PaymentMethod type for InboundTransfers is us_bank_account
  "origin_payment_method": "{{PAYMENT_METHOD_ID}}",

Die folgende Anfrage ruft den InboundTransfer mit dem id-Wert {{INBOUND_TRANSFER_ID}} ab. Durch Aufnehmen von transaction in das expand[]-Array des Texts werden die relevanten erweiterten Informationen zurückgegeben.

Bei Erfolg gibt die Antwort das InboundTransfer-Objekt mit den erweiterten Informationen zurück.

{
    "id": "{{INBOUND_TRANSFER_ID}}",
    "object": "inbound_transfer",
    "amount": 20000,
    "created": 1648071297,
    "currency": "usd",
    "description": "Inbound transfer",
    "failure_details": null,
    "financial_account": "{{FINANCIAL_ACCOUNT_ID}}",
    "hosted_regulatory_receipt_url": "https://payments.stripe.com/regulatory-receipt/{{INBOUND_TRANSFER_ID}}",

InboundTransfers auflisten

Verwenden Sie GET /v1/treasury/inbound_transfers, um alle InboundTransfers des Finanzkontos mit der zugehörigen ID abzurufen. Sie können die Liste mit den Standard-Listenparametern oder nach status sortieren.

{
  // Standard list parameters
  "limit", "starting_after", "ending_before",
  // Filter by status
  "status": "processing" | "succeeded" | "failed",
  // Filter by FinancialAccount (Required)
  "financial_account": "{{FINANCIAL_ACCOUNT_ID}}", // Required
}

Die folgende Anfrage ruft alle eingehenden Transfers mit dem Statussucceeded für das Finanzkonto mit der ID {{FINANCIAL_ACCOUNT_ID}} ab, das an das verbundene Konto mit der ID {{CONNECTED_ACCOUNT_ID}} angehängt ist.

InboundTransfers manuell überprüfen

Sie können das Risiko eingehender Transfers verringern, indem Sie die Übermittlung an unsere Bankpartner verzögern oder Gelder über einen längeren Zeitraum zurückhalten. Diese zurückgehaltenen Karten geben Ihnen zusätzliche Zeit, um potenziell verdächtige Aktivitäten zu überprüfen. Sie können Zugriff auf die inbound_transfers.ach.platform_review-Funktion anfordern und Finanzkonten mit dieser aktivierten Funktion erhalten alle eingehenden Überweisungen mit einem requires_confirmation-Status.

Das nachfolgende Beispiel zeigt die Einrichtung dieser Funktion bei einem neuen Finanzkonto. Sie können auch andere Funktionen hinzufügen.

Das nachfolgende Beispiel zeigt die Einrichtung dieser Funktion bei einem bestehenden Finanzkonto.

In der Regel senden wir eingehende Überweisungen nach ihrer Erstellung automatisch an die Bank. Eingehende Überweisungen mit dem Status requires_confirmation erfordern jedoch eine ausdrückliche Nutzerbestätigung über den /v1/treasury/inbound_transfers/{id}/confirm-Endpoint, bevor wir die Überweisungen an unsere Bankpartner senden können. Sie können die Details der eingehenden Überweisung und die Risikosignale überprüfen, bevor Sie die Überweisung bestätigen oder stornieren. Um eingehende Überweisungen mit dem Status requires_confirmation zu bestätigen oder zu stornieren, haben Sie 5 Werktage lang Zeit. Nach 5 Werktagen wird die eingehende Überweisung automatisch storniert. Sie haben beispielsweise bis zum folgenden Freitag Zeit, um eine eingehende Überweisung mit dem Status requires_confirmation, die an einem Freitag erstellt wurde (sofern es sich nicht um einen Feiertag in den USA handelt), zu bestätigen.

Verwenden Sie den funds_availability_delay-Parameter mit dem confirm-Endpoint, um die Verzögerung (in Sekunden) anzugeben, mit der die Gelder vor der Freigabe auf das vorgesehene Finanzkonto zurückgehalten werden sollen. Auf diese Weise können Sie die zusätzliche Verzögerung nutzen, um eine Überweisung manuell zu überprüfen. Sie können dieses Feld auch verwenden, um Gelder über das ACH-Rückgabefenster hinaus zu halten, sodass die Ursprungsbank Gelder nicht zurückrufen kann, nachdem sie ausgegeben wurden. Für zusätzliche Sicherheit empfehlen wir, funds_availability_delay auf 432.000 festzulegen, wodurch Gelder über das Rückgabefenster hinaus freigegeben werden.

Im Folgenden finden Sie ein Beispiel für den Aufruf des confirm-Endpoints ohne Verfügbarkeitsverzögerung.

Im Folgenden finden Sie ein Beispiel für den Aufruf des confirm-Endpoints mit einer Verfügbarkeitsverzögerung.

Status von InboundTransfers

In der folgenden Tabelle sind die einzelnen Status sowie die möglichen Übergangszustände beschrieben.

STATUS	BESCHREIBUNG	GEHT IN ANDEREN STATUS ÜBER
`processing`	Die Erstellung des `InboundTransfer` war erfolgreich. Stripe veranlasst die Übertragung des Gelds über das Netzwerk.	`failed`, `canceled`, `succeeded`, `requires_confirmation`
`requires_confirmation`	`InboundTransfer` wird in einem Wartezustand erstellt. Stripe hat die Bewegung von Geldern im Netzwerk nicht initiiert und der/die Nutzer/in muss seine Absicht, diese eingehende Überweisung über den `/v1/treasury/inbound_transfers/:ID/confirm`-Endpunkt auszulösen, ausdrücklich bestätigen.	`processing`, `canceled`
`failed` (Terminal)	Bestätigung des `InboundTransfer` fehlgeschlagen. Es wurde keine Transaktion erzeugt, und die `payment_method` wurde nicht belastet.	k.A.
`canceled` (Terminal)	Der `InboundTransfer` wurde vor der Übermittlung an das Netzwerk storniert. Stripe storniert die Transaktion, und es werden keine Gelder vom externen Bankkonto überwiesen.	k.A.
`succeeded` (Terminal)	Der `InboundTransfer` war erfolgreich und Gelder sind auf dem Konto angekommen. Eine Transaktion wurde erstellt. InboundTransfers können nach erfolgreichem Abschluss zurückgegeben werden, wenn das externe Konto seine Gelder zurückzieht, was durch eine verknüpfte ReceivedDebit dargestellt wird.	k.A.

InboundTransfers testen

Um einen End-to-End-Test Ihrer Integration durchzuführen, verwenden Sie die SetupIntents-Anfragen im Test-Modus, um eine PaymentMethod zu erstellen und dann diese PaymentMethod in eine InboundTransfer-Erstellungsanfrage zu übergeben. Gültige PaymentMethods führen zu erfolgreichen InboundTransfers, während ungültige PaymentMethods (z. B. nicht unterstützte Typen, die ein nicht verifiziertes Bankkonto enthalten oder nicht auf eingehende Geldbewegungen ausgelegt sind) dieselben Fehlermeldungen erzeugen, wie im Live-Modus.

Zustände von InboundTransfers testen

Stripe bietet auch eine Reihe an Token zum Testen von PaymentMethod, die Sie verwenden können, um bestimmte Statusübergänge auszulösen:

PAYMENT_METHOD-WERT	ERGEBNIS
`pm_usBankAccount`	Der Status des `InboundTransfer` wechselt von `processing` zu `succeeded`.
`pm_usBankAccount_processing`	Der Status des `InboundTransfer` verbleibt bei `processing`.
`pm_usBankAccount_internalFailure`	Der Status des `InboundTransfer` wechselt von `processing` zu `failed`.

Um verschiedene Grenzfälle schneller zu testen, simulieren die PaymentMethod-Token bestimmte Fehlertypen:

PAYMENT_METHOD-WERT	ERGEBNIS
`pm_usBankAccount_noAccount`	Der Status des `InboundTransfer` wechselt zu „failed“ mit `failure_details.code= "no_account"`.
`pm_usBankAccount_accountClosed`	Der Status des `InboundTransfer` wechselt zu `failed` mit `failure_details.code= "account_closed"`.
`pm_usBankAccount_invalidAccountNumber`	Der Status des `InboundTransfer` wechselt zu „fehlgeschlagen“ mit `failure_details.code= "invalid_account_number"`.
`pm_usBankAccount_insufficientFunds`	Der Status des `InboundTransfer` wechselt zu „fehlgeschlagen“ mit `failure_details.code= "insufficient_funds"`.
`pm_usBankAccount_debitNotAuthorized`	Der Status des `InboundTransfer` wechselt zu „fehlgeschlagen“ mit `failure_details.code= "debit_not_authorized"`.
`pm_usBankAccount_dispute`	Der Status des `InboundTransfer` wechselt von `processing` zu `succeeded` und wird später angefochten. `inbound_transfer.returned` wird `true` und ein verknüpftes Objekt `ReceivedDebit` wird erstellt.

In allen vorhergehenden Fällen befindet sich die InboundTransfer-Antwort im Status processing. Sie erhalten Webhook-Ereignisse für alle relevanten Zustandsübergänge und durch Abrufen des InboundTransfer nach der Erstellung wird der erwartete Zustand zurückgegeben.

Sie können den Fehlerstatus auch testen, indem Sie das Token pm_usBankAccount_sameDayACHIneligible als PaymentMethod übergeben. Dies löst einen fehlgeschlagenen InboundTransfer (mit ACH-Übermittlung am selben Tag) aus und gibt einen Fehler zurück.

Hilfs-Endpoints zum Testen von InboundTransfers

Stripe stellt zudem Endpoints bereit, mit denen Sie InboundTransfers in verschiedenen Zuständen testen können. Erstellen Sie einen InboundTransfer und gehen Sie anschließend wie folgt vor:

Verwenden Sie Endpoint für succeed Tests, um den Transfer mit der zugehörigen ID direkt in den Status succeeded zu übertragen.
POST /v1/test_helpers/treasury/inbound_transfers/{{INBOUND_TRANSFER_ID}}/succeed
Verwenden Sie Endpoint für fehlgeschlagene Tests, um den Transfer mit der zugehörigen ID direkt in den Status failed zu übertragen.
POST /v1/test_helpers/treasury/inbound_transfers/{{INBOUND_TRANSFER_ID}}/fail

Diese Endpoints sind besonders nützlich zum Testen von Fehlerszenarien, wie Rückgaben, die andernfalls eine Aktion von einem externen Konto, von dem der InboundTransfer Gelder abruft, erforderlich machen würde.

Fügen Sie den optionalen Parameter failure_details.code in den Text ein, um den Grund für das Fehlschlagen der Übertragung anzugeben. Wenn Sie ihn nicht angeben, schlägt die Übertragung mit dem Standardfehlercode could_not_process fehl.

{
  "failure_details": {
    "code": "account_closed" |
          "account_frozen" |
          "bank_account_restricted" |
          "bank_ownership_changed" |
          "could_not_process" | // Generic fallback code
          "invalid_account_number" |
          "incorrect_account_holder_name" |
          "invalid_currency" |
          "no_account"
  }
}

Financial Accounts for platforms also provides a return endpoint to simulate an InboundTransfer that succeeds, but is later returned.

Verwenden Sie Endpoint für Rückgabe-Tests, um die die simulierte Rückgabe für den InboundTransfer mit der zugehörigen ID auszulösen.

POST /v1/test_helpers/treasury/inbound_transfers/{{INBOUND_TRANSFER_ID}}/return

Alle Test-Endpoints lösen für alle relevanten Status-Übergänge Webhooks aus, und durch Abrufen des InboundTransfer nach dem Übergang wird der erwartete Status zurückgegeben.

InboundTransfer-Webhooks

Stripe gibt die folgenden InboundTransfer-Ereignisse an Ihren Webhook-Endpoint aus:

treasury.inbound_transfer.created bei Erstellen des InboundTransfer.
treasury.inbound_transfer.{{new_status}}, wenn sich der Status eines InboundTransfer ändert. Verfügbare Statuswertoptionen:
- treasury.inbound_transfer.succeeded
- treasury.inbound_transfer.failed