# Migrar para as APIs Payment Intents e Payment Methods

Saiba como fazer a transição das APIs Sources e Tokens para a API Payment Methods.

A [API Payment Methods](https://docs.stripe.com/api/payment_methods.md) substitui as APIs atuais [Tokens](https://docs.stripe.com/api/tokens.md) e [Sources](https://docs.stripe.com/api/sources.md) como forma recomendada de coleta e armazenamento de dados de pagamento a ser usada nas integrações. Ela trabalha com a [API Payment Intents](https://docs.stripe.com/payments/payment-intents.md) para criar pagamentos que usam diversas formas de pagamento.

Planejamos encerrar o suporte da API Sources para pagamentos com cartão e o suporte para a API [Cards](https://docs.stripe.com/api/cards.md). Se atualmente você processa alguma forma de pagamento com cartão usando a API Sources, deve migrá-la para a API Payment Intents. Enviaremos um e-mail com mais informações sobre o fim do suporte da API Sources.

Esta página fornece um resumo das diferenças entre os processos legados e atuais. Para informações detalhadas sobre o processo de migração, consulte o [documento de migração dos cartões legados e da API Sources (APIs Tokens/Cards) e da API Sources](https://docs.stripe.com/payments/payment-methods/migrate-from-legacy-cards-sources.md).

## Migre para a API Payment Intents

Para migrar sua integração, atualize seu servidor e frontend para utilizar a [API Payment Intents](https://docs.stripe.com/api/payment_intents.md). As opções típicas de integração incluem:

- Redirecione para o [Stripe Checkout](https://docs.stripe.com/payments/checkout.md) para o seu fluxo de pagamento.
- Use o Stripe [Payment Element](https://docs.stripe.com/payments/payment-element.md) na sua própria página de pagamento.
- Crie um formulário personalizado e utilize o Stripe JS SDK para concluir o pagamento.

Caso utilize o Checkout ou o Payment Element, é possível adicionar e gerenciar a maioria das formas de pagamento diretamente no Stripe Dashboard, sem necessidade de alterações no código.

Para informações específicas sobre como integrar uma forma de pagamento com cartão utilizando a API Payment Methods, consulte as instruções para essa forma de pagamento na [documentação de formas de pagamento](https://docs.stripe.com/payments/payment-methods/overview.md). O grupo a seguir apresenta uma comparação geral entre os diferentes tipos de pagamento.

| Integração antiga | Stripe Checkout | Payment Element | Formulário personalizado |
| --- | --- | --- | --- |
|  | Baixa complexidade | Média complexidade | Alta complexidade |
| Crie um Source no frontend ou no servidor. | Crie uma `CheckoutSession` no servidor. | Crie um `PaymentIntent` no servidor. | Crie um `PaymentIntent` no servidor. |
| Autorize o pagamento carregando um widget ou redirecionando para um terceiro. | Não é necessário | Informe o segredo do cliente ao frontend e utilize o Stripe JS SDK para renderizar um Payment Element e concluir o pagamento. | Informe o segredo do cliente ao frontend, utilize seu próprio formulário para coletar os dados do cliente e conclua o pagamento conforme a forma de pagamento. |
| Confirme que o Source está apto a ser cobrado e realize a cobrança do Source. | Não é necessário | Não é necessário | Não é necessário |
| Confirme de forma assíncrona que a cobrança foi bem-sucedida utilizando o webhook `charge.succeeded`. | Confirme que a sessão de checkout foi bem-sucedida utilizando o webhook `payment_intent.succeeded`. | Confirme que o PaymentIntent foi bem-sucedido utilizando o webhook `payment_intent.succeeded`. | Confirme que o PaymentIntent foi bem-sucedido utilizando o webhook `payment_intent.succeeded`. |

> #### Uso contínuo de objetos Charge
> 
> Um objeto `PaymentIntent` representa um pagamento na nova integração e cria um `Charge` quando você confirma o pagamento no frontend. Caso anteriormente você armazenasse referências ao `Charge`, poderá continuar fazendo isso buscando o ID do `Charge` a partir do `PaymentIntent` após a conclusão do pagamento pelo cliente. No entanto, também recomendamos que você armazene o ID do `PaymentIntent`.

### Verificar status do pagamento

Anteriormente, sua integração deveria verificar tanto o status do `Source` quanto o status do `Charge` após cada chamada da API. Agora não é mais necessário verificar dois objetos, basta verificar o status do `PaymentIntent` ou do `CheckoutSession` após a confirmação no frontend.

| payment_intent.status | Significado |
| --- | --- |
| `succeeded` | O pagamento foi bem-sucedido. |
| `requires_payment_method` | O pagamento falhou. |
| `requires_action` | O cliente ainda não concluiu a autorização do pagamento, possivelmente [devido a uma exigência de 3DS](https://docs.stripe.com/payments/3d-secure/authentication-flow.md#check-status). |

Sempre confirme o status do `PaymentIntent` buscando-o em seu servidor ou ouvindo os eventos de webhook em seu servidor. Não confie apenas no retorno do usuário para o `return_url` fornecido ao confirmar o `PaymentIntent`.

### Reembolsos

Você pode acionar a API Refunds usando o ID do `PaymentIntent` em vez do ID do `Charge`.

Alternativamente, você pode continuar a chamar a API Refunds com o ID da `Charge` que o `PaymentIntent` cria. Você pode obter o ID da `Charge` a partir da propriedade [latest_charge](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-latest_charge).

### Tratamento de erros

Anteriormente, era necessário tratar erros no `Source`. Com `PaymentIntents`, você deve verificar erros no `PaymentIntent` quando ele é criado e após o cliente autorizar o pagamento. A maioria dos erros no `PaymentIntent` é do tipo `invalid_request_error`, retornados em uma solicitação não válida.

Ao migrar sua integração, tenha em mente que os códigos de erro do `PaymentIntent` podem ser diferentes dos códigos de erro correspondentes para `Sources`.

### Webhooks

Se você anteriormente ouvia eventos de `Source`, talvez precise atualizar sua integração para ouvir eventos de outros objetos. O grupo a seguir mostra alguns exemplos.

| Evento antigo | Novo evento do Checkout | Novo evento do PaymentIntent | Instruções especiais |
| --- | --- | --- | --- |
| `source.chargeable` | Não se aplica | Não se aplica |  |
| `source.failed` | Não se aplica | Não se aplica |  |
| `source.canceled` | Não se aplica | Não se aplica |  |
| `charge.succeeded` | `checkout.session.completed` | `payment_intent.succeeded` | O evento `charge.succeeded` também é enviado, portanto, você pode continuar ouvindo esse evento em vez dos demais. |
| `charge.failed` | Não se aplica. O cliente pode tentar fazer o pagamento novamente na mesma sessão do Checkout até que ela [expire](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-expires_at), momento em que você recebe um evento `checkout.session.expired`. | `payment_intent.payment_failed` | O evento `charge.failed` também é enviado, portanto, você pode continuar ouvindo esse evento em vez dos demais. |
| `charge.dispute.created` | `charge.dispute.created` | `charge.dispute.created` |  |

## Transição para a API Payment Methods

A principal diferença entre as APIs Payment Methods e Sources é que a API Sources descreve o estado da transação por meio da propriedade [status](https://docs.stripe.com/api/sources/object.md#source_object-status). Isso significa que cada objeto `Source` deve passar para um estado apto a cobrança antes de ser utilizado em um pagamento. Em contrapartida, a API `PaymentMethod` não tem um estado, dependendo do objeto PaymentIntent para representar o estado do pagamento.

> A tabela a seguir não é uma lista abrangente de formas de pagamento. Se você integra outras formas de pagamento com a API Sources, migre-as também para a API Payment Methods.

| Fluxos | APIs Payment Methods e Payment Intents | Tokens ou Sources com APIs Charges |
| --- | --- | --- |
| Cartões | [Pagamentos com cartão](https://docs.stripe.com/payments/cards.md) | Descontinuado |
| Débito automático ACH | [Débitos automáticos em conta bancária dos EUA](https://docs.stripe.com/payments/ach-direct-debit.md) | [Compatível com Tokens](https://docs.stripe.com/ach-deprecated.md); Não compatível com Sources |

Depois de escolher a API para integrar, use o [guia de formas de pagamento](https://stripe.com/payments/payment-methods-guide) para determinar os tipos de pagamento que você precisa aceitar.

Este guia inclui descrições detalhadas de cada forma de pagamento e descreve as diferenças nos fluxos destinados aos clientes, além das [regiões geográficas](https://stripe.com/payments/payment-methods-guide#payment-methods-fact-sheets) em que são mais relevantes. Você pode habilitar qualquer forma de pagamento disponível no [Dashboard](https://dashboard.stripe.com/account/payments/settings). A ativação geralmente é instantânea e não exige contratos adicionais.

## See also

- [Guia das formas de pagamento](https://stripe.com/payments/payment-methods-guide)
- [Pagamentos com Connect](https://docs.stripe.com/connect/charges.md)
- [Referência da API Payment Methods](https://docs.stripe.com/api/payment_methods.md)