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 à 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 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.

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.

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.

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.

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 que você possa usaá-lo em um pagamento. Por outro lado, um PaymentMethod não tem estado e usa um objeto PaymentIntent para representar o estado do pagamento.

Depois de escolher a API para integrar, use o guia de formas de pagamento 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 em que são mais relevantes. Você pode habilitar qualquer forma de pagamento disponível no Dashboard. 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, 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.

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:

curl https://api.stripe.com/v1/payment_intents \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -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 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.

{
  "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,

{
  "id": "card_1EBXBSDuWL9wT9brGOaALeD2",
  "object": "payment_method",
  "billing_details": {
    "address": {
      "city": "San Francisco",
      "country": "US",
      "line1": "1234 Fake Street",
      "line2": null,
      "postal_code": null,

Nenhum objeto é criado com essa compatibilidade. A API Payment Methods oferece uma visualização diferente do mesmo objeto associado. 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.