Introduction

The Subscriptions Module provides merchants with a robust API-driven platform to orchestrate recurring payments. At the core of this service is the Subscription Billing Engine, which autonomously manages the entire agreement lifecycle from customer enrollment to recurring billing, status transitions, and dunning management.

Scenario Break Down: Choosing the Right Subscription Type

When configuring a subscription, merchants must decide between FIXED and VARIABLE amount types. This decision has significant implications for the payer experience, conversion rates, and operational complexity.

Scenario	When to Use	Supported Schemes	Recommended Setup
Truly Variable	Usage-based billing, consumption metering, variable service tiers	Cards, Pix Automático	All Schemes: subscriptionAmountType: VARIABLE
Fixed Plan with Occasional Overrides	Standard plans with rare adjustments (late fees, prorations, annual reindex)	Cards, Pix Automático	Pix Automático: subscriptionAmountType: VARIABLE Cards: subscriptionAmountType: VARIABLE OR subscriptionAmountType: FIXED using the override amount feature
Strictly Fixed	Use this when a merchant offers a subscription in the customer's local currency with a fixed amount, and the payer requires complete price certainty. This feature is powered by Pix Automático. Because the Central Bank locks the transaction amount within the payment system, neither party can change the permitted amount per charge attempt.	Pix Automático	Pix Automático: subscriptionAmountType: FIXED

Fixed Currency ≠ Fixed BRL Amount

If you set subscriptionAmountType: FIXED with a foreign currency (e.g., USD), the BRL amount charged to the payer will vary each cycle due to FX conversion at execution time. From the payer's perspective, this behaves like a VARIABLE subscription. Communicate this clearly at enrollment, or consider pricing in BRL to guarantee amount predictability.

Subscription Schemes

The engine is designed with a modular architecture driven by Payment Schemes. While the engine handles the high-level orchestration, the Scheme dictates the specific execution rules required to process that charge compliant with local regulations and provider capabilities.

A Scheme defines parameters such as:

• Execution Windows: Mandatory scheduling times (e.g., PIX Automático's 8-day window vs. Credit Card's real-time capture).
• Orchestration Logic: Whether the charge is triggered by the merchant or the engine.
• Retry Policies: Scheme-specific rules for recovering failed payments (Dunning).
• Enrollment Flows: Whether a setup requires synchronous payment or asynchronous authorization.

Supported Schemes:

• PIX Automático (Brazil) – Regulated by the Central Bank of Brazil.
• Cards (Multiple Countries) – Standard for credit/debit card recurring payments.

Subscription Flow

Guide for Merchants: Pricing Subscriptions in Local vs. Foreign Currency

When structuring recurring payments, merchants must carefully consider whether to denominate subscriptions in the local payment currency or in a foreign currency (such as USD or EUR). This decision dictates how transactions are processed, how price fluctuations are managed, and how payment schemes regulate customer consent.

Core Principles of Foreign Currency Subscription Pricing

To summarize the operational mechanics and regulatory demands of foreign currency pricing, the following matrix outlines the fundamental principles you must account for when designing your billing flow.

Pricing Principle	Operational Mechanism	Strategic Impact & Best Practice
Real-Time Conversion	Subscriptions priced in a foreign currency are converted on the fly into the customer's local payment currency at the precise moment of each charge attempt.	Merchants do not need to manage daily currency adjustments manually, as the processor handles the calculation at the spot rate.
Induced Variability	Because exchange rates fluctuate constantly, a strictly fixed price in a foreign currency will invariably result in a fluctuating charge amount in the local currency.	To prevent customer disputes and chargebacks, it is considered best practice to proactively notify payers that their local billing amount will vary due to market conditions.

The Pix Automático Particularity

While the principles above apply generally to cross-border and multi-currency recurring billing, the Central Bank of Brazil's Pix Automático framework introduces a highly specific rule regarding authorization for fixed-price foreign currency subscriptions:

• The Rule: If you offer a subscription of the type FIXED that is denominated in a foreign currency, your API request should still be transmitted with the parameter subscriptionAmountType: FIXED.
• The Payer Experience: Because the converted local amount will inevitably fluctuate, Pix Automático regulations mandate that the payer enrolls in a variable-amount modality.
• The Outcome: Consequently, while your system officially records a FIXED subscription type, the end-user will see and be required to authorize a variable amount Pix Automático agreement. Clear communication at the checkout stage is critical to ensure customers understand why a variable authorization is required for a fixed subscription.

Orchestration Models & Responsibility

The Subscriptions Module offers two distinct orchestration models, configured via the merchant_initiation flag. This parameter serves as the fundamental architectural decision for your integration, defining which party is responsible for driving the subscription lifecycle.

1. Merchant-Driven (merchant_initiation: true)

• Responsibility: The Merchant must explicitly trigger each payment attempt via the API. You are responsible for tracking due dates and calculating the amount to be charged for each cycle.
• Engine's Role: In this mode, the Billing Engine operates strictly as a System of Record for your subscription’s history. It handles the core administration of the subscription—such as creating billing cycles, tracking statuses, and mapping out the subscription's evolution over time. It will accurately record your transaction history and update subscription statuses based on the outcomes of your requests, but it will not automatically attempt charges on its own.
• Primary Use Case: Mandatory for subscriptions with VARIABLE amounts (e.g., usage-based billing) or irregular billing intervals.
• Specific Constraints: For PIX Automático, you must strict adherence to regulatory windows when triggering payments. See Merchant-Initiated Rules.

