Automatic Pix

Introduction

The Payer's Automatic Pix is an innovative feature of the Pix system, developed by the Central Bank of Brazil, which enables the automation of recurring payments, such as subscriptions, monthly fees, or bills, in a practical, secure manner with full control by the payer. It was designed to address use cases such as payments for subscriptions, school fees, gym memberships, condominiums, among others. Unlike other recurring payment methods, such as traditional automatic debit, the Automatic Pix offers greater control to the payer, who can manage authorizations directly through their financial institution's app. With this feature, the user (payer) pre-authorizes payments to be made on specific dates, being able to set conditions such as maximum value and frequency, as well as modify or cancel the authorization at any time within their financial institution's environment.

User Manual - Automatic Pix

How It Works?

• Prior Authorization: The payer grants authorization for recurring payments to a recipient, defining the payment conditions.
• Automatic Execution: Payments are made automatically on the agreed dates, respecting the authorized conditions.
• Payer Control: The payer can check, modify, or cancel the recurrence at any time, ensuring full autonomy.
• Security and Transparency: Transactions are carried out in the secure Pix environment, with traceability and data protection.

Benefits for Customers

• Automation of recurring charges, reducing delinquency.
• Greater control and convenience for payers.
• Simplified integration via FitBank APIs to manage authorizations and payments.
• Secure and traceable transactions within the Pix ecosystem.

Journeys of Automatic Pix

Automatic Pix offers different workflows to meet the needs of end-users and business units, ensuring flexibility in payment automation. Below, we detail the four available journeys, explaining how each works and the necessary steps for integration with FitBank APIs.

Journey 1: Notification with Confirmation via Webhook

In this journey, FitBank triggers a request via webhook to the Business Unit (BU), which is responsible for organizing and managing the notification (such as a pop-up or SMS) to be sent to the end-user through the app or another configured communication channel. The user must respond to this notification to authorize the Automatic Pix.

How it works:

• FitBank sends a confirmation request to the Business Unit via a webhook.
• The Business Unit uses the appropriate API to confirm or reject the request, according to the user's action.

API Integration:

• WebhookConfirmPixAutomatic: Set up an endpoint to receive Automatic Pix requests sent by FitBank.
• ConfirmPixAutomatic: Use this API to confirm or reject the request received from the webhook after the end-user's response.

Journey 2: QR Code Reading for Recurrence Authorization

The end-user scans a QR Code that contains only the recurrence data, without immediate payment information. The goal is to confirm the authorization of the recurrence using the SearchProtocol.

How it works:

• The QR Code is interpreted to retrieve recurrence information.
• The Business Unit confirms the recurrence authorization using the associated SearchProtocol.

API Integration:

• GetInfosPixHashCode: Method used to read and interpret the QR Code containing recurrence data.
• ConfirmPixAutomatic: API to confirm the recurrence authorization, using the SearchProtocol obtained during the scan or process generation.

Journey 3: QR Code with Immediate Payment and Recurrence

The end-user scans a QR Code containing both the details of an immediate payment and recurrence data. In this journey, when performing the payment via GeneratePixOut, the acceptance of the Automatic Pix is handled automatically, as a single action. There’s no option to simply pay or just accept the recurrence — by completing the payment, the user also automatically accepts the recurrence, since the confirmation is performed internally within the method.

How it works:

• The QR Code is interpreted to extract both payment and recurrence information.
• The GeneratePixOut API is used to generate the immediate payment, utilizing the SearchProtocol.
• The confirmation and acceptance of the recurrence are automatically done during the GeneratePixOut process if the user chooses to pay, effectively accepting the Automatic Pix.

API Integration:

GetInfosPixHashCode: method to read and interpret the QR Code containing payment and recurrence data.

GeneratePixOut: API used to generate the immediate payment, utilizing the SearchProtocol. It also internally manages the confirmation and acceptance of the recurrence when the payment is completed

Journey 4: QR Code for Payment with Due Date and Recurrence Option

In this journey, the user scans a QR Code to make a payment. The QR code can contain recurrence data along with payment information with a due date, or be a static QR code combined with recurrence data. After completing the payment, a recurrence offer is sent via webhook, allowing the user to choose whether to accept or decline the recurrence. The Business Unit is responsible for managing and organizing notifications (such as pop-ups or SMS) sent to the user through the app or another communication channel.

How it works:

