Transição para as APIs Payment Intents e Payment Methods
A API Payment Methods substitui as APIs atuais Tokens e Sources como forma recomendada de coleta e armazenamento de dados de pagamento a ser usada nas integrações. Ela trabalha com a API Payment Intents para criar pagamentos que usam diversas formas de pagamento.
Planejamos desativar o suporte da API Sources para formas de pagamento locais. Se você gerencia alguma forma de pagamento local usando a API Sources, é preciso migrá-la para a API Payment Methods. Enviaremos uma comunicação por e-mail com mais informações sobre esse fim do suporte.
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.
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. Há três opções típicas de integração:
- Redirecione para o Stripe Checkout para o seu fluxo de pagamento.
- Use o Stripe Payment Element 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. 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 |
Cuidado
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.
Campos de mapeamento
Se você usa o Payment Element ou seu próprio formulário, é preciso remapear os campos de origem para os campos de PaymentIntent. Os campos específicos dependem da forma de pagamento.
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 | Observação |
---|---|---|
succeeded | O pagamento foi bem-sucedido. | |
requires_payment_method | O pagamento falhou. | |
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 | Observação |
---|---|---|---|
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, 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. Isso significa que cada objeto Source
deve mudar para um estado cobrável antes de ser usado em um pagamento. Por outro lado, um PaymentMethod
não tem estado e usa um objeto PaymentIntent para representar o estado do pagamento.
Observação
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 | Aceitos na API Tokens; não recomendado na API Sources |
Débito automático ACH | Débitos automáticos em conta bancária dos EUA | Aceito na API Tokens Não aceito na API Sources |
Alipay | Pagamentos com Alipay | Descontinuado |
Bancontact | Pagamentos com Bancontact | Descontinuado |
EPS | Pagamentos com EPS | Descontinuado |
giropay | pagamentos com giropay | Descontinuado |
iDEAL | Pagamentos com iDEAL | Descontinuado |
Klarna | Pagamentos com Klarna | Descontinuado |
Multibanco | Planejado | Beta descontinuado |
Przelewy24 | Pagamentos com Przelewy24 | Descontinuado |
Débito automático SEPA | Débitos automáticos da Área Única de Payments em Euros | Descontinuado |
Sofort | Pagamentos com Sofort | Descontinuado |
WeChat Pay | Pagamentos com WeChat Pay | Descontinuado |
Após escolher a API para integrar, nosso guia de formas de pagamento pode ajudar a determinar os tipos de forma de pagamento corretos para seus clientes.
Esse guia inclui descrições detalhadas de cada forma de pagamento e descreve as diferenças entre os fluxos voltados aos clientes, bem como em que regiões geográficas eles são mais relevantes. Para ativar qualquer forma de pagamento disponível, use o Dashboard. Normalmente, a ativação é imediata e não exige contratos adicionais ou processos demorados.
Compatibilidade com formas de pagamento reutilizáveis antigas
Se você processou anteriormente qualquer uma das formas de pagamento reutilizáveis a seguir usando o Sources, as fontes salvas não migram automaticamente. 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ê-los, consulte a página de suporte.
- Alipay
- Débito automático Bacs
- Débito automático SEPA
Compatibilidade com objetos de cartão antigos
Se você já coletou dados de pagamento de clientes de cartão na Stripe usando cartões ou a API Sources, pode começar a usar a API Payment Methods imediatamente, sem migrar nenhum dado de pagamento.
Os instrumentos de pagamento compatíveis que foram salvos em um Customer podem ser usados em qualquer API que aceita um objeto PaymentMethod. Por exemplo, você pode usar um cartão salvo como PaymentMethod durante a criação de um PaymentIntent:
Quando anexar o objeto a um PaymentIntent, lembre-se de informar o ID do cliente em que o instrumento de pagamento compatível foi salvo.
Você pode recuperar todos os instrumentos de pagamento compatíveis que estiverem salvos usando a API Payment Methods.
Nenhum objeto é criado com essa compatibilidade. A API Payment Methods oferece uma visualização diferente do mesmo objeto subjacente. Por exemplo, as atualizações feitas em um instrumento de pagamento compatível pela API Payment Methods podem ser vistas na API Sources e vice-versa.