Create Pix Automático payment method through the Zuora API
Use this reference to create a Pix payment method in Zuora by using an existing EBANX enrollment token.
Call the Create a payment method operation with the Pix payment method type, the existing EBANX enrollment token, the customer information, and the EBANX gateway.
Use the accountKey field to associate the payment method with a customer account. To create an orphan payment method, omit accountKey. You can associate an orphan payment method with an account later by using the Update a payment method operation.
Example request
The following example shows the request structure. Replace the placeholder values with values from your tenant and your EBANX enrollment.
{
"accountKey": "402891a25a02e11c015a02f3c6100003",
"type": "Pix",
"identityNumber": "<cpf-or-cnpj>",
"accountHolderInfo": {
"accountHolderName": "<customer-name>",
"email": "<customer-email>",
"phone": "<customer-phone>"
},
"tokens": {
"tokenId": "<merchant-enrollment-code>"
},
"authGateway": "<ebanx-gateway-id>",
"currencyCode": "BRL",
"skipValidation": false
}The request must include the following information:
Before you create the payment method, ensure that the tenant properties required for Pix Automática are enabled. Contact Zuora Support to enable the required tenant properties.
| Field | Description |
|---|---|
type | Set to Pix. |
identityNumber | The customer's Brazilian tax identification number. Use CPF for an individual or CNPJ for a business. |
accountHolderInfo | The customer's full name and contact information. accountHolderName is required and must contain the customer's full name. Provide at least one contact method: an email address or phone number. |
tokens.tokenId | The EBANX merchant_enrollment_code returned after the external Pix Automático enrollment. |
authGateway | The ID of the EBANX gateway instance that processes the payment method. |
currencyCode | Set to BRL. |
skipValidation | Specifies whether Zuora validates the enrollment with EBANX before creating the payment method. The default value is false. |
Validate the enrollment during creation
By default, Zuora validates the existing enrollment with EBANX when you create the payment method. Zuora sends the enrollment code to EBANX and creates the payment method only when EBANX returns an accepted enrollment status.
If EBANX returns a pending, rejected, or expired status, Zuora does not create the payment method. Wait until the enrollment is accepted, and then submit the request again with the same enrollment code.
To use this behavior explicitly, set skipValidation to false in the request.
Create the payment method without validation
To store the payment method without a validation call to EBANX, set skipValidation to true. Use this option when you have already validated the enrollment in your own integration.
{
"accountKey": "402891a25a02e11c015a02f3c6100003",
"type": "Pix",
"identityNumber": "<cpf-or-cnpj>",
"accountHolderInfo": {
"accountHolderName": "<customer-name>",
"email": "<customer-email>"
},
"tokens": {
"tokenId": "<merchant-enrollment-code>"
},
"authGateway": "<ebanx-gateway-id>",
"currencyCode": "BRL",
"skipValidation": true
}skipValidation to true, ensure that the enrollment code is valid and that EBANX has accepted the enrollment. If the enrollment is invalid or later expires, recurring payments that use the payment method can fail.Response
When the request succeeds, Zuora returns the ID of the newly created payment method.
{
"id": "<payment-method-id>",
"success": true
}The payment method stores the EBANX enrollment code as its gateway token. You can retrieve the payment method by using the Retrieve a payment method operation and then use it for recurring billing.