Pix payments
Learn how to accept Pix, a common payment method in Brazil.
Stripe users can accept Pix payments from customers in Brazil. Customers pay by copying and pasting a Pix string or scanning a QR code directly in their bank apps.
Determine compatibility
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).
Accept a payment
Note
Build an integration to accept a payment with Checkout before using this guide.
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:
- Add
pix
to the list ofpayment_
.method_ types - Make sure all your
line_
use theitems brl
currency.
Additional payment method options
You can set the number of seconds before a pending Pix payment expires by specifying the optional expires_
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_
to 600, the Pix expires on Monday at 14:10. You can set expires_
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
Note
Unlike card payments, we don’t redirect your customer to the success_url with Pix payments.
After submitting the Checkout form successfully, we redirect your customer to the hosted_
. 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_
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:
Event Name | Description | Next steps |
---|---|---|
Your customer successfully submits the Checkout form and Stripe generates the Pix code. You can choose to email the | Wait for your customer to pay the Pix. | |
checkout.session.async_payment_succeeded | Your customer successfully paid the Pix. The PaymentIntent transitions to succeeded . | Fulfill the goods or services that your customer purchased. |
checkout.session.async_payment_failed | The Pix code is expired, or the payment has failed for some other reason. The PaymentIntent returns to a status of requires_ . | Send your customer an email and request that they place a new order. |
Test the integration
When testing your Checkout integration, select Pix as the payment method, then click the Pay button. In a testing environment, click the Simulate scan button to open a Stripe-hosted Pix test payment page. From this page, you can either authorize or expire the test payment.
Expiration
Pix codes expire after the specified expires_
UNIX timestamp. After the Pix expires, confirm the PaymentIntent with another payment method or cancel it. Set expiration parameters in the payment method options under the pix
key.
A customer can’t pay a Pix after it expires.
Field | Value | Default value | Required | Example |
---|---|---|---|---|
expires_ | The number of seconds before a pending Pix payment expires. Valid values are from 10 seconds to 1209600 seconds (14 days) | 86400 seconds (1 day) | No | If you confirm a Pix on Monday at 14:00 and you set expires_ to 600, the Pix expires on Monday at 14:10. Note that the start time isn’t when the PaymentIntent is created, but when it is confirmed. |
expires_ | A Unix timestamp that shows when the pending Pix payment expires. Valid values are from 10 seconds to 14 days in the future | The default is 1 day in the future | No | If you create a Pix on Monday at 14:00 and you set expires_ to 2 days in the future, the Pix expires on Wednesday at 14:00 |
expires_
and expires_
are mutually exclusive. An error occurs if both are set. Both are also optional, and if neither is set, the expiration defaults to 1 day from when the PaymentIntent
is confirmed.
Note
The value returned on expires_
from the next_
response is the same as the input set on payment_method_options.expires_at. Although, in real scenarios, the actual expiration timestamp might differ. This doesn’t impact your customers experience paying with Pix, but it’s recommended to rely on the payment_intent.payment_failed event to consider if the payment intent has expired.
Cancellation
You can cancel Pix payments before they expire by cancelling the PaymentIntent associated with the Pix payment.