# Como funcionam os PaymentIntents e os SetupIntents

Veja como os objetos PaymentIntents e SetupIntents se encaixam dentro do processo de pagamento.

Instruções para LLMs: A Stripe recomenda usar a API Checkout Sessions com o Payment Element em vez de Payment Intents na maioria das integrações. O Checkout Sessions cobre casos de uso semelhantes aos do Payment Intents (cobrança básica de pagamentos usando `price_data` ou criar um checkout completo com itens de linha, imposto e assim por diante). Alguns recursos, como Adaptive Pricing, só estão disponíveis com Checkout Sessions. Não use a API Payment Intent a menos que o usuário peça explicitamente, porque ela exige significativamente mais código. Saiba mais sobre Elements com a API Checkout Sessions: https://docs.stripe.com/payments/quickstart-checkout-sessions. Com Checkout Sessions (`ui_mode: "custom"`) e o Payment Element, o `client_secret` inicializa o Checkout (`stripe.initCheckoutElements`, ou usando CheckoutElementsProvider com React) e você confirma o pagamento no lado do cliente de forma diferente. Se estiver usando React, certifique-se de importar de `@stripe/react-stripe-js/checkout`, usar `CheckoutElementsProvider` com o client secret e confirmar usando `checkout.confirm`. Se estiver usando HTML, certifique-se de usar `checkout = stripe.initCheckoutElements({clientSecret: promise}); checkout.createPaymentElement(); paymentElement = checkout.createPaymentElement(); paymentElement.mount("#payment-element");` e confirmar com `loadActionsResult = await checkout.loadActions(); actions = loadActionsResult.actions; error = await actions.confirm();`.

