Enrollments with an Instant Payment | EBANX Developers Academy

Pix Automático works by establishing an authorization, achieved through an enrollment process, between merchant and customer, and referencing it in every recurring payment. This way, the customer's bank can validate the payment against the enrollment and transfer funds without the need for customer interaction, given that they know the payment request has been validated and comes from a valid source.

There are cases where a one-time purchase and a subscription are purchased at the same checkout - Pix Automático addresses this scenario by merging both transactions into a single one. It is also useful for subscriptions where the first payment is charged immediately, without a free trial period.

Note that these transactions—the instant payment and the enrollment—are executed in a single call. This means that, for example, if the customer does not have sufficient funds for the instant payment and it fails, the enrollment will also fail.

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 Direct API. To complete a payment with Pix Automático you will need a few API calls that will create an enrollment for your customer, the recurring payment and provide the necessary information for the customer to complete the transaction.

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.

Instructions

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

Call the /ws/direct API to get the Enrollment QR Code

Pix Automático generates a QR Code, which is scanned by the user in their banking app of choice. To get this, you just need to call the end-point /ws/direct (server-side) as you will request a payment but adding the enrollment data. Check the required fields below:

Parameter	Requirement	Description
`integration_key`	Required	Your integration key
`operation`	Required	Must be `request`

Instant Payment and Customer Data:

Parameter	Requirement	Description
`merchant_payment_code`	Required	Unique merchant payment code
`amount_total`	Required	Total amount to be charged. Note that the amount doesn't need to 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`
`expiration_time_in_seconds`	Optional	QR code expires based on the duration specified in this parameter or the default set by EBANX (24 hours). The time must be specified in seconds.
`email`	Required	Customer e-mail
`name`	Required	Customer name
`document`	Required	Customer document

Subscription data:

Parameter	Requirement	Description
`country`	Required	Must be `BR`
`email`	Required	Customer e-mail
`name`	Required	Customer name
`document`	Required	Customer document
`merchant_enrollment_code`	Required	Unique enrollment code
`subscription_name`	Required	Descriptor of the service being provided, which will be displayed in the customer's banking app
`expiration_date`	Optional	If necessary, defines when the enrollment is no longer valid and no further payments will be charged
`frequency`	Required	The billing cycle of the enrollment. Available frequencies are: `weekly`,`monthly`, `quarterly`,`halfyearly`,`yearly`
`retry`	Required	Determines whether the merchant will retry payments that fail on the expect billing day. The available retry policies are: `not_allowed` for no additional attempts or `allow_3R_7D` for up to three retries within seven days after the first payment
`fixed_amount`	Required	Provided when recurring payments will have a fixed value. For variable enrollments, use `max_amount_floor` instead
`start_date`	Required	Day when the payment that initiates the subscription will be charged

The instant payment will be processed immediately, and the recurrent payment will be set on the start_date.

Check the example below, of a 19.90 BRL monthly subscription that starts on December 30, with an instant payment of 39.90 BRL requested on December 18:

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": "{{unique_payment_code}}",
      "amount_total": 39.90,
      "currency_code": "BRL",
      "country": "BR",
      "payment_type_code": "pix-automatico",
      "expiration_time_in_seconds": 3600,
      "email": "{{customer_email}}",
      "name": "{{customer_name}}",
      "document": "{{customer_document}}",
      "enrollment": {
        "country": "BR",
        "email": "{{customer_email}}",
        "name": "{{customer_name}}",
        "document": "{{customer_document}}",
        "merchant_enrollment_code": "{{unique_enrollment_code}}",
        "subscription": {
            "subscription_name": "Descriptor of the subscription", 
            "expiration_date": "2025-12-30", 
            "frequency": "monthly", 
            "retry": "allow_3R_7D",
            "fixed_amount": 19.90, 
            "start_date": "2024-12-30"
            }
        }
      }
 }'

A successful request will return a JSON response like the one below. The Pix Automático raw QR Code value will be in the parameter qr_code_value.

You can also use the redirect_url to redirect your customer to an external page to display the Pix Automatico voucher and QR code. In Sandbox environment, you will find in the redirect_url the link to use our Simulator.

note

Both the enrollment and the instant payment are encoded in the same QR Code and are confirmed at the same time.

{
    "payment": {
        "hash": "676314e588106473c52fb2beaa9dfa3b213f05ca380db7",
        "country": "BR",
        "merchant_payment_code": "{{unique_payment_code}}",
        "order_number": null,
        "status": "PE",
        "status_date": null,
        "open_date": "2024-12-18 18:31:01",
        "confirm_date": null,
        "transfer_date": null,
        "amount_br": "39.90",
        "amount_ext": "39.75",
        "amount_iof": "0.15",
        "currency_rate": "1.0000",
        "currency_ext": "BRL",
        "due_date": "2024-12-18",
        "instalments": "1",
        "payment_type_code": "pix-automatico",
        "pre_approved": false,
        "capture_available": null,
        "redirect_url": "https://customer.ebanx.com/pix/checkout?hash=68daedc3e92db5fa8584ed485eeb85b264e887ee534248f5",
        "pix_automatico": {
            "qr_code_value": "00020101021226740014br.gov.bcb.pix2552pix.ebanx.com/qr/v2/DF6074A55EF8BA6FA05A18C391F5A9BE5204000053039865802BR5911Ebanx LTDA.6008CURITIBA62070503***80720014br.gov.bcb.pix2550pix.ebanx.com/rec/6749F69D5C44607AC4829C18672BA63163047E92"
        },
        "enrollment": {
            "status": "pending",  
            "merchant_enrollment_code": "{{unique_enrollment_code}}",
        },
        "subscription": {
            "subscription_name": "Descriptor of the subscription", 
            "start_date": "2024-12-30",
            "expiration_date": "2025-12-30", 
            "frequency": "monthly", 
            "retry": "allow_3R_7D",
            "fixed_amount": 19.90
            }
    },
    "status": "SUCCESS"
}