• The QR Code is scanned to obtain the payment information.
• The payment is generated using GeneratePixOut, utilizing the SearchProtocol.
• After the payment, FitBank sends a webhook with the recurrence offer.
• If the user accepts the recurrence, the confirmation is made via ConfirmPixAutomatic.

API Integration:

• GetInfosPixHashCode: To read the QR Code and retrieve payment info.
• GeneratePixOut: To generate the payment, utilizing the SearchProtocol.
• WebhookConfirmPixAutomatic: Receives notifications about the recurrence offer.
• ConfirmPixAutomatic: Used to confirm the recurrence whether the user accepts or declines.

GetInfosPixHashCode

APIs for Integration with Payer's Automatic Pix

Below, we present the available APIs for clients to integrate with the Payer's Automatic Pix. Each method is detailed with examples of requests and responses.

1. Confirmation of Automatic Pix (Recurrence Authorization)

Allows the payer to confirm the authorization of an automatic payment recurrence.

{
    "Method": "ConfirmPixAutomatic",
    "BusinessUnitId": "11427",
    "PartnerId": "564",
    "RecurrenceId": "RRR123456720240107000000001",
    "Description": "Cobrança de assinatura mensal do serviço X",
    "SearchProtocol": 336168424,
    "AuthorizationStatus": {
        "Status": "Approved",
        "ReasonCode": null
    },
    "Payer": {
        "TaxNumber": "12345678909",
        "Name": "João Silva",
        "Ispb": "13203354",
        "Bank": "450",
        "BankBranch": "3083",
        "BankAccount": "45843",
        "BankAccountDigit": "5",
        "ZipCode": "São Paulo"
    },
    "Payment": {
        "Notification": true,
        "Creditline": false,
        "MaximumValue": 150.00
    }
}

{
  "Success": "true",
  "Message": "Confirmação de recorrência Pix automática registrada com sucesso",
  "RecurrenceId": "12345678901234567890123456789"
}

2. Cancellation of Recurrence

Allows the payer to cancel a previously authorized recurrence.

{
  "Method": "CancelPixAutomatic",
  "PartnerId": 30519,
  "BusinessUnitId": 51138,
  "TaxNumber": "84928589076",
  "RecurrenceId": "12345678901234567890123456789"
}

{
  "Success": "true",
  "Message": "Cancelamento realizado com sucesso."
}

3. Cancellation of Schedule

Allows canceling a previously created automatic Pix schedule.

{
    "Method": "CancelTransactionPixAutomatic",
    "BusinessUnitId": 1234,
    "PartnerId": 4321,
    "PayerIspb": 12345678,
    "ReceiverIspb": 87654321,
    "RecurrenceId": "RRR123456720240107000000002",
    "SchedulerId": "absdhidddFFG348764kbsjsQKIp",
    "TaxNumber": "12345678901",
    "Reason": "SLBD"
}

{
  "Success": "true",
  "Message": "Cancelamento realizado com sucesso.",
  "RecurrenceId": "12345678901234567890123456789"
}

Note: The schedule can only be canceled until 11:59 PM on the day before the settlement date.Method or action to be executed in the request

4. Modification of Recurrence

Allows modification of recurrence settings, such as notifications, credit line usage, or maximum value.

{
  "Method": "ChangePixAutomatic",
  "PartnerId": 30519,
  "BusinessUnitId": 51138,
  "RecurrenceId": "12345678901234567890123456789",
  "TaxNumber": "12345678901",
  "Notification": true,
  "CreditLine": true,
  "MaximumValue": 2000
}

{
  "Success": "true",
  "Message": "Alteração de recorrência realizada com sucesso",
  "RecurrenceId": "12345678901234567890123456789"
}

5. Query Methods

The methods below allow querying information about recurrences and schedules.

5.1 Query Schedule by ID

Queries details of a specific schedule.

{
    "Method": "GetTransactionPixAutomaticById",
    "PartnerId": "1234",
    "BusinessUnitId": "4321",
    "TaxNumber": "12345678945",
    "RecurrenceId": "RR2222222220240429njua7shf40k",
    "ScheduledId": "122345"
}

