Bewegen von Geld mit InboundTransfer-Objekten

Bei eingehenden Überweisungen wird Geld mithilfe des ACH-Netzwerks von einem externen US-Bankkonto auf ein Finanzkonto übertragen. Diese Transfers werden mit InboundTransfer-Objekten initiiert.

Eingehende Überweisungen dauern 2-4 Werktage, es sei denn, Sie verwenden die ACH-Funktion für Überweisungen am selben Tag. Weitere Informationen finden Sie in der Anleitung Zeitpläne für Geldbewegungen.

Einen InboundTransfer erstellen

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: Die Herkunft der Geldmittel für die eingehende Überweisung. Sie müssen zuerst die kontospezifische Zahlungsmethode für eingehende Geldflüsse einrichten und das Bankkonto mit einem SetupAbsicht verifizieren. Alternativ können Sie ein vorhandenes Bankkonto nutzen, das zuvor als verifiziertes externes Konto eingerichet wurde. Unabhängig davon, ob Sie eine Zahlungsmethode oder ein Bankkonto verwenden, benötigen Sie die Erlaubnis des Kontoinhabers, um das Geld vom Konto 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 doesn't 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_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -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

Die Verwendung von ACH am selben Tag ermöglicht es, dass Geldmittel innerhalb desselben Werktags auf dem ursprünglichen Finanzkonto eingehen, wenn der Aufruf InboundTransfer vor Fristablauf erfolgreich abgeschlossen wird. Um ACH am selben Tag zu verwenden, setzen Sie den Parameter origin_payment_method_options.us_bank_account.ach.submission auf same_day.

Betrugsrisiko bei taggleicher ACH-Verfügbarkeit

Die schnelle Abwicklung von eingehenden ACH-Überweisungen am selben Tag kann Ihre Plattform einem größeren finanziellen Risiko aussetzen als bei standardmäßigen eingehenden ACH-Überweisungen. Beispielsweise kann ein verbundenes Konto eine eingehende Überweisung initiieren, die aufgrund unzureichender Deckung des Quellkontos zurückgegeben wird. Die Abrechnung am selben Tag lässt mehr Zeit, um das Geld möglicherweise vom Finanzkonto abzuheben, bevor es zurückgegeben wird. Wenn das verbundene Konto die Geldmittel abhebt und die Rückgabe dann einen negativen Saldo auf dem Finanzkonto verursacht, ist Ihre Plattform verantwortlich.

Wenn die Betrugspräventionssysteme von Stripe eine eingehende Überweisung als hochriskant einstufen, schlägt die Erstellungsanfrage mit einem Fehler fehl:

{
  "error": {
    "type": "invalid_request_error",
    "message_code": "inbound_transfer_not_same_day_eligible",
    "message": "This transaction is not eligible for same-day availability at this time. Please try again with `standard` ACH submission."
  }
}

Wenn der Meldungscode inbound_transfer_not_same_day_eligible fehlerhaft ist, wiederholen Sie die Anfrage mit dem als standard festgelegten Parameter origin_payment_method_options.us_bank_account.ach.submission.

Einen InboundTransfer abrufen

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

InboundTransfers auflisten

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_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -H "Stripe-Account: 
{{CONNECTED_ACCOUNT_ID}}
" \
  -d financial_account=
"{{FINANCIAL_ACCOUNT_ID}}" \
  -d status=succeeded

InboundTransfers manuell überprüfen

Sie können das Risiko eingehender Transfers verringern, indem Sie die Übermittlung an unsere Bankpartner verzögern oder Gelder über einen längeren Zeitraum zurückhalten. Diese zurückgehaltenen Karten geben Ihnen zusätzliche Zeit, um potenziell verdächtige Aktivitäten zu überprüfen. Sie können Zugriff auf die inbound_transfers.ach.platform_review-Funktion anfordern und Finanzkonten mit dieser aktivierten Funktion erhalten alle eingehenden Überweisungen mit einem requires_confirmation-Status.

Das nachfolgende Beispiel zeigt die Einrichtung dieser Funktion bei einem neuen Finanzkonto. Sie können auch andere Funktionen hinzufügen.

