Mit Kontoständen und Transaktionen arbeiten

Finanzkonten verfügen über einen eigenen Saldo, getrennt vom Saldo des Kontos, mit dem sie verknüpft sind (Plattformkonto oder verbundenes Konto). Balance-Objekte erfassen die Höhe der Gelder auf einem Finanzkonto und deren Verfügbarkeitsstatus. Transaction- und TransactionEntry-Objekte buchen Gelder von diesem Guthaben ab oder schreiben sie gut.

Guthaben

Ein Finanzkonto hat einen Kontostand. Die Summe des Saldos steht jedoch nicht immer zum Ausgeben zur Verfügung, da sie ausstehende Transaktionen auf das oder aus dem Finanzkonto enthalten kann. Der Saldo des Finanzkontos enthält drei Eigenschaften, die die Verfügbarkeit seiner Gelder definieren:

• cash: Gelder, die der/die Nutzer/in jetzt ausgeben kann.
• inbound_pending: Gelder, die noch nicht ausgegeben werden können, jedoch zu einem späteren Zeitpunkt verfügbar werden. Die Eigenschaft inbound_pending ist für zukünftige Funktionen reserviert und hat immer den Wert 0.
• outbound_pending: Gelder auf dem Konto, die nicht ausgegeben werden können, da sie für ausstehende ausgehende Transaktionen zurückgehalten werden.

Verwenden Sie GET /v1/treasury/financial_accounts/{{FINANCIAL_ACCOUNT_ID}}, um die Saldodetails eines Finanzkontos mit der zugehörigen ID abzurufen. Geben Sie den Stripe-Account-Header an, wenn das Finanzkonto an eines Ihrer verbundenen Konten angehängt ist. Ist das Finanzkonto an Ihr Plattformkonto angehängt, nehmen Sie den Stripe-Account-Header nicht auf.

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

Bei Erfolg ist die Antwort ein FinancialAccount-Objekt mit einem balance-Hash, der die Gelder und ihre Verfügbarkeit im Detail beschreibt.

{
  "object": "treasury.financial_account",
  "id": "{{FINANCIAL_ACCOUNT_ID}}",
  ...
  "balance": {
    // $90 is currently available for use,
    // with an additional $10 held in the outbound_pending sub-balance
    "cash": {"usd": 9000},
    "inbound_pending": {"usd": 0},
    "outbound_pending": {"usd": 1000}
  }
}

Negativsalden und Überziehungen

Wenn Ihr verbundenes Konto einen negativen Saldo aufweist (z. B. wenn Ihr Finanzkonto eine ACH-Gutschrift erhält, die storniert wird), sind Sie dafür verantwortlich, den Saldo auszugleichen und wieder auf 0 USD zu bringen. Sollte der Kontostand 180 Tage lang nicht ausgeglichen werden, belastet Stripe Ihre Plattform. Wir kontaktieren Sie auch, wenn einzelne oder aggregierte Salden unsere Risikolimits überschreiten.

Wir empfehlen Ihnen, Ihre verbundenen Konten und deren Salden im Blick zu behalten, für den Fall dass diese negativ werden sollten. Sie können Gelder auf Ihr Finanzkonto über Inbound Transfers oder Stripe Payouts einzahlen. Prüfen Sie Ihre die Kontostände Ihrer verbundenen Konten regelmäßig und melden Sie sich bei Bedarf umgehend bei diesen.

Wenn der Kontostand eines Finanzkontos 180 Tage lang negativ war, belastet Stripe das Finanzkonto Ihrer Plattform. Wir benachrichtigen Sie vorab per E-Mail über diesen Vorgang. Wenn die Überweisung aufgrund unzureichender Deckung fehlschlägt, kontaktiert Stripe Sie mit den nächsten Schritten.

Transaktionen

Alle Änderungen an einem Saldo haben ein entsprechendes Transaktions-Objekt, das Geldübertragungen detailliert nachverfolgt. Transaktionen betreffen nur einen Saldo und haben eine einzige Währung (derzeit unterstützt Stripe Treasury nur USD)

