Geld mit Treasury mithilfe von OutboundPayment-Objekten bewegen

Erfahren Sie, wie Sie Ausgangszahlungen erstellen, um Geld von den Treasury Finanzkonten an Dritte zu transferieren.

OutboundPayment-Objekte stellen Push-basierte Überweisungen von Ihrem Treasury-Finanzkonto auf ein externes Konto einer Drittpartei per ACH- oder Banküberweisung oder ein anderes Finanzkonto dar, das mit derselben Plattform verknüpft ist, die sofort das stripe-Netzwerk verwendet. Wenn Sie beispielsweise Geld von Ihrem Finanzkonto auf das externe US-Bankkonto Ihres Anbieters senden möchten, erstellen Sie eine OutboundPayment, um die Gelder zu verschieben. Die empfangenden Konten für eine OutboundPayment sind entweder ein externes Bankkonto oder ein anderes Finanzkonto.

Die typische Überweisungsdauer für ausgehende Zahlungen beträgt zwischen wenigen Minuten (bei Nutzung des Stripe-Netzwerks), bis Tagesende und 1 bis 2 Werktage (bei Nutzung des ACH-Netzwerks). Weitere Informationen finden Sie im Leitfaden zum Zeitplan für Geldübertragungen.

Eine OutboundPayment erstellen

Verwenden Sie POST /v1/treasury/outbound_payments, um eine OutboundPayment zu erstellen. Von den möglichen Parametern der Anfrage sind die folgenden verpflichtend:

amount: Zu zahlender Betrag in Cent.
currency: Dreistelliger ISO-Währungscode (nur usd wird unterstützt).
financial_account: Das quellseitige Finanzkonto, von dem Gelder gesendet werden.
destination_payment_method oder destination_payment_method_data: Informationen zum Ziel der Geldmittel für die Zahlung.
- Für destination_payment_method müssen Sie zunächst die PaymentMethod für ausgehende Zahlungsabläufe mit einem SetupIntent einrichten. Sie müssen außerdem die Kunden-ID angeben, die mit dem Customer-Objekt übereinstimmt, mit dem die PaymentMethod verknüpft ist. Alternativ können Sie ein dem Customer zugeordnetes bestehendes BankAccount-Objekt anstelle einer PaymentMethod verwenden.
- Mit destination_payment_method_data können Sie Details zur Zahlungsmethode inline angeben. Sie können diesen Parameter verwenden, um Bankkontodaten anzugeben oder wenn Sie Geld über das Stripe-Netzwerk an ein anderes Finanzkonto senden.

Erstellen einer OutboundPayment an ein externes Bankkonto

Verwenden Sie POST /v1/treasury/outbound_payments, um eine OutboundPayment aus dem Finanzkonto zu erstellen, das durch die ID im Parameterwert financial_account des Textes identifiziert wird. Die folgende Anfrage fügt die Informationen statement_descriptor und destination_payment_method_data hinzu.

Bei Erfolg gibt die Antwort die neu erstellte OutboundPayment zurück.

