# Casos de uso para expandir respostas

Expanda respostas de API para retornar dados de pagamento comuns.

Use o parâmetro `expand` na sua solicitação da API para recuperar detalhes que a API não retorna em sua resposta padrão. Os seguintes casos de uso ilustram isso em relação a informações frequentemente 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](https://docs.stripe.com/api/balance_transactions/object.md#balance_transaction_object-fee_details). O evento [charge.updated](https://docs.stripe.com/api/events/types.md#event_types-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`.

> *Usuários do IC+* (A pricing plan where businesses pay the variable network cost for each transaction plus the Stripe fee rather than a flat rate for all transactions. This pricing model provides more visibility into payments costs) não podem recuperar informações sobre tarifas de pagamento na transação de saldo. Use o Relatório de tarifas de pagamento.

#### curl

```bash
curl https://api.stripe.com/v1/payment_intents/pi_1Gpl8kLHughnNhxyIb1RvRTu \
  -u <<YOUR_SECRET_KEY>>: \-d "expand[]"="latest_charge.balance_transaction" \
  -G
```

Usuários na versão [2022-08-01](https://docs.stripe.com/upgrades.md#2022-08-01) da API ou mais antiga:

#### curl

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

> Um PaymentIntent deve ser [capturado](https://docs.stripe.com/payments/place-a-hold-on-a-payment-method.md#capture-funds) e ter [status](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-status) de `succeeded` para que as tarifas da Stripe estejam disponíveis.

Ao usar `automatic_async` (o `capture_method` padrão desde a versão `2024-04-10`), as transações de saldo são criadas após o pagamento ser bem-sucedido, mas de forma assíncrona em segundo plano. Isso significa:

- O campo `balance_transaction` no objeto Charge pode ser `null` imediatamente após a confirmação
- Se você expandir `balance_transaction` ou `latest_charge.balance_transaction`, pode não estar disponível na resposta
- Você pode ouvir o evento `charge.updated` para saber quando a transação de saldo torna-se disponível

Esse comportamento assíncrono melhora o desempenho do pagamento, mas requer que sua integração lide com a possibilidade de que a transação de saldo pode não estar imediatamente disponível.

## Ver as cobranças incluídas em um repasse

Cada *repasse* (A payout is the transfer of funds to an external account, usually a bank account, in the form of a deposit) 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](https://docs.stripe.com/api/balance_transactions/object.md), que você pode recuperar utilizando [Listar transações de saldo](https://docs.stripe.com/api/balance_transactions/list.md). Em uma lista de transações de saldo, você pode expandir a propriedade [source](https://docs.stripe.com/api/balance_transactions/object.md#balance_transaction_object-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

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

> Você só pode recuperar o histórico de transações de saldo em *automatic* payouts. Se tiver repasses manuais ativados, você precisa rastrear o histórico de transações sem usar esses recursos.

Saiba mais sobre a [reconciliação de repasses](https://docs.stripe.com/payouts/reconciliation.md).

Se estiver usando o *Connect* (Connect is Stripe's solution for multi-party businesses, such as marketplace or software platforms, to route payments between sellers, customers, and other recipients) 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](https://docs.stripe.com/api/charges/object.md#charge_object-source_transfer); e, daí, expandir a propriedade [source_transaction](https://docs.stripe.com/api/transfers/object.md#transfer_object-source_transaction) da transferência:

#### curl

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