# Subscription Concepts

# 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](#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](#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**:

```json
{
  "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**:

```json
{
  "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**:

1. Merchant creates subscription with `authorizationType: "BACKGROUND"`
2. System sends authorization request to user's bank
3. Bank sends push notification to user
4. User authorizes in their banking app
5. 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**:

1. Merchant creates subscription with `authorizationType: "USER_INTERACTION"`
2. System generates QR code and EMV code
3. User scans QR code or copies EMV code ("copia e cola")
4. User authorizes in their banking app
5. 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**:

```json
{
  "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](automatic-scheduling.md)**: Learn how automatic payment scheduling works
* **[Retry Policies](retry-policies.md)**: Understand retry policy configuration and behavior
* **[Webhooks and Notifications](webhooks-and-notifications.md)**: Set up event notifications
* **[PIX Automatic Overview](../payment-methods/pix-automatic/overview.md)**: Learn about PIX Automatic specifics