Recurring payments with Pix

We are working on adding subscription payments to our Pix offering, also known as Pix Automático. This page explains how the integration will look like.

The integration lets you accept flexible recurring payments, allowing you to choose from various billing cycles, and fixed or variable recurring amounts. It also allows you to retry failed subscription payments.

Requirements

Before you begin, take into account the following requirements, limitations, and preparations.

Authorization flows for subscription payments

You can offer two types of recurring payment flows:

• Authorization with QR code: Set up a subscription payment to bill shoppers regularly, where an initial payment is not required. This flow is ideal for setting up trial subscriptions. The Brazilian Central Bank refers to this flow as Journey 2.
• Authorization and payment with QR code: Set up a subscription payment to bill shoppers regularly, and charge them. This flow is ideal for subscriptions that require an initial payment to start, or when combining a one-off purchase with signing up to a subscription service. The Brazilian Central Bank refers to this flow as Journey 3.

How it works

The recurring payment flow with Pix works as follows:

1. You make a /payments request to:
   • Specify the frequency, amount, and other details for a subscription.
   • If you are using the Authorization and payment (Journey 3) flow, make an initial payment for the subscription, or for a one-off purchase.
2. You show a QR code or QR code data for the shopper to copy, using the action object you receive in the /payments response.
3. After the shopper confirms their subscription, you get the confirmation that the token is created in a Recurring tokens lifecycle events webhook.
   • If you are using the Authorization and payment (Journey 3) flow, you also get an AUTHORISATION webhook that informs you of the outcome of the immediate transaction.
4. Before the expected billing date, you make a /payments request to charge the shopper for the subscription.
5. On the billing date, you get a CAPTURE webhook that informs you of the payment result.

If a subscription payment fails, you can retry the payment up to three times.

Create a token with a billing plan

To set up a billing plan for a shopper, you need to store their payment details and specify the details of the subscription. If you are using the Authorization and payment flow, you make one request that combines the one-off payment and the billing plan setup.

1. Make a POST /payments request. In your request, include:

   • Standard tokenization parameters:

     Parameters	Required	Description
     paymentMethod.type		pix
     shopperReference		Your unique identifier for the shopper. Minimum length: three characters. This field is case-sensitive. Do not include personally identifiable information (PII), such as name or email address.
     shopperInteraction		Set to Ecommerce.
     recurringProcessingModel		Set to Subscription.
     storePaymentMethod		Set to true to store the shopper's payment details for future recurring payments.
     amount		The currency and value of the payment, in minor units. Set the amount.value field depending on your authorization flow: Authorization with QR code (Journey 2): Set to 0 to validate the payment details with a zero-auth transaction before processing payments. Authorization and payment with QR code (Journey 3): Set to the payment amount for the immediate payment.

   • Pix-specific parameters:

     Parameters	Required	Description
     shopperName		The first and last name of the shopper.
     socialSecurityNumber		The shopper's CPF or CNPJ number. This will be shown to the shopper on the Pix payment form.
     paymentMethod.pixRecurring.frequency		The frequency at which the shopper will be charged. Possible values: weekly, monthly, quarterly, half-yearly, and yearly.
     paymentMethod.pixRecurring.recurringStatement		The text that that will be shown on the shopper's bank statement for the recurring payments. We recommend to add a descriptive text about the subscription to let your shoppers recognize your recurring payments. Maximum length: 35 characters.
     paymentMethod.pixRecurring.minAmount		For a billing plan where the payment amounts are variable, the currency and value of the minimum amount to charge the shopper for each recurring payment, in minor units. When a shopper approves the billing plan, they can also specify a maximum amount in their banking app.
     paymentMethod.pixRecurring.recurringAmount		For a billing plan where the payment amount is fixed, the currency and value for each recurring payment, in minor units.
     paymentMethod.pixRecurring.startsAt		Start date of the billing plan, in YYYY-MM-DD format. The default value is the transaction date.
     paymentMethod.pixRecurring.endsAt		End date of the billing plan, in YYYY-MM-DD format. The end date must align with the frequency and the start date of the billing plan. If left blank, the subscription will continue indefinitely unless it is cancelled by the shopper.
     paymentMethod.pixRecurring.retryPolicy		When set to true, you can retry for failed recurring payments. The default value is true.

   The response contains the following data:

   • resultCode : informs you about the status of subscription setup and the payment.
   • action: contains the qrCodeData.

