Pix Automático Fixed Enrollments

Overview

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.



The simplest form of Pix Automático enrollments are fixed subscriptions, where the price stays fixed and changes are made only via new agreements with the customer, usually after a predetermined period of time. Some common use cases are:

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.

Availability

Pix Automático integration through Direct API will be available in Brazil only.

What you will need

A Sandbox Account

As with any secure payment integration, you will first need to set up authorization. The EBANX sandbox allows you to set up a test environment to run transactions using test credit card numbers and explore our payment solutions.

Sign up for an Sandbox Account at our EBANX Business Page, select your business model and answer a few questions. We'll get in touch with you shortly after!

Sign up for an EBANX Sandbox Account here

How it works

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

  1. Enable Pix Automático in your dashboard

    The first step is to check if Pix Automático is active in your EBANX Dashboard.

    All set? We can go ahead to next step, otherwise, please get in touch with our integration specialists.

  2. Call the /ws/userenrollment API to get the Enrollment QR Code

    Your title

    Pix Automático generates a QR Code, which is scanned by the user in their banking app of choice. To get this get it, you just need to call the end-point ws/userenrollment (server-side) with the following required fields:

    ParameterDescription
    operationMust be enrollment
    payment_type_codeMust be pix-automatico
    countryMust be BR
    currency_codeMust be BRL

    Notification URLs:

    ParameterDescription
    back_urls.successEnrollments authorized by the customer will be notified here
    back_urls.failureEnrollments that have been refused by the customer or failed due to operational reasons will be notified here

    Subscription data:

    ParameterDescription
    subscription_nameDescriptor of the service being provided, which will be displayed in the customer's banking app
    first_payment_dateDay when the payment that initiates the subscription will be charged
    expiration_dateOptional If necessary, defines when the enrollment is no longer valid and no further payments will be charged
    frequencyThe billing cycle of the enrollment.
    Available frequencies are: weekly,monthly, quarterly,semi-annual,annual
    amountProvided when recurring payments will have a fixed value. For variable enrollments, use max_amount instead
    retriesDetermines if the merchant will perform retries for payments that are not successful at first in the expect billing day

    Customer data:

    ParameterDescription
    customer.emailCustomer e-mail
    customer.documentCustomer document

    Pix Specific info:

    ParameterDescription
    pix.credit_allowedOptional Boolean value that determines wether the subscription will have access to the customer's credit limit or to their account balance only. This parameter is set to true by default if not informed

    Check the example:

    curl POST 'https://sandbox.ebanxpay.com/userenrollment/' \
    --header 'Content-Type: application/json' \
    --data '{
    "integration_key": "{{integration_key}}",
    "operation": "enrollment",
    "payment_type_code": "pix-automatico",
    "enrollment": {
    "merchant_enrollment_code": "{{unique_enrollment_code}}",
    "country": "BR",
    "currency_code": "BRL",
    "back_urls": {
    "success": "{{success_url}}",
    "failure": "{{failure_url}}"
    },
    "subscription": {
    "subscription_name": "Descriptor of the subscription.",
    "first_payment_date": "2024-01-17",
    "expiration_date": "2024-07-03",
    "frequency": "weekly",
    "amount": 19.90,
    "retries": true
    },
    "customer": {
    "email": "{{customer_email}}",
    "document": "{{customer_document}}",
    "phone_number": "{{customer_phone_number}}"
    },
    "pix": {
    "credit_allowed": true
    }
    }
    }'

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

    {
    "status": "PENDING",
    "payment_type_code": "pix-automatico",
    "enrollment": {
    "merchant_enrollment_code": "{{unique_enrollment_code}}",
    "country": "BR",
    "currency_code": "BRL",
    "back_urls": {
    "success": "{{success_url}}",
    "failure": "{{failure_url}}"
    },
    "subscription": {
    "subscription_name": "Descriptor of the subscription.",
    "first_payment_date": "2024-01-17",
    "expiration_date": "2024-07-03",
    "frequency": "weekly",
    "amount": 19.90,
    "retries": true
    },
    "customer": {
    "email": "{{customer_email}}",
    "document": "{{customer_document}}"
    },
    "pix": {
    "credit_allowed": true
    },
    "qr_code_value": "00020101021226740014br.gov.bcb.pix2552pix.ebanx.com\/qr\/v2\/F2D9448AA5B94ED3450A4A8933748F5952040000556345643602BR5911Ebanx LTDA.6008CURITIBA62070503***63045022"
    }
    }
  3. 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 enrollment.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.

  4. Confirming the Enrollment

    Your title

    As soon as the enrollment is confirmed by the customer in their banking app, the enrollment status is modified from PENDING to SUCCESS and a Status Update notification is sent to the URL defined in Success URL in step 2.

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

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

    Check the example:

    curl POST 'https://sandbox.ebanxpay.com/userenrollment/query' \
    --header 'Content-Type: application/json' \
    --data '{
    "integration_key": "{{integration_key}}",
    "merchant_enrollment_code": "{{unique_enrollment_code}}"
    }'

    A successful request will return a JSON response like the one below, with a status of SUCCESS for the enrollment approved by the customer.

    {
    "status": "SUCCESS",
    "payment_type_code": "pix-automatico",
    "enrollment": {
    "merchant_enrollment_code": "{{unique_enrollment_code}}",
    "country": "BR",
    "currency_code": "BRL",
    "back_urls": {
    "success": "{{success_url}}",
    "failure": "{{failure_url}}"
    },
    "subscription": {
    "subscription_name": "Descriptor of the subscription.",
    "first_payment_date": "2024-01-17",
    "expiration_date": "2024-07-03",
    "frequency": "weekly",
    "amount": 19.90,
    "retries": true
    },
    "customer": {
    "email": "{{customer_email}}",
    "document": "{{customer_document}}"
    },
    "pix":{
    "credit_allowed": true //true by default if not informed.
    },
    "qr_code_value": "00020101021226740014br.gov.bcb.pix2552pix.ebanx.com\/qr\/v2\/F2D9448AA5B94ED3450A4A8933748F5952040000556345643602BR5911Ebanx LTDA.6008CURITIBA62070503***63045022"
    }
    }
    Important!

    Pending enrollments expire after 30 days. If your customers don't complete the enrollment in time, the enrollment will be automatically canceled.

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

    Your title

    Scheduling a recurring payment with Pix Automático is really straightforward. The following fields are required:

    ParameterDescription
    operationMust be request
    payment_type_codeMust be pix-automatico

    Enrollment data:

    ParameterDescription
    merchant_enrollment_codeThe enrollment code generated in the previous steps. The enrollment must have a SUCCESS status to be used in recurring payments

    Charge data:

    ParameterDescription
    merchant_payment_codeUnique merchant payment code
    countryMust be BR
    currency_codeMust be BRL
    amount_totalTotal amount to be charged. Note that the amount must match the one set in the enrollment

    Check the example:

    curl -X POST 'https://sandbox.ebanxpay.com/ws/direct' \
    --data '{
    "integration_key": "{{integration_key}}",
    "operation": "request",
    "payment": {
    "amount_total": 19.90,
    "country": "BR",
    "currency_code": "BRL",
    "merchant_payment_code": "{{unique_payment_code}}",
    "payment_type_code": "pix-automatico",
    "merchant_enrollment_code": "{{unique_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"
    }
  6. Confirming the Payment

    Your title

    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 ID provided in merchant_payment_code, use the ws/query endpoint to get the latest status of the payment.

    Check the example:

    curl POST 'https://sandbox.ebanxpay.com/query' \
    --header 'Content-Type: application/json' \
    --data '{
    "integration_key": "{{integration_key}}",
    "merchant_payment_code": "{{unique_payment_code}}"
    }'

    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-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",
    "currency_rate": "1.0000",
    "currency_ext": "BRL",
    "due_date": "2024-01-17",
    "payment_type_code": "pix-automatico",
    "pre_approved": false
    },
    "status": "SUCCESS"
    }

    Now, for each new billing cycle, simply repeat 5 and 6!

note

Pix Automático goes live on June 16th 2025. Stay tuned for Sandbox Environment availability on December 1st 2024!

Still need help?

Help Image

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

Last updated on by Samuel Santos De Oliveira