Pix Automático Recurring Payment | EBANX Developers Academy

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.

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.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 and will be confirmed later by the customer's bank.

{
    "payment": {
        "hash": "{{unique_payment_hash}}",
        "country": "BR",
        "merchant_payment_code": "{{unique_payment_code}}",
        "status": "PE",
        "status_date": "2024-01-17 21:11:36",
        "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/execute?hash=683f3c53c065aab9b5151a38cd6b717e29df06dcb60cbb3c",
        "pre_approved": false,
        "enrollment": {
            "status": "accepted",           
            "merchant_enrollment_code": "{{unique_enrollment_code}}",
        },
        "subscription": {
            "subscription_name": "Descriptor of the subscription", 
            "start_date": "2024-01-01",
            "expiration_date": "2025-12-30", 
            "frequency": "monthly", 
            "retry": "allow_3R_7D",
            "fixed_amount": 19.90
        }, 
        "retries": {
            "retry_status": "LOCKED",
            "available_retries": 3,
            "payment_attempts": [
                {
                    "attempted_at": "2024-01-17 21:11:33",
                    "attempt_response": "PENDING"
                }
            ]
        }
    },
    "status": "SUCCESS"
}

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 -X POST 'https://sandbox.ebanx.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 21:11:36",
        "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=683f3c53c065aab9b5151a38cd6b717e29df06dcb60cbb3c",
        "pre_approved": false,
        "transaction_status": {
          "acquirer": "EBANX IP",
          "code": "OK",
          "description": "Recurring payment successfully paid",
          "description_code": "ACCEPTED"
        },     
        "enrollment": {
          "status": "accepted",           
          "merchant_enrollment_code": "{{unique_enrollment_code}}",
        },
        "subscription": {
            "subscription_name": "Descriptor of the subscription", 
            "start_date": "2024-01-01",
            "expiration_date": "2025-12-30", 
            "frequency": "monthly", 
            "retry": "allow_3R_7D",
            "fixed_amount": 19.90
        },         
        "retries": {
            "retry_status": "ENDED",
            "available_retries": 0,
            "payment_attempts": [
                {
                    "attempted_at": "2024-01-17 21:11:33",
                    "attempt_response": "CONFIRMED"
                }
            ]
        }
    },
    "status": "SUCCESS"
}

Now, for each new billing cycle, simply repeat these steps!

Congratulations!
You have succesfully integrated Pix Automático Recurring Payment.
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 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

Requirements​

Instructions​

Schedule the Pix Automático payment

Confirming the Payment

Congratulations!

Still need help?

Requirements

Instructions