Ir a contenido
Crea una cuenta o Inicia sesión
Logotipo de Stripe Docs
/
Crear una cuentaIniciar sesión
ResumenActualiza tu integración
Pagos electrónicos
ResumenEncuentra tu caso de usoUsar pagos administrados
Pagos en persona
Métodos de pago
Escenarios de pago
Más allá de los pagos

Pagos con Boleto

Descubre cómo aceptar Boleto, un método de pago muy usado en Brasil.

Los usuarios de Stripe de Brasil pueden aceptar pagos con Boleto de clientes de Brasil con las API Payment Intents y Payment Methods. Los clientes pagan usando el vale Boleto con un número generado en un cajero automático, un banco, el portal de un banco o agencias autorizadas.

Configurar Stripe
Lado del servidor

Primero, necesitas una cuenta de Stripe. Inscríbete ahora.

Usa nuestras bibliotecas oficiales para acceder a la API de Stripe desde tu aplicación:

Command Line
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
# Available as a gem
sudo gem install stripe
Gemfile
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
# If you use bundler, you can add this line to your Gemfile
gem 'stripe'

Crear un PaymentIntent
Lado del servidor

Stripe usa un objeto PaymentIntent para representar tu intención de cobrarle a un cliente y hace el seguimiento de los cambios de estado desde la creación del vale de Boleto hasta que se completa el pago.

Crea un PaymentIntent en tu servidor con un importe y la moneda brl (Boleto no admite otras monedas). Si ya tienes una integración con la API Payment Intents, agrega boleto a la lista de tipos de métodos de pago para tu PaymentIntent.

El PaymentIntent devuelto incluye un secreto de cliente que tendrás que usar para completar el proceso de pago en modo seguro. Vuelve a enviar esta clave secreta al cliente para que la use en los siguientes pasos.

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/payment_intents \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d amount=1099 \
  -d currency=brl \
  -d "payment_method_types[]"=boleto

Opciones de métodos de pago adicionales

Puedes especificar un parámetro opcional expires_after_days en las opciones de métodos de pago de tu PaymentIntent para definir la cantidad de días calendario que deben pasar para que venza el vale de Boleto. Por ejemplo, si creas un vale de Boleto un lunes y defines expires_after_days en 2, el vale de Boleto vencerá el miércoles a las 23:59, hora de América/Sao_Paulo (UTC-3). Si lo defines en 0, el vale de Boleto vencerá al final del día. El parámetro expires_after_days puede ser de 0 a 60 días. El valor predeterminado es de 3 días. Puedes personalizar los días de vencimiento predeterminados en tu cuenta en la configuración de métodos de pago

Recopilar datos del método de pago
Lado del cliente

Crea un formulario de pago del lado de tu cliente para recopilar los datos de facturación necesarios:

CampoValor
nameEl nombre completo del cliente.
emailLa dirección de correo electrónico del cliente.
tax_idEl número de CPF (para particulares) o el CNPJ (para empresas) del cliente. El CPF debe tener 11 dígitos en uno de los siguientes formatos: 000.000.000-00 o 00000000000. El CNPJ debe tener 14 dígitos en alguno de estos formatos: 00.000.000/0000-00 o 00000000000000.
addressLa calle y el número de la dirección del cliente.
cityLa ciudad de la dirección del cliente.
stateEl código de dos letras del estado brasileño (ISO_3166-2:BR) de la dirección del cliente.
postal_codeEl código postal de la dirección del cliente. El código postal debe tener uno de los siguientes dos formatos: XXXXX-XXX o XXXXXXXX.

Nota

Los campos name, address y city deben incluir al menos un carácter alfanumérico de la tabla de caracteres Unicode de latín básico (ASCII).

checkout.html
<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 el pago a Stripe
Lado del cliente

Cuando el cliente haga clic para pagar con Boleto, usa Stripe.js para enviar el pago a Stripe. Stripe.js es nuestra biblioteca principal de JavaScript para crear flujos de pago.

Incluye el script de Stripe.js en tu página de finalización de compra agregándolo al head de tu archivo HTML.

