Set up your client for Pix Automática integration for EBANX

Learn how to configure your client for PIX Automático integration with EBANX, including setting up Payment Pages 2.0 parameters and PIX mandate options.

Set up your client

Follow the instructions in Integrate Payment Pages 2.0 to integrate Payment Pages 2.0. When rendering the PIX Payment Page 2.0 form, pass the parameters in the Z.render or Z.renderWithErrorHandler function as described in this section.

Overview

To support PIX Automático enrollment and recurring payments through EBANX, use a PIX type of Payment Page 2.0 and configure your client as follows:

Use doPayment and storePaymentMethod together to select the appropriate flow:
- storePaymentMethod = "true" and doPayment = "false": PIX Automático mandate enrollment only (no initial payment).
- storePaymentMethod = "true" and doPayment = "true": PIX Automático enrollment with a one-time PIX payment.
- storePaymentMethod = "false": one-time PIX payment without creating a PIX Automático mandate.
Always set the PIX gateway currency to BRL and use a customer account configured for BRL.
Provide PIX Automático mandate configuration through gateway options so that EBANX can create and manage the recurring mandate.

Required parameters

The following table lists the required client-side parameters for implementing PIX Automático flows through EBANX.

Required parameter	Description
`doPayment`	Type: boolean Controls whether the Payment Page processes a one-time PIX payment in addition to enrollment. `"true"`: The Payment Page creates a PIX Automático payment method and processes a one-time PIX payment through EBANX. `"false"`: The Payment Page only performs PIX Automático enrollment and stores the payment method for future recurring payments.
`storePaymentMethod`	Type: boolean Controls whether the PIX payment method (PIX Automático enrollment) is stored in Zuora. `"true"`: Zuora stores the PIX Automático payment method and mandate information for subsequent recurring payments. `"false"`: Zuora processes a one-time PIX payment only; no PIX Automático payment method is stored.
`field_accountId`	Type: string Example: `8a90e5e48f2eade6018f2ed19133003a` Specifies the Zuora customer account ID. The PIX Automático payment method and payments are associated with this account. The account must use the `BRL` currency.
`authorizationAmount`	Required for enrollment with initial payment; not required for enrollment-only flows. For flows where `doPayment = "true"`, this is the BRL amount of the one-time PIX payment that Zuora sends to EBANX. For enrollment-only flows (`doPayment = "false"`), set `authorizationAmount` to `"0"` or omit it from the request.
`field_currency`	Type: string Value: `"BRL"` The currency of the one-time payment amount. PIX Automático on EBANX only supports BRL.
`documents`	Required when you want to associate specific invoices with the PIX Automático payment. An array of invoice objects to be paid in this transaction. Each object supports the following fields: `type` – Must be `"invoice"`. `ref` – Invoice number, for example `"INV0000001"`.
`gwOptions_PixMandateSubscriptionName`	Type: string Descriptor of the subscription or service that will be displayed in the customer’s banking application during PIX Automático mandate enrollment.
`gwOptions_PixMandateFrequency`	Type: string The billing cycle of the PIX Automático enrollment. Supported values include: `"weekly"`, `"monthly"`, `"quarterly"`, `"halfyearly"`, `"yearly"`
`gwOptions_PixMandateStartDate`	Type: date (YYYY-MM-DD) The date when the PIX Automático subscription becomes active. EBANX uses this value when evaluating the mandate schedule.
`gwOptions_PixMandateExpirationDate`	Type: date (YYYY-MM-DD). Optional. The mandate expiration date for PIX Automático. If omitted, EBANX uses its default expiration behavior.
`gwOptions_PixMandateMaxAmountFloor`	Type: number. Optional. Minimum allowed maximum amount that the customer can configure for variable recurring payments in their banking app. EBANX enforces this when the PIX Automático mandate supports variable amounts.
`gwOptions_shopperEmail`	Optional for account-based payment methods; required for orphan PIX Automático payment methods created without a customer account. Controls the email address that Zuora sends to EBANX for enrollment and notification. If not provided, Zuora derives the email from the account specified by `field_accountId` using the following priority: BillTo work email BillTo personal email SoldTo work email SoldTo personal email

Example: PIX Automático enrollment with one-time payment

The following example shows a params object passed to Z.render for a PIX Payment Page 2.0. This configuration creates a PIX Automático mandate, stores the payment method, and processes an initial one-time payment in BRL.


var params = {
  "doPayment": "true",
  "storePaymentMethod": "true",
  "field_accountId": "8a90e5e48f2eade6018f2ed19133003a",
  "authorizationAmount": "150.00",
  "field_currency": "BRL",
  "documents": "[{\"type\":\"invoice\",\"ref\":\"INV00026338\"}]",
  "gwOptions_PixMandateSubscriptionName": "Premium Subscription BR",
  "gwOptions_PixMandateFrequency": "monthly",
  "gwOptions_PixMandateStartDate": "2026-03-01",
  "gwOptions_PixMandateExpirationDate": "2031-03-01",
  "gwOptions_PixMandateMaxAmountFloor": "300.00",
  "gwOptions_shopperEmail": "subscriber@example.com"
};

Welcome to Zuora Product Documentation

Explore our rich library of product information

Set up your client for Pix Automática integration for EBANX