Guides
Support
Start typing to search…

Payment Subscriptions

Subscriptions Overview

What is the Subscriptions Module?

The Payments Subscriptions API enables merchants to create and manage recurring payment subscriptions across multiple payment methods. This solution provides a unified platform for handling subscription-based payment models, supporting various payment channels including PIX, Credit Card, SPEI, Wallet, and other payment methods.

The module is designed with a generic, extensible architecture that supports different payment methods, each with their specific requirements and workflows. While the initial implementation focuses on PIX Automatic (complying with Brazilian Central Bank regulations), the architecture is extensible to support other payment methods such as card tokenization, wallet-based subscriptions, and other recurring payment models.

Main Use Cases

  • Subscription Services: Monthly, quarterly, or annual subscription services (SaaS, streaming, memberships)
  • Recurring Billing: Automatic billing for utilities, insurance, or service fees
  • Donations: Regular recurring donations to non-profit organizations
  • Installment Plans: Structured payment plans for products or services
  • Membership Programs: Gym memberships, club subscriptions, or loyalty programs

Supported Payment Methods

Currently Available

  • PIX Automatic: Recurring payments using Brazil's instant payment system (PIX), with full compliance to Brazilian Central Bank regulations (Bacen). Payments are scheduled 2-10 days before the due date as required by Bacen regulations.

Coming Soon

  • Wallet: Wallet-based recurring payments
  • SPEI: Recurring bank transfers in Mexico
  • Card Tokenization: Recurring credit/debit card payments

Key Features

Automatic Payment Scheduling

The system automatically creates recurring payments without merchant intervention. When a subscription has automatic scheduling enabled, payments are created 48 hours before the due date (configurable per payment method), ensuring timely processing while giving customers advance notice.

Benefits:

  • No manual payment creation required
  • Consistent payment timing
  • Reduced operational overhead
  • Automatic handling of payment cycles

Automatic Retry Mechanisms

When a payment fails (e.g., insufficient funds), the system automatically retries the payment according to configurable retry policies. Different payment methods have different retry rules:

  • PIX Automatic: Up to 3 retries within 7 consecutive days (Bacen requirement)
  • Other Methods: Configurable retry policies with customizable intervals

Benefits:

  • Improved payment success rates
  • Automatic recovery from temporary failures
  • Method-specific compliance with regulatory requirements
  • Reduced manual intervention

Automatic Cancellation

Subscriptions are automatically cancelled on their expiration date without requiring merchant action. This ensures clean subscription lifecycle management and prevents unauthorized charges beyond the subscription period.

Benefits:

  • Automatic lifecycle management
  • Compliance with subscription terms
  • Reduced manual cancellation workload

Subscription Product Management

Merchants can create reusable subscription product templates (billing plans) that define common subscription parameters. These products can be reused across multiple subscriptions, ensuring consistency and simplifying management.

Benefits:

  • Consistent pricing and policies
  • Centralized plan management
  • Easy updates across multiple subscriptions
  • Simplified subscription creation

Architecture Overview

The Subscriptions API is designed to be method-agnostic and extensible:

  • Consistent API: Same API interface regardless of payment method
  • Standardized Events: All payment methods use standardized webhook events
  • Extensible Design: New payment methods can be added without changing the API
  • Method-Specific Handling: Payment method requirements (regulatory, technical) are handled transparently

This design ensures that:

  • Merchants have a consistent integration experience
  • New payment methods can be added without breaking existing integrations
  • Method-specific requirements are handled automatically

Getting Started

Ready to start implementing subscriptions? Check out our Getting Started Guide for a quick walkthrough of creating your first subscription.

For detailed information about specific payment methods, see:

For API reference documentation, see the Subscriptions API Reference.

Updated about 8 hours ago