PIX Automatic Overview

What is PIX Automatic?

PIX Automatic is Brazil's instant payment system for recurring payments, developed and regulated by the Central Bank of Brazil (Banco Central do Brasil - Bacen). It enables merchants to automatically charge customers' bank accounts on a recurring basis.

Important: While PIX uses instant payment technology, PIX Automatic payments must be scheduled 2-10 days before the due date as required by Bacen regulations (BCB IN 513). The payment is processed on the scheduled date, and settlement occurs instantly after processing.

PIX Automatic builds on the success of PIX (instant payments) by adding support for scheduled and recurring transactions, making it ideal for subscription services, recurring bills, and membership programs.

Key Characteristics

Payment Scheduling

PIX Automatic payments must be scheduled 2-10 days before the due date (as required by Bacen regulation BCB IN 513). Once the scheduled date arrives and the payment is processed, settlement occurs instantly, providing immediate access to funds.

24/7 Availability

PIX Automatic operates 24 hours a day, 7 days a week, including weekends and holidays, allowing for flexible payment scheduling.

Wide Adoption

PIX is Brazil's most widely used payment method, available across all major banks and fintech apps, ensuring broad customer reach.

Low Cost

For individuals, PIX transactions are free, making it an attractive payment method for customers.

Regulatory Requirements

PIX Automatic is regulated by the Brazilian Central Bank through several normative instructions:

BCB Normative Instruction 508

Requires that the system undergoes homologation (certification) and testing processes before going live. This ensures the system meets Bacen's quality and security standards.

BCB Normative Instruction 511

Defines operational procedures that must be followed, including:

• How to handle errors
• Notification requirements
• Communication protocols between payment service providers and banks

BCB Normative Instruction 512

Establishes transaction limits and value restrictions for Automatic PIX payments. The system must validate that payment amounts comply with these limits before processing.

BCB Normative Instruction 513

Specifies message formats and timelines for Automatic PIX operations, including:

• Payment instructions must be sent 2-10 days before the due date
• Cancellations must be requested before 22:00 (Brasil time) on the day before settlement
• Specific time windows for payment processing

Key Benefits

For Merchants

• Instant Settlement After Processing: Once processed on the scheduled date, funds are available immediately
• High Success Rates: Automatic retry mechanisms improve payment success
• Regulatory Compliance: Built-in compliance with Bacen regulations
• Automated Processing: No manual intervention required for recurring payments
• Wide Customer Base: Access to millions of PIX users in Brazil

For Customers

• Free Transactions: No fees for PIX payments
• Scheduled Processing: Payments are scheduled 2-10 days in advance and processed on the due date
• Easy Authorization: Simple authorization through banking apps
• Control: Customers can revoke authorization at any time
• Transparency: Clear visibility of recurring charges

Differences from Other Payment Methods

vs. Credit Card Subscriptions

vs. Bank Transfers (TED/DOC)

Authorization Journeys

PIX Automatic supports two authorization journeys:

Journey 1: Push (BACKGROUND)

The user authorizes the subscription through a push notification sent to their banking app. This provides a seamless experience with no interaction required at the time of subscription creation.

Best for: When you have the user's bank account information and want a frictionless experience.

Learn more about Journey 1 →

Journey 2: QR Code (USER_INTERACTION)

The user scans a QR code to authorize the subscription. This provides explicit consent and greater visibility for the user.

Best for: When you want explicit user consent at the moment of creation or don't have bank account information.

Learn more about Journey 2 →

Compliance and Requirements

PIX Automatic has specific requirements that must be followed:

Payment Timing

• Payments must be scheduled 2-10 days before the due date
• Payments are processed during specific time windows (0:00-8:00 BRT)

Retry Policy

• Maximum 3 retries within 7 consecutive days
• Specific time windows for retry attempts
• Automatic compliance with Bacen regulations

Cancellation Deadlines

• Payments can only be cancelled before 22:00 (Brasil time) on the day before settlement
• After this deadline, cancellation is not permitted

Authorization Requirements

• Users must explicitly authorize subscriptions before any payment can be processed
• Authorization can be revoked by the user at any time

Learn more about compliance requirements →

Next Steps

