Geld mit Treasury mithilfe von OutboundTransfer-Objekten bewegen
Ein OutboundTransfer
-Objekt erleichtert Geldbewegungen von Finanzkonten. Über OutboundTransfer
können Sie Gelder per ACH-Rails oder per Inlandsüberweisung auf ein externes Bankkonto senden, das einem Nutzer/einer Nutzerin eines verbundenen Kontos gehört.
Ausgehende Überweisungen gehen in der Regel zwischen dem gleichen Tag und zwei Werktagen bei der Empfängerbank ein, je nachdem, ob Sie Banküberweisung oder ACH verwenden.
Notiz
Multi FA beta Wenn Sie für die Beta-Funktion für mehrere Finanzkonten angemeldet sind, können Sie OutboundTransfer
verwenden, um Gelder über stripe
-Netzwerk-Rails an ein anderes Finanzkonto zu senden, das mit demselben verbundenen Konto verknüpft ist. Gelder gehen innerhalb von Minuten auf dem Zielkonto ein.
Weitere Informationen finden Sie im Leitfaden zum Zeitplan für Geldbewegungen.
OutboundTransfers
unterstützen den Zahlungsmethodentyp us_bank_account
. Alternativ können Sie ein bestehendes BankAccount, das dem Händler gehört, als ExternalAccount verwenden.
Einen OutboundTransfer erstellen
Verwenden Sie POST /v1/treasury/outbound_transfers
, um einen OutboundTransfer
für das Finanzkonto mit der zugehörigen ID zu erstellen. Von den möglichen Parametern der Anfrage sind vier verpflichtend:
amount
: Überweisungsbetrag in Cent.currency
: Der dreistellige ISO-Währungscode.financial_account
: Das quellseitige Finanzkonto, von dem Gelder abgezogen werden.destination_payment_method
: die ID der Destination-PaymentMethod
oder eineBankAccount
-ID zum Empfangen von Geldern.
{ // The source financial account to pull funds from. "financial_account": "{{FINANCIAL_ACCOUNT_ID}}", // The amount to send. 10.00 USD in this case. "amount": 1000, "currency": "usd", // The destination PaymentMethod or BankAccount. "destination_payment_method": "{{PAYMENT_METHOD_ID}}" | "{{BANK_ACCOUNT_ID}}", // Optionally, to explicitly specify a network, override the `network` value "destination_payment_method_options": { "us_bank_account": { "network": "ach" | "us_domestic_wire" } }, // A description visible on the external bank statement. "statement_descriptor": "Bank xfer", // An optional internal description to identify this OutboundTransfer "description": "Transfer to my external account", // Stripe does not support updating originated transfers after creation. // You can only set metadata at creation. "metadata": nil | Hash, }
Die folgende Anfrage erstellt einen OutboundTransfer
auf einer mit einem Konto verknüpften PaymentMethod
, wobei die Geldquelle von dem identifizierten Finanzkonto stammt.
Notiz
Same Day ACH beta Fügen Sie den optionalen Parameter destination_payment_method_options[us_bank_account][ach][submission]=same_day
ein, um Gelder über die ACH-Schienen zu senden, die am selben Werktag eintreffen, wenn der Aufruf von OutboundTransfer
vor der Annahmefrist erfolgreich abgeschlossen wurde. Wenn dieser Parameter bei der Erstellung einer OutboundPayment
nicht enthalten ist, 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.
Bei Erfolg gibt die Antwort die neu erstellte OutboundTransfer
-Objekt zurück.
{ "id": "{{OUTBOUND_TRANSFER_ID}}", "object": "outbound_transfer", "amount": 1000, "cancelable": true, "created": 1648479987, "currency": "usd", "description": null, "destination_payment_method": "{{PAYMENT_METHOD_ID}}", "destination_payment_method_details": {
Banküberweisung: Routingnummern
Einige Banken verwenden möglicherweise eine separate Routingnummer für Überweisungen, die sich von ACH unterscheiden. Möglicherweise erhalten Sie daher während der Erstellung einer Überweisung eine Fehlermeldung, wenn die Routingnummer für die Zahlungsmethode keine Überweisungen unterstützt. Wenn Sie diesen Fehler erhalten, müssen Sie eine neue Zahlungsmethode mit der Routingnummer für Ihre Banküberweisung hinzufügen.
Banküberweisung: Empfängeradresse
Banküberweisungen erfordern über ACH hinaus weitere Metadaten, insbesondere den Namen des Empfängers und die Rechnungsadresse. Bei der angegebenen Adresse sollte es sich um die Adresse des/der Kontoinhaber/in handeln, der/die die Überweisung erhält, und nicht die Adresse seiner/ihrer Bank.
Bei der Eingabe der billing_details.address
für eine Zahlungsmethode müssen alle Adressfelder ausgefüllt werden. Der Versuch, eine Überweisung mit unvollständigen Feldern in der billing_details.address
zu senden, führt zu einem Fehler.
Notiz
Wenn Sie beim Versenden einer Überweisung mit einem OutboundTransfer
keine Adressfelder ausfüllen, verwendet Stripe standardmäßig die juristische Person des/der primären Stripe-Kontoinhabers/in.
Einen OutboundTransfer abrufen
Verwenden Sie GET /v1/treasury/outbound_transfers/{{OUTBOUND_TRANSFER_ID}}
, um Details für den OutboundTransfer
mit der zugehörigen ID abzurufen.
Die folgende Anfrage ruft den OutboundTransfer
mit der zugehörigen ID ab und erweitert die Details der Transaction
.
Bei Erfolg gibt die Antwort das OutboundTransfer
Objekt mit der zugehörigen ID zurück. 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.
Eine OutboundTransfer stornieren
Verwenden Sie POST /v1/treasury/outbound_transfers/{{OUTBOUND_TRANSFER_ID}}/cancel
, um den OutboundTransfer
mit der zugehörigen ID zu stornieren. Das OutboundTransfer
-Objekt enthält den Parameter cancelable
mit einem booleschen Wert, der angibt, ob die Überweisung storniert werden kann. Nachdem ein OutboundTransfer
an das Netzwerk übertragen wurde, wird der Wert cancelable
false
, und Sie erhalten eine Fehlermeldung von diesem Endpoint für diesen Transfer.
Bei Erfolg gibt die Antwort das OutboundTransfer
-Objekt zurück, wobei der status canceled
ist.
{ "id": "{{OUTBOUND_TRANSFER_ID}} ", "object": "outbound_transfer", "amount": 1000, "cancelable": false, "created": 1648487177, "currency": "usd", ... "status": "canceled", "status_transitions": { "canceled_at": 1648487198, "failed_at": null, "posted_at": null, "returned_at": null }, "transaction": "{{TRANSACTION_ID}}" }
OutboundTransfers auflisten
Verwenden Sie GET /v1/treasury/outbound_transfers
, um die vom Finanzkonto gesendeten OutboundTransfers
mit der ID des financial_account
-Parameters aufzulisten. 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" | "posted" | "failed" | "returned" | "canceled", // Filter by FinancialAccount (Required) "financial_account": "{{FINANCIAL_ACCOUNT_ID}}", }
Die folgende Anfrage ruft OutboundTransfers
von dem identifizierten Finanzkonto ab. Die enthaltenen Parameter begrenzen die Antwort auf die ersten drei Transfers nach dem OutboundTransfer
mit der bereitgestellten ID.
Bei Erfolg gibt die Antwort eine Liste von OutboundTransfer
-Objekten zurück, die alle Filterbedingungen erfüllen.
Status des OutboundTransfer
In der folgenden Tabelle werden jeder status
für OutboundTransfers
sowie die möglichen Übergangszustände beschrieben.
STATUS | BESCHREIBUNG | GEHT IN ANDEREN STATUS ÜBER |
---|---|---|
processing | Der Ausgangszustand des OutboundTransfer . Gelder werden einer ausstehenden Transaktion zugeteilt (sind aber immer noch Teil des aktuellen Guthabens). Der/die Nutzer/in kann den OutboundTransfer stornieren, während der Wert des Parameters cancelable true ist. | posted , canceled , failed |
canceled (Terminal) | Ein/e Nutzer/in hat den OutboundTransfer vor der Buchung storniert. Stripe storniert die ausstehende Transaktion und gibt das Geld an den/die Nutzer/in zurück. | k.A. |
posted | Der OutboundTransfer wurde an das Netzwerk gesendet und die Gelder haben das Konto verlassen. Die Transaktion wird gebucht. | returned |
returned (Terminal) | Der OutboundTransfer konnte das Ziel nicht erfolgreich erreichen (z. B. aufgrund falscher Kontodaten). Stripe gibt das Geld mit dem Parameter returned_details[transaction] an den/die Nutzer/in zurück. | k.A. |
failed (Terminal) | Der OutboundTransfer konnte nicht an das Netzwerk gesendet werden. Stripe storniert die ausstehende Transaktion und gibt das Geld an den/die Nutzer/in zurück. Stripe kann mit diesem Status auf interne Fehler hinweisen. | k.A. |
OutboundTransfers testen
Im Test-Modus können Sie die destination_payment_method
als Zahlungsmethode im Test-Modus angeben. Sie können Ihre eigene PaymentMethods im Test-Modus erstellen oder unsere Test-IDs verwenden, um Ihre Integration zu testen.
TYP | ERGEBNIS | ZAHLUNGSMETHODE |
---|---|---|
us_bank_account | Standard, Übergang zu posted | pm_usBankAccount |
us_bank_account | Übergang zu posted , fügt einen Tag zum ursprünglichen expected_arrival_date hinzu. | pm_usBankAccount_expectedArrivalDateUpdated |
us_bank_account | Verbleibt in processing . | pm_usBankAccount_processing |
us_bank_account | Übergang zu canceled . | pm_usBankAccount_canceledByUser |
us_bank_account | Übergang zu failed . | pm_usBankAccount_internalFailure |
us_bank_account | Übergang zu returned mit returned_details.code="no_account" . | pm_usBankAccount_noAccount |
us_bank_account | Übergang zu returned mit returned_details.code="account_closed" . | pm_usBankAccount_accountClosed |
us_bank_account | Übergang zu returned mit returned_details.code="invalid_account_number" . | pm_usBankAccount_invalidAccountNumber |
In allen Fällen befindet sich die OutboundTransfer
-Antwort im Status processing
. Stripe löst Webhooks für die relevanten Zustandsübergänge aus, und durch Abrufen des OutboundTransfer
nach der Erstellung wird der erwartete Zustand zurückgegeben.
Hilfs-Endpoints zum Testen von OutboundTransfers
Stripe stellt Endpoints bereit, die Ihnen dabei helfen, OutboundTransfers
in verschiedenen Zuständen zu testen. Nach Erstellen eines OutboundTransfer
können Sie mit diesen Test-Endpoints einen OutboundTransfer
direkt in den neuen Zustand posted
, failed
, canceled
oder returned
übertragen.
Verwenden Sie den Test-Post-Endpoint, um den ermittelten
OutboundTransfer
vonprocessing
zuposted
zu verschieben.POST /v1/test_helpers/treasury/outbound_transfers/{{OUTBOUND_TRANSFER_ID}}/post
Verwenden Sie den Endpoint für fehlgeschlagene Tests, um den ermittelten
OutboundTransfer
vonprocessing
zufailed
zu verschieben.POST /v1/test_helpers/treasury/outbound_transfers/{{OUTBOUND_TRANSFER_ID}}/fail
Verwenden Sie den Test-Rückgabe-Endpoint, um den ermittelten
OutboundTransfer
vonposted
nachreturned
zu verschieben.POST /v1/test_helpers/treasury/outbound_transfers/{{OUTBOUND_TRANSFER_ID}}/return
Diese Endpoints sind besonders nützlich zum Testen von Fehlerszenarien, wie Rückgaben, die andernfalls eine Intervention von außen erforderlich machen würden.
Fügen Sie für den return
-Endpoint den optionalen Parameter returned_details.code
in den Hauptteil ein, um zu zeigen, warum der Transfer zurückgegeben wurde. Ohne diese Angabe gilt standardmäßig der Rückgabecode declined
für den Transfer.
{ "returned_details": { "code": "account_closed" | "account_frozen" | "bank_account_restricted" | "bank_ownership_changed" | "could_not_process" | "invalid_account_number" | "incorrect_account_holder_name" | "invalid_currency" | "no_account" | "declined" } }
Wir stellen auch einen Test-Update-Endpoint zur Verfügung, um die Veröffentlichung von Nachverfolgungsdetails bei einem Outbound Transfer
im Test-Modus zu simulieren. Das Feld tracking_details
kann nur für Test-Modus-Objekte festgelegt werden.
In allen Fällen löst Stripe für alle relevanten Zustandsübergänge Webhooks aus und durch Abrufen der OutboundTransfer
nach dem Übergang wird der erwartete Zustand zurückgegeben.
OutboundTransfers-Webhooks
Stripe gibt die folgenden OutboundTransfer
-Ereignisse an Ihren Webhook-Endpoint aus:
treasury.outbound_transfer.created
bei Erstellung von OutboundTransfers.treasury.outbound_transfer.{{new_status}}
, wenn sich der Status eines OutboundTransfer ändert. Verfügbare Statuswertoptionen:treasury.outbound_transfer.posted
treasury.outbound_transfer.failed
treasury.outbound_transfer.returned
treasury.outbound_transfer.canceled
treasury.outbound_transfer.expected_arrival_date_updated
, wenn sich dasexpected_arrival_date
einer OutboundTransfer ändert.treasury.outbound_transfer.tracking_details_updated
, wenn die Tracking-Details für einenOutboundTransfer
aktualisiert werden.