checkout.html
<head>
  <title>Checkout</title>
  <script src="https://js.stripe.com/clover/stripe.js"></script>
</head>

Crea una instancia de Stripe.js con el siguiente JavaScript en tu página de pago.

client.js
// 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'
);

Usa stripe.confirmBoletoPayment y el secreto de cliente del objeto PaymentIntent que creaste en el paso 2 para enviar los datos de facturación del cliente.

Una vez recibida la confirmación, Stripe abrirá automáticamente un cuadro de diálogo para mostrarle el vale Boleto al cliente.

client.js
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;
  }
});

Nota

stripe.confirmBoletoPayment puede tardar varios segundos en completarse. Durante ese tiempo, deshabilita tu formulario para no reenviarlo y muestra un indicador de espera, por ejemplo, un indicador giratorio. Si recibes un mensaje de error, muéstraselo al cliente, rehabilita el formulario y oculta el indicador de espera.

Cuando se crea un vale Boleto correctamente, el valor de la propiedad status del PaymentIntent devuelto es requires_action. Comprueba el estado del PaymentIntent en el Dashboard o examinando la propiedad de estado en el objeto. Si el vale Boleto no se creó correctamente, examina el mensaje de error recibido para determinar la causa (por ejemplo, si el formato de correo electrónico no es válido).

Opcional: Envía al cliente el enlace del vale por correo electrónico

Stripe envía un evento payment_intent.requires_action cuando se crea correctamente el vale de Boleto. Si necesitas enviar a tus clientes el enlace del vale por correo electrónico, puedes localizar la hosted_voucher_url en payment_intent.next_action.boleto_display_details.

Opcional: Personaliza tu vale

Stripe permite la personalización de las interfaces de usuario del cliente en la página de configuración de imagen de marca.

Se puede aplicar al vale la siguiente configuración de marca:

  • Ícono: tu imagen de marca y el nombre público de la empresa
  • Color de énfasis: Se utiliza como color del botón Copiar número
  • Color de la marca: se utiliza como color de fondo

Gestionar eventos posteriores al pago
Lado del servidor

Los pagos con Boleto son asincrónicos, de manera que los fondos no están disponibles de inmediato. Puede que el cliente no pague el vale Boleto inmediatamente después de realizar la compra.

Stripe envía un evento payment_intent.succeeded el siguiente día hábil (de lunes a viernes, excepto que sea día feriado en Brasil) por cada vale de Boleto pagado. Utiliza el Dashboard o un webhook personalizado para recibir estos eventos y ejecutar acciones (por ejemplo, enviar un correo electrónico de confirmación del pedido a tu cliente, registrar la venta en una base de datos o iniciar el flujo de envío).

Si el vale de Boleto no se abona antes de las 23:59, hora de América/Sao_Paulo (UTC -3), en la fecha de vencimiento, Stripe envía un evento payment_intent.payment_failed después de un día hábil. Por ejemplo, si un vale de Boleto vence el jueves, el evento se envía el viernes. Si un vale de Boleto vence el viernes, el evento se envía el lunes siguiente.

EventoDescripciónPróximos pasos
payment_intent.succeededEl cliente pagó el vale Boleto antes del vencimiento.Entrega los bienes o servicios que el cliente compró.
payment_intent.payment_failedEl cliente no pagó el vale Boleto antes del vencimiento.Comunícate con el cliente por correo electrónico o envía una notificación push y solicítale otro método de pago.

Probar la integración

En un entorno de prueba, establece payment_method.billing_details.email en los siguientes valores cuando llames a stripe.confirmBoletoPayment para probar diferentes escenarios.

Correo electrónicoDescripción

{any_prefix}@{any_domain}

Simula un vale Boleto abonado por el cliente al cabo de 3 minutos con el webhook payment_intent.succeeded recibido después de 3 minutos. En modo activo, este webhook llega 1 día hábil después del pago.

Ejemplo: fulaninho@example.com

{any_prefix}succeed_immediately@{any_domain}