2. Engine-Driven (merchant_initiation: false)

This model leverages the full power of our automation infrastructure. Once the subscription is created, the Engine takes over the operational burden.

• Responsibility: Our Subscription Billing Engine assumes full ownership of the lifecycle orchestration.
• Engine's Role (Active): The system acts autonomously to:
  • Calculate precise due dates based on the schedule.
  • Create billing cycles automatically.
  • Orchestrate scheduling: Interact with the Financial Institution (PSP) within mandatory windows (e.g., PIX Automático 8-day window).
  • Execute charges and manage the Retry Logic (Dunning) in case of failures.
• Primary Use Case: Best for merchants without a dedicated billing system who want a fully automated, out-of-the-box subscription solution.

Capabilities & Constraints Matrix

The following table outlines the logical availability of features based on the initiation model chosen.

Amount Type Decision Guide

Not sure whether to use FIXED or VARIABLE? See Override Amount for a full scenario comparison, including FX/cross-currency caveats and communication guidelines for exceptional charges.

Feature / Scenario	Engine-Driven (false)	Merchant-Driven (true)	Notes
Fixed Amount	Available	Available	Standard recurring model.
Variable Amount	Available	Available	In engine-driven mode, the merchant must use Override Amount every time they want to change the amount for upcoming billing cycles.
Local Currency (Order = Destination)	Available	Available	E.g., Charging BRL to a Brazilian payer.
Cross-Currency (FX) (Order ≠ Destination)	Available	Available	E.g., Charging USD to a Brazilian payer. The Engine handles the conversion automatically.

---

Data Model: Subscription Entity

The Subscription entity is the central component representing the recurring agreement.

Field	Type	Description
subscriptionId	UUID	Unique identifier generated by the system.
referenceId	String	Merchant's unique identifier for reconciliation.
person	Object	Customer/Payer information.
schedule	Object	Defines timing (startDate, endDate, periodicity).
schedule.billingCycle	Enum	WEEKLY, MONTHLY, QUARTERLY, HALF_YEARLY, YEARLY.
schedule.forceWorkDay	Boolean	If true, non-business due dates are adjusted to the next business day.
amount	Object	Financial value (orderAmount, currency).
type	Enum	FIXED or VARIABLE.
subscriptionScheme	Enum	The payment method (e.g., PIX_AUTOMATICO).
status	Enum	CREATED, PENDING, DECLINED, ERROR, ACTIVE, REJECTED, EXPIRED, PAST_DUE, UNPAID, SUSPENDED, FINISHED, CANCELED, REVOKED
retryPolicy	String	Identifier code for the dunning policy (e.g., 002).

Subscription Status Map

The Subscription entity functions as a state machine. Its status transitions are driven by three primary factors:

1. Enrollment Events: The authorization process with the Financial Institution (PSP).
2. Billing Results: Success or failure of recurring charges (including retries).
3. Manual Interventions: Actions triggered by the merchant (e.g., suspension, cancellation) or the payer (e.g., revocation).

State Transition Diagram

The following flowchart illustrates all valid transitions within the subscription lifecycle.

1. Onboarding & Enrollment Phase

Statuses related to the setup of the subscription and the initial authorization with the PSP.

Status	Description
CREATED	The subscription object has been initialized in our system but the enrollment request has not yet been sent to the PSP.
PENDING	The enrollment request has been sent and is awaiting Payer authorization (e.g., via Bank App) or PSP confirmation.
ACTIVE	The Goal State. The enrollment is authorized, and the subscription is healthy, valid, and ready to process charges according to the schedule.
DECLINED	The enrollment request was immediately declined by the PSP (e.g., invalid data or business rules).
REJECTED	The payer actively rejected the enrollment request in their banking app, or the PSP rejected it after analysis.
EXPIRED	The time window for the payer to authorize the enrollment (QR Code) has elapsed without action.
ERROR	A technical error occurred during the setup process preventing the enrollment.

2. Operational & Billing Phase

Statuses indicating the ongoing health of an active subscription based on payment performance.

Status	Description
PAST_DUE	A scheduled payment failed, but the Retry Policy is still active. The system will attempt to charge again within the defined window.
UNPAID	All retry attempts defined in the policy have failed. The subscription remains valid but is in default.
SUSPENDED	The merchant has manually paused the subscription. No new charges will be generated until it is reactivated.

3. Terminal States

Final states from which a subscription typically cannot return to ACTIVE (unless a new enrollment is created).

Status	Description
FINISHED	The subscription has reached its natural endDate as defined in the schedule.
CANCELED	The subscription was manually terminated by the merchant or the system (e.g., due to long-term default).
REVOKED	Critical State. The underlying authorization was revoked by the Payer directly at their bank or by the Financial Institution. No further charges are possible.