Boleto payments

A Checkout Session must satisfy all of the following conditions 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.
• You can only use one-time line items (recurring subscription plans are not supported).

Use this guide to learn how to enable Boleto—it shows the differences between accepting a card payment and using Boleto.

Enable Boleto as a payment method

When creating a new Checkout Session, you need to:

1. Add boleto to the list of payment_method_types
2. Make sure all your line_items use the brl currency.

Stripe::Checkout::Session.create({
  mode: 'payment',
  payment_method_types: ['card'],
  payment_method_types: ['card', 'boleto'],
  # The parameter is optional. The default value of expires_after_days is 3.
  payment_method_options: {
    boleto: {
      expires_after_days: 7
    }
  },
  line_items: [{
    price_data: {
      # To accept `boleto`, all line items must have currency: brl
      currency: 'brl',
      product_data: {
        name: 'T-shirt',
      },
      unit_amount: 2000,
    },
    quantity: 1,
  }],
  success_url: 'https://example.com/success',
  cancel_url: 'https://example.com/cancel',
})

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

Redirect to Stripe hosted voucher page

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:

When testing your Checkout integration, select Boleto as the payment method and click the Pay button.

Boleto payments can’t be refunded. Some merchants have created a separate process to credit their customers who reach out directly.

Boleto payments can’t be disputed by the customer.