Payer Journey

The payer journey allows a company or individual to set up automatic payments via Pix, defining recurrences, maximum values, credit lines, and notifications. Unlike other recurring payment methods, such as traditional direct debit, Automatic Pix offers greater control to the payer, who can manage authorizations directly through their financial institution’s app.

❗️

Regulatory Obligation

How It Works?

• Pre-Authorization: The payer grants authorization for recurring payments to a receiver, establishing specific conditions for the transactions.
• Automatic Execution: Payments are made automatically on the agreed dates, respecting the pre-authorized conditions.
• Payer Control: The payer has the freedom to check, modify, or cancel the recurrence at any time, ensuring complete autonomy.
• Security and Transparency: All transactions are processed in the secure Pix environment, ensuring traceability and data protection.

Automatic Pix Journeys

Automatic Pix offers different flows to meet the needs of end users and business units, ensuring flexibility in payment automation. Below, we detail the four journeys available for payers:

Journey 1: Notification with Confirmation via Webhook

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

• How it works: FitBank sends a confirmation request to the BU via webhook. The BU uses the appropriate API to confirm or reject the request based on the user’s response.
• API Integration: WebhookConfirmPixAutomatic (endpoint for receiving requests) and ConfirmPixAutomatic (to confirm or reject the request).

Journey 2: QR Code Scanning for Recurrence Authorization

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

• How it works: The QR code is interpreted to extract recurrence information, and the BU confirms the authorization using the associated SearchProtocol.
• API Integration: GetInfosPixHashCode (to read the QR code) and ConfirmPixAutomatic (to confirm the authorization).

Journey 3: QR Code with Immediate Payment and Recurrence

The user scans a QR code containing both immediate payment details and recurrence data. By making the payment through the GeneratePixOut API, the Automatic Pix acceptance is processed automatically as a single action.

• How it works: The QR code is interpreted to obtain payment and recurrence information. The GeneratePixOut API processes the immediate payment and confirms the recurrence internally.
• API Integration: GetInfosPixHashCode (to read the QR code) and GeneratePixOut (for payment and automatic recurrence acceptance).

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

The user scans a QR code to make a payment, which may include recurrence data along with payment information with a due date or be a static QR code combined with recurrence data. After the payment, a recurrence offer is sent via webhook, allowing the user to decide whether to accept or decline the recurrence.

• How it works: The QR code is scanned, the payment is processed via GeneratePixOut, and FitBank sends a webhook with the recurrence offer. If accepted, confirmation is made via ConfirmPixAutomatic.
• API Integration: GetInfosPixHashCode (to read the QR code), GeneratePixOut (for payment), WebhookConfirmPixAutomatic (endpoint for receiving the request), and ConfirmPixAutomatic (to confirm or reject the request).

APIs Available for the Payer

The APIs below are exclusive to the payer journey.

1. Confirmation of Automatic Pix (Recurrence Authorization)

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

{
    "Method": "ConfirmPixAutomatic",
    "BusinessUnitId": "11427",
    "PartnerId": "564",
    "RecurrenceId": "RRR123456720240107000000001",
    "Description": "Monthly subscription charge for service 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": "Automatic Pix recurrence confirmation registered successfully",
    "RecurrenceId": "12345678901234567890123456789"
}

2. Read the QR Codes

GetInfosPixHashCode Used for reading Composite QR Codes in Journeys 2, 3, and 4.

Webhooks for the Payer

Webhooks are used to send real-time notifications about events related to Automatic Pix transactions. Below, we detail the different webhook methods available, including payload examples and descriptions of their fields.

1. ConfirmPixAutomatic

This webhook is sent when an Automatic Pix confirmation is requested, typically in Journey 1 or 4, so that the Business Unit (BU) can notify the end user and obtain authorization.

{
    "Method": "ConfirmPixAutomatic",
    "PartnerId": 657,
    "BusinessUnitId": 11665,
    "RecurrenceId": "RR20250715703179819P6TN2OUFW8",
    "Description": "new winds broadband internet",
    "Payer": {
        "Name": "Etevaldo MT",
        "TaxNumber": "98905764061",
        "BankCode": "450",
        "BankISPB": "13203354",
        "BankBranch": "0001",
        "BankAccount": "408505",
        "BankAccountDigit": "5",
        "ZipCode": "2304103"
    },
    "Timestamp": "2025-07-15T11:13:09.2348675-03:00"
}

2. NotifyRecurrenceCanceled

This webhook notifies when a recurrence has been canceled by the receiver.

{
    "Method": "NotifyRecurrenceCanceled",
    "BusinessUnitId": 11665,
    "RecurrenceId": "RR2025071517611176B7XLH0W3KBC",
    "Description": "Recurrence canceled by the receiver",
    "Details": {
        "ReceiverName": "COMPUTADORES OCSIS S/A",
        "Description": "new winds broadband internet",
        "PendingPayments": "NaiBsj5eCLFhMYcN3FBim6KgoTi2ASj4Tw8",
        "Guidance": "Recurrence canceled by the receiver. New schedules will be suspended"
    },
    "Timestamp": "2025-07-15T11:05:16.939366-03:00"
}

3. NotifyLimit

This webhook is sent when the transaction value exceeds the configured per-transaction limit.

{
    "Method": "NotifyLimit",
    "BusinessUnitId": 11665,
    "RecurrenceId": "RR2025071594938451H2W9YMSRQG6",
    "Description": "Pix payment transaction value exceeds the Transaction Limit for this operation",
    "Details": {
        "ReceiverName": "COMPUTADORES OCSIS S/A",
        "Value": 1001.00,
        "Guidance": "Please try again later or contact the receiver"
    },
    "Timestamp": "2025-07-15T10:57:01.0223579-03:00"
}

4. NotifyValueExceed

This webhook is sent when the payment value exceeds the allowed limit for the operation.

{
    "Method": "NotifyValueExceed",
    "BusinessUnitId": 11665,
    "RecurrenceId": "RR20250715803986008I2Y4LB9S9O",
    "Description": "Payment value exceeds the allowed limit",
    "Details": {
        "ReceiverName": "COMPUTADORES OCSIS S/A",
        "Value": 1001.00,
        "Guidance": "Please contact the receiver to adjust the value"
    },
    "Timestamp": "2025-07-15T10:34:09.8100998-03:00"
}

5. NotifyOperationalFailure

This webhook notifies operational failures in payment processing.

{
    "Method": "NotifyOperationalFailure",
    "BusinessUnitId": 11665,
    "RecurrenceId": "RR202507106706383424EJPKFTZ66",
    "Description": "Operational failure in payment",
    "Details": {
        "ReceiverName": "COMPUTADORES OCSIS S/A",
        "Value": 0.01,
        "Guidance": "Please try again later or contact the receiver"
    },
    "Timestamp": "2025-07-11T09:15:31.7035239-03:00"
}

📘

For better management of cancellation, change, and consult, we have shared APIs for payer and receiver, available here .