Como funcionam os PaymentIntents e os SetupIntents
Veja como os objetos PaymentIntents e SetupIntents se encaixam dentro do processo de pagamento.
A principal diferença entre a API Payment Intents e a API Setup Intents é sua finalidade:
- API Payment Intents: usada para recolher o pagamento e cobrar o cliente imediatamente. Cria uma cobrança e processa uma transação para recolher fundos.
- ** API Setup Intents:** usada para coletar e salvar detalhes da forma de pagamento para uso futuro sem gerar cobrança. Configura credenciais de pagamento sem processar nenhum pagamento.
| 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 |
Pagamentos assíncronos podem ser desafiadores de gerenciar, pois podem depender de ações do cliente que ocorrem fora do seu aplicativo. Por exemplo, um usuário pode precisar confirmar um pagamento usando o 3D Secure.
Para simplificar o gerenciamento de pagamentos, a Stripe utiliza uma máquina de estados que permite rastrear o estado de um fluxo de pagamento. Para conhecer os estados de cada API, selecione a aba aplicável abaixo:
Quando o PaymentIntent é criado, seu status é requires_1 até que uma forma de pagamento seja vinculada.
Recomendamos que você crie o PaymentIntent assim que souber o valor a ser cobrado para que a Stripe possa registrar todas as tentativas de pagamento.
Depois que o cliente informa os dados de pagamento, o PaymentIntent está pronto para ser confirmado.
Na maioria das integrações, esse estado é ignorado porque os dados da forma de pagamento são informados ao mesmo tempo em que o pagamento é confirmado.
Se o pagamento exigir ações adicionais, como autenticação com 3D Secure, o PaymentIntent terá um status de requires_1.
Após a execução das ações exigidas, o PaymentIntent muda para processing para formas de pagamento assíncronas, 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ê autoriza e captura fundos separadamente, seu PaymentIntent pode mudar para requires_. Nesse caso, a tentativa de capturar os fundos o move para processing.
Um PaymentIntent com status “succeeded” significa que o fluxo de pagamento a que pertence foi concluído.
Os fundos estão na sua conta e você pode executar o pedido. Quando for necessário reembolsar o cliente, use a API Refunds.
Se a tentativa de pagamento falhar (por exemplo, o pagamento foi recusado), o status do PaymentIntent volta a ser requires_ para que o pagamento possa ser repetido.
Você pode cancelar um PaymentIntent a qualquer momento antes que ela fique em um estado processing2 ou succeeded. O cancelamento invalida o PaymentIntent para futuras tentativas de pagamento e não pode ser desfeito. Se houver fundos retidos, o cancelamento os libera.
PaymentIntents também podem ser automaticamente transferidos para o estado canceled depois de terem sido confirmados muitas vezes.
1 Versões do API anteriores a 2019-02-11 mostram requires_ em vez de requires_ e requires_ em vez de requires_.
2 Você pode cancelar um PaymentIntent no estado processing quando a forma de pagamento associada for conta bancária dos EUA. No entanto, ele pode falhar devido a uma janela de tempo de cancelamento limitada e variável.