Pagamentos por boleto
Veja como aceitar boletos, uma forma de pagamento comum no Brasil.
Os usuários da Stripe no Brasil podem receber pagamentos por boleto dos clientes brasileiros por meio das APIs Payment Intents e Payment Methods. O boleto tem um número exclusivo, que o cliente usa para fazer o pagamento em caixas eletrônicos, bancos, internet banking ou agências autorizadas.
Configurar a StripeLado do servidor
Primeiro, você precisa de uma conta Stripe. Cadastre-se aqui.
Use nossas bibliotecas oficiais para acessar a API da Stripe no seu aplicativo:
Criar um PaymentIntentLado do servidor
A Stripe usa um objeto PaymentIntent para representar sua intenção de coletar o pagamento de um cliente, acompanhando desde a criação do boleto até seu pagamento.
Crie um PaymentIntent no seu servidor com um valor em moeda brl (não é possível gerar boletos em outras moedas). Se você já tiver uma integração usando a API Payment Intents, adicione boleto à lista de tipos de forma de pagamento para seu PaymentIntent.
O PaymentIntent retornado contém um segredo do cliente, que você usa para finalizar o processo de pagamento com segurança. Devolva o segredo do cliente ao cliente para usá-lo nas próximas etapas.
Outras opções da forma de pagamento
Você pode especificar um parâmetro opcional expires_ nas opções da forma de pagamento para o PaymentIntent, definindo os dias corridos até o vencimento. Por exemplo, se você criar um boleto na segunda-feira e a configuração de expires_ for 2, o boleto vencerá na quarta-feira, às 23h59, horário Sao_Paulo (UTC-3). Se a configuração for 0, o boleto vencerá no final do dia. O parâmetro expires_ pode ser de 0 a 60 dias. O padrão é 3 dias. Você pode personalizar os dias de validade padrão na sua conta nas configurações de formas de pagamento
Coletar dados da forma de pagamentoLado do cliente
Crie um formulário para obter os dados necessários para cobrar o cliente:
| Campo | Valor |
|---|---|
name | Nome completo do cliente. |
email | Endereço de e-mail do cliente. |
tax_ | O CPF (para indivíduos) ou CNPJ (para empresas) do cliente. O CPF precisa ter 11 dígitos em um dos seguintes formatos: 000. ou 00000000000. O CNPJ precisa ter 14 dígitos em um dos seguintes formatos: 00. ou 00000000000000. |
address | Nome da rua e número do endereço do cliente. |
city | Cidade do endereço do cliente. |
state | Sigla com duas letras representando o estado brasileiro (ISO_3166-2:BR) do endereço do cliente. |
postal_ | CEP do endereço do cliente, com dois formatos possíveis: XXXXX-XXX ou XXXXXXXX. |
Observação
Os campos name, address, city (nome, endereço, cidade) devem conter no mínimo um caractere alfanumérico do Basic Latin (ASCII) Unicode Block.
<form id="payment-form"> <div class="form-row"> <label for="name"> Name </label> <input id="name" name="name" required> </div> <div class="form-row"> <label for="tax_id"> CPF/CNPJ </label> <input id="tax_id" name="tax_id" required> </div> <div class="form-row"> <label for="email"> Email </label> <input id="email" name="email" required> </div> <div class="form-row"> <label for="address"> Address </label> <input id="address" name="address" required> </div> <div class="form-row"> <label for="city"> City </label> <input id="city" name="city" required> </div> <div class="form-row"> <label for="state"> State </label> <input id="state" name="state" required> </div> <div class="form-row"> <label for="postal_code"> Postal Code </label> <input id="postal_code" name="postal_code" required> </div> <!-- Used to display form errors. --> <div id="error-message" role="alert"></div> <button id="submit-button">Pay with Boleto</button> </form>
Enviar o pagamento para a StripeLado do cliente
Quando o cliente optar por pagar com Boleto, use Stripe.js para enviar o pagamento à Stripe. Stripe.js é a nossa biblioteca principal de JavaScript para criação de fluxos de pagamento.
Inclua Stripe.js na sua página de checkout, adicionando o script ao head do seu arquivo HTML.
<head> <title>Checkout</title> <script src="https://js.stripe.com/v3/"></script> </head>
Crie uma instância de Stripe.js com o seguinte JavaScript em sua página de checkout:
// Set your publishable key. Remember to switch to your live publishable key in production! // See your keys here: https://dashboard.stripe.com/apikeys const stripe = Stripe();'pk_test_TYooMQauvdEDq54NiTphI7jx'
Use stripe.confirmBoletoPayment e o segredo do cliente do objeto PaymentIntent criado na etapa 2 para enviar os dados de cobrança do cliente.
Depois da confirmação, a Stripe abre automaticamente um modal que mostra o boleto ao cliente.
var form = document.getElementById('payment-form'); form.addEventListener('submit', async (event) => { event.preventDefault(); const result = await stripe.confirmBoletoPayment( '{{PAYMENT_INTENT_CLIENT_SECRET}}', { payment_method: { boleto: { tax_id: document.getElementById('tax_id').value, }, billing_details: { name: document.getElementById('name').value, email: document.getElementById('email').value, address: { line1: document.getElementById('address').value, city: document.getElementById('city').value, state: document.getElementById('state').value, postal_code: document.getElementById('postal_code').value, country: 'BR', }, }, }, } ); // Stripe.js will open a modal to display the Boleto voucher to your customer // This async function finishes when the customer closes the modal if (result.error) { // Display error to your customer const errorMsg = document.getElementById('error-message'); errorMsg.innerText = result.error.message; } });
Observação
stripe. pode levar vários segundos para finalizar. Nesse período, previna que o formulário seja reenviado e apresente um indicador de espera, como um spinner. Se receber um erro, mostre-o ao cliente, reative o formulário e oculte o spinner.
Quando o boleto é criado, o valor da propriedade status do PaymentIntent indica requires_. Verifique o status de um PaymentIntent no Dashboard ou verifique a propriedade do status do objeto. Se o boleto não for criado corretamente, inspecione o error recebido para entender o motivo (um e-mail com formato inválido, por exemplo).
Opcional: enviar um e-mail ao cliente com um link para o boleto
A Stripe envia um evento payment_intent.requires_action quando um boleto é criado. Para enviar um e-mail ao cliente com o link para o boleto, pode localizar o link hosted_ em payment_intent.next_action.boleto_display_details.
Opcional: personalizar o boleto
A Stripe permite personalizar as IUs exibidas para seus clientes na página Configurações da marca.
Estas configurações de marca podem ser aplicadas à guia:
- Ícone: a imagem de sua marca e nome fantasia da empresa
- Cor de destaque: usada no botão Copiar número
- Cor da marca: usada como cor de fundo
Processar eventos pós-pagamentoLado do servidor
Os pagamentos por boleto são assíncronos, ou seja, os fundos não ficam imediatamente disponíveis. O cliente pode não pagar o boleto imediatamente após o checkout.
A Stripe envia um evento payment_intent.succeeded no dia útil seguinte (de segunda a sexta, exceto feriados do calendário brasileiro) para todos os boletos pagos. Use o Dashboard ou um webhook personalizado para receber esses eventos e executar ações (por exemplo, enviar um e-mail de confirmação de pedido ao cliente, registrar a venda em um banco de dados ou iniciar um fluxo de entrega).
Se o boleto não for pago antes das 23h59 América/Sao_Paulo (UTC-3) na data de vencimento, a Stripe envia um evento payment_intent.payment_failed após 1 dia útil. Por exemplo, se um boleto vencer na quinta-feira, o evento será enviado na sexta-feira. Se o boleto vencer na sexta-feira, o evento será enviado na segunda-feira seguinte.
| Evento | Descrição | Próximas etapas |
|---|---|---|
payment_ | O cliente pagou o boleto antes do vencimento. | Execute o pedido de mercadorias ou serviços do cliente. |
payment_ | O cliente não pagou o boleto antes do vencimento. | Entre em contato com o cliente por e-mail ou notificação push e solicite outra forma de pagamento. |
Testar a integração
Em uma área restrita, defina payment_ de acordo com os valores a seguir ao chamar stripe.confirmBoletoPayment para testar diferentes cenários.
| Descrição | |
|---|---|
| Simula um boleto pago pelo cliente depois de 3 minutos, com o webhook Exemplo: fulaninho@exemplo.com.br |
| Simula um boleto pago imediatamente pelo cliente, com o webhook Exemplo: succeed_immediately@exemplo.com.br |
| Simula um boleto que vence sem ser pago pelo cliente, com o webhook O campo Exemplo: expire_immediately@exemplo.com.br |
| Simula um boleto que vence sem ser pago pelo cliente, com o webhook O campo Exemplo: expire_with_delay@exemplo.com.br |
| Simula um boleto que nunca é pago; ele expira de acordo com o campo Exemplo: fill_never@exemplo.com.br |
| Código Fiscal | Descrição |
|---|---|
CPF CNPJ | Em uma área restrita, defina |
Validade e cancelamento
Os boletos vencem após a data UNIX expires_, e o cliente não pode pagar um boleto vencido. Não é possível cancelar um boleto antes do vencimento.
Depois do vencimento do boleto, o status do PaymentIntent muda para requires_. Neste ponto, você pode confirmar o PaymentIntent com outra forma de pagamento ou cancelar.