Geld mit Treasury mithilfe von InboundTransfer-Objekten bewegen

Verwenden Sie POST /v1/treasury/inbound_transfers, um ein InboundTransfer-Objekt zu erstellen, das Pull-basierte Überweisungen von einem externen Konto, das Sie besitzen, auf Ihr Finanzkonto darstellt. Mit anderen Worten, Sie erstellen einen InboundTransfer, um Gelder auf Ihr Finanzkonto zu überweisen, indem Sie Ihr externes US-Bankkonto belasten. Folgende Parameter müssen Sie in Ihre Anfrage aufnehmen:

• amount: Der Betrag in Cent, der auf das Finanzkonto übertragen werden soll.
• currency: Dreistelliger ISO-Währungscode (derzeit wird nur der Wert usd unterstützt).
• financial_account: Die ID des Finanzkontos, das den Transfer empfängt.
• origin_payment_method: Der Ursprungsort der eingehenden Zahlung. Sie müssen zunächst die mit dem Konto verknüpfte Zahlungsmethode für Zahlungseingänge einrichten und das Bankkonto verifizieren, indem Sie einen SetupIntent einrichten. Alternativ können Sie auch ein bestehendes BankAccount verwenden, das zuvor als verifiziertes ExternalAccount eingerichtet wurde. Unabhängig davon, ob Sie eine Zahlungsmethode oder ein Bankkonto verwenden, benötigen Sie die Zustimmung der Kontoinhaber/innen, um Gelder abzubuchen.

Der folgende JSON zeigt die Daten, die Sie in den Text Ihrer Anfrage aufnehmen können.

{
  // The source PaymentMethod or BankAccount. Funds are pulled from this account.
  "origin_payment_method": "{{PAYMENT_METHOD_ID}}" | "{{BANK_ACCOUNT_ID}}",
  // The destination FinancialAccount. Funds arrive in this account.
  "financial_account": "{{FINANCIAL_ACCOUNT_ID}}",
  // The amount to debit. 10.00 USD in this case.
  "amount": 1000,
  "currency": "usd",
  // An optional, internal description for the InboundTransfer.
  "description": "Funds for vendor payment payment_234281",
  // An optional descriptor for the InboundTransfer to send
  // to the network with the debit request. Max 10 characters
  "statement_descriptor": "payment_1",
  // Stripe does not support updating InboundTransfers after creation.
  // You can only set metadata at creation time.
  "metadata": null | {{Hash}}
}

Bei der folgenden Anfrage werden 200 USD mit einer mit einem Konto verknüpften Zahlungsmethode auf das Finanzkonto mit der angegebenen ID überwiesen. Der Stripe-Account-Header-Wert gibt das verbundene Stripe-Konto an, das sowohl das Finanzkonto als auch die Zahlungsmethode enthält.

curl https://api.stripe.com/v1/treasury/inbound_transfers \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -H "Stripe-Account: 
{{CONNECTED_ACCOUNT_ID}}
" \
  -d origin_payment_method=
{{PAYMENT_METHOD_ID}} \
  -d financial_account=
{{FINANCIAL_ACCOUNT_ID}} \
  -d amount=20000 \
  -d currency=usd \
  -d description="Funds for repair" \
  -d statement_descriptor="Invoice 12"

Bei Erfolg stellt die Antwort das Objekt InboundTransfer bereit. Dieses enthält eine hosted_regulatory_receipt_url, die dem Kontoinhaber/der Karteninhaberin weitere Angaben zur Transaktion auf Ihrer Plattform bereitstellt.

{
    "id": "{{INBOUND_TRANSFER_ID}}",
    "object": "inbound_transfer",
    "amount": 20000,
    "created": 1648071297,
    "currency": "usd",
    "description": "Funds for repair",
    "financial_account": "{{FINANCIAL_ACCOUNT_ID}}",
    "hosted_regulatory_receipt_url": "https://payments.stripe.com/regulatory-receipt/{{IBT_URL}}",
    "linked_flows": null,
    "livemode": false,
    "metadata": {},
    "origin_payment_method": "{{PAYMENT_METHOD_ID}}",
    ...
    "statement_descriptor": "Invoice 12",
    "status": "processing",
    ...
}

ACH-Abwicklung am selben Tag

Durch die Nutzung der ACH-Abwicklung am selben Tag können Gelder innerhalb desselben Werktages auf dem ursprünglichen Finanzkonto eingehen, wenn der Aufruf InboundTransfer erfolgreich vor der Annahmefrist abgeschlossen wurde. Um die ACH-Abwicklung am selben Tag zu verwenden, setzen Sie den Parameter origin_payment_method_options.us_bank_account.ach.submission auf same_day.

Verwenden Sie GET /v1/treasury/inbound_transfers/{{INBOUND_TRANSFER_ID}}, um Details für den InboundTransfer mit der zugehörigen ID abzurufen.

Der folgende JSON zeigt die Daten, die Sie in den Text Ihrer Anfrage aufnehmen können. 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": "{{INBOUND_TRANSFER_ID}}",
  "object": "inbound_transfer",
  "livemode": false,
  "created": "{{Timestamp}}",
  "financial_account": "{{FINANCIAL_ACCOUNT_ID}}", // Expandable
  "amount": 1000,
  "currency": "usd",
  // The only current valid PaymentMethod type for InboundTransfers is us_bank_account
  "origin_payment_method": "{{PAYMENT_METHOD_ID}}",