Presenting the Pix QR Code
You can present the QR code by rendering the code at your page.

Copying QR Code to Clipboard
Alternatively, you can simply deliver the QR Code number from qr_code_value to your customer's clipboard so they can paste it into their banking/wallet app.
At this point you have a pending enrollment and will be notified via webhook when there is a status change. Additionally, you'll have a pending payment, which will also be notified separately, upon confirmation.

Confirming the Enrollment and Instant Payment

As soon as the enrollment is confirmed by the customer in their banking app, the enrollment status is modified from pending to accepted and a Status Update notification is sent to the URL defined in your merchant configuration.

{
   "operation":"enrollment_status_change",
   "notification_type":"update",
   "merchant_enrollment_code":"{{unique_enrollment_code}}"
}

Using the ID provided in merchant_enrollment_code, use the /ws/userenrollments/query endpoint to get the latest status of the enrollment.

Check the example:

curl -X POST 'https://sandbox.ebanx.com/ws/userenrollments/query' \
--header 'Content-Type: application/json' \
--data '{
    "integration_key": "{{integration_key}}",
    "enrollment": {
        "merchant_enrollment_code": "{{unique_enrollment_code}}"
    }
}'

A successful request will return a JSON response like the one below, with a status of accepted for the enrollment approved by the customer. Other possible enrollment statuses include not accepted, pending, expired, not_found and revoked, depending on the actions taken by the merchant or customer.

{
    "status": "SUCCESS",
    "payment_type": "pix-automatico",
    "enrollment": {
        "status": "accepted",
        "email": "",
        "spi_code": "RR2101818220250811jYwwlNucP9A"
    },
    "subscription": {
        "subscription_name": "Descriptor of the subscription",
        "start_date": "2024-12-30",
        "expiration_date": "2025-12-30",
        "frequency": "monthly",
        "retry": "allow_3R_7D",
        "fixed_amount": "19.90"
    }
}

Additionaly, the payment status of the payment created in step 2 is modified from PE to CO and a Status Update notification is sent.

Using the hash provided in the 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}}",
       "merchant_enrollment_code": "{{unique_enrollment_code}}",
       "status": "CO",
       "status_date": "2024-12-18 14:00:00",
       "open_date": "2024-12-18 13:00:00",
       "confirm_date": "2024-12-18 14:00:00",
       "transfer_date": null,
       "amount_br": "39.90",
       "amount_ext": "39.90",
       "amount_iof": "0.00",
       "currency_rate": "1.0000",
       "currency_ext": "BRL",
       "due_date": null,
       "payment_type_code": "pix-automatico",
       "pre_approved": false
   },
    "enrollment": {
        "status": "accepted",  
        "merchant_enrollment_code": "{{unique_enrollment_code}}",
    },
    "subscription": {
        "subscription_name": "Descriptor of the subscription", 
        "start_date": "2024-12-30",
        "expiration_date": "2025-12-30", 
        "frequency": "monthly", 
        "retry": "allow_3R_7D",
        "fixed_amount": 19.90
    },   
    "status": "SUCCESS"
}

Important:

Pending enrollments expire by default after 24 hours. If the customer does not complete the process in time, the enrollment will be marked as expired. You can override this behavior by setting the field expiration_time_in_seconds, which defines the QR code expiration time for each request.

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 December 30th, the payment request must be sent no earlier than December 20th and no later than December 28th.

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?hash=683f3c53c065aab9b5151a38cd6b717e29df06dcb60cbb3c",
        "pre_approved": false,
        "enrollment": {
            "status": "accepted",  
            "merchant_enrollment_code": "{{unique_enrollment_code}}",
        },
        "subscription": {
            "subscription_name": "Descriptor of the subscription", 
            "start_date": "2024-12-30",
            "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-12-30",
          "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 5 and 6!

Congratulations!
You have succesfully integrated Pix Automático Enrollments with an Instant 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.

Pix Automático Enrollments with an Instant Payment

Requirements​

Instructions​

Call the /ws/direct API to get the Enrollment QR Code

Instant Payment and Customer Data:​

Subscription data:​

Presenting the Pix QR Code

Confirming the Enrollment and Instant Payment

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

Confirming the Payment

Congratulations!

Still need help?

Requirements

Instructions

Instant Payment and Customer Data:

Subscription data: