Guia de migração de SCA para o Billing

Autenticação forte de cliente

Autenticação Forte de Cliente (SCA), um regulamento que entrou em vigor em 14 de setembro de 2019 com a PSD2 na Europa e exige mudanças na autenticação de pagamentos online para clientes europeus. Esse regulamento aplica-se a pagamentos online quando tanto o banco do cliente quanto a empresa estão no Espaço Econômico Europeu (EEE).

A SCA exige que as empresas usem dois elementos de autenticação independentes para verificar pagamentos. Na prática, é preciso adicionar mais uma etapa de pagamento para que os clientes confirmem o pagamento com uma autenticação como senha, token de hardware ou biometria. O 3D Secure 2 é o principal método de autenticação usado para requisitos SCA com pagamentos no cartão.

Transações que não cumpram esses requisitos de autenticação e não se qualifiquem para uma isenção podem ser recusadas.

Alterações no Stripe Billing

Com o aumento do atrito nos pagamentos causado pela SCA, esperamos mais demora nos prazos de cobrança e taxas de conversão mais baixas. As alterações no Stripe Billing permitem maximizar sua receita sob essas restrições. O que foi alterado:

• Novos status de assinatura para facilitar o pagamento inicial
• PaymentIntents agora são expostos em faturas, para facilitar pagamentos em mais de um estado
• SetupIntents que podem ser usados para coletar autenticação enquanto os clientes estão na sessão
• Um novo webhook, que indica quando a SCA é necessária para o pagamento
• Uma Página de fatura hospedada, que permite aos clientes concluir a etapa de autenticação exigida por SCA
• Um novo conjunto de e-mails de cobrança para ajudar a coletar pagamentos quando a SCA for exigida

Como a SCA impacta o Billing

A SCA afeta cobranças com cartão entre empresas e clientes no EEE, mudando o processamento de pagamentos na sessão e fora da sessão.

Usar contratos de autorização anteriores

Você pode usar Contratos de autorização anteriores para pagamentos fora de sessão que cumpram os seguintes critérios:

• Cartões de clientes da UE salvos antes de 31 de dezembro de 2020
• Cartões de clientes do Reino Unido salvos antes de 14 de setembro de 2021

Para os seguintes cenários, isso significa que você não precisa salvar os cartões novamente e reautenticar esses clientes. Se usar a Stripe para pagamentos não recorrentes, consulte o guia pagamentos fora de escopo.

Atualizar sua integração do Billing para aceitar SCA

As atualizações necessárias à sua integração dependem de como você usa o Stripe Billing. Há quatro possibilidades de situações que você precisa gerenciar para aceitar SCA. Analise sua integração em relação a esses cenários para saber quais se aplicam a você.

• Cenário 1: cobrar clientes na sessão pelo pagamento inicial
• Cenário 2: cobrar clientes fora da sessão pelo pagamento inicial
• Cenário 3: gerenciar cobranças recorrentes depois que o cliente fizer o primeiro pagamento
• Cenário 4: faturas isoladas

O primeiro cenário é para quando você cobrar o cliente assim que a assinatura for feita. Isso significa que o primeiro pagamento do cliente acontece na sessão. O segundo cenário acontece quando você não cobra a assinatura imediatamente, de forma que o primeiro pagamento ocorre com o cliente fora da sessão.

O terceiro cenário se aplica à maioria dos usuários do Billing porque gerencia pagamentos recorrentes, ou seja, todos os pagamentos feitos após o primeiro pagamento. O quarto cenário só é válido para quem usa faturas avulsas.

Em qualquer cenário, ao criar assinaturas, você pode expandir o atributo latest_invoice.payments para saber o resultado dos pagamentos. Também é possível expandir o pending_setup_intent ao gerenciar assinaturas sem um pagamento inicial, como mostrado no cenário 2.

Cenário 1: cobrar o pagamento inicial dos clientes na sessão

Se a cobrança for imediata, o primeiro pagamento da assinatura exigirá SCA. É preciso adicionar a gestão da autenticação ao seu fluxo de checkout ou cadastro. Na primeira configuração da assinatura, o cliente está na sessão, o que significa que está no navegador ou aplicativo e pode responder às suas solicitações.

Ao criar uma assinatura com cobrança imediata, a Stripe tenta cobrar o cartão cadastrado do cliente na chamada Criar assinatura ou Criar cliente que gera a assinatura.

Etapa 1: criar assinaturas

