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 StripeLado 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:
Crear un PaymentIntentLado 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 en brl (Boleto no acepta 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 de 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.
Opciones de métodos de pago adicionales
Puedes especificar un parámetro opcional expires_ 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_ 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_ 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 pagoLado del cliente
Crea un formulario de pago del lado de tu cliente para recopilar los datos de facturación necesarios:
| Campo | Valor |
|---|---|
name | El nombre completo del cliente. |
email | La dirección de correo electrónico del cliente. |
tax_ | El 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. o 00000000000. El CNPJ debe tener 14 dígitos en alguno de estos formatos: 00. o 00000000000000. |
address | La calle y el número de la dirección del cliente. |
city | La ciudad de la dirección del cliente. |
state | El código de dos letras del estado brasileño (ISO_3166-2:BR) de la dirección del cliente. |
postal_ | El 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).
<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 StripeLado 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.
<head> <title>Checkout</title> <script src="https://js.stripe.com/v3/"></script> </head>
Crea una instancia de Stripe.js con el siguiente JavaScript en tu página de pago.
// 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.
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. 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_. 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_ 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 pagoLado 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.
| Evento | Descripción | Próximos pasos |
|---|---|---|
payment_ | El cliente pagó el vale Boleto antes del vencimiento. | Entrega los bienes o servicios que el cliente compró. |
payment_ | El 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_ en los siguientes valores cuando llames a stripe.confirmBoletoPayment para probar diferentes escenarios.
| Correo electrónico | Descripción |
|---|---|
| Simula un vale Boleto abonado por el cliente al cabo de 3 minutos con el webhook Ejemplo: fulaninho@example.com |
| Simula un vale Boleto abonado por el cliente de inmediato con el webhook Ejemplo: succeed_immediately@example.com |
| Simula un vale Boleto que venza antes de que pague el cliente con el webhook El campo Ejemplo: expire_immediately@example.com |
| Simula un vale Boleto que venza antes de que pague el cliente con el webhook El campo Ejemplo: expire_with_delay@example.com |
| Simula un vale de Boleto que nunca se realiza correctamente. Vence según indica el campo Ejemplo: fill_never@example.com |
| Identificación fiscal | Descripción |
|---|---|
CPF CNPJ | En el entorno de prueba, establece |
Vencimiento y cancelación
Los vales Boleto vencen después de la marca de tiempo UNIX expires_, 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_. A estas alturas, puedes confirmar el PaymentIntent con otro método de pago o cancelarlo.