{
    "RecurrenceId": "RR2222222220240429njua7shf40k",
    "ScheduledId": "122345",
    "Receiver": {
        "Name": "Netflix",
        "TaxNumber": "12.345.678/0001-00"
    },
    "Debtor": {
        "Name": "João Silva",
        "TaxNumber": "123.***.***-45"
    },
    "AuthorizationId": null,
    "Status": "Criado",
    "ContractId": "e791f33f-a8ca-4f30-8c29-ef8fdfe4f2e3",
    "Description": "Fatura de energia elétrica",
    "PaymentDate": "12/05/2025",
    "Value": "50,00",
    "AdditionalInfo": null
}

5.2 Query Schedules by Account

Queries all schedules associated with a specific account.

{
    "Method": "GetTransactionPixAutomatic",
    "PartnerId": "1234",
    "BusinessUnitId": "4321",
    "TaxNumber": "12345678945",
    "Bank": "450",
    "BankBranch": "0001",
    "BankAccount": "33072795",
    "BankAccountDigit": "7"
}

[
    {
        "ScheduledId": "122344",
        "ReceiverName": "Spotify",
        "ReceiverTaxNumber": "12.345.693/0001-00",
        "PaymentDate": "2025-06-10T10:00:00Z",
        "Status": "Criado"
    },
    {
        "ScheduledId": "122344",
        "ReceiverName": "Youtube",
        "ReceiverTaxNumber": "54.345.678/0001-00",
        "PaymentDate": "2025-06-11T10:00:00Z",
        "Status": "Cancelado"
    }
]

5.3 Query Recurrence by Account

Queries all recurrences associated with a specific account.

{
  "Method": "GetPixAutomatic",
  "PartnerId": 30519,
  "BusinessUnitId": 51138,
  "TaxNumber": "12345678945",
  "Bank": "450",
  "BankBranch": "0001",
  "BankAccount": "440246",
  "BankAccountDigit": "3"
}

{
    "PixAutomatic": [
        {
            "RecurrenceId": "RR2222222220240429njua7shf40k",
            "ReceiverName": "Netflix",
            "ReceiverTaxNumber": "12.345.678/0001-00",
            "Status": "Pendente"
        },
        {
            "RecurrenceId": "RR2222222220240429njua7shf40k",
            "ReceiverName": "Spotify",
            "ReceiverTaxNumber": "12.345.693/0001-00",
            "Status": "Liquidado"
        }
    ]
}

5.4 Query Recurrence by ID

Queries details of a specific recurrence.

{
    "Method": "GetPixAutomaticById",
    "PartnerId": "1234",
    "BusinessUnitId": "4321",
    "TaxNumber": "12345678945",
    "RecurrenceId": "RR2222222220240429njua7shf40k"
}

{
    "RecurrenceId": "RR2222222220240429njua7shf40k",
    "Receiver": {
        "Name": "Netflix",
        "TaxNumber": "12.345.678/0001-00"
    },
    "Debtor": {
        "Name": "João Silva",
        "TaxNumber": "123.***.***-45"
    },
    "AuthorizationId": null,
    "Status": "Pendente",
    "ContractId": "e791f33f-a8ca-4f30-8c29-ef8fdfe4f2e3",
    "Description": "Fatura de energia elétrica",
    "InitialDate": "12/05/2025",
    "FinalDate": "12/05/2026",
    "Frequency": "Semanal",
    "OriginalValue": null,
    "MaximumValue": null,
    "Creditline": true,
    "Notification": true
}

6. Webhook for Automatic Pix Confirmation

Below is an example of a payload received via webhook for Automatic Pix confirmation requests:

{
  "Method": "ConfirmPixAutomatic",
  "PartnerId": 123,
  "BusinessUnitId": 456,
  "RecurrenceId": "abc123",
  "Description": "Contract description",
  "Payer": {
    "Name": "Payer's Name",
    "TaxNumber": "12345678900",
    "BankCode": "001",
    "BankISPB": "12345678",
    "BankBranch": "0001",
    "BankAccount": "12345",
    "BankAccountDigit": "6",
    "ZipCode": "12345678"
  },
  "Timestamp": "2024-06-07T12:34:56.789Z"
}

Final Considerations

The FitBank Automatic Pix offers flexibility to accommodate different payment scenarios, from direct notifications managed by the Business Unit to integrations with QR Codes for payments with due dates or Recurrences. Make sure to properly configure webhooks and use the APIs as described for each journey.

For more details on the mentioned APIs, refer to the documentation reference section or contact FitBank technical support. If you need code examples or flow diagrams, we are available to assist.

🚧

This document is still being finalized and may undergo further changes or updates. We recommend checking back periodically to access the most current information.