• Authorization Journeys: Understand the two authorization flows
• Compliance Requirements: Learn about regulatory requirements
• PIX Specific Features: Explore PIX-specific functionality
• Getting Started: Create your first PIX Automatic subscription

PIX Automatic Authorization Journeys

PIX Automatic supports two authorization journeys that determine how users authorize their subscriptions. The journey you choose depends on your use case and whether you have the user's bank account information.

Journey 1: Push (BACKGROUND)

Overview

Journey 1 uses a push notification sent to the user's banking app. The user authorizes the subscription directly in their bank's mobile application without any interaction required at the time of subscription creation.

When to Use

• You have the user's bank account information (account number, bank code, account type)
• You want a seamless, frictionless user experience
• The user has already provided their banking details during registration or checkout

Flow

1. Merchant creates subscription with authorizationType: "BACKGROUND" and provides bank account details
2. System sends authorization request to the user's bank
3. Bank sends push notification to the user's mobile banking app
4. User opens banking app and sees the authorization request
5. User authorizes the subscription in their banking app
6. Subscription becomes ACTIVE automatically
7. Merchant receives webhook notification (subscription_activation)

Required Fields

When creating a subscription with Journey 1, you must provide bank account information:

{
  "authorizationType": "BACKGROUND",
  "authorizationDetails": {
    "bankAccount": "12345",
    "bankCode": "001",
    "accountType": "CHECKING"
  }
}

Fields:

• bankAccount: User's bank account number
• bankCode: Bank code (e.g., "001" for Banco do Brasil)
• accountType: Account type (e.g., "CHECKING", "SAVINGS")

Advantages

• Seamless Experience: No interaction required at subscription creation time
• User-Friendly: User authorizes in their familiar banking app
• Faster Onboarding: Can be done asynchronously after subscription creation
• Higher Conversion: Less friction in the subscription flow

Considerations

• Requires bank account information upfront
• User must have push notifications enabled in their banking app
• Authorization happens asynchronously (may take a few minutes)
• Subscription remains in PENDING_USER_AUTH status until authorized

Journey 2: QR Code (USER_INTERACTION)

Overview

Journey 2 requires the user to scan a QR code with their banking app to authorize the subscription. This provides explicit consent at the moment of subscription creation.

When to Use

• You don't have the user's bank account information
• You want explicit user consent at the moment of creation
• You want to show the user exactly what they're authorizing
• You prefer a synchronous authorization flow

Flow

1. Merchant creates subscription with authorizationType: "USER_INTERACTION"
2. System generates QR code and returns it in the response
3. Merchant displays QR code to the user (on screen, in email, etc.)
4. User scans QR code with their banking app
5. User authorizes the subscription in their banking app
6. Subscription becomes ACTIVE automatically
7. Merchant receives webhook notification (subscription_activation)

Response Format

When creating a subscription with Journey 2, the response includes checkout information:

{
  "subscriptionId": "660e8400-e29b-41d4-a716-446655440001",
  "status": "PENDING_USER_AUTH",
  "checkout": {
    "checkoutUrl": "https://checkout.payretailers.com/qr/...",
    "payload": {
      "code": "00020126580014br.gov.bcb.pix...",
      "image": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
    }
  }
}

Fields:

• checkout.checkoutUrl: URL where the user can view and scan the QR code (optional)
• checkout.payload.code: EMV code (PIX "copia e cola" - copy and paste code)
• checkout.payload.image: Base64-encoded QR code image (can be displayed directly in HTML)

Displaying the QR Code

Option 1: Display QR Code Image Directly

Use the base64 image from checkout.payload.image:

<img src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..." alt="Scan to authorize subscription" />

Option 2: Provide "Copia e Cola" (Copy and Paste) Option

Use the EMV code from checkout.payload.code to allow users to copy and paste the PIX code:

<div>
  <p>Scan the QR code or copy the PIX code:</p>
  <img src="data:image/png;base64,..." alt="QR Code" />
  <textarea readonly>00020126580014br.gov.bcb.pix...</textarea>
  <button onclick="copyToClipboard()">Copy PIX Code</button>
</div>

Option 3: Redirect to Checkout URL

If checkout.checkoutUrl is provided, you can redirect users:

