Boleto payments
Learn how to accept Boleto, a common payment method in Brazil.
Checkout
Elements
Direct API
Boleto is a single use payment method where customers are required to take additional steps to complete their payment. Customers pay by using a Boleto voucher with a generated number either in ATMs, banks, bank portals or authorized agencies.
Determine compatibility
A Checkout Session must satisfy the following condition to support Boleto payments:
- Prices for all line items must be in the same currency. If you have line items in different currencies, create separate Checkout Sessions for each currency.
Accept a payment
Note
Build an integration to accept a payment with Checkout before using this guide.
Enable Boleto as a payment method
When creating a new Checkout Session, you need to:
- Enable Boleto in your Dashboard. Stripe automatically displays Boleto to eligible customers using dynamic payment methods . If you currently specify payment _ method _ types , see the migration guide .
- Make sure all your line _ items use the brl currency.
Command Line
Select a language
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
Additional payment method options
You can specify an optional expires_after_days parameter in the payment method options for your Session that sets the number of calendar days before a Boleto voucher expires. For example, if you create a Boleto voucher on Monday and you set expires_after_days to 2, the Boleto voucher expires on Wednesday at 23:59 America/Sao_Paulo (UTC-3) time. If you set it to 0, the Boleto voucher expires at the end of the day. The expires_after_days parameter can be set from 0 to 60 days. The default is 3 days. You can customize the default expiration days on your account in the Payment methods settings.
Command Line
Select a language
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
Redirect to Stripe hosted voucher page
Note
Unlike card payments, the customer won’t be redirected to the success_url with Boleto payment.
After submitting the Checkout form successfully, the customer is redirected to the hosted_voucher_url. The customer can copy the Boleto number or download the voucher PDF from the hosted voucher page.
Stripe sends a payment_intent.requires_action event when a Boleto voucher is created successfully. If you need to email your customers the voucher link, you can locate the hosted_voucher_url in payment_intent.next_action.boleto_display_details. Learn more about how to monitor a PaymentIntent with webhooks.
Stripe allows customization of customer-facing UIs on the Branding Settings page. The following brand settings can be applied to the voucher:
- Icon —your brand image and public business name
- Accent color —used as the color of the Copy Number button
- Brand color —used as the background color
Fulfill your orders
Because Boleto is a delayed notification payment method, you need to use a method such as webhooks to monitor the payment status and handle order fulfillment. Learn more about setting up webhooks and fulfilling orders.
The following events are sent when the payment status changes:
| Event Name | Description | Next steps |
|---|---|---|
| checkout.session.completed | The customer has successfully submitted the Checkout form. Stripe has generated the Boleto voucher. You can choose to email the hosted_voucher_url to your customer in case they lose the Boleto voucher. | Wait for the customer to pay the Boleto. |
| checkout.session.async_payment_succeeded | The customer has successfully paid the Boleto. The PaymentIntent transitions to succeeded. | Fulfill the goods or services that the customer purchased. |
| checkout.session.async_payment_failed | The Boleto voucher has expired, or the payment has failed for some other reason. The PaymentIntent returns to a status of requires_payment_method. | Contact the customer through email and request that they place a new order. |
Test your integration
When testing your Checkout integration, select Boleto as the payment method and click the Pay button.
| Description | |
|---|---|
{any_prefix}@{any_domain} | Simulates a Boleto voucher which a customer pays after 3 minutes and the payment_intent.succeeded webhook arrives after about 3 minutes. In production, this webhook arrives 1 business day after a payment. Example: |
{any_prefix}succeed_immediately@{any_domain} | Simulates a Boleto voucher which a customer pays immediately and the payment_intent.succeeded webhook arrives within several seconds. In production, this webhook arrives 1 business day after a payment. Example: |
{any_prefix}expire_immediately@{any_domain} | Simulates a Boleto voucher which expires before a customer pays and the payment_intent.payment_failed webhook arrives within several seconds. The expires_at field in next_action.boleto_display_details is set to the current time regardless of what the expires_after_days parameter in payment method options is set to. Example: |
{any_prefix}expire_with_delay@{any_domain} | Simulates a Boleto voucher which expires before a customer pays and the payment_intent.payment_failed webhook arrives after about 3 minutes. The expires_at field in next_action.boleto_display_details is set to 3 minutes in the future regardless of what the expires_after_days parameter in payment method options is set to. Example: |
{any_prefix}fill_never@{any_domain} | Simulates a Boleto voucher which never succeeds; it expires according to the expires_at field in next_action.boleto_display_details per the provided parameters in the payment method options and the payment_intent.payment_failed webhook arrives after that. Example: |
| Tax ID | Description |
|---|---|
CPF 000.000.000-00 the related setting 00.000.000/0000-00 | In a sandbox, set tax_id to these values, so they bypass the tax ID validation. |
Handle refunds
Boleto payments can’t be refunded. Some merchants have created a separate process to credit their customers who reach out directly.
Handle disputes
Boleto payments can’t be disputed by the customer.