curl https://api.stripe.com/v1/treasury/financial_accounts \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -H "Stripe-Account: 
{{CONNECTED_ACCOUNT_ID}}
" \
  -d "supported_currencies[]"=usd \
  -d "inbound_transfers[ach][requested]"=true \
  -d "inbound_transfers[ach][platform_review][requested]"=true

Das nachfolgende Beispiel zeigt die Einrichtung dieser Funktion bei einem bestehenden Finanzkonto.

curl https://api.stripe.com/v1/treasury/financial_accounts/fa_xxx/features \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -H "Stripe-Account: 
{{CONNECTED_ACCOUNT_ID}}
" \
  -d "supported_currencies[]"=usd \
  -d "inbound_transfers[ach][requested]"=true \
  -d "inbound_transfers[ach][platform_review][requested]"=true

In der Regel senden wir eingehende Überweisungen nach ihrer Erstellung automatisch an die Bank. Eingehende Überweisungen mit dem Status requires_confirmation erfordern jedoch eine ausdrückliche Nutzerbestätigung über den /v1/treasury/inbound_transfers/{id}/confirm-Endpoint, bevor wir die Überweisungen an unsere Bankpartner senden können. Sie können die Details der eingehenden Überweisung und die Risikosignale überprüfen, bevor Sie die Überweisung bestätigen oder stornieren. Um eingehende Überweisungen mit dem Status requires_confirmation zu bestätigen oder zu stornieren, haben Sie 5 Werktage lang Zeit. Nach 5 Werktagen wird die eingehende Überweisung automatisch storniert. Sie haben beispielsweise bis zum folgenden Freitag Zeit, um eine eingehende Überweisung mit dem Status requires_confirmation, die an einem Freitag erstellt wurde (sofern es sich nicht um einen Feiertag in den USA handelt), zu bestätigen.

Verwenden Sie den funds_availability_delay-Parameter mit dem confirm-Endpoint, um die Verzögerung (in Sekunden) anzugeben, mit der die Gelder vor der Freigabe auf das vorgesehene Finanzkonto zurückgehalten werden sollen. Auf diese Weise können Sie die zusätzliche Verzögerung nutzen, um eine Überweisung manuell zu überprüfen. Sie können dieses Feld auch verwenden, um Gelder über das ACH-Rückgabefenster hinaus zu halten, sodass die Ursprungsbank Gelder nicht zurückrufen kann, nachdem sie ausgegeben wurden. Für zusätzliche Sicherheit empfehlen wir, funds_availability_delay auf 432.000 festzulegen, wodurch Gelder über das Rückgabefenster hinaus freigegeben werden.

Im Folgenden finden Sie ein Beispiel für den Aufruf des confirm-Endpoints ohne Verfügbarkeitsverzögerung.

curl -X POST https://api.stripe.com/v1/treasury/inbound_transfers/ibt_xxx/confirm \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -H "Stripe-Account: 
{{CONNECTED_ACCOUNT_ID}}
"

Im Folgenden finden Sie ein Beispiel für den Aufruf des confirm-Endpoints mit einer Verfügbarkeitsverzögerung.

curl https://api.stripe.com/v1/treasury/inbound_transfers/ibt_xxx/confirm \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -H "Stripe-Account: 
{{CONNECTED_ACCOUNT_ID}}
" \
  -d funds_availability_delay=432000

Status von InboundTransfers

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

InboundTransfers testen

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.

Zustände von InboundTransfers testen

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 vorhergehenden Fällen befindet sich die InboundTransfer-Antwort im Status processing. Sie erhalten Webhook-Ereignisse für alle relevanten Zustandsübergänge und durch Abrufen des InboundTransfer nach der Erstellung wird der erwartete Zustand zurückgegeben.

Sie können den Fehlerstatus auch testen, indem Sie das Token pm_usBankAccount_sameDayACHIneligible als PaymentMethod übergeben. Dies löst einen fehlgeschlagenen InboundTransfer (mit ACH-Übermittlung am selben Tag) aus und gibt einen Fehler zurück.

Hilfs-Endpoints zum Testen von InboundTransfers

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

Finanzkonten für Plattformen bieten auch einen return-Endpoint, um einen erfolgreichen InboundTransfer zu simulieren, der jedoch 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.

InboundTransfer-Webhooks

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