2. From the response, use the action field that contains the qrCodeData to render the QR code or present the QR code data.

3. Wait for the following webhooks to get:

   • The outcome of your request.
   • The storedPaymentMethodId that you need to include in subsequent recurring payment requests.

   Webhook	Description
   AUTHORISATION	Informs you whether the amount for the immediate payment is authorized.
   Recurring tokens life cycle events	Contains type: recurring.token.created, and the storedPaymentMethodId.

Make recurring payments

Make a request for the recurring payment within a period of ten to two days before the billing date. This is called the schedule window. For example, if the expected billing date is August 12, 2025, you can make the request between August 02 and August 10 to schedule the payment.

1. Make a POST /payments request, including:

   Field	Required	Description
   paymentMethod.type		pix
   paymentMethod.storedPaymentMethodId		The token for the shopper's stored payment details. This is the storedPaymentMethodId from the Recurring token life cycle events webhook with type: recurring.token.created.
   amount		The currency and value of the recurring payment, in minor units. If you included the recurringAmount field when you created the billing plan, the amount must match the one in your initial request to create the token. If you included the minAmount field when you created the billing plan, you can set a new amount.
   shopperReference		Your unique identifier for the shopper. Must be the same one you included with the request to create the token with a billing plan.
   shopperInteraction		Set to ContAuth.
   recurringProcessingModel		Set to Subscription.
   paymentMethod.pixRecurring.billingDate		The date on which the shopper's payment method will be charged, in YYYY-MM-DD format.
   paymentMethod.pixRecurring.businessDayOnly		When set to true, if the billingDate is not a business day, the payment will be processed on the next business day. The default value is false.

   After you make the request to schedule the payment, the response contains:

   • resultCode : Pending.

2. When the payment scheduling is confirmed, you receive an AUTHORISATION webhook. If you receive:

   • success: true, the payment is successfully scheduled, and the shopper will be charged for the subscription on the billing date you specified.
   • success: false, the payment was not successfully scheduled. This can happen when:
     • The amount in the request does not match the amount you specified when you created the billing plan.
     • A payment was already scheduled for this billing cycle.
     • The request to schedule was not sent during the schedule window.
     • The details in your request to schedule does not match a successfully created billing plan.

3. After the billing date you specified in the /payments request, wait for the CAPTURE webhook to learn about the outcome of the subscription transaction. If you receive:

   • success: true, the shopper was successfully charged for the subscription.
   • success: false, the subscription payment failed. Save the pspReference from this webhook to retry the payment.

Retry a recurring payment

If the CAPTURE webhook you received after the billing date contains success: false, you can retry the payment up to three times. You can only retry recurring payments if the paymentMethod.pixRecurring.retryPolicy was enabled in your request to create the billing plan.

To retry a recurring payment, copy your failed recurring payment request, including:

• The same fields you used in your first recurring payment request. Make sure that the amount in your retry request is the same as the amount from the failed recurring payment request.
• A new paymentMethod.pixRecurring.billingDate:
  • Must be at least 24 hours later than when you are making the request.
  • Must be within seven days from the billing date of the failed recurring payment.
• paymentMethod.pixRecurring.originalPspReference: The pspReference for the failed recurring payment. Find this in AUTHORISATION webhook you received after the billing date.

Cancel a billing plan

If your shopper wants to end their billing plan, you need to cancel the billing plan generated for their stored payment details on your side.

Delete the token with a DELETE /storedPaymentMethods/{storedPaymentMethodId} request.

Shoppers can also request to cancel the billing plan from their bank. In these cases, Adyen deletes the token on your behalf. It is still your responsibility to make sure any remaining shopper details are deleted from your servers, after payment details stored with Adyen are deleted.

When a token is deleted, you receive a recurring.token.disabled webhook.

Refund or cancel a recurring payment

You can refund a recurring payment within 90 days after the payment in the Customer Area or with an API request.

You can only refund a payment after it is captured. If you have already scheduled a payment, but the payment is not captured yet, you can cancel the payment.

To make things easier for you and allow more flexibility in the way you manage cancels and refunds, we recommend to use the reversal flow.

See also

• Pix API only
• Tokenization