Pix Automática for EBANX Payment gateway integration
Integrate Pix Automática with the EBANX payment gateway to enable automatic recurring payments using Brazil's instant payment system, Pix.
Pix Automática (Pix Automatic) is a recurring payment solution built on Brazil's instant payment system, Pix. It enables merchants to collect recurring payments automatically after the customer grants authorization through a one-time enrollment process.
Prerequisites
Before integrating Pix Automática, make sure the following requirements are met in your Zuora tenant.
-
You must configure the EBANX payment gateway to support Pix Automática transactions.
-
Pix Automática relies on Hosted Pages for customer enrollment and authentication. You must create Hosted Pages enabled with 3DS2 support. For more detailed information, see Hosted payment page approach.
For Pix recurring mandates, you must send the recurring payment request between 2 and 10 days before the next billing date.
For example, if a payment is due on December 30, the payment request must be sent no earlier than December 20 and no later than December 28.
This configuration is required in Zuora. Contact your Technical Account Manager (TAM) to have this setting enabled. If this configuration is not in place, Zuora will not send the payment request to customers.
Supported and unsupported features
The following table lists the supported and unsupported operations and features for PIX Automático on the EBANX integration.
| Supported | Unsupported |
|---|---|
| Recurring payment processing with PIX Automático mandates | One-time Pix payments without creating a PIX Automático mandate |
| Payment method creation with initial enrollment via hosted payment pages | Creating a PIX Automático payment method directly from the Zuora UI without hosted pages |
| Using a stored Pix mandate token for subsequent recurring debits | Changing Pix mandate amount limits after enrollment (requires a new enrollment) |
| Referenced refunds through standard Zuora refund APIs | Non-referenced refunds for Pix Automático payments |
| Real-Time Reconciliation (RTR) updates for Pix recurring payments | Manual reconciliation of Pix Automático transactions without RTR |
Orphan Payment Methods - use | Orphan payment method without a valid email |
Recurring Payments Flow
After a PIX Automático mandate is successfully enrolled, Zuora processes recurring payments using the stored mandate token.
Invoice Generation and Payment Selection
When a billing run posts an invoice with an outstanding balance in BRL, and the account is configured with a Pix payment method enrolled for PIX Automático on an EBANX v1 gateway, Zuora selects this payment method for automatic collection.
Recurring Debit Request
Zuora sends a recurring Pix debit request to EBANX, referencing the stored merchant_enrollment_code, customer details, amount, and due date.
EBANX initiates the Pix transfer through the customer's bank and applies the configured retry policy for failed attempts.
Real-Time Reconciliation and Status Updates
EBANX returns an initial response and updates payment status over time. Zuora retrieves final status information through RTR and maps EBANX statuses to Zuora payment states:
CO (Confirmed) → Approved payment in Zuora
PE (Pending / Expired) → Pending or error state depending on timing and retry outcome
CA / OP (Cancelled / Open) → Failed payment in Zuora
Retries and Failure Handling
EBANX automatically retries failed Pix debits according to the configured retry policy (for example, 3 retries over 7 days). If all retries fail, the payment remains cancelled and no further attempts are made.
If a customer revokes the mandate in their banking app, subsequent payments fail. You should remove the Pix payment method in Zuora and prompt the customer to re-enroll.
Stored token information
After a successful PIX Automático enrollment:
Zuora creates a Pix payment method for the customer account.
The
merchant_enrollment_codereturned by EBANX is stored as the token on the payment method and is used for all subsequent recurring debits.This tokenized approach allows Zuora to initiate recurring Pix debits without storing raw banking credentials or Pix identifiers.
You can retrieve PIX Automático payment methods and their tokens from the Electronic Payment Methods section of the customer account or by using Zuora's REST APIs, similar to other tokenized payment methods.