Introduction

Pix Automático is a payment solution developed by the Central Bank of Brazil to automate Merchant Initiated Transactions. The process follows a structured sequence:

1. Subscription Creation & Enrollment: Once a subscription is created, the user must provide an "Enrollment" authorization via their banking app.
2. Billing Cycle Generation: Upon successful authorization, the Billing Cycle is created based on the subscription's defined periodicity.

Crucially, the Billing Cycle is generated regardless of the merchant_initiation setting (true or false). Even if the Merchant is responsible for the scheduling and payment request, the Billing Cycle remains the core entity responsible for:

• Controlling the subscription status.
• Verifying payments.
• Dispatching necessary notifications and webhooks back to the Merchant.

Core Rules & Constraints

• Provider Consistency: To ensure security, all transactions for a specific subscription including enrollment, the initial charge, and all subsequent retries must be processed through the same provider.
• Mandatory Scheduling: PIX Automático requires payments to be scheduled in advance. The Engine handles this automatically during the "Scheduling Window" for subscriptions.
  • Minimum Setup Time: Due to these mandatory scheduling windows, the dueDate (start date) for a new subscription must be set to at least 2 days after the current date (Today + 2 days).

Capabilities & Constraints Matrix (PIX Automático)

The following table outlines the logical availability of features for the PIX Automático scheme based on the chosen initiation model.

Feature / Scenario	Engine-Driven (false)	Merchant-Driven (true)	Notes
Fixed Amount	✅ Available	✅ Available	Standard recurring model.
Variable Amount	❌ Not Available	✅ Available	Requires merchant_initiation: true as the Merchant must provide the specific value per cycle.
Local Currency (Order = Destination)	✅ Available	✅ Available	E.g., Charging BRL to a Brazilian payer.
Cross-Currency (FX) (Order ≠ Destination)	✅ Available	✅ Available	E.g., Defining a price in USD. The Engine automatically handles conversion to BRL at the time of execution.

Lifecycle Windows

The engine manages the billing cycle based on rigid time windows defined by regulation. All times are relative to the cycle's dueDate.

Window Phase	Start Time	End Time	Description
Scheduling	dueDate - 8 days	dueDate - 2 days	Critical. The engine (or Merchant) sends the scheduling request. If missed, the payment cannot be processed.
Charge (Payer's Bank)	dueDate + 00:00	dueDate + 06:00	The actual debit attempt occurs on the due date.
Charge 2 (Intra-day)	dueDate + 18:00	dueDate + 23:00	Secondary execution window on the same day.
Retry Window	dueDate + 1 day	dueDate + 7 days	If previous attempts fail, subsequent retries occur here (up to 3 attempts).

---

Supported Configurations

For PIX Automático, the Subscription entity supports the following specific parameters:

• Amount Types:
  • FIXED: Supported.
  • VARIABLE: Supported (Requires merchant_initiation: true).
• Retry Policies:
  • 001: NOT_ALLOW (No retries).
  • 002: ALLOW_3_RETRIES_7_DAYS (Up to 3 retries within the 7-day window).

---

Operational Flows

Enrollment Only

Used when the customer authorizes future payments without an immediate charge.

1. Creation: Status is PENDING until user authorization.
2. Cycle Management: The Engine waits until the date enters the Scheduling Window (dueDate - 8 days) to create the cycle and schedule the charge.

Payment on Enrollment

Used when the customer pays for the first cycle and authorizes the subscription simultaneously.

1. Creation: Subscription and first Billing Cycle created immediately.
2. Processing: The first cycle bypasses the Scheduling Window and moves directly to the CHARGE phase.
3. Outcome: If successful, status becomes ACTIVE. If failed, REJECTED (no retries allowed for enrollment).

---

Cycle Calculation & Edge Cases

The dueDate is the primary anchor for all calculations.

• Month-End Logic: Automatically adjusts dates for shorter months (e.g., Jan 31st results in a Feb 28th/29th due date).
• The forceWorkDay Flag:
  • If true, weekend/holiday due dates move to the next business day.

---

Merchant-Initiated Orchestration

Specifics for merchant_initiation: true with PIX Automático.

When operating in this mode, your system acts as the initiation engine. You must:

1. Send payment/schedule requests to the designated API endpoint.
2. Strictly adhere to the Lifecycle Windows defined above (e.g., you cannot schedule a payment after Day -2).
3. Listen to webhooks to update the Billing Cycle and Subscription status in your local records.