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.
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.
Journey | QR Code Reading | API Confirmation | Use of SearchProtocol | Notes |
---|---|---|---|---|
1 | No | ConfirmPixAutomatic after webhook | No | Notifications managed by BU |
2 | GetInfosPixHashCode | ConfirmPixAutomatic | Yes, in the ConfirmPixAutomatic | QR with only recurrence data |
3 | GetInfosPixHashCode | GeneratePixOut | Yes, in the GeneratePixOut | QR with immediate payment and recurrence |
4 | GetInfosPixHashCode | ConfirmPixAutomatic after webhook | Yes, in the GeneratePixOut | The 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"
}
Parameter | Description | Mandatory | Type | Comments |
---|---|---|---|---|
Method | Method or action to be executed in the request | Yes | String | |
BusinessUnitId | Identifier of the business unit | Yes | Integer | |
PartnerId | Partner identifier | Yes | Integer | |
RecurrenceId | Recurrence identifier | Yes | String | |
Description | Description of the transaction or charge | Yes | String | |
SearchProtocol | Search or reference protocol | Conditional | Integer | Mandatory only for journeys 2 |
AuthorizationStatus | Object containing authorization status information | Yes | Object | |
AuthorizationStatus.Status | Authorization status | Yes | String | |
AuthorizationStatus.ReasonCode | Reason code for rejection | Conditional | String | Mandatory only when the status is rejected. |
Payer | Object containing payer information | Yes | Object | |
Payer.TaxNumber | CPF/CNPJ of the Payer | Yes | String | |
Payer.Name | Payer's name | Yes | String | |
Payer.Ispb | ISPB code of the payer's institution | Yes | Integer | |
Payer.Bank | Payer's bank code | Yes | String | |
Payer.BankBranch | Payer's bank branch code | Yes | String | |
Payer.BankAccount | Payer's bank account number | Yes | String | |
Payer.BankAccountDigit | Payer's bank account digit | Yes | String | |
Payer.ZipCode | Payer's postal code or city | Yes | String | |
Payment | Object containing payment information | Yes | Object | |
Payment.Notification | Indicates if scheduling notifications will be received | No | Boolean | Other notifications will be sent normally. |
Payment.Creditline | Indicates if payment is via credit line | No | Boolean | |
Payment.MaximumValue | Maximum allowed value for the payment | No | Float |
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."
}
Parameter | Description | Mandatory | Type | Comments |
---|---|---|---|---|
Method | Method or action to be executed in the request | Yes | String | |
BusinessUnitId | Identifier of the business unit | Yes | Integer | |
PartnerId | Partner identifier | Yes | Integer | |
TaxNumber | CPF/CNPJ of the user performing the action | Yes | String | |
RecurrenceId | Recurrence identifier | Yes | String |
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
Parameter | Description | Mandatory | Type | Comments |
---|---|---|---|---|
Method | Method or action to be executed in the request | Yes | String | |
BusinessUnitId | Identifier of the business unit | Yes | Integer | |
PartnerId | Partner identifier | Yes | Integer | |
PayerIspb | ISPB code of the payer's institution | Yes | Integer | |
ReceiverIspb | ISPB code of the receiver's institution | Yes | Integer | |
TaxNumber | CPF/CNPJ of the user performing the action | Yes | String | |
RecurrenceId | Recurrence identifier | Yes | String | |
SchedulerId | Identifier for the scheduled transaction | Yes | String | |
Reason | Reason for cancellation | Yes | String | Can 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"
}
Parameter | Description | Mandatory | Type | Comments |
---|---|---|---|---|
Method | Method or action to be executed in the request | Yes | String | |
BusinessUnitId | Identifier of the business unit | Yes | Integer | |
PartnerId | Partner identifier | Yes | Integer | |
RecurrenceId | Recurrence identifier | Yes | String | |
Notification | Indicates if scheduling notifications will be received | No | Boolean | At least one of Notification, CreditLine, or MaximumValue must be filled. |
Creditline | Indicates if payment is via credit line | No | Boolean | At least one of Notification, CreditLine, or MaximumValue must be filled. |
MaximumValue | Maximum allowed value for the payment | No | Float | At 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
}
Parameter | Description | Mandatory | Type | Comments |
---|---|---|---|---|
Method | Method or action to be executed in the request | Yes | String | |
BusinessUnitId | Identifier of the business unit | Yes | Integer | |
PartnerId | Partner identifier | Yes | Integer | |
RecurrenceId | Recurrence identifier | Yes | String | |
ScheduledId | Identifier for the scheduled transaction | No | String |
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"
}
]
Parameter | Description | Mandatory | Type | Comments |
---|---|---|---|---|
Method | Method or action to be executed in the request | Yes | String | |
BusinessUnitId | Identifier of the business unit | Yes | Integer | |
PartnerId | Partner identifier | Yes | Integer | |
Bank | Bank code of the user performing the action | Yes | String | |
Payer.BankBranch | Bank branch code of the user performing the action | Yes | String | |
BankAccount | Bank account number of the user performing the action | Yes | String | |
BankAccountDigit | Bank account digit of the user performing the action | Yes | String |
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"
}
]
}
Parameter | Description | Mandatory | Type | Comments |
---|---|---|---|---|
Method | Method or action to be executed in the request | Yes | String | |
BusinessUnitId | Identifier of the business unit | Yes | Integer | |
PartnerId | Partner identifier | Yes | Integer | |
Bank | Bank code of the user performing the action | Yes | String | |
Payer.BankBranch | Bank branch code of the user performing the action | Yes | String | |
BankAccount | Bank account number of the user performing the action | Yes | String | |
BankAccountDigit | Bank account digit of the user performing the action | Yes | String |
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
}
Parameter | Description | Mandatory | Type | Comments |
---|---|---|---|---|
Method | Method or action to be executed in the request | Yes | String | |
BusinessUnitId | Identifier of the business unit | Yes | Integer | |
PartnerId | Partner identifier | Yes | Integer | |
RecurrenceId | Recurrence identifier | Yes | String | |
ScheduledId | Identifier for the scheduled transaction | No | String |
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"
}
Parameter | Description | Mandatory | Type | Comments |
---|---|---|---|---|
Method | Method or action to be executed in the request | Yes | String | |
BusinessUnitId | Identifier of the business unit | Yes | Integer | |
PartnerId | Partner identifier | Yes | Integer | |
RecurrenceId | Recurrence identifier | Yes | String | |
Description | Description of the transaction or charge | Yes | String | |
Payer | Object containing payer information | Yes | Object | |
Payer.TaxNumber | CPF/CNPJ of the Payer | Yes | String | |
Payer.Name | Payer's name | Yes | String | |
Payer.Ispb | ISPB code of the payer's institution | Yes | String | |
Payer.Bank | Payer's bank code | Yes | String | |
Payer.BankBranch | Payer's bank branch code | Yes | String | |
Payer.BankAccount | Payer's bank account number | Yes | String | |
Payer.BankAccountDigit | Payer's bank account digit | Yes | String | |
Payer.ZipCode | Payer's postal code or city | Yes | String | |
Timestamp | Timestamp of the webhook event | Yes | String |
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.
Updated about 5 hours ago