Accept a one-time payment
Learn how to accept a Pix one-time payment, a common payment method in Brazil.
Checkout
Elements
Direct API
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 for Pix one-time payments. Setup mode and recurring subscription plans are supported through Pix Automático .
Accept a payment
Note
Build an integration to accept a payment with Checkout before using this guide.
Enable Pix as a payment method
When creating a new Checkout Session, you need to:
- Enable Pix in your Dashboard. Stripe automatically displays Pix 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 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 example, if a customer completes the Checkout Session with expires_after_seconds set to 600 on Monday at 14:00, they have until Monday at 14:10 to transfer the funds and complete the payment.
You can set expires_after_seconds to a value between 10 seconds and 1209600 seconds (14 days). The default is 14400 seconds (4 hours).
Command Line
Select a language
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
Fulfill your orders
After accepting a payment, learn how to fulfill orders.
Test your integration
To test your integration:
- Select Pix.
- Enter the customer’s details and tap Pay . In a testing environment, use 000. 000. 000-00 as a test tax identifier (CPF or the related setting).
- 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.
| Description | |
|---|---|
{any_prefix}@{any_domain} | Simulates a Pix that a customer pays after 3 minutes. The payment_intent.succeeded webhook arrives after approximately 3 minutes. In production, this webhook arrives immediately after the Pix is paid. Stripe ignores the payment_method_options.pix.expires_at and payment_method_options.pix.expires_after_seconds parameters in this case. Example: `` |
{any_prefix}succeed_immediately@{any_domain} | Simulates a Pix that your customer pays immediately. The payment_intent.succeeded webhook arrives within several seconds. In production, this webhook arrives immediately after the Pix is paid. Stripe ignores the payment_method_options.pix.expires_at and payment_method_options.pix.expires_after_seconds parameters in this case. Example: `` |
{any_prefix}expire_immediately@{any_domain} | Simulates a Pix that expires before your customer pays. The payment_intent.payment_failed webhook arrives within several seconds. Stripe ignores the payment_method_options.pix.expires_at and payment_method_options.pix.expires_after_seconds parameters in this case. Example: `` |
{any_prefix}expire_with_delay@{any_domain} | Simulates a Pix that expires before your customer pays. The payment_intent.payment_failed webhook arrives after approximately 3 minutes. Stripe ignores the payment_method_options.pix.expires_at and payment_method_options.pix.expires_after_seconds parameters in this case. Example: `` |
{any_prefix}fill_never@{any_domain} | Simulates a Pix that never succeeds. It expires according to the payment_method_options.pix.expires_at or payment_method_options.pix.expires_after_seconds parameter. The payment_intent.payment_failed webhook arrives after the simulation completes. Example: `` |
Optional Refunds Server-side
See also
Expiration
Pix codes expire after the specified expires_at the related setting 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_after_seconds | The number of seconds before a pending Pix payment expires. Valid values are from 10 seconds to 259200 seconds (3 days) | 14400 seconds (4 hours) | No | 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. The start time isn’t when the PaymentIntent is created, but when it’s confirmed. |
expires_at | A Unix timestamp that shows when the pending Pix payment expires. Valid values are from 10 seconds to 3 days in the future | The default is 4 hours in the future | No | If you create a Pix on Monday at 14:00 and you set expires_at to 2 days in the future, the Pix expires on Wednesday at 14:00 |
expires_after_seconds and expires_at are mutually exclusive. An error occurs if both are set. Both are also optional, and if neither is set, the expiration defaults to 4 hours from when the PaymentIntent is confirmed.
Note
The value returned on expires_at from the next_action 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 customer’s 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 canceling the PaymentIntent associated with the Pix payment.