Recurring Payment Schedule

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.

Requirements

• EBANX Sandbox Account - Provides a test environment where you can explore our payment solutions.
  • Sign up for an EBANX Sandbox Account.
  • Complete the online form.
  • Our team will reach out to you shortly.
• API credentials - Ensure you have your EBANX integration key. If not, complete the Merchant Signup Form.
• Familiarity with EBANX Direct - This setup follows the same general structure as other payment methods, with a few unique parameters. See EBANX Direct for more info.

Instructions

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

1. Schedule the Pix Automático payment

   Important!

   The recurring payment request must be sent between 2 and 10 days prior to the next billing date.
   For instance, if the payment is due on January 17th, the request must be submitted between January 7th and 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.

2. 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!

3. Congratulations!

   You have succesfully integrated Pix Automático Recurring Payment.

   For more information, refer to the

   Direct API reference guidechevron_right

Product Launch Date

Pix Automático will be available starting June 16, 2025. In the meantime, you can test and explore the features using our Sandbox environment, which has been live since December 1, 2024.

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 integration@ebanx.com for assistance.
• Not a partner yet? Please complete the Merchant Signup Form, and our commercial team will reach out to you.