window.location.href = checkout.checkoutUrl;

Option 4: Open Checkout URL in Modal/Iframe

// Open in modal
window.open(checkout.checkoutUrl, 'Authorization', 'width=600,height=800');

Advantages

• Explicit Consent: User explicitly authorizes at the moment of creation
• No Bank Account Required: Don't need bank account information upfront
• Visual Confirmation: User sees exactly what they're authorizing
• Synchronous Flow: Can wait for authorization before proceeding

Considerations

• Requires user interaction at subscription creation time
• User must have a banking app installed
• QR code must be displayed to the user
• May add friction to the subscription flow

Journey Comparison

Choosing the Right Journey

Use Journey 1 (Push) When:

• ✅ You collect bank account information during registration
• ✅ You want the smoothest user experience
• ✅ Users are already logged in and have provided banking details
• ✅ You're okay with asynchronous authorization

Use Journey 2 (QR Code) When:

• ✅ You don't collect bank account information upfront
• ✅ You want explicit consent at the moment of creation
• ✅ You want to show users what they're authorizing
• ✅ You prefer a synchronous authorization flow

Authorization Status

Both journeys result in the same subscription statuses:

PENDING_USER_AUTH

The subscription is created and waiting for user authorization. The subscription remains in this status until the user authorizes or rejects it.

ACTIVE

The user has authorized the subscription. Payments can now be processed according to the subscription schedule.

REJECTED

The user rejected the subscription authorization. No payments will be processed.

Webhook Notifications

You'll receive webhook notifications for authorization events:

subscription_activation

Triggered when the user authorizes the subscription (both journeys):

{
  "eventType": "subscription_activation",
  "entityId": "subscription-guid",
  "status": "ACTIVE",
  "eventDate": "2025-01-15T10:30:00Z"
}

subscription_rejection (if applicable)

Triggered if the user rejects the authorization:

{
  "eventType": "subscription_rejection",
  "entityId": "subscription-guid",
  "status": "REJECTED",
  "eventDate": "2025-01-15T10:35:00Z"
}

Best Practices

For Journey 1 (Push)

• Collect bank information early: Gather bank account details during registration or checkout
• Set expectations: Inform users they'll receive a push notification
• Monitor status: Check subscription status periodically until it becomes ACTIVE
• Handle timeouts: Consider what to do if authorization doesn't happen within a reasonable time

For Journey 2 (QR Code)

• Display QR code prominently: Make it easy for users to scan
• Provide instructions: Tell users to scan with their banking app
• Mobile-friendly: Ensure QR code is easily scannable on mobile devices
• Handle expiration: QR codes may expire; be prepared to regenerate if needed

Next Steps

• Compliance Requirements: Learn about regulatory requirements for PIX Automatic
• PIX Specific Features: Explore PIX-specific functionality
• Getting Started: Create your first subscription

PIX Automatic Compliance Requirements

PIX Automatic is regulated by the Brazilian Central Bank (Banco Central do Brasil - Bacen) through several normative instructions. This document outlines the key compliance requirements that affect how you integrate with PIX Automatic subscriptions.

Regulatory Framework

BCB Normative Instructions

PIX Automatic compliance is governed by:

• BCB IN 508: Homologation and certification requirements
• BCB IN 511: Operational procedures and error handling
• BCB IN 512: Transaction limits and value restrictions
• BCB IN 513: Message formats and timing requirements

These regulations ensure security, reliability, and consumer protection in PIX Automatic transactions.

Payment Timing Requirements

Payment Creation Window

Payments must be created between 2 and 10 days before the due date. This ensures:

• Customers receive advance notice of upcoming charges
• Sufficient time for payment processing
• Compliance with Bacen regulations

Example:

Payment Due Date: February 15, 2025
Earliest Creation Date: February 5, 2025 (10 days before)
Latest Creation Date: February 13, 2025 (2 days before)

What happens if you try to create outside this window?

• The system will reject the payment creation request
• You'll receive an error indicating the date is outside the allowed window
• You must adjust the scheduled date to comply with the requirement

Payment Processing Window

Initial payments are processed during the 0:00-8:00 AM BRT time window. This is a regulatory requirement for PIX Automatic.

