Casi d'uso per l'ampliamento delle risposte

Utilizza il parametro expand nella richiesta API per recuperare i dati che l’API non restituisce nella sua risposta predefinita. I seguenti casi d’uso mostrano questa situazione per le informazioni richieste più di frequente.

Visualizzare le commissioni di Stripe per un determinato pagamento

Puoi controllare le commissioni di elaborazione di un pagamento dopo che il pagamento è stato elaborato e Stripe crea la transazione saldo. L’evento charge.updated fa riferimento alla proprietà balance_transaction (ad esempio, txn_123), che indica che è pronta per l’uso.

Anziché cercare separatamente la transazione del saldo, puoi recuperarla in una singola chiamata utilizzando il parametro expand.

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

Utenti con versione API 2022-08-01 o precedente:

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

Quando si utilizza automatic_async (il metodo capture_method predefinito dalla versione 2024-04-10), le transazioni saldo vengono create dopo il pagamento, ma in modo asincrono in background. Ciò significa che:

• Il campo balance_transaction dell’oggetto Charge potrebbe essere null subito dopo la conferma.
• Se espandi balance_transaction o latest_charge.balance_transaction, potrebbe non essere disponibile nella risposta.
• Puoi ascoltare l’evento charge.updated per sapere quando la transazione saldo diventa disponibile

Questo comportamento asincrono migliora le prestazioni dei pagamenti, ma richiede che l’integrazione sia in grado di gestire la possibilità che la transazione saldo non sia immediatamente disponibile.

Visualizzare gli addebiti inclusi in un bonifico

Ogni bonifico automatico è legato a modifiche storiche del saldo del tuo account Stripe. L’API registra queste modifiche sotto forma di transazioni a saldo, che puoi recuperare utilizzando un elenco di transazioni a saldo. Da questo elenco, puoi ampliare la proprietà source per raccogliere informazioni sull’elemento che ha attivato la modifica del saldo dell’account (addebito, rimborso, trasferimento e così via). Ad esempio:

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

Scopri di più sulla riconciliazione dei bonifici.

Se utilizzi Connect con addebiti indiretti, puoi recuperare le stesse informazioni per conto dei tuoi account connessi. Una differenza, tuttavia, sta nel fatto che tali addebiti indiretti prevedono sia un trasferimento sia un pagamento collegato (sotto forma di oggetto Charge) per spostare i fondi in un account connesso. Pertanto, quando elenchi le transazioni a saldo incluse nei bonifici dell’account connesso, l’origine di ciascuna di queste transazioni è collegata al pagamento del trasferimento anziché all’addebito di origine. Per recuperare l’addebito di origine, devi ampliare il trasferimento collegato di un pagamento mediante la proprietà source_transfer, poi ampliare la proprietà source_transaction del trasferimento:

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