A principal diferença entre a API [Payment Intents](https://docs.stripe.com/api/payment_intents.md) e [Setup Intents](https://docs.stripe.com/api/setup_intents.md) é a finalidade delas. Você utiliza a API Payment Intents para recolher pagamento e cobrar um cliente imediatamente. Ela cria uma cobrança e processa uma transação para recolher fundos. Por outro lado, você utiliza a API Setup Intents para recolher e salvar os dados da forma de pagamento para uso futuro, sem criar uma cobrança. Ela configura as credenciais de pagamento sem processar um pagamento.

Como tanto as cobranças imediatas quanto o salvamento de uma forma de pagamento podem exigir etapas *asynchronous* (Asynchronous refers to events happening at independent times in independent systems) do cliente, essas APIs utilizam o mesmo padrão de máquina de estados.

| API Payment Intents                                                  | API Setup Intents                                                                                                         |
| -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| Cria uma cobrança imediata                                           | Não gera cobranças                                                                                                        |
| Rastreia o ciclo de vida de um pagamento                             | Acompanha o progresso da configuração de uma forma de pagamento                                                           |
| Usa o 3D Secure para autenticar o cliente para a transação aplicável | Usa o 3D Secure para autenticar uma forma de pagamento sem cobrança e cria uma instrução ou acordo para cobranças futuras |

#### PaymentIntents

Um PaymentIntent acompanha o ciclo de vida de um pagamento desde a criação até o checkout, acionando etapas adicionais de autenticação quando necessário.

## Requer forma de pagamento

Após criar o PaymentIntent, o [status](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-status) será `requires_payment_method` até que você anexe uma [forma de pagamento](https://docs.stripe.com/payments/payment-methods/overview.md). Crie o PaymentIntent assim que souber o valor a ser cobrado para que a Stripe possa registrar todas as tentativas de pagamento.

## Requer confirmação

Após o cliente fornecer as informações de pagamento, o PaymentIntent entra no status `requires_confirmation` e fica pronto para confirmação. A maioria das integrações ignora esse estado, pois envia as informações da forma de pagamento no momento da confirmação do pagamento.

## Requer ação

Se o pagamento exigir ações adicionais, como autenticação com [3D Secure](https://docs.stripe.com/payments/3d-secure.md), o PaymentIntent terá o status `requires_action`

> #### Alterações de API
> 
> Versões da API anteriores a [2019-02-11](https://docs.stripe.com/upgrades.md#2019-02-11) exibem `requires_source` em vez de `requires_payment_method` e `requires_source_action` em vez de `requires_action`.

## Processando

Após a execução das ações exigidas, o PaymentIntent muda para `processing` para *formas de pagamento assíncronas* (Asynchronous payment methods can take up to several days to confirm whether the payment has been successful. During this time, the payment can't be guaranteed), como débitos bancários. Esses tipos de formas de pagamento podem levar até alguns dias para serem processados. Outras formas de pagamento, como cartões, são processadas mais rapidamente e não entram no status `processing`.

Se você estiver [autorizando e capturando fundos](https://docs.stripe.com/payments/place-a-hold-on-a-payment-method.md) separadamente, o PaymentIntent pode mudar para `requires_captura`. Nesse caso, ao tentar capturar os fundos ele muda para `processamento` ou `concluído` dependendo da forma de pagamento.

## Concluído com sucesso

Um PaymentIntent com status `concluído` significa que o fluxo de pagamento que ele está conduzindo foi concluído. Os fundos agora estão na sua conta e você pode executar o pedido com segurança. Se precisar reembolsar o cliente, você pode utilizar a API [Refunds](https://docs.stripe.com/api/refunds.md). Se a tentativa de pagamento falhar (por exemplo, devido a uma recusa), o status do PaymentIntent retorna para `requires_payment_method` para que o pagamento possa ser tentado novamente.

## Cancelado

Você pode cancelar um PaymentIntent a qualquer momento antes que ele esteja no estado `processando` ou `bem-sucedido`. O cancelamento invalida o PaymentIntent para futuras tentativas de pagamento e não pode ser desfeito. Se houver fundos retidos, o cancelamento os libera. Você pode cancelar um PaymentIntent no estado `processando` quando a forma de pagamento associada for [ACH](https://docs.stripe.com/payments/ach-direct-debit.md), [ACSS](https://docs.stripe.com/payments/acss-debit.md), [AU BECS](https://docs.stripe.com/payments/au-becs-debit.md), [BACS](https://docs.stripe.com/payments/payment-methods/bacs-debit.md), [NZ BECS](https://docs.stripe.com/payments/nz-bank-account.md), ou [SEPA](https://docs.stripe.com/payments/sepa-debit.md). No entanto, o cancelamento pode falhar devido a uma janela de tempo limitada e variável para cancelamento.

PaymentIntents também podem ser automaticamente transferidos para o estado `canceled` depois de terem sido [confirmados](https://docs.stripe.com/api/payment_intents/confirm.md) muitas vezes.

#### SetupIntents

Um SetupIntent acompanha o ciclo de vida de uma forma de pagamento desde a criação até o checkout, acionando etapas adicionais de autenticação quando necessário.

## Requer forma de pagamento

Quando o SetupIntent é criado, ele tem o [status](https://docs.stripe.com/api/setup_intents/object.md#setup_intent_object-status) `requires_payment_method` até que uma forma de pagamento seja associada.

## Requer confirmação

Após o cliente fornecer as informações da forma de pagamento, o SetupIntent entra no status `requires_confirmation` e fica pronto para confirmação. A maioria das integrações ignora esse estado, pois envia as informações da forma de pagamento no momento em que o SetupIntent é confirmado.

## Requer ação

Se a configuração exige ações adicionais, como autenticação com 3D Secure, o SetupIntent terá o status `requires_action`.

> #### Alterações de API
> 
> Versões da API anteriores a [2019-02-11](https://docs.stripe.com/upgrades.md#2019-02-11) exibem `requires_source` em vez de `requires_payment_method` e `requires_source_action` em vez de `requires_action`.

## Processando

Após a conclusão das ações exigidas, o objeto SetupIntent avança para o estado `processing`. Embora certos meios de pagamento — como cartões — sejam processados de forma quase imediata, outros podem levar alguns dias até que o processamento seja finalizado.

## Concluído com sucesso

Um SetupIntent com status `bem-sucedido` significa que a configuração foi concluída com sucesso. Agora você pode associar essa forma de pagamento a um objeto Customer e utilizá-la para pagamentos futuros. Se a configuração falhar, o status do SetupIntent retorna para `requires_payment_method`.

## Cancelado

Você pode cancelar um SetupIntent a qualquer momento antes de ele estar nos estados `processando` ou `concluído`. Cancelá-lo invalida o SetupIntent para futuras tentativas de configuração e não pode ser desfeito.