# Pagamentos por boleto Veja como aceitar boletos, uma forma de pagamento comum no Brasil. # Direct API 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* (Customer objects represent customers of your business. They let you reuse payment methods and give you the ability to track multiple payments) usa para fazer o pagamento em caixas eletrônicos, bancos, internet banking ou agências autorizadas. ## Configurar a Stripe [Lado do servidor] Primeiro, você precisa de uma conta Stripe. [Cadastre-se aqui](https://dashboard.stripe.com/register). Use nossas bibliotecas oficiais para acessar a API da Stripe no seu aplicativo: #### Ruby ```bash # Available as a gem sudo gem install stripe ``` ```ruby # If you use bundler, you can add this line to your Gemfile gem 'stripe' ``` ## Criar um PaymentIntent [Lado do servidor] A Stripe usa um objeto [PaymentIntent](https://docs.stripe.com/api/payment_intents.md) 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 e a moeda `brl` (o Boleto não aceita outras moedas). Se você já tiver uma integração usando a [API Payment Intents](https://docs.stripe.com/payments/payment-intents.md), adicione `boleto` à lista de [tipos de forma de pagamento](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-payment_method_types) para o seu `PaymentIntent`. O PaymentIntent retornado contém um *segredo do cliente* (The client secret is a unique key returned from Stripe as part of a PaymentIntent. This key lets the client access important fields from the PaymentIntent (status, amount, currency) while hiding sensitive ones (metadata, customer)), 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. ```curl curl https://api.stripe.com/v1/payment_intents \ -u "<>:" \ -d amount=1099 \ -d currency=brl \ -d "payment_method_types[]=boleto" ``` ### Outras opções da forma de pagamento Você pode especificar um parâmetro opcional `expires_after_days` nas [opções da forma de pagamento](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-payment_method_options-boleto-expires_after_days) 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_after_days` 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_after_days` 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](https://dashboard.stripe.com/settings/payment_methods) ## Coletar dados da forma de pagamento [Lado 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_id` | O CPF (para indivíduos) ou CNPJ (para empresas) do cliente. O CPF precisa ter 11 dígitos em um dos seguintes formatos: `000.000.000-00` ou `00000000000`. O CNPJ precisa ter 14 dígitos em um dos seguintes formatos: `00.000.000/0000-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](https://en.wikipedia.org/wiki/ISO_3166-2:BR)) do endereço do cliente. | | `postal_code` | CEP do endereço do cliente, com dois formatos possíveis: `XXXXX-XXX` ou `XXXXXXXX`. | > Os campos `name`, `address`, `city` (nome, endereço, cidade) devem conter no mínimo um caractere alfanumérico do [Basic Latin (ASCII) Unicode Block](https://en.wikipedia.org/wiki/Basic_Latin_\(Unicode_block\)). ```html
``` ## Enviar o pagamento para a Stripe [Lado do cliente] Quando o cliente optar por pagar com Boleto, use Stripe.js para enviar o pagamento à Stripe. [Stripe.js](https://docs.stripe.com/payments/elements.md) é 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. ```html Checkout ``` Crie uma instância de Stripe.js com o seguinte JavaScript em sua página de checkout: ```javascript // 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('<>'); ``` Use [stripe.confirmBoletoPayment](https://docs.stripe.com/js/payment_intents/confirm_boleto_payment) e o [segredo do cliente](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-client_secret) 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. ```javascript 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; } }); ``` > `stripe.confirmBoletoPayment` 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 uma guia de boleto é devidamente criada, o valor da propriedade `status` do PaymentIntent retornado é `requires_action`. Verifique o status de um PaymentIntent no [Dashboard](https://dashboard.stripe.com/test/payments) ou inspecionando a propriedade status no objeto. Se a guia do boleto não for devidamente criada, inspecione o `error` retornado para determinar a causa (por exemplo, formato de e-mail inválido). ### Opcional: enviar um e-mail ao cliente com um link para o boleto A Stripe envia um evento [payment_intent.requires_action](https://docs.stripe.com/api/events/types.md#event_types-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_voucher_url` em [payment_intent.next_action.boleto_display_details](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-next_action-boleto_display_details-hosted_voucher_url). ### Opcional: personalizar o boleto A Stripe permite personalizar as IUs exibidas para seus clientes na página [Configurações da marca](https://dashboard.stripe.com/account/branding). 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-pagamento [Lado do servidor] Os pagamentos por boleto são assíncronos, ou seja, os fundos não ficam disponíveis imediatamente. O cliente pode não pagar o boleto imediatamente após o checkout. A Stripe envia um evento [payment_intent.succeeded](https://docs.stripe.com/api/events/types.md#event_types-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* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) 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 uma guia de boleto não for paga antes das 23h59 America/Sao_Paulo (UTC-3) do dia do vencimento, a Stripe enviará um evento [payment_intent.payment_failed](https://docs.stripe.com/api/events/types.md#event_types-payment_intent.payment_failed) após 1 dia útil. Por exemplo, se uma guia de boleto vencer na quinta-feira, o evento será enviado na sexta-feira. Se uma guia de boleto expirar na sexta-feira, o evento será enviado na segunda-feira seguinte. | Evento | Descrição | Próximas etapas | | ------------------------------- | --------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | | `payment_intent.succeeded` | O cliente pagou o boleto antes do vencimento. | Execute o pedido de mercadorias ou serviços do cliente. | | `payment_intent.payment_failed` | O cliente não pagou a guia de 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* (A sandbox is an isolated test environment that allows you to test Stripe functionality in your account without affecting your live integration. Use sandboxes to safely experiment with new features and changes), defina `payment_method.billing_details.email` de acordo com os valores a seguir ao chamar [stripe.confirmBoletoPayment](https://docs.stripe.com/js/payment_intents/confirm_boleto_payment) para testar diferentes cenários. | E-mail | Descrição | | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `{any_prefix}@{any_domain}` | Simula um boleto pago pelo cliente depois de 3 minutos, com o webhook `payment_intent.succeeded` recebido depois de cerca de 3 minutos. Em produção, este webhook chega 1 dia útil após o pagamento. Exemplo: fulaninho@exemplo.com.br | | `{any_prefix}succeed_immediately@{any_domain}` | Simula um boleto pago imediatamente pelo cliente, com o webhook `payment_intent.succeeded` recebido depois de alguns segundos. Em produção, este webhook chega 1 dia útil após o pagamento. Exemplo: succeed_immediately@exemplo.com.br | | `{any_prefix}expire_immediately@{any_domain}` | Simula um boleto que vence sem ser pago pelo cliente, com o webhook `payment_intent.payment_failed` recebido depois de alguns segundos. O campo `expires_at` em [next_action.boleto_display_details](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-next_action-boleto_display_details-expires_at) está configurado para o horário atual, independente da configuração do parâmetro `expires_after_days` em [opções de forma de pagamento](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-payment_method_options-boleto-expires_after_days). Exemplo: expire_immediately@exemplo.com.br | | `{any_prefix}expire_with_delay@{any_domain}` | Simula um boleto que vence sem ser pago pelo cliente, com o webhook `payment_intent.payment_failed` recebido depois de 3 minutos. O campo `expires_at` em [next_action.boleto_display_details](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-next_action-boleto_display_details-expires_at) está configurado para 3 minutos no futuro, independente da configuração do parâmetro `expires_after_days` em [opções de forma de pagamento](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-payment_method_options-boleto-expires_after_days). Exemplo: expire_with_delay@exemplo.com.br | | `{any_prefix}fill_never@{any_domain}` | Simula um boleto que nunca é pago; ele expira de acordo com o campo `expires_at` em [next_action.boleto_display_details](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-next_action-boleto_display_details-expires_at) de acordo com os parâmetros informados em [opções de forma de pagamento](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-payment_method_options-boleto-expires_after_days). O webhook `payment_intent.payment_failed` é recebido em seguida. Exemplo: fill_never@exemplo.com.br | | Código Fiscal | Descrição | | ------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | | CPF `000.000.000-00` CNPJ `00.000.000/0000-00` | Em uma área restrita, defina `tax_id` como esses valores, para que eles ignorem a validação do ID fiscal. | ## Optional: Crie sua própria interface de boletos [Lado do cliente] Recomendamos usar o arquivo Stripe.js para exibir o boleto com `confirmBoletoPayment`. Mas você também pode exibir o boleto aos clientes manualmente. Para indicar que você vai gerenciar a próxima ação para exibir os dados do boleto ao seu cliente, especifique `handleActions: false` ao chamar stripe.confirmBoletoPayment na etapa 4. ```javascript 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', }, }, }, }, {handleActions: false}, ); if (result.error) { // Display error to your customer const errorMsg = document.getElementById('error-message'); errorMsg.innerText = result.error.message; } else { // An Boleto voucher was successfully created const amount = result.paymentIntent.amount; const currency = result.paymentIntent.currency; const details = result.paymentIntent.next_action.boleto_display_details; const number = details.number; const expires_at = details.expires_at; // Handle the next action by displaying the Boleto details to your customer // You can also use the generated hosted voucher const hosted_voucher_url = details.hosted_voucher_url; } }); ``` Incluir, no mínimo, o seguinte: | Detalhe | Descrição | | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Número | Exiba o número do boleto de forma que o cliente possa copiá-lo facilmente para a área de transferência. Localize o número no objeto `PaymentIntent` em [next_action.boleto_display_details.number](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-next_action-boleto_display_details-number). | | Data de vencimento | Exiba a data de vencimento do boleto. Localize o carimbo de data e hora UNIX para vencimento do boleto no `PaymentIntent` em [next_action.boleto_display_details.expires_at](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-next_action-boleto_display_details-expires_at). | | Baixar PDF | Exiba um botão para download que permite que o cliente baixe o boleto em PDF. O PDF do boleto que o cliente pode baixar fica no `PaymentIntent`, em [next_action.boleto_display_details.pdf](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-next_action-boleto_display_details-pdf). | ## Optional: Confirmar Payment Intent no lado do servidor [Lado do servidor] Recomendamos o arquivo Stripe.js para *confirmar* (Confirming an intent indicates that the customer intends to use the current or provided payment method. Upon confirmation, the intent attempts to initiate the portions of the flow that have real-world side effects) um Payment Intent com boleto usando `confirmBoletoPayment`. O arquivo Stripe.js facilita a extensão da sua integração para outras formas de pagamento. No entanto, você também pode confirmar um Payment Intent no lado do servidor da seguinte maneira: ```curl curl https://api.stripe.com/v1/payment_intents \ -u "<>:" \ -d amount=1099 \ -d currency=brl \ -d confirm=true \ -d "payment_method_types[]=boleto" \ -d "payment_method_data[type]=boleto" \ -d "payment_method_data[billing_details][name]=João da Silva" \ --data-urlencode "payment_method_data[billing_details][email]=joao@exemplo.com" \ -d "payment_method_data[billing_details][address][line1]=1234 Av. Paulista" \ -d "payment_method_data[billing_details][address][city]=São Paulo" \ -d "payment_method_data[billing_details][address][state]=SP" \ -d "payment_method_data[billing_details][address][postal_code]=01310-000" \ -d "payment_method_data[billing_details][address][country]=BR" \ -d "payment_method_data[boleto][tax_id]=000.000.000-00" ``` ## Optional: Enviar e-mails de instrução de pagamento Você pode habilitar e-mails com instruções de pagamento do boleto na página [Configurações de e-mail](https://dashboard.stripe.com/settings/emails) no Dashboard. Após a habilitação, a Stripe envia e-mails com instruções de pagamento na confirmação do PaymentIntent. Os e-mails contêm o número do boleto e um link para a página do boleto hospedada na Stripe. > Nos ambientes de teste, os e-mails com instruções só são enviados para endereços de e-mail vinculados à conta Stripe. ## Validade e cancelamento Os boletos vencem após a data UNIX `expires_at`, 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_payment_method`. Neste ponto, você pode confirmar o PaymentIntent com outra forma de pagamento ou cancelar.