Geld mit Treasury mithilfe von OutboundTransfer-Objekten bewegen

Erfahren Sie, wie Sie Geld von den Treasury Finanzkonten auf externe Konten überweisen können.

Ein OutboundTransfer-Objekt ermöglicht Geldübertragungen von Finanzkonten. Über OutboundTransfer können Sie Gelder über die ACH-Netzwerke oder per Inlandsüberweisung auf ein externes Bankkonto senden, das einem verbundenen Konto 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 Geldübertragungen.

OutboundTransfers unterstützen den Zahlungsmethodentyp us_bank_account. Alternativ können Sie ein bestehendes BankAccount, das der/dem Händler/in 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 eine BankAccount-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.

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": {

ACH-Abwicklung am selben Tag

Beta

Die ACH-Abwicklung am selben Tag befindet sich derzeit in der Beta 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 Verwendung der ACH-Abwicklung am selben Tag können Sie Gelder senden, die am selben Werktag eingehen, wenn der Aufruf OutboundTransfer erfolgreich vor der Annahmefrist abgeschlossen wurde. Um die ACH-Abwicklung am selben Tag zu verwenden, setzen Sie den Parameter destination_payment_method_options.us_bank_account.network auf ach und den Parameter destination_payment_method_options.us_bank_account.ach.submission auf same_day.

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

Für Banküberweisungen sind ACH-Metadaten sowie der Empfängername und die Rechnungsadresse erforderlich. Die Adresse ist die Adresse der Kontoinhaberin/des Kontoinhabers, an die/den die Überweisung geht, nicht die Adresse der 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.

JSON (mit Kommentar)
{
  "id": "{{OUTBOUND_TRANSFER_ID}}",
  "object": "outbound_transfer",
  "livemode": Boolean,
  "created": Timestamp,
  "financial_account": "{{FINANCIAL_ACCOUNT_ID}}", // Expandable
  "amount": 1000,
  "currency": "usd",
  "destination_payment_method": "{{PAYMENT_METHOD_ID}}",
  "description": "Transfer to my external account",

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 der OutboundTransfer-Objekte zurück, die alle Filterbedingungen erfüllt.

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 angeben. Zum Testen Ihrer Integration, können Sie Ihre eigenen PaymentMethods im Test-Modus erstellen oder unsere Test-IDs verwenden.

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`

Die OutboundTransfer-Antwort gibt in allen Fällen den Status processing zurück. Stripe löst Webhooks für die relevanten Statuswechsel aus und durch Abrufen der OutboundTransfer nach der Erstellung wird der erwartete Status 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 die erkannte OutboundTransfer vom Status processing in posted zu ändern.
POST /v1/test_helpers/treasury/outbound_transfers/{{OUTBOUND_TRANSFER_ID}}/post
Verwenden Sie den Endpoint für fehlgeschlagene Tests, um die erkannte OutboundTransfer vom Status processing in failed zu ändern.
POST /v1/test_helpers/treasury/outbound_transfers/{{OUTBOUND_TRANSFER_ID}}/fail
Verwenden Sie Endpoint für Rückgabe-Tests, um den erkannten OutboundTransfer vom Status posted in returned zu ändern.
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 Darstellung der Sendungsnachverfolgung für einen Outbound Transfer im Test-Modus zu simulieren. Das Feld tracking_details kann nur für Test-Modus-Objekte festgelegt werden.

Stripe löst in allen Fällen für alle relevanten Statuswechsel Webhooks aus und durch Abrufen der OutboundTransfer nach dem Wechsel wird der erwartete Status 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 das expected_arrival_date einer OutboundTransfer ändert.
treasury.outbound_transfer.tracking_details_updated , wenn die Tracking-Details für einen OutboundTransfer aktualisiert werden.