Prerequisites

• An Ebanx gateway connection.
• Ability to work with APIs and render QR codes — Base64 encoding knowledge is required.
• BRL currency support on your site.

Limitations

• BRL is the only supported currency.
• One-time transactions and force collections are not supported — only subscription sign-ups and automatic renewals.
• Renewal date must remain fixed — Flexible schedules, net terms, and renewal date modifications are not supported. PIX requires the renewal date to stay consistent with the original sign-up, with no more than one successful transaction per billing period. Changing renewal dates without a new sign-up will cause renewals to fail.
• No manual or forced trial conversion — PIX requires a static start date for the first renewal based on plan data. Conversion attempts before this date will fail.
• Supported billing frequencies — PIX subscriptions must use one of: Weekly, Monthly, Quarterly, Half-yearly, or Yearly — or their equivalent day-based values (7 days, 30 days, every 4 weeks, every 3 months, every 180 days, etc.). Schedules outside this pattern return a validation error and the sign-up will fail.
• The following features are not supported: invoice/calendar aggregation, parent/child accounts, multiple subscriptions per account, proration during subscription upgrades or changes, and funds verification/wallet payment instrument visibility.
• 100% coupons during signup are not supported — e-mandate creation is required for this payment method. Use a free trial instead. Standard coupons are supported.

Definition

Key details

Supported features

• Subscription sign-ups — Customers authorize subscriptions via QR code. One-time transactions are not supported.
  • Journey 2 is supported for trial subscriptions.
  • Journey 3 is supported for subscriptions with an immediate payment amount due.
• Mobile and desktop support — Supports transaction flows on both mobile and desktop.
• Compliant retries — Retries occur automatically within the current billing period, per PIX requirements. See the Static Retries documentation for details. No additional configuration is required.

Customer bank interactions

Customers can cancel or modify their subscription from within their banking app:

• Pending payment cancellation — Customers have 2 full days before the official processing date to cancel a pending Pix transaction. When this occurs, Recurly consumes a webhook and marks the scheduled transaction as declined. You can then reach out to the customer about payment options, cancel the subscription, or allow dunning to expire it.
• Enrollment revocation — Customers can cancel their entire subscription by revoking the enrollment in their banking app. This immediately cancels the active subscription in Recurly.

Merchant-initiated actions: When you expire a subscription manually or through dunning, Recurly sends a revocation request to the gateway to expire the mandate in the customer's banking app.

Required fields

Always send the following customer data with Pix Automático transactions:

• Customer name and billing address
• Customer email address
• Customer phone number
• Tax ID and Tax ID type (required for Brazil)

Retries and dunning

Pix Automático requires all retries to occur within the current billing period. For example, on a weekly subscription, the initial renewal attempt and all retries must occur within 7 days. It's important to set your dunning window to match the billing period to avoid dunning extending beyond the window where retries can occur.

Pix Automático retries are asynchronous and remain in a Scheduled state until Recurly receives an update from the gateway.

• Up to 3 retries are available per billing period.
• If all 3 retries fail after the initial renewal attempt, your configured dunning settings for the invoice/subscription apply.

FAQs