Simula un vale Boleto abonado por el cliente de inmediato con el webhook payment_intent.succeeded recibido después de unos segundos. En modo activo, este webhook llega 1 día hábil después del pago.

Ejemplo: succeed_immediately@example.com

{any_prefix}expire_immediately@{any_domain}

Simula un vale Boleto que venza antes de que pague el cliente con el webhook payment_intent.payment_failed recibido después de unos segundos.

El campo expires_at en next_action.boleto_display_details está configurado en la hora actual, independientemente de cómo esté definido el parámetro expires_after_days en opciones de métodos de pago.

Ejemplo: expire_immediately@example.com

{any_prefix}expire_with_delay@{any_domain}

Simula un vale Boleto que venza antes de que pague el cliente con el webhook payment_intent.payment_failed recibido después de 3 minutos.

El campo expires_at en next_action.boleto_display_details está configurado en 3 minutos en el futuro, independientemente de la configuración que tenga el parámetro expires_after_days en opciones de métodos de pago.

Ejemplo: expire_with_delay@example.com

{any_prefix}fill_never@{any_domain}

Simula un vale de Boleto que nunca se realiza correctamente. Vence según indica el campo expires_at en next_action.boleto_display_details según los parámetros proporcionados en las opciones de métodos de pago y el webhook payment_intent.payment_failed llega después.

Ejemplo: fill_never@example.com

Identificación fiscalDescripción

CPF 000.000.000-00

CNPJ 00.000.000/0000-00

En el entorno de prueba, establece tax_id en estos valores para saltear la validación de la identificación fiscal.

OpcionalCrea tu propia página de vales
Lado del cliente

Te recomendamos que uses Stripe.js para mostrar en pantalla el vale Boleto con confirmBoletoPayment. No obstante, también puedes presentar el vale a tus clientes manualmente.

Puedes especificar handleActions: false al llamar a stripe.confirmBoletoPayment en el paso 4 para indicar que te encargarás de la siguiente acción de mostrar los datos de Boleto a tu cliente.

client.js
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;
  }
});

Incluye, como mínimo, lo siguiente:

DetalleDescripción
NúmeroPresenta el número del vale de Boleto de modo que el cliente pueda copiarlo en el portapapeles fácilmente. Busca el número en el objeto PaymentIntent en next_action.boleto_display_details.number.
Fecha de vencimientoMuestra la fecha de vencimiento del vale de Boleto. Busca la marca de tiempo UNIX después de la cual vencerá el vale de Boleto en el PaymentIntent en next_action.boleto_display_details.expires_at.
Descargar PDFPresenta un botón que le permita al cliente descargar el boleto en formato PDF. Busca el PDF, de donde el cliente puede descargar el vale de Boleto, en el PaymentIntent en next_action.boleto_display_details.pdf.

OpcionalConfirmar el Payment Intent del lado del servidor
Lado del servidor

Te recomendamos usar Stripe.js para confirmar un Payment Intent de Boleto con confirmBoletoPayment. Stripe.js facilita ampliar tu integración a otros métodos de pago. Sin embargo, también puedes confirmar un Payment Intent del lado del servidor de la siguiente forma:

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/payment_intents \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -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"

OpcionalEnviar correos electrónicos con instrucciones de pago

Puedes habilitar los correos electrónicos con instrucciones de pago con Boleto en la página de configuración de correo electrónico en el Dashboard. Una vez habilitados, Stripe envía estos correos cuando se confirma el PaymentIntent. Los correos contienen el número de Boleto y un enlace a la página del vale alojada en Stripe.

Nota

En entornos de prueba, los correos electrónicos con instrucciones solo se envían a las direcciones de correo vinculadas a la cuenta de Stripe.

Vencimiento y cancelación

Los vales Boleto vencen después de la marca de tiempo UNIX expires_at, y el cliente ya no puede pagar uno de estos vales una vez vencido. Los vales Boleto no se pueden cancelar antes de su vencimiento.

Después del vencimiento del vale Boleto, el estado del PaymentIntent cambia a requires_payment_method. A estas alturas, puedes confirmar el PaymentIntent con otro método de pago o cancelarlo.