Important: Payments scheduled outside this window will be processed at the next available window.

Cancellation Deadlines

Payment Cancellation Deadline

Payments can only be cancelled before 22:00 (Brasil time) on the day before settlement.

Example:

Payment Scheduled: February 15, 2025
Settlement Date: February 15, 2025
Cancellation Deadline: February 14, 2025 at 22:00 BRT

What happens if you try to cancel after the deadline?

• The cancellation request will be rejected
• You'll receive an error indicating the cancellation deadline has passed
• The payment will proceed as scheduled

Subscription Cancellation

Subscriptions can be cancelled at any time. However:

• Payments already scheduled cannot be cancelled after their deadline
• Only future payments will be prevented

Retry Policy Requirements (PIX_SPECIFIC)

The PIX_SPECIFIC retry policy is designed to comply with Bacen regulations:

Maximum Retries

• Maximum 3 retries within 7 consecutive days from the first failure
• Maximum 3 distinct days with retry attempts

Retry Timing Windows

• Initial Payment Window: 0:00-8:00 AM BRT
• Intraday Retry Window: 6:00 PM-9:00 PM BRT (18:00-21:00) - only for Retry #1 if initial payment failed between 0:00-8:00
• Next Day Retry Window: 0:00-8:00 AM BRT (for Retry #2 and #3)

Retry Restrictions

During the retry period:

• Payment amount cannot change - must remain the same as the original payment
• Subscription must remain active - cancelled or expired subscriptions cannot be retried
• Cannot exceed next billing cycle - retries must occur before the next scheduled payment

What happens if retry limits are exceeded?

• No further retries are attempted
• Payment is marked as permanently FAILED
• Merchant receives webhook notification
• Next payment in the subscription cycle proceeds as scheduled

Transaction Limits

BCB IN 512 Limits

BCB Normative Instruction 512 establishes transaction limits for PIX Automatic payments. These limits are:

• Validated automatically by the system
• Enforced before payment creation
• May vary based on account type and bank policies

What happens if you exceed limits?

• Payment creation will be rejected
• You'll receive an error indicating the limit has been exceeded
• You must adjust the payment amount to comply

Note: Specific limit values are determined by Bacen and may be updated. The system automatically enforces current limits.

Authorization Requirements

Mandatory Authorization

Users must explicitly authorize subscriptions before any payment can be processed. This is a fundamental requirement of PIX Automatic.

Authorization Methods:

• Journey 1 (Push): User authorizes via push notification in banking app
• Journey 2 (QR Code): User authorizes by scanning QR code

What happens without authorization?

• Subscription remains in PENDING_USER_AUTH status
• No payments can be created or processed
• Subscription will not become active

Authorization Revocation

Users can revoke authorization at any time through their banking app. When authorization is revoked:

• Subscription status may change
• Future payments will not be processed
• Merchant receives webhook notification
• Existing scheduled payments may be cancelled

Data Requirements

Bank Account Information

For Journey 1 (BACKGROUND authorization), you must provide:

• Bank Account Number: User's account number
• Bank Code: Valid Brazilian bank code
• Account Type: CHECKING or SAVINGS

Validation:

• All fields are validated before subscription creation
• Invalid bank codes or account numbers will be rejected
• Account must be valid and active

Customer Information

Customer information must be validated through the Customer Module:

• Customer must exist in the system
• Customer information must be accurate
• Customer must be eligible for PIX Automatic

Compliance Best Practices

Payment Scheduling

• Plan ahead: Schedule payments well within the 2-10 day window
• Monitor deadlines: Track cancellation deadlines for each payment
• Handle errors: Implement proper error handling for compliance violations

Retry Handling

• Monitor retry attempts: Track retry counts and dates
• Notify customers: Consider notifying customers after failed retries
• Handle permanent failures: Have a process for handling permanently failed payments

Authorization Management

• Collect authorization early: Request authorization as soon as possible
• Monitor authorization status: Track subscription status changes
• Handle revocations: Implement logic to handle authorization revocations

Error Handling

• Validate before creation: Check all requirements before creating payments
• Handle compliance errors: Implement specific handling for compliance-related errors
• Log compliance events: Keep records of compliance-related actions

Common Compliance Errors

Payment Date Outside Window

Error: Payment scheduled date is outside the 2-10 day window

Solution: Adjust the scheduled date to be between 2 and 10 days before the due date

Cancellation After Deadline

Error: Payment cancellation requested after 22:00 BRT deadline

Solution: Cancel payments before the deadline, or accept that the payment will proceed

Exceeded Transaction Limits

Error: Payment amount exceeds BCB transaction limits

Solution: Reduce payment amount to comply with limits, or split into multiple payments

Missing Authorization

Error: Attempting to create payment for unauthorized subscription

Solution: Ensure subscription is in ACTIVE status before creating payments

Regulatory Updates

Bacen regulations may be updated periodically. The system automatically enforces current regulatory requirements, so you don't need to update your integration when regulations change.

Important: Always refer to the latest Bacen documentation for authoritative regulatory information. This documentation reflects current system behavior, which complies with applicable regulations.

Next Steps

• Retry Policies: Learn more about retry policy implementation
• Authorization Journeys: Understand authorization requirements
• PIX Specific Features: Explore PIX-specific functionality

PIX Specific Features

This document covers PIX-specific features and identifiers that you'll encounter when working with PIX Automatic subscriptions.

PIX Identifiers

End-to-End ID (End2EndId)

The End-to-End ID is a unique identifier for each PIX transaction. It's generated by the payment provider and follows the PIX standard format.

Format: E[timestamp][random] (e.g., E1323434-acac-3214324-adasd)

Where you'll see it:

• In webhook notifications for payment events
• In payment response data
• In transaction records

Use cases:

• Track individual PIX transactions
• Reconcile payments with bank statements
• Reference specific transactions in support requests

Example in webhook:

{
  "eventType": "subscription.payment",
  "entityId": "payment-guid",
  "status": "PAID",
  "end2EndId": "E1323434-acac-3214324-adasd",
  "pspReference": "123456-7890-acasfsa-23424"
}

PSP Reference

The PSP Reference (Payment Service Provider Reference) is a unique identifier assigned by the payment provider for each transaction.

Format: Varies by payment provider (e.g., 123456-7890-acasfsa-23424)

Where you'll see it:

• In webhook notifications
• In payment response data
• In transaction records

Use cases:

• Reference transactions with the payment provider
• Track payments across different systems
• Support and troubleshooting

Example in webhook:

{
  "eventType": "subscription.payment",
  "entityId": "payment-guid",
  "status": "PAID",
  "pspReference": "123456-7890-acasfsa-23424",
  "end2EndId": "E1323434-acac-3214324-adasd"
}

Settlement Information

Settlement Process

PIX Automatic payments must be scheduled 2-10 days before the due date (Bacen requirement). Once the scheduled date arrives and the payment is processed, settlement occurs instantly, providing immediate access to funds.

Settlement Timeline:

• Scheduling: Payment is scheduled 2-10 days before the due date
• Processing: Payment is processed during the scheduled time window (0:00-8:00 AM BRT) on the due date
• Settlement: Funds are available immediately after processing
• Confirmation: Webhook notification confirms successful settlement

Settlement Times

• Initial Payments: Processed during 0:00-8:00 AM BRT window
• Retry Payments: Processed during retry windows (intraday or next day)
• Settlement: Instant after processing (payment must be scheduled 2-10 days in advance)

Bank Account Validation

Required Bank Information

For PIX Automatic subscriptions using Journey 1 (BACKGROUND authorization), you must provide:

Bank Account Number:

• User's account number
• Must be valid and active
• Format varies by bank

Bank Code:

• Brazilian bank code (e.g., "001" for Banco do Brasil)
• Must be a valid PIX-participating bank
• Validated before subscription creation

Account Type:

• CHECKING: Checking account (Conta Corrente)
• SAVINGS: Savings account (Conta Poupança)

Validation

The system validates bank account information before creating subscriptions:

• Bank code validation: Ensures bank participates in PIX
• Account validation: Verifies account exists and is active
• Account type validation: Confirms account type is valid

What happens if validation fails?

• Subscription creation is rejected
• Error message indicates the validation failure
• You must correct the information and retry

PIX-Specific Error Codes

Common PIX Error Codes

INSUFFICIENT_FUNDS:

• Customer's account has insufficient funds
• Most common reason for payment failure
• Triggers automatic retry (if retry policy allows)

ACCOUNT_CLOSED:

• Customer's bank account has been closed
• Payment cannot be processed
• May require customer to update account information

AUTHORIZATION_REVOKED:

• Customer revoked subscription authorization
• Future payments will not be processed
• Subscription may need to be re-authorized

REJECTED_BY_BANK:

• Bank rejected the payment
• May be due to account restrictions or bank policies
• Customer may need to contact their bank

PAYMENT_EXPIRED:

• Payment expired before processing
• May occur if payment is not processed within the time window
• Payment must be recreated

INVALID_ACCOUNT:

• Bank account information is invalid
• Account may not exist or be inactive
• Requires valid account information

Error Handling

When a PIX payment fails:

1. Error code is provided in the webhook notification
2. Error message explains the reason for failure
3. Retry is attempted (if retry policy allows)
4. Merchant is notified via webhook

Example error webhook:

{
  "eventType": "subscription.payment",
  "entityId": "payment-guid",
  "status": "FAILED",
  "errorCode": "INSUFFICIENT_FUNDS",
  "errorMessage": "Insufficient funds in account",
  "eventDate": "2025-01-15T05:00:00Z"
}

PIX Transaction Limits

BCB Transaction Limits

PIX Automatic payments are subject to transaction limits established by BCB IN 512. These limits:

• Are enforced automatically by the system
• Vary based on account type and bank policies
• Are validated before payment creation

What to know:

• Limits are enforced at payment creation time
• Exceeding limits results in payment rejection
• Limits may vary by bank and account type

Best practices:

• Check limits before creating payments
• Handle limit errors gracefully
• Consider splitting large payments if needed

PIX Payment Statuses

PIX payments follow the standard payment statuses, with PIX-specific behaviors:

PENDING

Payment is scheduled and waiting to be processed. For PIX:

• Payment is scheduled for the 0:00-8:00 AM BRT window
• Will be processed automatically on the scheduled date

IN_PROGRESS

Payment is being processed by the PIX network. For PIX:

• Processing happens in real-time
• Usually completes within seconds

PAID

Payment was successfully processed. For PIX:

• Funds are available immediately
• End2EndId and PSP Reference are provided
• Webhook notification confirms settlement

FAILED

Payment failed to process. For PIX:

• Common reasons: insufficient funds, account closed, authorization revoked
• Automatic retry may be attempted (if retry policy allows)
• Error code and message explain the failure

CANCELLED

Payment was cancelled. For PIX:

• Must be cancelled before 22:00 BRT on the day before settlement
• After deadline, cancellation is not permitted

PIX-Specific Webhook Fields

PIX payment webhooks include additional fields:

end2EndId: PIX End-to-End ID for the transaction pspReference: Payment Service Provider reference errorCode: PIX-specific error code (if payment failed) errorMessage: Human-readable error message

Example:

{
  "eventType": "subscription.payment",
  "entityId": "payment-guid",
  "status": "PAID",
  "eventDate": "2025-01-15T05:30:00Z",
  "pspReference": "123456-7890-acasfsa-23424",
  "end2EndId": "E1323434-acac-3214324-adasd",
  "additionalData": []
}

Best Practices

Track PIX Identifiers

• Store End2EndId: Use for transaction reconciliation
• Store PSP Reference: Use for support and troubleshooting
• Link to your records: Associate PIX identifiers with your internal records

Handle PIX Errors

• Monitor error codes: Track common error codes
• Implement retry logic: Let the system handle automatic retries
• Notify customers: Inform customers of payment failures
• Update account info: Help customers update invalid account information

Settlement Management

• Expect instant settlement after processing: PIX payments are scheduled 2-10 days in advance and settle immediately once processed
• Reconcile quickly: Use End2EndId for fast reconciliation
• Monitor status: Track payment status changes via webhooks

Next Steps

• Compliance Requirements: Understand regulatory requirements
• Authorization Journeys: Learn about authorization flows
• Retry Policies: Understand retry behavior