JSON (mit Kommentar)
{
  "id": "{{OUTBOUND_PAYMENT_ID}}",
  "object": "outbound_payment",
  // The source FinancialAccount. Funds are pulled from this account.
  "financial_account": "{{FINANCIAL_ACCOUNT_ID}}",
  // The amount to send. 10.00 USD in this case.
  "amount": 1000,
  "cancelable": true | false,
  "currency": "usd",
  // The destination payment method. Either this or `destination_payment_method_data`

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 sending funds that arrive the same business day if the OutboundPayment call successfully completes before the cutoff time. To use same-day ACH, set the destination_payment_method_options.us_bank_account.network parameter to ach and the destination_payment_method_options.us_bank_account.ach.submission parameter to 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.

Erstellen einer OutboundPayment an ein Finanzkonto

Um Geld zwischen Finanzkonten zu verschieben, rufen Sie POST /v1/treasury/outbound_payments auf dem Ursprungskonto auf und geben das Zielkonto im Parameter destination_payment_method_data an. Beide Finanzkonten müssen mit derselben Plattform, dürfen aber nicht mit demselben verbundenen Konto verknüpft sein. Um Geld zwischen den Finanzkonten zu übertragen, die mit demselben verbundenen Konto verknüpft sind, verwenden Sie OutboundTransfer.

Der Text Ihrer Anfrage muss x-www-form-urlencoded sein, aber das folgende JSON definiert die Daten, die Sie senden können.

JSON (mit Kommentar)
{
  // The source FinancialAccount. Funds are pulled from this account.
  "financial_account": "{{SOURCE_FINANCIAL_ACCOUNT_ID}}",
  // The amount to send.
  "amount": 1000,
  "currency": "usd",
  // The destination payment method. This parameter is the only way to
  // send an OutboundPayment through the `stripe` network.
  "destination_payment_method_data": {
    "type": "financial_account",

Eine OutboundPayment abrufen

Verwenden Sie GET /v1/treasury/outbound_payments/{{OUTBOUND_PAYMENT_ID}}, um Details für die OutboundPayment mit der zugehörigen ID abzurufen.

Bei Erfolg gibt die Antwort das OutboundPayment 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_PAYMENT_ID}}",
  "object": "outbound_payment",
  "livemode": true | false,
  "created": "{{Timestamp}}",
  "financial_account": "{{FINANCIAL_ACCOUNT_ID}}", // Expandable
  "amount": 1000,
  "currency": "usd",
  // Will only be set if `destination_payment_method` was used during the creation of
  // the OutboundPayment

Eine OutboundPayment stornieren

Verwenden Sie POST /v1/treasury/outbound_payments/{{OUTBOUND_PAYMENT_ID}}/cancel, um die OutboundPayment mit der zugehörigen ID zu stornieren. Das OutboundPayment-Objekt enthält den Parameter cancelable mit einem booleschen Wert, der angibt, ob die Überweisung storniert werden kann. Nachdem eine OutboundPayment an das Netzwerk übertragen wurde, wird der Wert cancelable false, und Sie erhalten eine Fehlermeldung von diesem Endpoint für diesen Transfer.

Bei Erfolgt gibt die Antwort das OutboundPayment-Objekt zurück, wobei der status-Wert auf canceled gesetzt ist.

{
  "id": "{{OUTBOUND_PAYMENT_ID}}",
  "object": "outbound_payment",
  "livemode": false,
  "created": 123456,
  "financial_account": "{{FINANCIAL_ACCOUNT_ID}}",
  "amount": 1000,
  "currency": "usd",
  ...
  "status": "canceled",

OutboundPayments auflisten

Verwenden Sie GET /v1/treasury/outbound_payments, um die OutboundPayments des Finanzkontos mit der zugehörigen ID aufzulisten. Sie können die Liste mit den Standard-Listenparametern oder nach status oder customer sortieren.

{
  // Standard list parameters
  "limit", "starting_after", "ending_before",
  // Filter by status
  "status": "processing" | "canceled" | "failed" | "posted" | "returned",
  // Filter by FinancialAccount (Required)
  "financial_account": "{{FINANCIAL_ACCOUNT_ID}}",
  // Filter by Customer
  "customer": "{{CUSTOMER_ID}}",
}

Die folgende Anfrage ruft die letzten fünf OutboundPayment-Objekte für das Finanzkonto ab, das mit der Plattform verknüpft ist und an den erkannten Customer gezahlt wurde.

Zustände von OutboundPayment

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

STATUS	BESCHREIBUNG	KANN STATUS WECHSELN
`processing`	Der Startstatus von `OutboundPayment`. Gelder werden einer ausstehenden Transaktion zugewiesen (sind aber immer noch Teil des aktuellen Saldos). Der/die Nutzer/in kann die `OutboundPayment` stornieren, während der Wert des Parameters `cancelable` auf `true` eingestellt ist.	`posted`, `canceled`, `failed`
`failed` (Terminal)	`OutboundPayment` konnte nicht bestätigt werden. Stripe storniert die ausstehende Transaktion und gibt das Geld an den/die Nutzer/in zurück.	k.A.
`canceled` (Terminal)	Ein/e Nutzer/in hat die `OutboundPayment` vor der Buchung storniert. Stripe storniert die ausstehende Transaktion und gibt die Gelder an den/die Nutzer/in zurück.	k.A.
`posted`	Die `OutboundPayment` wird gebucht, und die Gelder haben das Konto verlassen. Die zugrunde liegende Transaktion wird gebucht.	`returned`
`returned` (Terminal)	`OutboundPayment` ist nicht erfolgreich am Ziel angekommen. Gelder werden mit einer Transaktion (`returned_details[transaction]`) an den/die Nutzer/in zurückgesendet.	k.A.

OutboundPayments testen

Um einen End-to-End-Test Ihrer Integration durchzuführen, empfehlen wir die SetupIntents-Anfrage im Test-Modus, mit der Sie eine PaymentMethod erstellen können. Diese PaymentMethod wird dann über eine OutboundPayment-Erstellungsanfrage mit einem destination_payment_method-Parameter übergeben.

Stripe ermöglicht auch das Testen von PaymentMethod-Token und -Zahlen, um bestimmte Funktionen auszulösen:

Durch Übergabe eines Test-PaymentMethod-Token an destination_payment_method (für ach- und us_domestic_wire-Netzwerke)
- Wenn Sie ein Test-Token des Typs PaymentMethod direkt an destination_payment_method übergeben, müssen Sie dennoch eine Kunden-ID an den customer-Parameter übergeben. Der Einfachheit halber können Sie bei Stripe jede/n bestehende/n Kunden/Kundin im Test-Modus übergeben. Beachten Sie, dass sich dies vom Live-Modus unterscheidet. Dort muss die vorhandene PaymentMethod mit einer/einem Customer verknüpft und dieselbe Kunden-ID an den Parameter customer übergeben werden.
Durch Übergabe von Test-Routing-und Kontonummern an destination_payment_method_data[us_bank_account] (für ach- und us_domestic_wire-Netzwerke).
Durch Übergabe der ID eines bestehenden Finanzkontos im Test-Modus, das einem plattforminternen Konto gehört, an destination_payment_method_data[financial_account] (für das Stripe-Netzwerk)

Die OutboundPayment-Antwort gibt in allen Fällen den Status „wird verarbeitet“ zurück. Stripe löst Webhooks für die relevanten Statuswechsel aus und durch Abrufen der OutboundPayment nach der Erstellung wird der erwartete Status zurückgegeben.

ERSTELLT	DESTINATION_PAYMENT_METHOD (MIT ALLEN BESTEHENDEN KUNDINNEN/KUNDEN IM TEST-MODUS)	DESTINATION_PAYMENT_METHOD_DATA[US_BANK_ACCOUNT]
`OutboundPayment` im Ausgangszustand „wird verarbeitet“	`pm_usBankAccount_processing`	`routing_number`: 110000000 `account_number`: 000000000009
`OutboundPayment`, die zu `posted` wechselt (von `processing`)	`pm_usBankAccount`	`routing_number`: 110000000 `account_number`: 000123456789
`OutboundPayment`, die zu `posted` wechselt (von `processing`). Zusätzlich wird ein Tag zum ursprünglichen `expected_arrival_date` hinzugefügt.	`pm_usBankAccount_expectedArrivalDateUpdated`	`routing_number`: 110000000 `account_number`: 000123457890
`OutboundPayment`, die zu `canceled` wechselt (von `processing`)	`pm_usBankAccount_canceledByUser`	`routing_number`: 110000000 `account_number`: 000000000123
`OutboundPayment`, die zu `failed` wechselt (von `processing`)	`pm_usBankAccount_internalFailure`	`routing_number`: 110000000 `account_number`: 000000000234
`OutboundPayment`, die aufgrund einer Kontoschließung in `returned` übergeht (von „wird verarbeitet“ nach „gebucht“)	`pm_usBankAccount_accountClosed`	`routing_number`: 110000000 `account_number`: 000111111113
`OutboundPayment`, die aufgrund einer nicht vorhandenen Kontonummer in „zurückgegeben“ übergeht (von „wird bearbeitet“ nach „gebucht“)	`pm_usBankAccount_noAccount`	`routing_number`: 110000000 `account_number`: 000111111116
`OutboundPayment`, die aufgrund einer ungültigen Kontonummer in `returned` übergeht (von „wird verarbeitet“ nach „gebucht“)	`pm_usBankAccount_invalidAccountNumber`	`routing_number`: 110000000 `account_number`: 000111111119

Hilfs-Endpoints zum Testen von OutboundPayments

Stripe stellt Endpoints bereit, die Ihnen dabei helfen, OutboundPayments in verschiedenen Zuständen zu testen. Mit den Test-Endpoints können Sie eine von Ihnen erstellte OutboundPayment direkt in den neuen Status posted, failed oder returned übertragen.

Verwenden Sie den Test-Post-Endpoint, um die erkannte OutboundPayment vom Status processing in posted zu ändern.
POST /v1/test_helpers/treasury/outbound_payments/{{OUTBOUND_PAYMENT_ID}}/post
Verwenden Sie den Endpoint für fehlgeschlagene Tests, um die erkannte OutboundPayment vom Status processing in failed zu ändern.
POST /v1/test_helpers/treasury/outbound_payments/{{OUTBOUND_PAYMENT_ID}}/fail
Verwenden Sie Endpoint für Rückgabe-Tests, um die erkannte OutboundPayment vom Status processing in returned zu ändern.
POST /v1/test_helpers/treasury/outbound_payments/{{OUTBOUND_PAYMENT_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 Details zur Sendungsnachverfolgung für eine Outbound Payment 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 OutboundPayment nach dem Wechsel wird der erwartete Status zurückgegeben.

OutboundPayment-Webhooks

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

treasury.outbound_payment.created bei OutboundPayment-Erstellung.
treasury.outbound_payment.{{new_status}}, wenn sich der Status einer OutboundPayment ändert. Verfügbare Statuswertoptionen:
- treasury.outbound_payment.posted
- treasury.outbound_payment.failed
- treasury.outbound_payment.canceled
- treasury.outbound_payment.returned
treasury.outbound_payment.expected_arrival_date_updated, wenn sich das expected_arrival_date einer OutboundPayment ändert.
treasury.outbound_payment.tracking_details_updated, wenn die Tracking-Details für eine OutboundPayment aktualisiert werden.