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.

Eingehende Überweisungen dauern in der Regel 2 bis 4 Werktage, außer Sie nutzen die Funktionalität für die ACH-Abwicklung am selben Tag. Weitere Informationen finden Sie im Leitfaden zum Zeitplan für Geldübertragungen.

Notiz

Mit den eingehenden Übertragungen können Sie Gelder vom Bankkonto einer Inhaberin/eines Inhabers eines Finanzkontos übertragen. Um externe Gelder auf ein Finanzkonto einzuzahlen, senden Sie den Betrag per ACH-Lastschrift an das Zahlungsguthaben und zahlen die Gelder anschließend an das Finanzkonto aus.

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: Der Ursprungsort der eingehenden Zahlung. Sie müssen zunächst die mit dem Konto verknüpfte Zahlungsmethode für Zahlungseingänge einrichten und das Bankkonto verifizieren, indem Sie einen SetupIntent einrichten. Alternativ können Sie auch ein bestehendes BankAccount verwenden, das zuvor als verifiziertes ExternalAccount eingerichtet wurde. Unabhängig davon, ob Sie eine Zahlungsmethode oder ein Bankkonto verwenden, benötigen Sie die Zustimmung der Kontoinhaber/innen, um Gelder abzubuchen.

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 does not 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.

Durch die Nutzung der ACH-Abwicklung am selben Tag können Gelder innerhalb desselben Werktages auf dem ursprünglichen Finanzkonto eingehen, wenn der Aufruf InboundTransfer erfolgreich vor der Annahmefrist abgeschlossen wurde. Um die ACH-Abwicklung am selben Tag zu verwenden, setzen Sie den Parameter origin_payment_method_options.us_bank_account.ach.submission auf same_day.

Notiz

Die schnelle Abwicklung von eingehenden Übertragungen mit ACH-Abwicklung am selben Tag kann für Ihre Plattform ein größeres finanziellen Risiko bedeuten als dies bei herkömmlichen ACH-Übertragungen der Fall ist. So kann ein verbundenes Konto z. B. eine eingehende Übertragung einleiten, die aufgrund unzureichender Mittel auf dem Quellkonto zurückgesendet wird. Bei der Abwicklung am selben Tag ist der Zeitraum länger, in dem die Gelder möglicherweise vom Finanzkonto abgehoben werden, bevor sie zurückgegeben werden. Wenn das verbundene Konto das Geld abhebt und die Rückgabe dann einen negativen Saldo im Finanzkonto verursacht, ist Ihre Plattform dafür verantwortlich.

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 Fällen befindet sich die InboundTransfer-Antwort im Status processing. Sie empfangen Webhooks für jeden relevanten Statuswechsel, und durch Abrufen des InboundTransfer nach der Erstellung wird der erwartete Status zurückgegeben.

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"
  }
}

Treasury stellt auch einen return-Endpoint bereit, um einen erfolgreichen InboundTransfer zu simulieren, der erfolgreich ist, aber später zurückgegeben wird.

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