Jede Transaktion verweist auf das saldorelevante Geldübertragungsobjekt, z. B. OutboundTransfer, ReceivedCredit oder ReceivedDebit.

Transaktionszustand Maschine

Die verfügbaren Transaction-Endpoints ermöglichen es Ihnen, bestimmte Transaktionen abzurufen und Transaktionen aufzulisten oder zu sortieren, die sich auf ein Finanzkonto auswirken. Im Gegensatz zu den zugehörigen Geldbewegungs-Objekten (z. B. OutboundPayments) sind für Transaktionen keine Webhooks verfügbar.

Transaktion abrufen

Verwenden Sie GET/v1/treasury/transactions/{{TRANSACTION_ID}}, um die Transaktion mit der zugehörigen ID abzurufen.

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

Bei Erfolg gibt die Antwort das Transaction-Objekt zurück.

{
  "id": "{{TRANSACTION_ID}}",
  "object": "treasury.transaction",
  "created": "{{Timestamp}}",
  "livemode": false,
  // The FinancialAccount this Transaction impacts
  "financial_account": "{{FINANCIAL_ACCOUNT_ID}}",
  // The flow responsible for this Transaction. Each Transaction is created
  // synchronously (that is, in the same API request for initiated objects) with
  // its flow.

Transaktionen auflisten

Verwenden Sie GET /v1/treasury/transactions, um Transaktionen für ein Finanzkonto aufzulisten. Setzen Sie den Pflichtparameter financial_account im Text auf den Wert der Finanzkonto-ID, für die Transaktionen abgerufen werden sollen. Nehmen Sie zusätzliche Parameter auf, um die zurückgegebenen Ergebnisse zu sortieren.

Zusätzlich zu den standardmäßigen Listenparametern können Sie Transaktionen folgendermaßen filtern.

• status
• flow
• Entweder created oder posted_at, aber nicht beide

{
  // Standard list parameters
  limit, starting_after, ending_before,
  // Filter by FinancialAccount, required
  financial_account: "{{FINANCIAL_ACCOUNT_ID}}"
  // Filter by status
  status: "open" | "posted" | "void",
  // Filter by flow
  flow: "{{FLOW_OBJECT_ID}}",
  // Order the results by the created or posted_at timestamps, default is `created`.
  // For order_by=posted_at, setting status='posted' is required
  order_by: "created" | "posted_at",
  // created can only be specified with order_by = 'created'
  created: {gt, gte, lt, lte},
  status_transitions: {
    // status_transitions.posted_at can only be specified with order_by = 'posted_at' and status = 'posted'
    posted_at: {gt, gte, lt, lte}
  }
}

Die folgende Anfrage ruft die letzten drei Transaktionen ab, die auf dem Finanzkonto erstellt wurden und den status posted aufweisen.

curl -G https://api.stripe.com/v1/treasury/transactions \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -H "Stripe-Account: 
{{CONNECTED_ACCOUNT_ID}}
" \
  -d financial_account=
{{FINANCIAL_ACCOUNT_ID}} \
  -d limit=3 \
  -d status=posted \
  -d order_by=created

Webhooks

Es gibt keine Webhooks für Transaktionen, da die verschiedenen Geldbewegungen, die eine Transaktion veranlassen, über eigene Webhooks verfügen.

Transaktionseinträge

Bei TransactionEntry-Objekten handelt es sich um die detaillierteste Ansicht der Geldübertragungen, die sich auf das Guthaben eines Finanzkontos auswirken. Eine einzelne Übertragung kann aus mehreren individuellen Geldübertragungen bestehen, von denen jede durch eine Transaktion dargestellt wird. Bei Transaktionen handelt es sich hingegen um eine Gruppierung von Transaktionseinträgen. Wenn beispielsweise eine ausgehende Zahlung in Höhe von 10 USD zum Zeitpunkt T eingeleitet wird, werden Gelder aus dem Teilguthaben cash in das Teilguthaben outbound_pending verschoben. Die folgende Transaction-Objektantwort demonstriert dieses erste Ereignis.

{
  "id": "{{TRANSACTION_ID}}",
  "object": "treasury.transaction",
  "created": "{{T}}",
  ...
  "flow": "{{OUTBOUND_PAYMENT_ID}}",
  "flow_type": "outbound_payment",
  "status": "open",
  "amount": -1000,
  "currency": "usd",

Nachdem die ausgehende Zahlung zum Zeitpunkt T+1 gebucht wird, werden die Gelder von outbound_pending abgezogen und der Transaktion wird ein neuer Transaktionseintrag hinzugefügt. Die folgende Transaction-Antwort demonstriert diesen Fortschritt.

{
  "id": "{{TRANSACTION_ID}}",
  "object": "treasury.transaction",
  "created": "{{T}}",
  ...
  "flow": "{{OUTBOUND_PAYMENT_ID}}",
  "flow_type": "outbound_payment",
  "status": "posted",
  "amount": -1000,
  "currency": "usd",

Wie die vorangegangenen Antworten zeigen, kann eine Transaktion mehrere Transaktionseinträge enthalten. Mit den verfügbaren TransactionEntry-Endpoints können Sie bestimmte Transaktionseinträge abrufen und sie für eine bestimmte Transaktion auflisten oder filtern.

Zu einer Transaction mit dem Status void werden keine neuen Transaktionseinträge hinzugefügt. Einer Transaction mit dem Status posted, bei der das gesamte balance_impact auf das Unter-Guthaben cash entfällt, werden auch keine neuen Transaktionseinträge hinzugefügt.

Transaktionseinträge abrufen

Verwenden Sie GET /v1/treasury/transaction_entries/{{TRANSACTIONENTRY_ID}}, um Details für den Transaktionseintrag mit der zugehörigen ID abzurufen.

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

Bei Erfolg gibt die Antwort ein TransactionEntry-Objekt in der folgenden Form zurück.

{
  "id": "{{TRANSACTION_ENTRY_ID}}",
  "object": "treasury.transaction_entry",
  "created": "{{Timestamp}}",
  "livemode": false,
  // The FinancialAccount this transaction entry impacts.
  "financial_account": "{{FINANCIAL_ACCOUNT_ID}}",
  // The transaction that this transaction entry belongs to.
  "transaction": "{{TRANSACTION_ID}}",
  // The flow responsible for this transaction entry.

TransactionEntries auflisten

Verwenden Sie GET /v1/treasury/transaction_entries, um die Transaktionseinträge für ein Finanzkonto aufzulisten. Setzen Sie den Pflichtparameter financial_account im Text auf den Wert der Finanzkonto-ID, für die Transaktionseinträge abgerufen werden sollen. Nehmen Sie zusätzliche Parameter auf, wenn Sie die Liste sortieren möchten.

Zusätzlich zu den standardmäßigen Listenparametern können Sie Transaktionen folgendermaßen sortieren:

• transaction
• Entweder created oder effective_at, aber nicht beide

{
  // Standard list parameters
  limit, starting_after, ending_before,
  // Filter by FinancialAccount, required
  financial_account: "fa_123"
  // Filter by transaction
  transaction: 'trxn_123',
  // Order the results by the created or effective_at timestamps, default is `created`.
  order_by: "created" | "effective_at",
  // created can only be specified with order_by = 'created'
  created: {gt, gte, lt, lte},
  // effective_at can only be specified with order_by = 'effective_at'
  effective_at: {gt, gte, lt, lte},
}

Die folgende Anfrage ruft die Transaktionseinträge ab, die vor dem {{Timestamp}} erstellt wurden und bestellt sie am created-Datum.

curl -G https://api.stripe.com/v1/treasury/transaction_entries \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -H "Stripe-Account: 
{{CONNECTED_ACCOUNT_ID}}
" \
  -d financial_account=
{{FINANCIAL_ACCOUNT_ID}} \
  -d order_by=created \
  -d "created[lt]"=1234567890

Webhooks

Es gibt keine Webhooks für Transaktionseinträge, da die verschiedenen Geldbewegungen, die einen Transaktionseintrag veranlassen, über eigene Webhooks verfügen.