Save payment details with Pix
Learn how to save Pix payment details and charge your customers later.
Save a customer’s Pix account for future payments. Saving Pix payment details for recurring use requires Pix Automático, which creates a customer-authorized mandate. Your recurring payments might fail if the mandate options are violated.
If you use Stripe Billing, you can set up a subscription with Pix instead.
Checkout
Direct API
This guide covers how to save Pix payment details using Checkout, Stripe’s fully hosted checkout page.
Set up Stripe Server-side
First, you need a Stripe account. Register now.
Use our official libraries for access to the Stripe API from your application:
Command Line
Select a language
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
# Available as a gem
sudo gem install stripe
Gemfile
Select a language
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
# If you use bundler, you can add this line to your Gemfile
gem 'stripe'
Create or retrieve a customer Server-side
To save a Pix payment method for future payments, you must attach it to an object that represents your customer. This can be either a customer-configured Account object or a Customer object.
Use the Accounts v2 API to represent customers
The Accounts v2 API is generally available for Connect users, and in public preview for other Stripe users. If you’re part of the Accounts v2 preview, you need to specify a preview version in your code.
To join the Accounts v2 preview, go to Account previews and features in your Dashboard and enable Reusable payment methods for Global Payouts.
For most use cases, we recommend modeling your customers as customer-configured Account objects instead of using Customer objects.
Create an object to represent your customer when they create an account with your business, or before you save a payment method for future payments. Associate this object’s ID with your own internal representation of the customer.
Create a new Customer or retrieve an existing Customer to associate with this payment. Include the following code on your server to create a new Customer.
Command Line
Select a language
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
Create a Checkout Session Server-side
Your customer must authorize a Pix Automático mandate for future payments through Stripe Checkout. This allows you to charge their Pix account on a recurring basis.
Add a checkout button to your website that calls a server-side endpoint to create a Checkout Session.
index.html
<html>
<head>
<title>Checkout</title>
</head>
<body>
<form action="/create-checkout-session" method="POST">
<button type="submit">Checkout</button>
</form>
</body>
</html>
Create a Checkout Session in setup mode to collect Pix payment details without charging the customer. After creating the Checkout Session, redirect your customer to the URL returned in the response.
Mandate options dictate how the payment method can be saved for future payments. Learn more about the available Pix Automático customization parameters.
Command Line
Select a language
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
After the customer completes the Checkout Session and authorizes the mandate in their banking app, the resulting SetupIntent has a status of succeeded and the PaymentMethod is attached to the Customer.
Charge the saved payment method Server-side
After collecting and saving payment details, create a PaymentIntent to charge the customer using the saved payment method.
Command Line
Select a language
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
Handle reusable payment method revocation Server-side
A customer can revoke a Pix mandate in their banking app. In this case, Stripe sends you a mandate.updated event. To handle this, subscribe to webhook events, and bring your customer back on-session to create a new mandate.
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}expire_immediately@{any_domain} | Simulates a Pix that expires immediately. The payment_intent.payment_failed or setup_intent.setup_failed webhook arrives within several seconds. No active mandate is created. Example: `` |
{any_prefix}expire_with_delay@{any_domain} | Simulates a Pix that expires after 3 minutes. The payment_intent.payment_failed or setup_intent.setup_failed webhook arrives after about 3 minutes. No active mandate is created. Example: `` |
{any_prefix}succeed_mandate_expire_payments_immediately@{any_domain} | Simulates a Pix that a customer pays immediately. The payment_intent.succeeded or setup_intent.succeeded webhook arrives within several seconds. An active mandate is created. Recurring payments with the same payment method expire immediately. The payment_intent.payment_failed webhook arrives within several seconds. Example: `` |
{any_prefix}succeed_mandate_expire_payments_with_delay@{any_domain} | Simulates a Pix that a customer pays after 3 minutes. The payment_intent.succeeded or setup_intent.succeeded webhook arrives within several seconds. An active mandate is created. Recurring payments with the same payment method expire after 3 minutes. The payment_intent.payment_failed webhook arrives after about 3 minutes. Example: `` |
{any_prefix}succeed_immediately@{any_domain} | Simulates a Pix that a customer pays immediately. The payment_intent.succeeded or setup_intent.succeeded webhook arrives within several seconds. An active mandate is created. Any recurring payments with the same payment method succeed immediately. The payment_intent.succeeded webhook arrives within several seconds. Example: `` |
{any_prefix}@{any_domain} | Simulates a Pix that a customer pays after 3 minutes. The payment_intent.succeeded or setup_intent.succeeded webhook arrives after approximately 3 minutes. An active mandate is created. Any recurring payments with the same payment method succeed after 3 minutes. The payment_intent.succeeded webhook arrives after approximately 3 minutes. Example: `` |