Subscription Concepts

This document explains the key concepts and entities you'll work with when using the Subscriptions API.

Main Entities

Subscription

A Subscription represents a recurring payment agreement between a merchant and a customer. It defines:

The customer who will be charged
The payment method (channel) to use
The frequency of payments
The amount or amount range
The retry policy for failed payments
Whether automatic scheduling is enabled
The subscription lifecycle dates (start, expiration)

Key Properties:

subscriptionId: Unique identifier for the subscription
status: Current state of the subscription (see Subscription Statuses)
channel: Payment method (PIX, WALLET, etc.)
frequency: How often payments occur (WEEKLY, MONTHLY, etc.)
automaticScheduleAllowed: Whether the system should automatically create payments

SubscriptionProduct

A SubscriptionProduct is a reusable template that defines common subscription parameters. Instead of specifying all parameters each time you create a subscription, you can create a product once and reuse it.

Use Cases:

Standardize pricing and policies across multiple subscriptions
Simplify subscription creation
Centralize plan management
Easily update multiple subscriptions by updating the product

Key Properties:

subscriptionProductId: Unique identifier for the product
channel: Payment method this product is configured for
frequency: Payment frequency
amount: Amount configuration (fixed or variable)
retryPolicy: Retry policy configuration
isActive: Whether the product is currently active

SubscriptionPayment

A SubscriptionPayment represents a single recurring payment instance within a subscription. Each payment has:

A scheduled date when it should be processed
An amount (which may vary if the subscription allows variable amounts)
A status indicating its current state
A reference to the transaction in the Payments API

Key Properties:

subscriptionPaymentId: Unique identifier for the payment
subscriptionId: Reference to the parent subscription
status: Current state of the payment (see Payment Statuses)
scheduledDate: When the payment should be processed
payDate: When the payment was actually processed
amount: Payment amount
retryCount: Number of retry attempts made

SubscriptionPaymentRetry

A SubscriptionPaymentRetry represents a retry attempt for a failed payment. You can track retry attempts through:

Payment status updates via webhooks
Payment details in API responses (includes retry count)
Webhook notifications for each retry attempt

Information Available:

Retry count (how many times a payment has been retried)
Retry dates (when each retry was attempted)
Retry results (success or failure)

Subscription Statuses

A subscription goes through several states during its lifecycle:

PENDING_USER_AUTH

The subscription has been created but is waiting for user authorization. The user must authorize the subscription before it can become active.

Transitions to:

ACTIVE: User authorizes the subscription
REJECTED: User rejects the subscription

ACTIVE

The subscription is active and processing payments. Payments will be created and processed according to the subscription's schedule and configuration.

Transitions to:

CANCELLED: Subscription is cancelled (by merchant or user)
EXPIRED: Subscription reaches its expiration date

CANCELLED

The subscription has been cancelled. No further payments will be created or processed.

Can be cancelled by:

Merchant (via API)
User (via their bank/app)
System (automatic cancellation on expiration)

EXPIRED

The subscription has reached its expiration date and has been automatically cancelled by the system.

REJECTED

The user rejected the subscription during the authorization process. No payments will be processed.

Payment Statuses

Each payment within a subscription has its own status:

PENDING

The payment has been scheduled but not yet processed. It's waiting for its scheduled date.

Transitions to:

IN_PROGRESS: Payment processing begins
CANCELLED: Payment is cancelled before processing

IN_PROGRESS

The payment is currently being processed by the payment provider.

Transitions to:

PAID: Payment is successful
FAILED: Payment fails

PAID

The payment was successfully processed. The funds have been transferred.

FAILED

The payment failed (e.g., insufficient funds, account closed, authorization revoked). The system may automatically retry based on the retry policy.

Transitions to:

PAID: Retry is successful
FAILED: All retries exhausted, payment permanently failed

CANCELLED

The payment was cancelled before it could be processed. This can happen if:

The merchant cancels the payment
The subscription is cancelled
The payment is cancelled due to timing restrictions (e.g., PIX cancellation deadline)

