Set up a subscription with Pix
Learn how to create and charge for a subscription with Pix.
Use this guide to set up a subscription using Pix as a payment method. Pix subscriptions use Pix Automático to create a customer-authorized mandate for automatic recurring charges.
You can use the Checkout API to create and confirm a subscription with a prebuilt checkout page.
Create a product and price Dashboard
Products represent the item or service you’re selling. Prices define how much and how frequently you charge for a product. This includes how much the product costs, what currency you accept, and whether it’s a one-time or recurring charge. If you only have a few products and prices, create and manage them in the Dashboard.
This guide uses a stock photo service as an example and charges customers a 20 BRL monthly subscription. To model this:
- Go to the Products page and click Create product .
- Enter a Name for the product. You can optionally add a Description and upload an image of the product.
- Select a Product tax code . Learn more about product tax codes .
- Select Recurring . Then enter 20 for the price and select BRL as the currency.
- Choose whether to Include tax in price . You can either use the default value from your tax settings or set the value manually. In this example, select Auto .
- Select Monthly for the Billing period .
- Click More pricing options . Then select Flat rate as the pricing model for this example. Learn more about flat rate and other pricing models .
- Add an internal Price description and Lookup key to organize, query, and update specific prices in the future.
- Click Next . Then click Add product .
After you create the product and the price, record the price ID so you can use it in subsequent steps. The pricing page displays the ID and it looks similar to this: price_G0FvDp6vZvdwRZ.
Create a Checkout Session Server-side
Your customer must authorize a Pix Automático mandate for the subscription through Stripe Checkout.
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 subscription mode with Pix Automático mandate options. After creating the Checkout Session, redirect your customer to the URL returned in the response.
Note
If you want to encourage users to upgrade to a higher subscription plan without coming back on session, you can pass a higher amount in payment_method_options.pix.mandate_options.amount.
Command Line
Select a language
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
After the customer authorizes the mandate in their banking app, the subscription activates and subsequent invoices charge automatically.
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: `` |