Skip to main content
Pix is a real-time payment method in Brazil that lets customers pay by scanning a QR code or copying a Pix string in their banking app. In PayNext, Pix is available through Stripe. The integration also supports recurring Pix flows (Pix Automático).

​
Payment Method Details

​
Prerequisites

  1. Connect and activate the Stripe integration in PayNext
  2. Enable Pix in your Stripe Dashboard under Settings → Payment methods
  3. Make sure Pix is enabled for your Stripe account and environment
  4. Turn on Pix in your PayNext checkout configuration
Pix is available only for BRL payments for customers in Brazil.

​
How it works

Pix in PayNext is offered through Pix Automático, a mandate-based flow built for subscriptions. Every Pix payment authorizes a mandate — the customer’s authorization for future automatic charges. The mandate defines the allowed charge frequency and a maximum amount, and the customer approves it once during checkout by scanning a QR code or copying the Pix string in their banking app.

​
Initial payment (Pix Automático)

When the subscription has an initial charge (for example a paid trial or a first payment), the customer’s approval does both things at once — it pays the initial amount and authorizes the recurring mandate in a single step. There is no separate “set up now, pay later” step.

​
Recurring charges

After the mandate is active, recurring charges are taken automatically according to the subscription’s billing cycle. Important notes for recurring Pix:
  • the subscription billing cycle must match the mandate’s allowed frequency
  • only one Pix charge can be taken per billing cycle
  • supported recurring cadences are weekly, monthly, quarterly, halfyearly, and yearly
  • daily billing is not supported

​
Settlement and timing

Pix runs on Brazil’s instant account-to-account rails, so there is no card-style authorization or manual capture step. In the PayNext payment status flow, a Pix payment never enters AUTHORIZED. It stays PENDING while waiting for the customer’s approval in the banking app, moves to SETTLING once the charge is processing, and becomes SETTLED when Stripe confirms success. A failed charge ends as DECLINED or FAILED, and an abandoned approval leaves the payment INCOMPLETE.
  • Initial payment: the payment remains pending until the customer approves it in their banking app, then settles. This usually happens within minutes. You receive the final status through a Stripe webhook in PayNext.
  • Recurring charges: Pix requires advance notice to the payer before an automatic debit, so recurring charges are initiated ahead of the billing date. Allow a short window (up to a few days) for a recurring charge to complete and settle.
A successful authorization or approval is not the same as settlement. Treat a Pix payment as complete only once it reaches the succeeded status via webhook.

​
If the customer doesn’t complete payment

  • Authentication not completed: if the customer closes or cancels the banking-app step, the payment is marked incomplete. No charge is taken, no mandate is created, and no subscription is started. The customer can retry within the same checkout session.
  • Mandate cancelled by the customer: once a mandate is revoked, no further recurring charges can be taken against it. Upcoming recurring charges will fail, and the subscription follows your normal retry and cancellation handling.
Grant product access based on a successful payment status, not on checkout approval alone.

​
IOF handling

For international businesses, Stripe applies Brazilian consumer tax (IOF) handling for Pix. Default behavior:
  • amount_includes_iof = never
  • the customer pays the IOF
  • the amount shown in the customer’s banking app is marked up to include IOF
Alternative behavior:
  • amount_includes_iof = always
  • the merchant absorbs the IOF
  • Stripe deducts the IOF from settlement
If you use a direct API integration, show the appropriate customer disclosure based on the selected IOF behavior.

​
Testing

1

Configure Stripe credentials

Use the correct Stripe environment in your PayNext integration and make sure Pix is enabled for that account.
2

Create a Pix payment

Start a Pix payment via PayNext checkout using BRL for a customer in Brazil.
3

Complete customer approval

Approve the payment by scanning the QR code or using the Pix string in the banking app. For a subscription with an initial charge, this single approval both pays the initial amount and authorizes the recurring mandate.
4

Verify the payment

Confirm the payment appears in the PayNext dashboard and that the final succeeded status is received via Stripe webhook.
5

Check the incomplete path

Start another payment and cancel at the banking-app step. Confirm the payment is marked incomplete, no subscription is created, and the same checkout session can be retried.
6

Verify recurring behavior

For recurring Pix, confirm the next charge is scheduled according to the subscription’s billing cycle and the mandate.

​
Refunds

Pix payments can be refunded after a successful payment. Refund handling follows Stripe processing and webhook updates in PayNext.

​
Notes

  • Pix does not support manual capture.
  • For recurring Pix, the mandate must stay aligned with the subscription billing cycle.
  • Recurring charges are initiated ahead of the billing date due to Pix advance-notice requirements.

​
If the customer revokes the mandate

A customer can cancel the Pix Automático mandate in their banking app. PayNext receives that from Stripe and sets the payment method status to revoked. A revoked payment method can’t be charged. Renewals stop being attempted—the aborted attempt is recorded as INCOMPLETE with decline_code payment_method_disabled—and the subscription stays past_due for 14 days before it is cancelled with reason dead_instrument. See Dead payment methods. Each change is reported by customer.payment_method.updated.