Geld mit Treasury mithilfe von InboundTransfer-Objekten bewegen
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 Transfers dauern in der Regel 2 bis 4 Werktage, außer Sie nutzen die ACH-Funktion für Überweisungen am gleichen Tag. Weitere Informationen finden Sie im Leitfaden zum Zeitplan für Geldbewegungen.
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 Wertusd
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 einenSetupIntent
einrichten. Alternativ können Sie auch ein bestehendesBankAccount
verwenden, das zuvor als verifiziertesExternalAccount
eingerichtet wurde. Unabhängig davon, ob Sie eine Zahlungsmethode oder ein Bankkonto verwenden, benötigen Sie die nutzerseitige Zustimmung, 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", ... }
Notiz
origin_payment_method_options[us_bank_account][ach][submission]=same_day
ermöglicht das Eintreffen von Geldern auf dem ursprünglichen Finanzkonto noch am selben Werktag, wenn der InboundTransfer
-Aufruf vor der Annahmefrist erfolgreich abgeschlossen wurde. Wenn dieser Parameter bei der Erstellung eines InboundTransfer
nicht angegeben wird, verwendet die Transaktion die Standard-Zeitleiste für Geldbewegungen. Geben Sie destination_payment_method_options[us_bank_account][network]=ach
an, wenn Sie diese Funktion nutzen. Kontaktieren Sie treasury-support@stripe.com, um der ACH-Beta-Warteliste für denselben Tag beizutreten. 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.
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 |
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 weiterzugeben. Gültige PaymentMethods
führen zu erfolgreichen InboundTransfers
, während ungültige PaymentMethods
(z. B. nicht unterstützte PaymentMethods
-Typen, PaymentMethods
, die ein nicht verifiziertes Bankkonto enthalten oder PaymentMethods
, die nicht auf eingehende Zahlungsflüsse 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 Zustandsübergang, 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
succeed
-Endpoint testen, um den Transfer mit der zugehörigen ID direkt in den Statussucceeded
zu übertragen.POST /v1/test_helpers/treasury/inbound_transfers/{{INBOUND_TRANSFER_ID}}/succeed
Verwenden Sie
fail
-Endpoint testen, um den Transfer mit der zugehörigen ID direkt in den Statusfailed
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 return
-Endpoint testen, 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 Zustandsübergänge Webhooks aus, und durch Abrufen des InboundTransfer
nach dem Übergang wird der erwartete Zustand zurückgegeben.
InboundTransfer-Webhooks
Stripe gibt die folgenden InboundTransfer
-Ereignisse an Ihren Webhook-Endpoint aus:
treasury.inbound_transfer.created
bei Erstellen desInboundTransfer
.treasury.inbound_transfer.{{new_status}}
, wenn sich der Status einesInboundTransfer
ändert. Verfügbare Statuswertoptionen:treasury.inbound_transfer.succeeded
treasury.inbound_transfer.failed