Bewegen von Geld mit OutboundPayment-Objekten

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 Überweisungszeit für ausgehende Zahlungen kann von Minuten (bei Nutzung des Stripe-Netzwerks) am selben Tag bis zu 1-2 Werktagen (bei Nutzung des ACH-Netzwerks) reichen. Weitere Informationen finden Sie im Leitfaden Zeitpläne 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 (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.

curl https://api.stripe.com/v1/treasury/outbound_payments \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -H "Stripe-Account: 
{{CONNECTED_ACCOUNT_ID}}
" \
  -d financial_account=
"{{FINANCIAL_ACCOUNT_ID}}" \
  -d amount=2000 \
  -d currency=usd \
  -d statement_descriptor=payment_1 \
  -d "destination_payment_method_data[type]"=us_bank_account \
  -d "destination_payment_method_data[us_bank_account][account_holder_type]"=individual \
  -d "destination_payment_method_data[us_bank_account][routing_number]"=110000000 \
  -d "destination_payment_method_data[us_bank_account][account_number]"=1234567890 \
  --data-urlencode "destination_payment_method_data[billing_details][email]"="jenny@example.com" \
  -d "destination_payment_method_data[billing_details][phone]"=7135551212 \
  -d "destination_payment_method_data[billing_details][address][city]"=Alvin \
  -d "destination_payment_method_data[billing_details][address][state]"=TX \
  -d "destination_payment_method_data[billing_details][address][postal_code]"=77511 \
  -d "destination_payment_method_data[billing_details][address][line1]"="123 Main St." \
  -d "destination_payment_method_data[billing_details][name]"="Jenny Rosen"

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

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

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.

Erstellen einer OutboundPayment an ein Finanzkonto

Um Geld zwischen Finanzkonten zu überweisen, rufen Sie POST /v1/treasury/outbound_payments auf dem Ursprungskonto auf und geben Sie das Zielkonto im Parameter destination_payment_method_data an. Beide Finanzkonten müssen mit derselben Plattform verknüpft sein, können aber entweder mit einem verbundenen Konto oder der Plattform verknüpft werden.

curl https://api.stripe.com/v1/treasury/outbound_payments \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -H "Stripe-Account: 
{{CONNECTED_ACCOUNT_ID}}
" \
  -d financial_account={{SOURCE_FINANCIAL_ACCOUNT_ID}} \
  -d amount=2000 \
  -d currency=usd \
  -d statement_descriptor="Test outbound payment to FA" \
  -d "destination_payment_method_data[type]"=financial_account \
  -d "destination_payment_method_data[financial_account]"={{DESTINATION_FINANCIAL_ACCOUNT_ID}}

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

{
  // 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.

curl https://api.stripe.com/v1/treasury/outbound_payments/{{OUTBOUND_PAYMENT_ID}} \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -H "Stripe-Account: 
{{CONNECTED_ACCOUNT_ID}}
"

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.

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

curl -X POST https://api.stripe.com/v1/treasury/outbound_payments/{{OUTBOUND_PAYMENT_ID}}/cancel \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -H "Stripe-Account: 
{{CONNECTED_ACCOUNT_ID}}
"

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.

curl -G https://api.stripe.com/v1/treasury/outbound_payments \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d financial_account=
"{{FINANCIAL_ACCOUNT_ID}}" \
  -d limit=5 \
  -d customer=
"{{CUSTOMER_ID}}"

Zustände von OutboundPayment

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

OutboundPayments testen

Um Ihre Integration End-to-End zu testen, empfehlen wir die Verwendung von Test-SetupIntent-Anforderungen, um eine PaymentMethod zu erstellen und übergeben Sie dann diese PaymentMethod in ein OutboundPayment-Erstellungsanfrage mit dem Parameter destination_payment_method.

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.

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.