Frequencies

The frequency determines how often payments occur within a subscription:

WEEKLY

Payments occur every 7 days from the start date or last payment date.

Example: If the first payment is on January 1st, the next payment will be on January 8th.

MONTHLY

Payments occur every month from the start date or last payment date.

Example: If the first payment is on January 15th, the next payment will be on February 15th.

QUARTERLY

Payments occur every 3 months from the start date or last payment date.

Example: If the first payment is on January 1st, the next payment will be on April 1st.

SEMIANNUAL

Payments occur every 6 months from the start date or last payment date.

Example: If the first payment is on January 1st, the next payment will be on July 1st.

ANNUAL

Payments occur every year from the start date or last payment date.

Example: If the first payment is on January 1st, 2025, the next payment will be on January 1st, 2026.

Amount Types

FIXED

The payment amount is fixed and cannot change. This is required for automatic scheduling.

Configuration:

{
  "amount": {
    "type": "FIXED",
    "fixedValue": 10000,
    "currency": "BRL"
  }
}

Use Cases:

Subscription services with fixed monthly fees
Membership programs with standard pricing
Any subscription where the amount doesn't vary

VARIABLE

The payment amount can vary within defined limits. Automatic scheduling is not available for variable amounts.

Configuration:

{
  "amount": {
    "type": "VARIABLE",
    "minValue": 5000,
    "maxValue": 50000,
    "currency": "BRL"
  }
}

Use Cases:

Utility bills that vary monthly
Usage-based billing
Subscriptions where the merchant needs to set different amounts per payment

Authorization Types

The authorization type determines how the user authorizes the subscription:

BACKGROUND

The user authorizes the subscription through a push notification sent to their banking app. No interaction is required at the time of subscription creation.

Flow:

Merchant creates subscription with authorizationType: "BACKGROUND"
System sends authorization request to user's bank
Bank sends push notification to user
User authorizes in their banking app
Subscription becomes ACTIVE

Required Fields:

Bank account information (account number, bank code, account type)

Use Cases:

When you have the user's bank account information
When you want a seamless user experience
For PIX Automatic Journey 1

USER_INTERACTION

The user must interact with a QR code or checkout page to authorize the subscription.

Flow:

Merchant creates subscription with authorizationType: "USER_INTERACTION"
System generates QR code and EMV code
User scans QR code or copies EMV code ("copia e cola")
User authorizes in their banking app
Subscription becomes ACTIVE

Response Includes:

checkout.checkoutUrl: URL where user can view QR code (optional)
checkout.payload.code: EMV code for "copia e cola" (copy and paste)
checkout.payload.image: QR code image (base64 encoded)

Use Cases:

When you don't have the user's bank account information
When you want explicit user consent at the moment of creation
For PIX Automatic Journey 2

Retry Policy Types

The retry policy determines how the system handles failed payments:

PIX_SPECIFIC

Automatically configured retry policy for PIX Automatic that complies with Brazilian Central Bank regulations.

Configuration:

maxRetries: 3 (fixed)
retryIntervalDays: 7 (fixed)
Maximum 3 retries within 7 consecutive days
Specific time windows for retries

Only available for: PIX channel

FIXED_RETRY

Configurable retry policy for any payment method.

Configuration:

maxRetries: Configurable (e.g., 3, 5, 10)
retryIntervalDays: Configurable (e.g., 1, 2, 7)

Example:

{
  "retryPolicy": {
    "type": "FIXED_RETRY",
    "maxRetries": 5,
    "retryIntervalDays": 2
  }
}

NOT_ALLOWED

No automatic retries will be performed. Failed payments are immediately marked as permanently failed.

Use Cases:

When you want to handle retries manually
When retries are not allowed by the payment method
For testing or specific business requirements

Next Steps

Now that you understand the key concepts, explore:

Automatic Scheduling: Learn how automatic payment scheduling works
Retry Policies: Understand retry policy configuration and behavior
Webhooks and Notifications: Set up event notifications
PIX Automatic Overview: Learn about PIX Automatic specifics