Pix Automático Sandbox Simulator

Overview

This section provides information on how to use pix-automatico payment type and simulate specific scenarios on sandbox environment.

By following this basic integration guide, you will understand how you can create enrollments and accept Pix Automático recurring payments in your check-out, by using EBANX Sandbox and simulating how this payment method will work when launched in June/2025.

Availability

Pix Automático integration through Direct API will be available in Brazil only.

What you will need

A Sandbox Account

As with any secure payment integration, you will first need to set up authorization. The EBANX sandbox allows you to set up a test environment to run transactions using test credit card numbers and explore our payment solutions.

Sign up for a Sandbox Account at our EBANX Business Page, select your business model and answer a few questions. We'll get in touch with you shortly after!

Sign up for an EBANX Sandbox Account here

How it works

To complete a Pix Automático enrollment and recurring payments, please follow the steps below.

1. Enable Pix Automático in your dashboard

   The first step is to check if Pix Automático is active in your EBANX Dashboard.

   All set? We can go ahead to next step, otherwise, please get in touch with our integration specialists.

2. Call the ws/userenrollment API to get the Enrollment QR Code

   As detailed in the Variable Enrollments and Fixed Enrollments sections, you can create a new enrollment by calling the ws/userenrollment API, or the ws/direct API if the enrollment is accompanied by an instant payment.

   In all these cases, the Sandbox environment will return a redirect_url containing a link to our Simulator. By accessing this link, you will be directed to a screen where you can simulate the user’s enrollment acceptance or expiration.

3. Simulate Enrollment Status on Sandbox

   Access the link returned in the redirect_url to view the enrollment simulator screen. In the subscription info section, you can either accept or expire an enrollment by clicking the respective buttons to simulate user actions and update the enrollment status.

   Alternatively, you can force an enrollment status update by calling the ws/simulator/userenrollment API, with the following parameters:

   Parameter	Requirement	Description
   integration_key	Required	Your integration key
   merchant_enrollment_code	Required	The unique enrollment identification
   payment_type_code	Required	Must be pix-automatico
   simulate_action	Required	Define on this field, the desired outcome for the enrollment: confirm, reject, expire or revoke

   Request example:

   {

   "integration_key": "<your-integration-key>",

   "merchant_enrollment_code": "<enrollment-identifier>",

   "payment_type_code": "pix-automatico",

   "simulate_action": "<action>"

   }

   A successful request will return a JSON response like the one below, confirming your action request.

   {

   "status": "SUCCESS",

   "entity": "enrollment",

   "operation": "<action>"

   }

4. Send a payment request to an active Enrollment

   When the enrollment status is accepted, you are able to create recurring payments by calling ws/direct API and referencing its merchant_enrollment_code.

   Pix automático recurring payments operate using a scheduling concept. You must schedule the payments 2 to 10 days before the expected billing date. The following fields are required:

   Parameter	Requirement	Description
   operation	Required	Must be request
   merchant_payment_code	Required	Unique merchant payment code
   amount_total	Required	Total amount to be charged. Note that the amount must match the one set in the enrollment
   currency_code	Required	Must be BRL
   country	Required	Must be BR
   payment_type_code	Required	Must be pix-automatico
   email	Required	Customer e-mail
   name	Required	Customer name
   document	Required	Customer document
   due_date	Required	Expected billing date (DD/MM/YYYY) - it must be between 2 and 10 days after the current date
   merchant_enrollment_code	Required	The enrollment code generated in the previous steps. The enrollment must have a accepted status to be used in recurring payments

   Check the example:

   curl -X POST 'https://sandbox.ebanxpay.com/ws/direct' \

   --data '{

   "integration_key": "{{integration_key}}",

   "operation": "request",

   "payment": {

   "merchant_payment_code": {{merchant_payment_code}},

   "amount_total": 19.90,

   "currency_code": "BRL",

   "country": "BR",

   "payment_type_code": "pix-automatico",

   "email": "{{customer_email}}",

   "name": "{{customer_name}}",

   "document": "{{customer_document}}",

   "due_date": "17/01/2024",

   "enrollment": {

   "merchant_enrollment_code": "{{merchant_enrollment_code}}"

   }

   }

   }'

   A successful request will return a JSON response like the one below. The Pix Automático payment will have a pending (PE) status and will be confirmed later, by the customer's bank.

   {

   "payment": {

   "hash": "{{unique_payment_hash}}",

   "country": "BR",

   "merchant_payment_code": "{{unique_payment_code}}",

   "merchant_enrollment_code": "{{unique_enrollment_code}}",

   "status": "PE",

   "status_date": null,

   "open_date": "2024-01-10 13:00:00",

   "confirm_date": null,

   "transfer_date": null,

   "amount_br": "19.90",

   "amount_ext": "19.90",

   "amount_iof": "0.00",

   "currency_rate": "1.0000",

   "currency_ext": "BRL",

   "due_date": "2024-01-17",

   "payment_type_code": "pix-automatico",

   "pre_approved": false

   },

   "status": "SUCCESS",

   "redirect_url": "https://sandbox.ebanx.com/ws/redirect/execute?hash=6762e422391626568b710810924fdaea7401f4f5bb4881"

   }

   On the due_date set, the payment will be processed and confirmed, and the status will be changed to CO(confirmed).

   In case it fails, and you set the enrollment to allow payment retries, the status will remain PE (pending) for 7 days - within these days you can submit up to 3 retries with maximum one per day.

   After the seven days and no successful payment retry, the payment will be automatically cancelled and its status will be CA (canceleld).

5. Simulate payment status change

   To simulate a Pix payment confirmation, cancellation, or keep it as pending in our sandbox environment, access the link returned on redirect_url on the response of your payment request.

   Or use the URL https://sandbox.ebanx.com/ws/simulator/confirm?hash=paymentHash, replacing "paymentHash" with the actual hash generated during your test transaction.

   Following this link, you will be on the simulation page, in which you can choose from the following options:

   • Confirm the payment
   • Cancel the payment
   • Keep the payment in a pending state

note

Pix Automático goes live on June 16th 2025. Stay tuned for Sandbox Environment availability on December 1st 2024!

Still need help?

We hope this article was helpful. If you still have questions, you can explore the following options:

• Customer support: Contact our support team at integration@ebanx.com for assistance.
• Not a partner yet? Please complete the Merchant Signup Form, and our commercial team will reach out to you.