| [ Web Proxy ] |
| Viewing: https://docs.stripe.com/payments/boleto/accept-a-payment | [Back] [Original] |
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.
Supported business locations: BR
Supported currencies: brl
Presentment currencies: brl
Payment mode: Yes
Setup mode: No
Subscription mode: Yes
A Checkout Session must satisfy the following condition to support Boleto payments:
Build an integration to accept a payment with Checkout before using this guide.
When creating a new Checkout Session, you need to:
payment_method_types, see the migration guide.line_items use the brl currency.curl https://api.stripe.com/v1/checkout/sessions \ -u "sk_test_wU7nrJCZspk1NPDxiQgAF05q:" \ -d "line_items[0][price_data][currency]=brl" \ -d "line_items[0][price_data][product_data][name]=T-shirt" \ -d "line_items[0][price_data][unit_amount]=2000" \ -d "line_items[0][quantity]=1" \ -d mode=payment \ --data-urlencode "success_url=https://example.com/success"
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.
curl https://api.stripe.com/v1/checkout/sessions \ -u "sk_test_wU7nrJCZspk1NPDxiQgAF05q:" \ -d "line_items[0][price_data][currency]=brl" \ -d "line_items[0][price_data][product_data][name]=T-shirt" \ -d "line_items[0][price_data][unit_amount]=2000" \ -d "line_items[0][quantity]=1" \ -d mode=payment \ -d "payment_method_options[boleto][expires_after_days]=7" \ --data-urlencode "success_url=https://example.com/success"
Unlike card payments, the customer wont 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:
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 |
|---|---|---|
The customer has successfully submitted the Checkout form. Stripe has generated the Boleto voucher. You can choose to email the | 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. |
When testing your Checkout integration, select Boleto as the payment method and click the Pay button.
| Description | |
|---|---|
| Simulates a Boleto voucher which a customer pays after 3 minutes and the Example: fulaninho@example.com |
| Simulates a Boleto voucher which a customer pays immediately and the Example: succeed_immediately@example.com |
| Simulates a Boleto voucher which expires before a customer pays and the The Example: expire_immediately@example.com |
| Simulates a Boleto voucher which expires before a customer pays and the The Example: expire_with_delay@example.com |
| Simulates a Boleto voucher which never succeeds; it expires according to the Example: fill_never@example.com |
| Tax ID | Description |
|---|---|
CPF CNPJ | In a sandbox, set |
Boleto payments cant be refunded. Some merchants have created a separate process to credit their customers who reach out directly.
Boleto payments cant be disputed by the customer.
| Web Proxy Viewer | New URL | Original Page |