Geld mit Treasury mithilfe von OutboundPayment-Objekten bewegen

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.

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_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -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

Durch die Verwendung der ACH-Abwicklung am selben Tag können Sie Gelder senden, die am selben Werktag eingehen, wenn der Aufruf OutboundPayment 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.

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 verknüpft sein. Dabei können diese mit einem verbundenen Konto oder mit dem Finanzkonto der Plattform verknüpft sein.

curl https://api.stripe.com/v1/treasury/outbound_payments \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -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 via the `stripe` network.
  "destination_payment_method_data": {
    "type": "financial_account",

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_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -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

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_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -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",

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_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d financial_account=
{{FINANCIAL_ACCOUNT_ID}} \
  -d limit=5 \
  -d customer=
{{CUSTOMER_ID}}

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

Um einen End-to-End-Test Ihrer Integration durchzuführen, empfiehlt Stripe 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.

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.

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.