Pix Automático Sandbox Simulator

This section provides information on how to use pix-automatico payment type and simulate specific scenarios in the 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.

Requirements

API credentials - Ensure you have your EBANX integration key. If not, complete the Merchant Signup Form.

Instructions

Follow the steps below.

Get enrollment QR code
As detailed in the Variable Enrollments and Fixed Enrollments sections, you can create a new enrollment by calling the /ws/userenrollment/pix-automatico endpoint, or the /ws/direct endpoint 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.

Simulate enrollment status in 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`, `expire` or `revoke`

Request example:

curl -X POST 'https://sandbox.ebanx.com/ws/simulator/userenrollment' \
--header 'Content-Type: application/json' \
--data '{
	"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>"
}

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.ebanx.com/ws/direct' \
  --header 'Content-Type: application/json' \
  --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 untill it is processed on the due date.

{
  "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",
    "redirect_url": "https://sandbox.ebanx.com/ws/redirect?hash=6762e422391626568b710810924fdaea7401f4f5bb4881",
    "pre_approved": false
  },
  "status": "SUCCESS"
}

On the due_date, the payment will be processed and confirmed by the customer's bank, changing the status to CO(confirmed). In the Sandbox context, you must confirm or fail the payment by yourself in the Simulator.

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).

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.

By following this link, you will be directed to the simulation page, in which you can choose from the following options:

Confirm the payment
Fail the payment
Keep the payment in a pending state to send retry requests

Another option is to simulate payment statuses via API you can use the /ws/simulator/payment endpoint, and all actions will trigger a callback to the configured notification URL.

Check the request instructions below:

Parameter	Requirement	Description
`integration_key`	Required	Your integration key
`hash`	Required	The unique payment identification
`simulate_action`	Required	Define on this field, the desired outcome for the enrollment: `confirm`, `cancel`, `expire` or `fail`

Request example:

curl --location --request POST 'https://sandbox.ebanx.com/ws/simulator/payment' \
--header 'Content-Type: application/json' \
--data '{
	"integration_key": "<your-integration-key>",
	"hash": "<payment-hash>",
	"simulate_action": "<action>"
}'

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

{
  "status": "SUCCESS",
  "entity": "payment",
  "operation": "<action>"
}

Note: Canceling a payment request or experiencing a payment failure does not cancel the enrollment. Only one payment is allowed per cycle, but you will be able to request a new payment in the next cycle.

Congratulations!
You have succesfully used the Pix Automático Simulator.
For more information, refer to the
Direct API reference guide

Still need help?

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

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

Requirements​

Instructions​

Get enrollment QR code