Casos de uso para expandir respostas

Use o parâmetro expand em sua solicitação de API para recuperar detalhes que a API não retorna em sua resposta padrão. Os seguintes casos de uso ilustram isso para obter informações comumente solicitadas.

Veja a tarifa da Stripe para um determinado pagamento

Você pode conferir as tarifas de processamento de um pagamento após o processamento do pagamento e a Stripe cria a transação de saldo. O evento charge.updated faz referência à propriedade balance_transaction (por exemplo, txn_123), indicando que ele está pronto para uso.

Em vez de procurar a transação de saldo separadamente, você pode recuperá-la em uma única chamada usando expand.

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

Usuários na versão 2022-08-01 da API ou mais antiga:

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

Ver as cobranças incluídas em um repasse

Cada repasse automático é vinculado às alterações anteriores no saldo da sua conta Stripe. A API registra essas alterações anteriores como transações de saldo, que você pode recuperar utilizando Listar transações de saldo. Em uma lista de transações de saldo, você pode expandir a propriedade source para reunir informações sobre o que acionou a alteração no saldo da conta (cobrança, reembolso, transferência etc.). Por exemplo:

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

Saiba mais sobre a reconciliação de repasses.

Se estiver usando o Connect com cobranças de destino, é possível recuperar as mesmas informações em nome de suas contas conectadas. Uma diferença é que as cobranças de destino envolvem uma transferência e um pagamento vinculado (na forma de um objeto Cobrança) para mover os fundos para uma conta conectada. Por isso, quando listar as transações de saldo agrupadas nos repasses da sua conta conectada, a origem de cada transação de saldo é vinculada ao pagamento da transferência e não da cobrança de origem. Para recuperar a cobrança de origem, é preciso expandir a transferência vinculada de um pagamento por meio da propriedade source_transfer; e, daí, expandir a propriedade source_transaction da transferência:

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