Introduction

Credit Card is a flexible subscription scheme that leverages card tokenization for recurring billing. Unlike PIX Automático, there is no enrollment step — card authorization happens on the merchant's website before the subscription request is sent to ePag. As a result, the subscription lifecycle is simpler:

CREATED → ACTIVE

Upon creation, if a valid card token is associated with the subscription, the status immediately transitions to ACTIVE and the billing engine takes over.

Core Rules & Constraints

• Provider Consistency: Payments can be processed through any provider that supports the card token in use.
• No Mandatory Scheduling: Unlike PIX Automático, there is no scheduling window. The charge is triggered directly on the dueDate.
• Cycle Creation Logic: The dueDate for each new BillingCycle is calculated by the engine based on the subscription's startDate and the defined periodicity (e.g., MONTHLY, WEEKLY).
• Amount Override: Supported — the merchant can override the charge amount on a per-cycle basis.

Capabilities & Constraints Matrix (Credit Card)

The following table outlines the logical availability of features for the CREDIT_CARD 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	⏳ Coming Soon	✅ 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.
Amount Override	✅ Available	✅ Available	Merchant can override the amount for a specific billing cycle.

Lifecycle Windows

The engine manages the billing cycle based on the following time windows. All times are relative to the cycle's dueDate.

Window Phase	Start Time	End Time	Description
Scheduling	N/A	N/A	Not applicable to Credit Card.
Charge	dueDate + 00:00	dueDate + 23:59	The actual charge attempt occurs on the due date.
Retry / Dunning	dueDate + 1 day	Varies by policy	If the initial charge fails and the retry policy allows it, subsequent attempts occur here.

---

Supported Configurations

For Credit Card, the Subscription entity supports the following parameters:

• Amount Types:
  • FIXED: The order amount is constant for every billing cycle.
  • VARIABLE: The order amount can change each billing cycle. Requires.
• Periodicities:
  • DAILY
  • WEEKLY
  • BI_WEEKLY
  • MONTHLY
  • QUARTERLY
  • HALF_YEARLY
  • YEARLY
  • CUSTOM: Define a period and a count.
    • Example: period: "month", count: 2 → every 2 months.
    • Example: period: "day", count: 45 → every 45 days.
• Retry Policies:
  • 000: CUSTOM — All retries are managed by the merchant.
  • 001: NOT_ALLOW — No retries.
  • 002: ALLOW_3_RETRIES_7_DAYS — Three attempts, one per day, for up to 7 days into the dunning period.
  • 003: ALLOW_8DAYS_4 — Attempts on days 1, 3, 5, and 8 of the dunning period.
  • 004: ALLOW_3WEEKS_5 — Attempts on days 1, 3, 7, 14, and 21 of the dunning period.
  • 005: ALLOW_P2_BACKOFF_16 — Attempts on days 1, 2, 4, 8, and 16 of the dunning period.

---

Operational Flows

Subscription with New Card (Enrollment)

Used when the merchant collects card details on their checkout and passes them to ePag for tokenization.

1. Card Data Submission: The merchant sends card details (number, expiry, CVV, holder name) along with mandatory payer fields.
2. Tokenization: ePag tokenizes the card (network token + COF) and associates the token with the subscription.
3. Activation: If tokenization succeeds and the subscription is valid, status becomes ACTIVE.

Subscription with Existing Token

Used when the merchant already holds a valid ePag card token for the payer.

1. Token Reference: The merchant provides public_person_id and public_card_id.
2. Validation: ePag validates the token.
3. Activation: If valid, subscription status becomes ACTIVE immediately.

---

Cycle Calculation & Edge Cases

The dueDate is the primary anchor for all calculations.

• Month-End Logic: Automatically adjusts dates for shorter months (e.g., a subscription starting on Jan 31st results in a Feb 28th/29th due date).
• The forceWorkDay Flag:
  • If true, weekend/holiday due dates are moved to the next business day.
• Multiple Charges on the Same Day: In DAILY subscriptions with active retry policies, it is possible for multiple billing cycles to generate charges on the same day. The subscription status is updated based on the most recently received notification for the current billing cycle.

---

Merchant-Initiated Orchestration

Specifics for merchant_initiation: true with Credit Card.

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

1. Send charge requests to the designated API endpoint for each billing cycle.
2. Provide the amount and asset per cycle when using VARIABLE amount type.
3. Listen to webhooks to update the Billing Cycle and Subscription status in your local records.