Configurar pagamentos futuros
A API Setup Intents salva os dados de pagamento do cliente sem um pagamento inicial. É uma função útil para integrar um cliente agora e deixar tudo configurado para pagamentos futuros com o cliente fora de sessão.
Use esta integração para configurar pagamentos recorrentes ou criar pagamentos avulsos de valores a serem definidos mais tarde, talvez depois de o cliente receber seu serviço.
Conformidade
You’re responsible for your compliance with all applicable laws, regulations, and network rules when saving a customer’s payment details. These requirements generally apply if you want to save your customer’s payment method for future use, such as displaying a customer’s payment method to them in the checkout flow for a future purchase or charging them when they’re not actively using your website or app. Add terms to your website or app that state how you plan to save payment method details and allow customers to opt in.
When you save a payment method, you can only use it for the specific usage you have included in your terms. To charge a payment method when a customer is offline and save it as an option for future purchases, make sure that you explicitly collect consent from the customer for this specific use. For example, include a “Save my payment method for future use” checkbox to collect consent.
To charge them when they’re offline, make sure your terms include the following:
- A concordância do cliente para que você inicie um pagamento ou uma série de pagamentos em nome dele para transações específicas.
- O momento e a frequência previstos para os pagamentos (por exemplo, se são cobranças de parcelas agendadas, pagamentos de assinatura ou recargas não agendadas).
- Como você determina o valor do pagamento.
- Sua política de cancelamento, se a forma de pagamento for usada em um serviço de assinatura.
Não se esqueça de manter um registro por escrito da concordância do cliente com esses termos.
Observação
Se você precisar usar confirmação manual no lado do servidor, ou se sua integração exigir a apresentação de formas de pagamento separadamente, consulte o nosso guia alternativo.
Configurar a StripeLado do servidor
Primeiro, crie uma conta Stripe ou entre.
Use nossas bibliotecas oficiais para acessar a API da Stripe no seu aplicativo:
Ativar formas de pagamento
Veja suas configurações de formas de pagamento e habilite as formas de pagamento que deseja aceitar. Você precisa de pelo menos uma forma de pagamento habilitada para criar um SetupIntent.
Por padrão, a Stripe habilita cartões e outras formas de pagamento comuns que podem ajudar você a alcançar mais clientes, mas recomendamos ativar outras formas de pagamento que sejam relevantes para sua empresa e seus clientes. Consulte Opções de integração de formas de pagamento para saber mais sobre suporte a produtos e formas de pagamento, e nossa página de preços para ver as tarifas.
Criar um clienteLado do servidor
Para configurar uma forma de pagamento para pagamentos futuros, você deve anexá-la a um Customer. Crie um objeto Customer
quando seu cliente criar uma conta com sua empresa. Os objetos Customer
permitem reutilizar formas de pagamento e rastrear vários pagamentos.
Criar um SetupIntentLado do servidor
Observação
Se quiser renderizar o Payment Element antes de criar um SetupIntent, consulte Coletar detalhes do pagamento antes de criar um Intent.
Um SetupIntent é um objeto que representa sua intenção de configurar uma forma de pagamento do cliente para pagamentos futuros. As formas de pagamento mostradas aos clientes durante o processo de checkout também são incluídas no SetupIntent. Você pode deixar que a Stripe extraia automaticamente as formas de pagamento das configurações do Dashboard ou listá-las manualmente.
Se sua integração não exige uma opção baseada em código para oferecer formas de pagamento, a Stripe recomenda a opção automática. A Stripe avalia a moeda, as restrições e outros parâmetros dessas formas de pagamento para criar a lista das que são aceitas. Priorizamos as que aumentam a conversão e são mais relevantes para a moeda e a localização do cliente. As formas de pagamento de menor prioridade são ocultas em um menu de estouro.
Recuperar o segredo do cliente
O SetupIntent inclui um segredo do cliente que o lado do cliente usa para concluir com segurança o processo de pagamento. Você pode usar abordagens diferentes para enviar a senha do cliente ao lado do cliente.
Uso do Radar
Ao salvar a forma de pagamento de um cliente sem um pagamento inicial, o Radar não age no SetupIntent por padrão. Se quiser ativá-lo como padrão, acesse as configurações do Radar e habilite Use o Radar em formas de pagamento salvas para uso futuro.
Coletar dados de pagamentoLado do cliente
Você está com tudo pronto para coletar dados de pagamento no cliente com o Payment Element. O Payment Element é um componente de IU que simplifica a coleta de dados de pagamento para uma ampla variedade de formas de pagamento.
O Payment Element contém um iframe que envia dados de pagamento à Stripe com segurança por uma conexão HTTPS. O endereço da página de checkout precisa começar com https://
em vez de http://
para que sua integração funcione. Você pode testar sua integração sem fazer isso, mas lembre-se de habilitar o HTTPS quando estiver tudo pronto para você aceitar pagamentos em tempo real.
O Payment Element renderiza um formulário dinâmico que permite ao cliente escolher uma forma de pagamento. Para cada forma de pagamento, o formulário solicita automaticamente que o cliente preencha todos os dados de pagamento necessários.
Personalizar a aparência
Personalize o Payment Element para corresponder ao design do seu site, passando o objeto appearance para options
ao criar o provedor do Elements
.
Solicitar token de comerciante do Apple Pay
Se você aceita pagamentos com Apple Pay, recomendamos configurar a interface do Apple Pay para retornar um token de comerciante que habilite transações iniciadas por comerciantes (MIT). Solicite o tipo de token de comerciante relevante no Payment Element. O exemplo a seguir mostra uma solicitação para o token de comerciante de pagamentos diferidos.
const paymentElement = elements.create('payment', { applePay: { deferredPaymentRequest: { paymentDescription: 'My deferred payment', managementURL: 'https://example.com/billing', deferredBilling: { amount: 2500, label: 'Deferred Fee', deferredPaymentDate: new Date('2024-01-05') }, } }, // Other options });
Configurar moeda
Ao usar SetupIntents com automatic_payment_methods, passar a moeda ao em options
ao criar o provedor do Elements
influencia quais formas de pagamento são processadas pelo Payment Element. O Payment Element processa as formas de pagamento habilitadas no Stripe Dashboard que aceitam a moeda informada. Consulte Opções de integração de forma de pagamento para obter mais detalhes sobre o que é aceito.
Solicitar endereços
Por padrão, o Payment Element coleta apenas os detalhes necessários do endereço de cobrança. Para coletar o endereço de cobrança completo (por exemplo, para calcular o imposto para mercadorias e serviços digitais) ou o endereço de entrega de um cliente, use o Address Element.
Envie os dados do pagamento para a StripeLado do cliente
Use stripe.confirmSetup para concluir a configuração usando os detalhes coletados pelo Element Pagamento. Forneça um return_url a esta função para que a Stripe possa redirecionar o usuário após a conclusão da configuração. Primeiro, poderemos redirecioná-lo a um site intermediário, como uma página de autorização do banco, antes de redirecioná-lo ao return_url
.
Se o seu cliente salvar os dados do cartão, nós o redirecionaremos imediatamente para o return_url
quando a configuração estiver concluída. SE você não quiser redirecionar para pagamentos com cartão, defina redirecionar como if_required
. Isso somente redireciona os clientes que fazem checkout com formas de pagamento baseadas em redirecionamento.
Certifique-se de que o return_url
corresponda a uma página no seu site que fornece o status do SetupIntent
. A Stripe fornece os seguintes parâmetros de consulta de URL para verificar o status quando redirecionamos o cliente ao return_url
. Você também pode anexar nossos próprios parâmetros de consulta ao fornecer o return_url
, e eles persistem por meio do processo de redirecionamento.
Parâmetro | Descrição |
---|---|
setup_intent | O identificador único do SetupIntent . |
setup_intent_client_secret | O segredo do cliente do objeto SetupIntent . |
Você pode usar stripe.retrieveSetupIntent para recuperar o SetupIntent usando o parâmetro de consulta setup_intent_client_secret
. A confirmação do SetupIntent salva o ID do PaymentMethod
resultante (em result.setupIntent.payment_method
) no Customer
informado.
Cuidado
Se você tiver ferramentas que rastreiam a sessão do cliente no navegador, pode ser necessário adicionar o domínio stripe.com
à lista de exclusão de referenciadores. Os redirecionamentos fazem com que algumas ferramentas criem sessões, o que impede que você rastreie a sessão completa.
Cobrar mais tarde a forma de pagamento salvaLado do servidor
Conformidade
Você é responsável por cumprir todas as leis, regulamentos e regras da bandeira em vigor ao salvar os dados de pagamento de um cliente. Quando exibir formas de pagamento passadas ao seu cliente final para compras futuras, certifique-se de listar as formas de pagamento para as quais obteve consentimento do cliente para salvar os dados para esse uso futuro específico. Para diferenciar entre formas de pagamento vinculadas a clientes que podem e não podem ser apresentados ao seu cliente final como uma forma de pagamento salva para compras futuras, use o parâmetro allow_redisplay.
Quando estiver pronto para cobrar do cliente fora da sessão, use os IDs do cliente e do PaymentMethod para criar um PaymentIntent. Para encontrar uma forma de pagamento para cobrar, liste as formas de pagamento associadas ao seu cliente. Este exemplo lista cartões, mas você pode listar qualquer tipo.) aceito.
Quando tiver os IDs de Customer e PaymentMethod, crie um PaymentIntent com o valor e moeda do pagamento. Outros parâmetros que precisam ser definidos para o pagamento fora de sessão:
- Defina off_session como
true
para indicar que o cliente não está em seu fluxo de checkout durante uma tentativa de pagamento e não pode executar uma solicitação de autenticação feita por um parceiro, como emissor de cartão, banco ou outra instituição de pagamento. Se, durante o fluxo de checkout, um parceiro solicitar autenticação, a Stripe solicitará isenções usando informações do cliente de uma transação na sessão anterior. Se as condições de isenção não forem atendidas, o PaymentIntent pode gerar um erro. - Defina o valor da propriedade confirm do PaymentIntent como
true
, para que a confirmação ocorra imediatamente após a criação do PaymentIntent. - Defina payment_method com o ID do PaymentMethod e customer com o ID do Customer.
Quando uma tentativa de pagamento falha, a solicitação também falha (código de status HTTP 402) e o status do PaymentIntent fica sendo requires_payment_method. Você deverá notificar o cliente para que ele acesse novamente seu aplicativo para finalizar o pagamento (envie um e-mail ou notificação pelo aplicativo, por exemplo).
Verifique o código do erro indicado pela biblioteca da API Stripe. Se o pagamento falhou com o código authentication_required, use o segredo do cliente do PaymentIntent recusado com confirmPayment para permitir que o cliente autentique o pagamento.
const form = document.getElementById('payment-form'); form.addEventListener('submit', async (event) => { event.preventDefault(); const {error} = await stripe.confirmPayment({ // The client secret of the PaymentIntent clientSecret, confirmParams: { return_url: 'https://example.com/order/123/complete', }, }); if (error) { // This point will only be reached if there is an immediate error when // confirming the payment. Show error to your customer (for example, payment // details incomplete) const messageContainer = document.querySelector('#error-message'); messageContainer.textContent = error.message; } else { // Your customer will be redirected to your `return_url`. For some payment // methods like iDEAL, your customer will be redirected to an intermediate // site first to authorize the payment, then redirected to the `return_url`. } });
Observação
stripe.confirmPayment
pode levar vários segundos para finalizar. Durante esse período, desative o formulário para impedir que seja reenviado e apresente um indicador de espera, como uma ampulheta. Se receber um erro, mostre-o ao cliente, reative o formulário e oculte o indicador de espera. Se o cliente precisar executar etapas adicionais para finalizar o pagamento, como autenticação, o Stripe.js o orientará durante a execução.
Se o pagamento falhar por outros motivos, como insuficiência de fundos, envie o cliente para uma página de pagamento para que ele insira outra forma de pagamento. Você pode reaproveitar o PaymentIntent atual para tentar repetir o pagamento com os dados do novo pagamento.
Testar a integração
Use os detalhes de pagamento de teste e a página de redirecionamento de teste para verificar sua integração. Clique nas guias abaixo para ver os detalhes de cada forma de pagamento.
Teste a cobrança de um PaymentMethod de débito SEPA
Confirmar o SetupIntent usando iDEAL, Bancontact ou Sofort, gera um débito automático SEPA PaymentMethod. O débito automático SEPA é uma forma de pagamento de notificação posterior que muda para um estado de processing
intermediário antes de mudar vários dias depois para um estado succeeded
ou requires_payment_method
.
Divulgue a Stripe para seus clientes
A Stripe coleta informações sobre interações do cliente com o Elements para fornecer serviços a você, evitar fraudes e melhorar os serviços. Isso inclui o uso de cookies e endereços IP para identificar quais Elements o cliente visualizou durante uma única sessão de checkout. Você é responsável por divulgar e obter todos os direitos e consentimentos necessários para que a Stripe use os dados dessas maneiras. Para saber mais, acesse nossa central de privacidade.