Die folgende Anfrage ruft den InboundTransfer mit dem id-Wert {{INBOUND_TRANSFER_ID}} ab. Durch Aufnehmen von transaction in das expand[]-Array des Texts werden die relevanten erweiterten Informationen zurückgegeben.

curl -G https://api.stripe.com/v1/treasury/inbound_transfers/{{INBOUND_TRANSFER_ID}} \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -H "Stripe-Account: 
{{CONNECTED_ACCOUNT_ID}}
" \
  -d "expand[]"=financial_account

Bei Erfolg gibt die Antwort das InboundTransfer-Objekt mit den erweiterten Informationen zurück.

{
    "id": "{{INBOUND_TRANSFER_ID}}",
    "object": "inbound_transfer",
    "amount": 20000,
    "created": 1648071297,
    "currency": "usd",
    "description": "Inbound transfer",
    "failure_details": null,
    "financial_account": "{{FINANCIAL_ACCOUNT_ID}}",
    "hosted_regulatory_receipt_url": "https://payments.stripe.com/regulatory-receipt/{{INBOUND_TRANSFER_ID}}",

Verwenden Sie GET /v1/treasury/inbound_transfers, um alle InboundTransfers des Finanzkontos mit der zugehörigen ID abzurufen. 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" | "succeeded" | "failed",
  // Filter by FinancialAccount (Required)
  "financial_account": "{{FINANCIAL_ACCOUNT_ID}}", // Required
}

Die folgende Anfrage ruft alle eingehenden Transfers mit dem Statussucceeded für das Finanzkonto mit der ID {{FINANCIAL_ACCOUNT_ID}} ab, das an das verbundene Konto mit der ID {{CONNECTED_ACCOUNT_ID}} angehängt ist.

curl -G https://api.stripe.com/v1/treasury/inbound_transfers \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -H "Stripe-Account: 
{{CONNECTED_ACCOUNT_ID}}
" \
  -d financial_account=
{{FINANCIAL_ACCOUNT_ID}} \
  -d status=succeeded

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, verwenden Sie die SetupIntents-Anfragen im Test-Modus, um eine PaymentMethod zu erstellen und dann diese PaymentMethod in eine InboundTransfer-Erstellungsanfrage zu übergeben. Gültige PaymentMethods führen zu erfolgreichen InboundTransfers, während ungültige PaymentMethods (z. B. nicht unterstützte Typen, die ein nicht verifiziertes Bankkonto enthalten oder nicht auf eingehende Geldbewegungen ausgelegt sind) dieselben Fehlermeldungen erzeugen, wie im Live-Modus.

Stripe bietet auch eine Reihe an Token zum Testen von PaymentMethod, die Sie verwenden können, um bestimmte Statusübergänge auszulösen:

Um verschiedene Grenzfälle schneller zu testen, simulieren die PaymentMethod-Token bestimmte Fehlertypen:

In allen Fällen befindet sich die InboundTransfer-Antwort im Status processing. Sie empfangen Webhooks für jeden relevanten Statuswechsel, und durch Abrufen des InboundTransfer nach der Erstellung wird der erwartete Status zurückgegeben.

Stripe stellt zudem Endpoints bereit, mit denen Sie InboundTransfers in verschiedenen Zuständen testen können. Erstellen Sie einen InboundTransfer und gehen Sie anschließend wie folgt vor:

• Verwenden Sie Endpoint für succeed Tests, um den Transfer mit der zugehörigen ID direkt in den Status succeeded zu übertragen.

  POST /v1/test_helpers/treasury/inbound_transfers/{{INBOUND_TRANSFER_ID}}/succeed

• Verwenden Sie Endpoint für fehlgeschlagene Tests, um den Transfer mit der zugehörigen ID direkt in den Status failed zu übertragen.

  POST /v1/test_helpers/treasury/inbound_transfers/{{INBOUND_TRANSFER_ID}}/fail

Diese Endpoints sind besonders nützlich zum Testen von Fehlerszenarien, wie Rückgaben, die andernfalls eine Aktion von einem externen Konto, von dem der InboundTransfer Gelder abruft, erforderlich machen würde.

Fügen Sie den optionalen Parameter failure_details.code in den Text ein, um den Grund für das Fehlschlagen der Übertragung anzugeben. Wenn Sie ihn nicht angeben, schlägt die Übertragung mit dem Standardfehlercode could_not_process fehl.

{
  "failure_details": {
    "code": "account_closed" |
          "account_frozen" |
          "bank_account_restricted" |
          "bank_ownership_changed" |
          "could_not_process" | // Generic fallback code
          "invalid_account_number" |
          "incorrect_account_holder_name" |
          "invalid_currency" |
          "no_account"
  }
}

Treasury stellt auch einen return-Endpoint bereit, um einen erfolgreichen InboundTransfer zu simulieren, der erfolgreich ist, aber später zurückgegeben wird.

Verwenden Sie Endpoint für Rückgabe-Tests, um die die simulierte Rückgabe für den InboundTransfer mit der zugehörigen ID auszulösen.

POST /v1/test_helpers/treasury/inbound_transfers/{{INBOUND_TRANSFER_ID}}/return

Alle Test-Endpoints lösen für alle relevanten Status-Übergänge Webhooks aus, und durch Abrufen des InboundTransfer nach dem Übergang wird der erwartete Status zurückgegeben.

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

• treasury.inbound_transfer.created bei Erstellen des InboundTransfer.
• treasury.inbound_transfer.{{new_status}}, wenn sich der Status eines InboundTransfer ändert. Verfügbare Statuswertoptionen:
  • treasury.inbound_transfer.succeeded
  • treasury.inbound_transfer.failed