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: For merchants who want to trigger each individual charge directly from their own external billing engines.
• 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 full Subscription state machine — the status transition diagram and the description of every status — now lives in Subscriptions — Status Maps & Updates, alongside its notification, callback, and update-endpoint details.

That page also explains the important distinction between a Subscription status update (a change to the recurring agreement itself) and a Payment status update for an individual charge generated by the subscription.

Notification & Callback

For status notifications, callback payloads, and how to query updates for this transaction, see Subscriptions — Status Maps & Updates.