Use Cases für erweiterte Antworten

Verwenden Sie den Parameter expand in Ihrer API-Anfrage, um Details abzurufen, die die API in ihrer Standardantwort nicht zurückgibt. Die folgenden Use cases veranschaulichen dies für häufig angeforderte Informationen.

Stripe-Gebühr für eine bestimmte Zahlung anzeigen

Sie können die Bearbeitungsgebühren einer Zahlung prüfen, nachdem die Zahlung verarbeitet wurde und Stripe die Saldo-Transaktion erstellt hat. Das Ereignis charge.updated verweist auf die Eigenschaft balance_transaction (zum Beispiel txn_123) und zeigt an, dass sie einsatzbereit ist.

Anstatt die Saldotransaktion separat zu suchen, können Sie sie mit expand in einem einzigen Anruf abrufen.

curl https://api.stripe.com/v1/payment_intents/pi_1Gpl8kLHughnNhxyIb1RvRTu \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -d "expand[]"="latest_charge.balance_transaction" \
  -G

Nutzer/innen mit API-Version 2022-08-01 oder älter:

curl https://api.stripe.com/v1/payment_intents/pi_1Gpl8kLHughnNhxyIb1RvRTu \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -d "expand[]"="charges.data.balance_transaction" \
  -G

Bei Verwendung von automatic_async (dem Standard der capture_method seit Version 2024-04-10) werden Saldo-Transaktionen erstellt, nachdem die Zahlung erfolgreich war, jedoch asynchron im Hintergrund. Das bedeutet:

• Das Feld balance_transaction im Zahlungsobjekt könnte unmittelbar nach der Bestätigung null sein.
• Wenn Sie balance_transaction oder latest_charge.balance_transaction erweitern, könnte es in der Antwort noch nicht verfügbar sein.
• Sie können auf das Ereignis charge.updated warten, um zu wissen, wann die Saldo-Transaktion verfügbar wird

Dieses asynchrone Verhalten verbessert die Zahlungsleistung, erfordert jedoch, dass Ihre Integration die Möglichkeit berücksichtigt, dass die Saldo-Transaktion möglicherweise nicht sofort verfügbar ist.

In einer Auszahlung enthaltene Gebühren anzeigen

Jede automatische Auszahlung ist an historische Änderungen des Saldos Ihres Stripe-Kontos gebunden. Die API zeichnet diese historischen Änderungen als Saldo-Transaktionen auf, die Sie mit Saldo-Transaktionen auflisten abrufen können. Aus einer Liste von Saldo-Transaktionen können Sie die Eigenschaft source erweitern, um Informationen darüber zu erhalten, was die Änderung des Kontosaldos ausgelöst hat (Zahlung, Erstattung, Überweisung usw.). Zum Beispiel:

curl https://api.stripe.com/v1/balance_transactions \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -d payout=po_1Gl3ZLLHughnNhxyDrOia0vI \
  -d type=charge \
  -d "expand[]"="data.source" \
  -G

Weitere Infos zum Auszahlungsabgleich.

Wenn Sie Connect mit Zielgebühren verwenden, können Sie die gleichen Informationen im Namen Ihrer verbundenen Konten abrufen. Ein Unterschied besteht darin, dass Zielgebühren sowohl eine Überweisung als auch eine verknüpfte Zahlung (in Form eines Charge-Objekts) beinhalten, um Mittel auf ein verbundenes Konto zu verschieben. Bei der Auflistung der Saldo-Transaktionen, die in den Auszahlungen Ihres verbundenen Kontos gebündelt sind, ist die Quelle jeder Saldo-Transaktion also mit der Zahlung der Überweisung verknüpft und nicht mit der Ursprungsgebühr. Um die verursachende Gebühr abzurufen, müssen Sie die verknüpfte Überweisung einer Zahlung über die Eigenschaft source_transfer erweitern und von dort aus müssen Sie die Eigenschaft source_transaction der Überweisung erweitern:

curl https://api.stripe.com/v1/balance_transactions \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -d payout=po_1G7bnaD2wdkPsFGzdVOqU44u \
  -d type=payment \
  -d "expand[]"="data.source.source_transfer.source_transaction" \
  -H "Stripe-Account: acct_1G7PaoD2wdkPsFGz" \
  -G