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.

JourneyQR Code ReadingAPI ConfirmationUse of SearchProtocolNotes
1NoConfirmPixAutomatic after webhookNoNotifications managed by BU
2GetInfosPixHashCodeConfirmPixAutomaticYes, in the ConfirmPixAutomaticQR with only recurrence data
3GetInfosPixHashCodeGeneratePixOutYes, in the GeneratePixOutQR with immediate payment and recurrence
4GetInfosPixHashCodeConfirmPixAutomatic after webhookYes, in the GeneratePixOutThe QR code can be a due date QR code or a static QR code, both containing recurrence data; notifications managed by BU

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"
}
ParameterDescriptionMandatoryTypeComments
MethodMethod or action to be executed in the requestYesString
BusinessUnitIdIdentifier of the business unitYesInteger
PartnerIdPartner identifierYesInteger
RecurrenceIdRecurrence identifierYesString
DescriptionDescription of the transaction or chargeYesString
SearchProtocolSearch or reference protocolConditionalIntegerMandatory only for journeys 2
AuthorizationStatusObject containing authorization status informationYesObject
AuthorizationStatus.StatusAuthorization statusYesString
AuthorizationStatus.ReasonCodeReason code for rejectionConditionalStringMandatory only when the status is rejected.
PayerObject containing payer informationYesObject
Payer.TaxNumberCPF/CNPJ of the PayerYesString
Payer.NamePayer's nameYesString
Payer.IspbISPB code of the payer's institutionYesInteger
Payer.BankPayer's bank codeYesString
Payer.BankBranchPayer's bank branch codeYesString
Payer.BankAccountPayer's bank account numberYesString
Payer.BankAccountDigitPayer's bank account digitYesString
Payer.ZipCodePayer's postal code or cityYesString
PaymentObject containing payment informationYesObject
Payment.NotificationIndicates if scheduling notifications will be receivedNoBooleanOther notifications will be sent normally.
Payment.CreditlineIndicates if payment is via credit lineNoBoolean
Payment.MaximumValueMaximum allowed value for the paymentNoFloat

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."
}
ParameterDescriptionMandatoryTypeComments
MethodMethod or action to be executed in the requestYesString
BusinessUnitIdIdentifier of the business unitYesInteger
PartnerIdPartner identifierYesInteger
TaxNumberCPF/CNPJ of the user performing the actionYesString
RecurrenceIdRecurrence identifierYesString

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

ParameterDescriptionMandatoryTypeComments
MethodMethod or action to be executed in the requestYesString
BusinessUnitIdIdentifier of the business unitYesInteger
PartnerIdPartner identifierYesInteger
PayerIspbISPB code of the payer's institutionYesInteger
ReceiverIspbISPB code of the receiver's institutionYesInteger
TaxNumberCPF/CNPJ of the user performing the actionYesString
RecurrenceIdRecurrence identifierYesString
SchedulerIdIdentifier for the scheduled transactionYesString
ReasonReason for cancellationYesStringCan be SLCR: Cancellation requested by the receiving user or SLDB: Cancellation requested by the paying user.

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"
}
ParameterDescriptionMandatoryTypeComments
MethodMethod or action to be executed in the requestYesString
BusinessUnitIdIdentifier of the business unitYesInteger
PartnerIdPartner identifierYesInteger
RecurrenceIdRecurrence identifierYesString
NotificationIndicates if scheduling notifications will be receivedNoBooleanAt least one of Notification, CreditLine, or MaximumValue must be filled.
CreditlineIndicates if payment is via credit lineNoBooleanAt least one of Notification, CreditLine, or MaximumValue must be filled.
MaximumValueMaximum allowed value for the paymentNoFloatAt least one of Notification, CreditLine, or MaximumValue must be filled.

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
}
ParameterDescriptionMandatoryTypeComments
MethodMethod or action to be executed in the requestYesString
BusinessUnitIdIdentifier of the business unitYesInteger
PartnerIdPartner identifierYesInteger
RecurrenceIdRecurrence identifierYesString
ScheduledIdIdentifier for the scheduled transactionNoString

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"
    }
]
ParameterDescriptionMandatoryTypeComments
MethodMethod or action to be executed in the requestYesString
BusinessUnitIdIdentifier of the business unitYesInteger
PartnerIdPartner identifierYesInteger
BankBank code of the user performing the actionYesString
Payer.BankBranchBank branch code of the user performing the actionYesString
BankAccountBank account number of the user performing the actionYesString
BankAccountDigitBank account digit of the user performing the actionYesString

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"
        }
    ]
}
ParameterDescriptionMandatoryTypeComments
MethodMethod or action to be executed in the requestYesString
BusinessUnitIdIdentifier of the business unitYesInteger
PartnerIdPartner identifierYesInteger
BankBank code of the user performing the actionYesString
Payer.BankBranchBank branch code of the user performing the actionYesString
BankAccountBank account number of the user performing the actionYesString
BankAccountDigitBank account digit of the user performing the actionYesString

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
}
ParameterDescriptionMandatoryTypeComments
MethodMethod or action to be executed in the requestYesString
BusinessUnitIdIdentifier of the business unitYesInteger
PartnerIdPartner identifierYesInteger
RecurrenceIdRecurrence identifierYesString
ScheduledIdIdentifier for the scheduled transactionNoString

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"
}
ParameterDescriptionMandatoryTypeComments
MethodMethod or action to be executed in the requestYesString
BusinessUnitIdIdentifier of the business unitYesInteger
PartnerIdPartner identifierYesInteger
RecurrenceIdRecurrence identifierYesString
DescriptionDescription of the transaction or chargeYesString
PayerObject containing payer informationYesObject
Payer.TaxNumberCPF/CNPJ of the PayerYesString
Payer.NamePayer's nameYesString
Payer.IspbISPB code of the payer's institutionYesString
Payer.BankPayer's bank codeYesString
Payer.BankBranchPayer's bank branch codeYesString
Payer.BankAccountPayer's bank account numberYesString
Payer.BankAccountDigitPayer's bank account digitYesString
Payer.ZipCodePayer's postal code or cityYesString
TimestampTimestamp of the webhook eventYesString

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.