Recurring Payment Schedule

Overview

Once your enrollment is accepted, you can schedule recurring payments according to the cycle you have configured(through frequency and start_date).

Pix Automático operates on a schedule-based approach. The Central Bank of Brazil requires that payment requests be made between 2 and 10 days before the expected billing date, ensuring customers have sufficient visibility of upcoming charges.

For example, if a payment is due on January 12th, the payment request must be sent no earlier than January 2nd and no later than January 10th.

At every cycle, you must repeat the process described below to ensure your charges are processed on time.

How it works

To schedule a Pix Automático recurring payment, please follow the steps below.

Call the /ws/direct API to schedule the Pix Automático payment

Very Important!

The recurring payment request must be sent between 2 and 10 days before the next billing day. For example, if a payment is due on January 17th, the payment request must be sent no earlier than January 7th and no later than January 15th.

Scheduling a recurring payment with Pix Automático is really straightforward. The following fields will be 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"
}

note

In the Sandbox environment, the redirect_url in the response of your payment schedule will lead you to the payment Simulator, allowing you to reproduce multiple payment processing scenarios.

Confirming the Payment
As soon as the payment is confirmed by the customer's bank, the payment status is modified from PE to CO and a Status Update notification is sent.
{
"operation":"payment_status_change",
"notification_type":"update",
"merchant_payment_code":"{{unique_payment_code}}"
}
Using the hash provided in the payment response, use the ws/query endpoint to get the latest status of the payment.
Check the example:
curl POST 'https://sandbox.ebanxpay.com/ws/query' \
--header 'Content-Type: application/json' \
--data '{
"integration_key": "{{integration_key}}",
"hash": "{{unique_payment_hash}}"

}'
A successful request will return a JSON response like the one below, with a status of CO for the successful recurring payment.
{
"payment": {
"hash": "{{unique_payment_hash}}",
"country": "BR",
"merchant_payment_code": "{{unique_payment_code}}",
"status": "CO",
"status_date": "2024-01-17 03:00:00",
"open_date": "2024-01-10 13:00:00",
"confirm_date": "2024-01-17 03:00:00",
"transfer_date": null,
"amount_br": "19.90",
"amount_ext": "19.90",
"amount_iof": "0.00",
"amount_ext_requested": "0.00",
"currency_rate": "1.0000",
"currency_ext": "BRL",
"due_date": "2024-01-17",
"instalments": "1",
"payment_type_code": "pix-automatico",
"redirect_url": "00020101021226740014br.gov.bcb.pix2552pix.ebanx.com\/qr\/v2\/F2D9448AA5B94ED3450A4A8933748F5952040000556345643602BR5911EbanxLTDA.6008CURITIBA62070503***63045022",
"pre_approved": false,
"capture_available": null,
"customer": {
"document": "{{customer_document}}",
"email": "{{customer_email}}",
"name": "{{customer_name}}",
"birth_date": "1992-08-15",
"address": "",
"street_number": "",
"street_complement": "",
"city": "",
"state": "",
"zipcode": "",
"country": "BR",
"phone_number": ""
},
"single_transaction": {
"amount_local": "0.00",
"amount_crossborder": "19.90"
},
"enrollment": {
"merchant_enrollment_code": "{{merchant_enrollment_code}}"
}
}
}
Now, for each new billing cycle, simply repeat these steps!

In the event of a failed payment attempt, EBANX will send a notification to inform you of the failure.

If you configured the retry policy during enrollment creation as allow_3R_7D, the payment status will remain pending (PE). According to the standards of this payment method, you can request up to three retries within a seven-day window, with a maximum of one retry per day. By following the instructions of the Retries page.

note

Pix Automático will go live on June 16, 2025. In the meantime, you can use our Sandbox environment, available since December 1, 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.

Recurring Payment Schedule#

Overview#

How it works#

Call the /ws/direct API to schedule the Pix Automático payment

Very Important!

note

Confirming the Payment

note

Still need help?

Recurring Payment Schedule

Overview

How it works