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.

The Role of 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.

Subscription Flow

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 not only which party is responsible for driving the subscription lifecycle, but also governing the behavior of critical financial parameters:

1. Amount Strategy (FIXED vs. VARIABLE): This setting dictates whether the Engine has the autonomy to schedule and execute payments based on a known constant value, or if it must remain passive, waiting for the Merchant to calculate and submit usage-based values for each cycle.

2. Currency & FX Logic: This defines how the system handles multi-currency scenarios. Regardless of the initiation model, the Engine provides native support for Cross-Currency transactions (e.g., defining a price in USD to charge a payer in BRL), automatically handling the foreign exchange (FX) conversion at the moment of execution without requiring manual calculation by the merchant.

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 Role: The Billing Engine operates strictly as a System of Record. It records the transaction history and updates the subscription status based on the outcome of your requests, but it will not automatically generate cycles or 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 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: Ideal for standard recurring plans with FIXED amounts (e.g., SaaS fees, memberships).

Capabilities & Constraints Matrix

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

Feature / Scenario	Engine-Driven (false)	Merchant-Driven (true)	Notes
Fixed Amount	✅ Available	✅ Available	Standard recurring model.
Variable Amount	❌ Not Available	✅ Available	The Engine cannot automate unknown values; the Merchant must provide them 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., 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.