Pix payments

A Checkout Session must satisfy all of the following conditions to support Pix payments:

• Prices for all line items must be in the brl currency.
• You can only use one-time line items (recurring subscription plans aren’t supported).

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

Enable Pix as a payment method

When creating a new Checkout Session, you need to:

1. Add pix 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', 'pix'],
  line_items: [{
    price_data: {
      currency: 'usd',
      # To accept `pix`, 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 set the number of seconds before a pending Pix payment expires by specifying the optional expires_after_seconds parameter in the payment method options for your PaymentIntent. For example, if you confirm a Pix on Monday at 14:00 and you set expires_after_seconds to 600, the Pix expires on Monday at 14:10. You can set expires_after_seconds to a value between 10 seconds and 1209600 seconds (14 days). The default is 86400 seconds (1 day). After you create the PaymentIntent, confirm it to start the expiry timer.

Redirect to a Stripe-hosted instructions page

After submitting the Checkout form successfully, we redirect your customer to the hosted_instructions_url. Your customer scans the QR code or copies the Pix string from the Stripe-hosted instructions page.

We send a payment_intent.requires_action event when a Pix code is created successfully. Locate the hosted_instructions_url in payment_intent.next_action.pix_display_qr_code.hosted_instructions_url to email your customers the instructions link. Learn more about how to monitor a PaymentIntent with webhooks.

We allow customization of customer-facing UIs on the branding settings page. You can apply the following brand settings to the Stripe-hosted instructions page:

• Icon—your brand image and public business name
• Accent color—use as the color of the Copy Code button
• Brand color—use as the background color

Fulfill your orders

Because Pix 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.

We send the following events when the payment status changes:

To test your integration:

1. Select Pix.
2. Enter the buyer’s details and tap Pay. In a testing environment, you can use 000.000.000-00 as a test tax identifier (CPF or CNPJ).
3. Click Simulate scan to open a Stripe-hosted Pix test payment page. From this page, you can either authorize or expire the test payment.

In live mode, the Pay button displays a Pix QR code. You need a Brazilian bank account with Pix enabled to complete or cancel this payment flow.

You can also set payment_method.billing_details.email to the following values to test different scenarios.