# 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 desativar o suporte da Sources API para *formas de pagamento locais* (Payment methods used in specific countries or regions, such as bank transfers, vouchers, and digital wallets. Examples include Pix (Brazil, bank transfers), Konbini (Japan, vouchers), and WeChat Pay (China, digital wallet)). Se você atualmente gerencia alguma *forma de pagamento local* (Payment methods used in specific countries or regions, such as bank transfers, vouchers, and digital wallets. Examples include Pix (Brazil, bank transfers), Konbini (Japan, vouchers), and WeChat Pay (China, digital wallet)) usando a Sources API, é necessário [migrá-la para a API Payment Methods](https://docs.stripe.com/payments/payment-methods/transitioning.md#migrate-local-payment-methods). Enviaremos um comunicado por e-mail com mais informações sobre o fim do suporte às APIs Sources e Tokens. Embora não esteja em nossos planos desativar o suporte às formas de pagamento com cartão, ainda recomendamos migrá-las para as APIs Payment Methods e Payment Intents. Para obter mais informações sobre a migração de formas de pagamento com cartão, consulte [Migrar para a API Payment Intents](https://docs.stripe.com/payments/payment-intents/migration.md). ## Migrar formas de pagamento locais da API Sources para a API Payment Intents Para migrar sua integração para formas de pagamento locais, atualize seu servidor e front-end para usar a [API PaymentIntents](https://docs.stripe.com/api/payment_intents.md). Há três opções típicas de integração: - 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 seu próprio formulário e use o SDK JS da Stripe para concluir o pagamento. Se você usa o Stripe Checkout ou o Payment Element, pode adicionar e gerenciar a maioria das formas de pagamento no Stripe Dashboard sem precisar alterar o código. Para obter informações específicas sobre a integração de uma forma de pagamento local usando a API Payment Methods, consulte as instruções dessa forma de pagamento na [documentação das formas de pagamento](https://docs.stripe.com/payments/payment-methods/overview.md). A tabela a seguir oferece uma comparação de alto nível entre os diferentes tipos de pagamento. | Integração antiga | Stripe Checkout | Payment Element | Próprio formulário | | ------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | Baixa complexidade | Média complexidade | Alta complexidade | | Crie uma Source no front-end ou no servidor | Crie uma sessão do Checkout no servidor | Criar um PaymentIntent no servidor | Criar um PaymentIntent no servidor | | Autorize o pagamento carregando um widget ou redirecionando a um terceiro | Não é necessário | Passe o segredo do cliente para o front-end e use o SDK JS da Stripe para renderizar um Payment Element e concluir o pagamento | Passe o segredo do cliente para o front-end, use seu próprio formulário para coletar os dados do cliente e conclua o pagamento de acordo com a forma de pagamento | | Confirme se a fonte pode ser cobrada e cobre a Source | Não é necessário | Não é necessário | Não é necessário | | Confirme se a Charge foi bem-sucedida de forma assíncrona com o webhook `charge.succeeded` | Confirme o sucesso da sessão do Checkout com o webhook `payment_intent.succeeded` | Confirme se o PaymentIntent foi bem-sucedido com o webhook `payment_intent.succeeded` | Confirme se o PaymentIntent foi bem-sucedido com o webhook `payment_intent.succeeded` | > Um objeto PaymentIntent representa um pagamento na nova integração e cria uma Charge quando você confirma o pagamento no front-end. Se você armazenou referências à Charge anteriormente, pode continuar armazenando o ID da Charge no PaymentIntent depois que o cliente finaliza o pagamento. Entretanto, também recomendamos que você armazene o ID do PaymentIntent. ### Verificar status do pagamento Anteriormente, sua integração deveria ter verificado o status da Source e o status da Charge após cada chamada de API. Não é preciso mais verificar dois status. Você só precisa verificar o status do PaymentIntent ou da sessão do Checkout depois de confirmá-lo no front-end. | payment_intent.status | Significado | Instruções especiais | | ------------------------- | -------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | `succeeded` | O pagamento foi bem-sucedido. | Não se aplica | | `requires_payment_method` | O pagamento falhou. | Não se aplica | | `requires_action` | O cliente não concluiu a autorização do pagamento. | Se o cliente não concluir o pagamento em 48 horas, o PaymentIntent muda para `requires_payment_method` e você pode tentar fazer a confirmação novamente. | Sempre confirme o status do PaymentIntent obtendo-o no seu servidor ou escutando os webhooks no seu servidor. Não dependa apenas do retorno do usuário ao `return_url` informado quando você confirmar o PaymentIntent. ### Reembolsos Você pode continuar chamando a API Refunds com uma Charge criada pelo PaymentIntent. O ID da Charge pode ser acessado no parâmetro `latest_charge`. Como opção, você pode informar o ID do PaymentIntent à API Refunds em vez da Charge. ### Tratamento de erros Anteriormente, era preciso gerenciar erros no Sources. Com o PaymentIntents, em vez de verificar erros em uma Source, você verifica se há 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 inválida. Quando migrar sua integração, lembre-se de que os códigos de erro do PaymentIntent podem diferir dos códigos de erro correspondentes do Sources. ### Webhooks Se você escutou eventos do Source anteriormente, pode precisar atualizar sua integração para escutar novos tipos de eventos. A tabela a seguir mostra alguns exemplos. | Webhook antigo | Novo webhook no Checkout | Novo webhook no PaymentIntents | 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 webhook `charge.succeeded` também é enviado, você não precisa atualizar a integração para escutar o novo webhook. | | `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 webhook `charge.failed` também é enviado, você não precisa atualizar a integração para escutar o novo webhook. | | `charge.dispute.created` | `charge.dispute.created` | `charge.dispute.created` | | ## Migraçã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 usando a propriedade [status](https://docs.stripe.com/api/sources/object.md#source_object-status). Isso significa que cada objeto `Source` deve mudar para um estado cobrável antes que você possa usaá-lo em um pagamento. Por outro lado, um `PaymentMethod` não tem estado e usa um objeto *PaymentIntent* (The Payment Intents API tracks the lifecycle of a customer checkout flow and triggers additional authentication steps when required by regulatory mandates, custom Radar fraud rules, or redirect-based payment methods) 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 | Integrar Payment Methods com a API Payment Intents | Tokens ou Sources com a API Charges | | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | | Cartões | [Pagamentos com cartão](https://docs.stripe.com/payments/cards.md) | [Aceitos na API Tokens](https://docs.stripe.com/payments/charges-api.md); não recomendado na API Sources | | Débito automático ACH | [Débitos automáticos em conta bancária dos EUA](https://docs.stripe.com/payments/ach-direct-debit.md) | [Aceito na API Tokens](https://docs.stripe.com/ach-deprecated.md) Não aceito na API Sources | | Transferência de crédito ACH | [Transferências bancárias em USD](https://docs.stripe.com/payments/customer-balance/migrating-from-sources.md) | [Descontinuado](https://docs.stripe.com/sources/ach-credit-transfer.md) | | Alipay | [Pagamentos com Alipay](https://docs.stripe.com/payments/alipay.md) | [Descontinuado](https://docs.stripe.com/sources/alipay.md) | | Bancontact | [Pagamentos com Bancontact](https://docs.stripe.com/payments/bancontact.md) | [Descontinuado](https://docs.stripe.com/sources/bancontact.md) | | EPS | [Pagamentos com EPS](https://docs.stripe.com/payments/eps.md) | Descontinuado | | giropay | [pagamentos com giropay](https://docs.stripe.com/payments/giropay.md) | [Descontinuado](https://docs.stripe.com/sources/giropay.md) | | iDEAL | [Pagamentos com iDEAL](https://docs.stripe.com/payments/ideal.md) | [Descontinuado](https://docs.stripe.com/sources/ideal.md) | | Klarna | [Pagamentos com Klarna](https://docs.stripe.com/payments/klarna.md) | Descontinuado | | Multibanco | [Pagamentos com Multibanco](https://docs.stripe.com/payments/multibanco.md) | [Beta descontinuado](https://docs.stripe.com/sources/multibanco.md) | | Przelewy24 | [Pagamentos com Przelewy24](https://docs.stripe.com/payments/p24.md) | [Descontinuado](https://docs.stripe.com/sources/p24.md) | | Transferência de crédito SEPA | [Transferências bancárias em EUR](https://docs.stripe.com/payments/customer-balance/migrating-from-sepa-credit-transfer.md) | [Descontinuado](https://docs.stripe.com/sources/sepa-credit-transfer.md) | | Débito automático SEPA | [Débitos automáticos da Área Única de Payments em Euros](https://docs.stripe.com/payments/sepa-debit.md) | [Descontinuado](https://docs.stripe.com/sources/sepa-debit.md) | | WeChat Pay | [Pagamentos com WeChat Pay](https://docs.stripe.com/payments/wechat-pay.md) | [Descontinuado](https://docs.stripe.com/sources/wechat-pay.md) | 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. ## Compatibilidade com formas de pagamento reutilizáveis antigas Se você processou anteriormente qualquer uma das formas de pagamento reutilizáveis a seguir usando a [Sources](https://docs.stripe.com/sources.md), as fontes salvas não migram automaticamente: - Alipay - Débito automático Bacs - Débito automático SEPA Para preservar as formas de pagamento salvas dos clientes, converta essas fontes em formas de pagamento usando uma ferramenta de migração de dados no Stripe Dashboard. Para obter instruções de como convertê-las, consulte a [página de suporte](https://support.stripe.com/questions/reusable-object-migration). ## Compatibilidade com objetos de cartão antigos Se você já utiliza a Stripe para coletar informações de pagamento com cartão do cliente, seja por meio de [cards](https://docs.stripe.com/payments/charges-api.md) ou [Sources](https://docs.stripe.com/sources.md), pode começar a empregar a API de Formas de Pagamento imediatamente — sem necessidade de migrar os dados existentes. As formas de pagamento compatíveis que foram salvos em um *Customer* (Customer objects represent customers of your business. They let you reuse payment methods and give you the ability to track multiple payments) podem ser usados em qualquer API que aceita um objeto *PaymentMethod* (PaymentMethods represent your customer's payment instruments, used with the Payment Intents or Setup Intents APIs). Por exemplo, você pode usar um cartão salvo como PaymentMethod ao criar um PaymentIntent: ```curl curl https://api.stripe.com/v1/payment_intents \ -u "<>:" \ -d "payment_method_types[]=card" \ -d amount=1099 \ -d currency=usd \ -d "customer={{CUSTOMER_ID}}" \ -d "payment_method={{CARD_ID}}" ``` Quando anexar o objeto a um PaymentIntent, lembre-se de informar o ID do cliente em que a forma de pagamento compatível foi salva. Você pode [recuperar](https://docs.stripe.com/api/payment_methods/retrieve.md) todas as formas de pagamento compatíveis que estiverem salvas na API Payment Methods. #### Cartão ```json { "id": "card_1EBXBSDuWL9wT9brGOaALeD2", "object": "card", "address_city": "San Francisco", "address_country": "US", "address_line1": "1234 Fake Street", "address_line1_check": null, "address_line2": null, "address_state": null, "address_zip": null, "address_zip_check": null, "brand": "Visa", "country": "US", "customer": "{{CUSTOMER_ID}}", "cvc_check": null, "dynamic_last4": null, "exp_month": 8, "exp_year": 2024, "fingerprint": "53v265akSHAnIk1X", "funding": "credit", "last4": "4242", "metadata": { }, "name": null, "tokenization_method": null } ``` ```json { "id": "card_1EBXBSDuWL9wT9brGOaALeD2", "object": "payment_method", "billing_details": { "address": { "city": "San Francisco", "country": "US", "line1": "1234 Fake Street", "line2": null, "postal_code": null, "state": null }, "name": null, "phone": null, "email": null }, "card": { "brand": "visa", "checks": { "address_line1_check": null, "address_postal_code_check": null, "cvc_check": null }, "country": "US", "exp_month": 8, "exp_year": 2024, "fingerprint": "53v265akSHAnIk1X", "funding": "credit", "last4": "4242", "three_d_secure_usage": { "supported": true }, "wallet": null }, "created": 123456789, "customer": "cus_EepWxEKrgMaywv", "livemode": false, "metadata": { }, "type": "card" } ``` #### Fonte do cartão ```json { "id": "src_1AhIN74iJb0CbkEwmbRYPsd4", "object": "source", "amount": null, "client_secret": "src_client_secret_sSPHZ17iQG6j9uKFdAYqPErO", "created": 1500471469, "currency": null, "flow": "none", "livemode": false, "metadata": { }, "owner": { "address": { "city": "Berlin", "country": "DE", "line1": "Nollendorfstraße 27", "line2": null, "postal_code": "10777", "state": null }, "email": "jenny.rosen@example.com", "name": "Jenny Rosen", "phone": null, "verified_address": null, "verified_email": null, "verified_name": null, "verified_phone": null }, "status": "chargeable", "type": "card", "usage": "reusable", "card": { "exp_month": 4, "exp_year": 2024, "address_line1_check": "unchecked", "address_zip_check": "unchecked", "brand": "Visa", "country": "US", "cvc_check": "unchecked", "funding": "credit", "last4": "4242", "three_d_secure": "optional", "tokenization_method": null, "dynamic_last4": null } } ``` ```json { "id": "card_1EBXBSDuWL9wT9brGOaALeD2", "object": "payment_method", "billing_details": { "address": { "city": "Berlin", "country": "DE", "line1": "Nollendorfstraße 27", "line2": null, "postal_code": "10777", "state": null }, "name": "Jenny Rosen", "phone": null, "email": "jenny.rosen@example.com" }, "card": { "brand": "visa", "checks": { "address_line1_check": null, "address_postal_code_check": null, "cvc_check": null }, "country": "US", "exp_month": 4, "exp_year": 2024, "fingerprint": "53v265akSHAnIk1X", "funding": "credit", "last4": "4242", "three_d_secure_usage": { "supported": true }, "wallet": null }, "created": 1500471469, "customer": "{{CUSTOMER_ID}}", "livemode": false, "metadata": { }, "type": "card" } ``` Com essa compatibilidade, nenhum novo objeto é criado; a API Payment Methods fornece uma visualização diferente do mesmo objeto subjacente. Por exemplo, as atualizações de formas de pagamento compatíveis por meio da API Payment Methods são visíveis na API Sources e vice-versa. ## 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)