Geld mit Treasury mithilfe von OutboundPayment-Objekten bewegen
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 kann zwischen Minuten (bei Nutzung des Stripe -Netzwerks) am selben Tag und 1 bis 2 Werktagen (bei Nutzung des ACH -Netzwerks) betragen. Weitere Informationen finden Sie im Leitfaden zum Zeitplan für Geldbewegungen.
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 (nurusd
wird unterstützt).financial_account
: Das quellseitige Finanzkonto, von dem Gelder gesendet werden.destination_payment_method
oderdestination_payment_method_data
: Informationen zum Ziel der Geldmittel für die Zahlung.- Für
destination_payment_method
müssen Sie zunächst diePaymentMethod
für ausgehende Zahlungsabläufe mit einem SetupIntent einrichten. Sie müssen außerdem die Kunden-ID angeben, die mit demCustomer
-Objekt übereinstimmt, an das diePaymentMethod
angehängt ist. Alternativ können Sie ein demCustomer
zugeordnetes bestehendes BankAccount anstelle einerPaymentMethod
verwenden. - Mit
destination_payment_method_data
können Sie Details zur Zahlungsmethode inline angeben. Sie können dies verwenden, um Bankkontodaten anzugeben oder wenn Sie Geld über das Stripe-Netzwerk an ein anderes Finanzkonto senden.
- Für
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.
Notiz
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 OutboundPayment
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 OutboundPayment
zurück.
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.
Erstellen einer OutboundPayment an ein Finanzkonto
Verwenden Sie POST /v1/treasury/outbound_payments
mit einem anderen Finanzkonto, das in der Eigenschaft destination_payment_method_data
angegeben ist, um Geld zwischen Finanzkonten zu verschieben. Beide Finanzkonten müssen mit derselben Plattform verknüpft sein, es kann sich jedoch entweder um ein mit einem verbundenen Konto verknüpftes Finanzkonto oder um das Finanzkonto der Plattform handeln.
Der Text Ihrer Anfrage muss x-www-form-urlencoded
sein, aber das folgende JSON definiert die Daten, die Sie senden können.
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.
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 an die Plattform angehängt und an den identifizierten 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 Ihre Integration durchgängig zu testen, empfiehlt Stripe die SetupIntents-Anfrage im Test-Modus zur Erstellung einer PaymentMethod
. Diese PaymentMethod
wird dann über eine OutboundPayment
-Erstellungsanfrage mit einem destination_payment_method
-Parameter weitergegeben.
Stripe ermöglicht auch das Testen von PaymentMethod
-Token und -Zahlen, um bestimmte Funktionen auszulösen:
- Durch Übergabe eines Test-
PaymentMethod
-Token andestination_payment_method
(fürach
- undus_domestic_wire
-Netzwerke)- Wenn Sie ein Test-
PaymentMethod
-Token direkt andestination_payment_method
übergeben, müssen Sie trotzdem an dencustomer
-Parameter eine Kunden-ID übergeben. Der Einfachheit halber ermöglicht Stripe Ihnen in diesem Szenario, jede/n bestehende/n Kund/in im Test-Modus zu übergeben. Beachten Sie, dass sich dies vom Live-Modus unterscheidet, bei dem die vorhandenePaymentMethod
an eine/nCustomer
angehängt und dieselbe Kunden-ID an den Parametercustomer
übergeben werden muss.
- Wenn Sie ein Test-
- Durch Übergabe von Test-Routing-und Kontonummern an
destination_payment_method_data[us_bank_account]
(fürach
- undus_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)
In allen Fällen gibt die OutboundPayment
-Antwort den Status „wird verarbeitet“ zurück. Stripe löst Webhooks für die relevanten Zustandsübergänge aus, und durch Abrufen der OutboundPayment
nach der Erstellung wird der erwartete Zustand zurückgegeben.
ERSTELLT | DESTINATION_PAYMENT_METHOD (MIT ALLEN BESTEHENDEN KUND/INNEN IM TEST-MODUS) | DESTINATION_PAYMENT_METHOD_DATA[US_BANK_ACCOUNT] |
---|---|---|
OutboundPayment im Ausgangszustand „wird verarbeitet“ | pm_usBankAccount_processing |
|
OutboundPayment , die zu posted wechselt (von processing ) | pm_usBankAccount |
|
OutboundPayment , die zu posted wechselt (von processing ). Zusätzlich wird ein Tag zum ursprünglichen expected_arrival_date hinzugefügt. | pm_usBankAccount_expectedArrivalDateUpdated |
|
OutboundPayment , die zu canceled wechselt (von processing ) | pm_usBankAccount_canceledByUser |
|
OutboundPayment , die zu failed wechselt (von processing ) | pm_usBankAccount_internalFailure |
|
OutboundPayment , die aufgrund einer Kontoschließung in returned übergeht (von „wird verarbeitet“ nach „gebucht“) | pm_usBankAccount_accountClosed |
|
OutboundPayment , die aufgrund einer nicht vorhandenen Kontonummer in „zurückgegeben“ übergeht (von „wird bearbeitet“ nach „gebucht“) | pm_usBankAccount_noAccount |
|
OutboundPayment , die aufgrund einer ungültigen Kontonummer in returned übergeht (von „wird verarbeitet“ nach „gebucht“) | pm_usBankAccount_invalidAccountNumber |
|
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 ermittelte
OutboundPayment
vonprocessing
zuposted
zu verschieben.POST /v1/test_helpers/treasury/outbound_payments/{{OUTBOUND_PAYMENT_ID}}/post
Verwenden Sie den Endpoint für fehlgeschlagene Tests, um die ermittelte
OutboundPayment
vonprocessing
zufailed
zu verschieben.POST /v1/test_helpers/treasury/outbound_payments/{{OUTBOUND_PAYMENT_ID}}/fail
Verwenden Sie den Test-Rückgabe-Endpoint, um die ermittelte
OutboundPayment
vonprocessing
zureturned
zu verschieben.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 Veröffentlichung von Nachverfolgungsdetails für eine Outbound Payment
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 OutboundPayment
nach dem Übergang wird der erwartete Zustand zurückgegeben.
OutboundPayment-Webhooks
Stripe gibt die folgenden OutboundPayment
-Ereignisse an Ihren Webhook-Endpoint aus:
treasury.outbound_payment.created
beiOutboundPayment
-Erstellung.treasury.outbound_payment.{{new_status}}
, wenn sich der Status einerOutboundPayment
ä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 dasexpected_arrival_date
einerOutboundPayment
ändert.treasury.outbound_payment.tracking_details_updated
, wenn die Tracking-Details für eineOutboundPayment
aktualisiert werden.