Temos um novo status incompleto nas assinaturas, que devemser usados para aceitar SCA. No entanto, você tem duas opções para acessar esses status. A primeira permite manter uma versão anterior da API, mas exige um sinalizador em algumas chamadas de API. A segunda opção é atualizar sua versão da API. As opções são explicadas nas próximas seções, mas os diagramas abaixo fornecem uma visão geral do comportamento da assinatura com esses status.

Quando um pagamento é bem-sucedido, o status da assinatura é definido como active e nenhuma outra ação é necessária. Quando um pagamento falha, o status da assinatura é definido como incomplete e o atributo status do PaymentIntent é definido como requires_payment_method. Você pode obter o Payment Intent no recurso Invoice Payment expandindo latest_invoice.payments.data.payment.payment_intent ou especificando o parâmetro da fatura com a lista Invoice Payment. Nessas situações, você deve cobrar o cliente com outra forma de pagamento usando o endpoint Pay Invoice.

Quando um pagamento exige SCA, o status da assinatura é definido como incomplete, e o atributo status do Payment Intent relevante é definido como requires_action. Você pode obter o Payment Intent no recurso Invoice Payment expandindo latest_invoice.payments.data.payment.payment_intent ou especificando o parâmetro da fatura com a lista Invoice Payment. Nessas situações, você precisa que o cliente realize um fluxo de autenticação 3D Secure usando o PaymentIntent. A próxima etapa explica como fazer isso.

Você pode usar os cartões de teste regulatório para explorar esse comportamento no seu ambiente de teste. Para obter instruções detalhadas sobre como criar uma integração de assinaturas completa, consulte o guia de integração.

Opção 1: usar o sinalizador de comportamento de pagamento

Se você não atualizar sua versão da API, mas passar um novo sinalizador payment_behavior= allow_incomplete nas chamadas de criação e atualização de assinaturas, suas assinaturas usarão o novo status incompleto. Isso permite gerenciar cenários que exigem SCA, o que é explicado na próxima etapa. Consulte as perguntas frequentes na parte inferior deste documento para ver uma lista completa de endpoints aos quais você precisa passar esse sinalizador.

Se você não atualizar sua versão da API e não passar o sinalizador payment_behavior, as tentativas de criar assinaturas que exigem SCA falharão e retornarão um card_error. Isso é consistente com o comportamento antigo que bloqueia a criação de assinaturas se o pagamento falhar.

Opção 2: atualizar sua API

Se você atualizar para a versão da API 2019-03-14 ou mais recente, as assinaturas adotarão automaticamente a nova funcionalidade status incompleto. Após atualizar a API, siga para a próxima etapa.

Etapa 2: gerenciar SCA

Para concluir o pagamento de uma cobrança que precisa de SCA, você pode usar o Stripe.js ou um fluxo de redirecionamento no navegador. O Stripe.js é recomendado porque a maioria dos usuários da Stripe já o utiliza, e ele ajuda a gerenciar a autenticação 3DS. O uso do Stripe.js envolve passar o latest_invoice.confirmation_secret.client_secret para o método confirmCardPayment, que exibe um modal que permite ao cliente fornecer a autenticação do pagamento.

Se preferir não usar o Stripe.js, envie um return_url para o endpoint de confirmação do PaymentIntent e inicie um fluxo de redirecionamento:

curl https://api.stripe.com/v1/payment_intents/{{PAYMENT_INTENT_ID}}/confirm \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  --data-urlencode return_url="https://www.example.com/return_url"

Para saber mais sobre como usar a API Payment Intents para concluir a autenticação do 3D Secure para o Billing, consulte o guia de visão geral.

Quando o cliente finalizar o redirecionamento ou a janela de autenticação, o status da assinatura será active e o status da fatura será paid. O cliente pode fechar o navegador após a autenticação, mas antes do redirecionamento. Para melhorar o gerenciamento, a Stripe recomenda escutar webhooks de faturas (veja instruções na próxima etapa).

Etapa 3: provisionamento e processamento

O cliente pode sair do navegador antes do retorno de chamada confirmCardPayment ou do redirecionamento return_url. Nesses casos, seu aplicativo pode não entender que o pagamento foi concluído e o produto em questão pode não ser enviado ao cliente. Para evitar isso, escute a notificação do evento invoice.paid para verificar se a fatura está paid e billing_reason=subscription_create. Isso significa que você pode enviar a assinatura ao cliente.

Cenário 1: cobrar o pagamento inicial dos clientes fora de sessão

Assinaturas com avaliações gratuitas ou faturamento por consumo e faturas com desconto por cupons ou saldos do cliente geralmente ocasionam faturas sem pagamento. Isso significa que o cliente não é cobrado assim que a assinatura é criada. Nessas situações, é preciso salvar os dados de pagamento e autenticar o cartão quando ele estiver na sessão para fazer a cobrança depois.

Para gerenciar essas situações, a Stripe criou a API Setup Intents, que permite que você:

• Colete dados de pagamento
• Autentique o cartão do cliente
• Autorize o cartão do cliente sem cobrá-lo

Se você coletar dados de pagamento antecipadamente e autenticar pagamentos, a Stripe pode pedir isenções em seu nome. Essas isenções costumam reduzir a probabilidade de exigência de 3DS quando você cobra o cliente fora de sessão.

Se a criação da assinatura não exigir um pagamento inicial e se a autenticação for recomendada com o cliente em sessão, o Stripe Billing cria automaticamente um SetupIntent. Isso é exposto no objeto Subscription por meio do atributo pending_setup_intent. Consulte a seção Como usar o SetupIntents para saber mais sobre SetupIntents e como usá-los com o Billing. Para criar assinaturas e cobrar o primeiro pagamento do cliente fora de sessão, é preciso:

1. Use CreatePaymentMethod para coletar informações de pagamento
2. Crie um cliente usando o ID do PaymentMethod criado por você
3. Crie a assinatura
4. Configure o gerenciamento de erros com confirmCardSetup para falhas de autenticação e confirmCardPayment para falhas de autorização

Também é possível usar SetupIntents para alterar a forma de pagamento em um cliente ou assinatura. A seção salvar cartões sem pagamento explica como fazer isso no nível do cliente. No nível da assinatura, a Stripe atualiza automaticamente o campo pending_setup_intent no objeto de assinatura se a autenticação for recomendada na forma de pagamento padrão atualizada.

Cenário 3: gerenciar cobranças recorrentes após os clientes realizarem o primeiro pagamento

Cobranças recorrentes normalmente ocorrem com o cliente fora de sessão. Se a cobrança não tiver nenhuma isenção e a SCA for necessária, peça para que o usuário abra uma sessão e faça o pagamento. Para fazer isso, use as ferramentas prontas da Stripe ou crie sua própria solução. O diagrama abaixo explica essas opções.

No prazo do ciclo de faturamento ou ao se atingir determinado limite da assinatura, ocorre uma tentativa de pagamento. Se a cobrança exigir SCA, o status da assinatura muda para past_due. Com as ferramentas da Stripe, você pode habilitar um conjunto de e-mails específicos para 3D Secure, enviados aos seus clientes em caso de exigência de SCA. Se quiser enviar seus próprios e-mails sem criar um fluxo de autenticação próprio, use a nossa Página de faturas hospedadas.

Se optar por criar sua própria solução, escute o webhook invoice.payment_action_required ou o webhook existente customer.subscription.updated para receber notificação de assinaturas past_due (vencidas) por causa da SCA. Quando isso acontecer, peça que o cliente abra uma sessão e siga um fluxo de autenticação similar ao explicado no primeiro cenário.

Depois da autenticação e conclusão do pagamento, o status da assinatura muda para active e o status da fatura, para paid.

Cenário 4: faturas isoladas

Faturas isoladas também podem exigir SCA. As alterações para gerenciar faturas isoladas dependem de como você usa o Billing. Se já utiliza a nossa página de faturas hospedadas, a SCA já é atendida e você não precisa mudar nada. Se utiliza collection_method=charge_automatically, o cliente pode precisar abrir uma sessão para fazer a SCA. Para isso, use a página de faturas hospedadas ou a gestão personalizada descrita no terceiro cenário.

Se o seu aplicativo usar o endpoint Pagar fatura, você precisa começar a usar a página de faturas hospedadas ou criar um gerenciamento personalizado, porque o endpoint retornará o erro HTTP 402 quando a SCA for exigida. Se optar pelo gerenciamento personalizado, use o PaymentIntent da fatura para concluir o pagamento. Também é preciso definir off_session quando tentar pagar uma fatura usando o endpoint.

Ferramentas para receber pagamentos fora de sessão

O Stripe Billing oferece ferramentas prontas para uso que podem gerenciar automaticamente pagamentos que exigirem autenticação 3D Secure.

Você pode escolher que a Stripe:

• Envie e-mail aos seus clientes quando um pagamento fora de sessão exigir autenticação 3D Secure
• Agende e-mails para lembrar os clientes de fazer a autenticação
• Envie um link para uma página de fatura hospedada onde os clientes podem fazer a autenticação.

Os e-mails e a página de fatura hospedada podem ser personalizados nas configurações de Marca.

A tabela a seguir descreve o que você ou a Stripe podem fazer para acionar a SCA e se a Stripe considera que a ação acontece por padrão dentro ou fora da sessão. Para ações fora de sessão, a Stripe envia um link de autenticação se a configuração do e-mail para SCA estiver habilitada.

As ações da API para criar e atualizar assinaturas e pagar faturas também têm o atributo off_session, que pode ser definido manualmente. Configurar esse atributo como true indica que o pagamento é fora de sessão e false indica que o pagamento é na sessão.

E-mails e cobrança

Você pode enviar um e-mail de cobrança aos clientes com pagamentos em atraso com o propósito de aumentar a chance de êxito na recuperação. Nosso conjunto de e-mails para clientes foi atualizado com novas notificações para casos em que a autenticação do 3D Secure é exigida em pagamentos fora da sessão. Além disso, permitimos o envio de faturas, recibos e notificações de falha de pagamentos.

Configurações de pagamento 3D Secure

É possível programar o envio de e-mails sobre 3D Secure determinar o que acontece com a assinatura se ela não for paga. Use as configurações do Billing no Stripe Dashboard para fazer essas configurações.

Solicitar autenticação de pagamento com e-mails sobre 3D Secure

Temos um modelo configurável para enviar um e-mail automático aos seus clientes, solicitando que façam a autenticação para pagar a fatura ou assinatura.

Página de fatura hospedada

O Stripe Billing fornece uma página de fatura hospedada que aceita todas as faturas. Para cumprir os requisitos SCA, essa página aceita a autenticação 3D Secure.

Se um pagamento fora de sessão exigir que o cliente realize autenticação 3D Secure, envie um link para uma página de fatura hospedada, onde ele pode confirmar o pagamento ou adicionar outra forma de pagamento, se necessário. Após confirmar o pagamento, o cliente pode fazer a autenticação junto ao banco na janela para 3D Secure 2 que é aberta.

Isenções de SCA

As normas SCA contêm um conjunto de isenções. Essas isenções significam que os clientes podem não precisar da autenticação para confirmar alguns pagamentos. O objetivo da Stripe é otimizar seu fluxo de pagamentos e tentar aplicar automaticamente o máximo possível de isenções, para que os clientes precisem fazer menos autenticações.

Resumo das mudanças na API

A API contém várias atualizações para ajudar a gerenciar requisitos de SCA e o fluxo de autenticação.

Status da assinatura

Acrescentamos dois status ao recurso Assinatura: incomplete e incomplete_expired. As assinaturas entram no status incomplete somente quando a primeira tentativa de cobrança falha ou exige SCA. As assinaturas no estado incomplete que não forem pagas expiram em 23 horas. Isso altera automaticamente o status para incomplete_expired. Depois que uma assinatura está active, ela não pode entrar em incomplete novamente. Os pagamentos futuros que exigem SCA fazem com que a assinatura se torne past_due.

As assinaturas mencionam a última fatura

O campo latest_invoice indica a fatura responsável pelo status de uma assinatura. Essa mudança foi inserida em todas as versões da API.

Todas as faturas usam PaymentIntents para pagamento

A API Payment Intents gerencia o ciclo de vida de um pagamento. Isso inclui um status de pagamento requires_action e um atributo next_action. Esses acréscimos indicam como realizar um pagamento, o que normalmente é feito por meio de um redirecionamento ao banco do titular do cartão para executar a autenticação ou com um URL integrado à resposta. O objeto Invoice tem um campo payments com objetos Invoice Payment que fornecem os vínculos entre fatura e pagamento que você pode usar para gerenciar o ciclo de vida do pagamento.

Aceitação do Stripe.js na API Payment Intents

Faturas para o Stripe Billing são totalmente compatíveis com a API Payment Intents, e você pode aproveitar as funções do Stripe.js para auxiliar no fluxo de pagamento do checkout. A função JavaScript de confirmCardPayment ajuda a exibir uma janela para 3D Secure para coletar os dados necessários para autenticar e concluir o pagamento. Essa mudança só afeta quem usa o PaymentIntents.

Um webhooksinvoice.payment_action_required é enviado quando SCA for exigida

Quando uma fatura exigir ação do cliente, a Stripe envia um novo webhook invoice.payment_action_required contendo a fatura em questão. Esse webhook complementa os webhooks existentes invoice.paid e invoice.payment_failed. A alteração foi acrescentada a todas as versões da API. Usuários existentes do Stripe Billing que não estiverem sujeitos à SCA podem ignorar esse webhook.

As assinaturas mencionam o SetupIntents para coletar a autenticação

As assinaturas agora têm um atributo pending_setup_intent, que indica um SetupIntent. Esse SetupIntent pode ser usado para coletar autenticação enquanto os clientes estão na sessão, o que otimiza pagamentos fora da sessão. Essa mudança foi acrescentada a todas as versões da API.

Perguntas frequentes (FAQ)

• A SCA afeta minha empresa?

  A Autenticação forte de cliente (SCA) aplica-se a pagamentos online quando o banco do titular do cartão e o provedor de pagamentos da empresa estão no Espaço Econômico Europeu (EEE). Leia mais na Visão geral da Autenticação forte de cliente.

• Quais formas de pagamento exigem SCA?

  A Autenticação Forte do Cliente aplica-se a pagamentos online “iniciados pelo cliente” na Europa. Por isso, a maioria dos pagamentos com cartão e todas as transferências bancárias exigirão SCA. As principais alterações necessárias na integração referem-se aos cartões, como documentado neste guia. Transferências bancárias não exigem mudanças na integração porque cabe ao banco do cliente autenticar transferências usando a sua própria interface bancária.

• O que acontece se eu não atualizar minha integração ou começar a passar o sinalizador payment_behavior?

  Chamadas para criar ou atualizar assinaturas com cobranças que exijam SCA receberão o erro HTTP 402. Chamadas para o endpoint Pagar fatura também vão falhar. Assim, sua taxa de pagamentos malsucedidos pode aumentar muito.

• Como usar o novo comportamento de assinatura sem atualizar a versão da minha API?

  Se você não puder atualizar a versão da API, será preciso usar o sinalizador payment_behavior=allow_incomplete. Como os pagamentos podem ser iniciados ao atualizar ou criar a assinatura, passe esse sinalizador em todas as chamadas de criação ou atualização de subscription e subscription_item. Veja abaixo a lista de endpoints aos quais esse sinalizador se aplica.

  • Criar cliente
  • Atualizar cliente
  • Criar assinatura
  • Atualizar assinatura
  • Atualizar item de assinatura

  Para criar e atualizar clientes, o sinalizador payment_behavior só é aceito quando a assinatura do cliente é feita com uma solicitação de API. Criar e atualizar assinaturas com o objeto Customer não é mais documentado, mas as APIs ainda são aceitas.

• Com que frequência a SCA será exigida e quando poderei contar com as isenções?

  Para assinaturas, a Stripe está trabalhando para otimizar as isenções reivindicadas em seu nome. A SCA será sistematicamente aplicada à primeira cobrança em uma assinatura quando o comerciante e o cliente estiverem localizados no EEE. Cobranças subsequentes podem estar sujeitas a isenções. Para faturas e cobranças isoladas, a Stripe solicitará isenções por você, quando possível.

  Há algumas restrições conhecidas para as isenções de SCA:

  • Determinados bancos emissores de cartões não aceitam algumas categorias de isenções ou todas elas, mas isso pode mudar no futuro.
  • O banco emissor do cartão tem o direito incondicional de contestar um pedido legítimo de isenção. Isso deve acontecer quando o banco considerar que a transação é de alto risco.

  Ao planejar uma atualização de integração, considere sempre a SCA.

• O que significa “fora de sessão” e qual a importância disso?

  Pagamentos fora da sessão são os que não têm envolvimento direto do cliente, usando dados de pagamento coletados previamente. Marcar transações como fora da sessão permite à Stripe solicitar isenções por você. Por exemplo: a isenção transação iniciada por comerciante (MIT) aplica-se somente a pagamentos fora da sessão. Solicitar essa isenção diminui a chance de necessidade de um SCA, reduzindo as complicações para o cliente.

• Quando a Stripe detecta automaticamente por você se o pagamento está sendo feito na sessão e fora de sessão?

  • Pagamentos iniciados por criação de assinatura presumidamente são feitos em sessão.
  • Pagamentos iniciados pelos sistemas automatizados da Stripe, como um pagamento de assinatura recorrente, são considerados fora de sessão.
  • Pagamentos que usam o endpoint Pagar fatura precisam ser marcados explicitamente como em sessão ou fora de sessão, com o atributo off_session. Se nenhum valor for definido, a Stripe considera true por padrão.

Log de alterações do Guia de migração de SCA

Lista das principais revisões deste guia.

15-07-2019

• Adicionar conteúdo explicando SetupIntents e quando usá-los
• Explicar quando a Stripe determina automaticamente se um pagamento acontece na sessão ou fora de sessão
• Explicar quando e como definir off_session no endpoint Pagar fatura
• Adicionar link para novo cartão para testar SCA
• Renomear o sinalizador enable_incomplete_payments para payment_behavior
  • payment_behavior pode ser definido como allow_incomplete ou error_if_incomplete

15-04-2019

• Publicar conteúdo inicial