Skip to content
/
Subscriptions
Last updated

Subscriptions

Automate recurring payments with flexible subscription management.

Overview

Subscriptions are recurring payments of a fixed amount, automatically charged at regular intervals. They're perfect for membership services, SaaS products, and any business model requiring predictable recurring revenue.

Key Features

  • Automatic Billing: Payments processed automatically on schedule
  • Flexible Frequencies: From daily to every 3 years
  • Retry Logic: Configurable retries for failed payments
  • Fallback Methods: Secondary payment method if primary fails
  • Finite or Unlimited: Set end date/capture limit or run indefinitely
  • Easy Management: Activate, pause, update, or cancel anytime

Supported Payment Methods

  • Credit/Debit Card
  • Direct Debit

Frequency Options

FrequencyDescription
1DDaily
1WWeekly
2WBi-weekly (every 2 weeks)
1MMonthly
2MBi-monthly (every 2 months)
3MQuarterly (every 3 months)
4MEvery 4 months
6MSemi-annually (every 6 months)
1YAnnually
2YEvery 2 years
3YEvery 3 years

Subscription Lifecycle

Subscription lifecycle

Quick Start

Create a Subscription

POST /subscription

{
  "frequency": "1M",
  "value": 29.99,
  "currency": "EUR",
  "method": "cc",
  "start_time": "2024-02-01 00:00",
  "max_captures": 12,
  "customer": {
    "name": "John Doe",
    "email": "john@example.com"
  },
  "capture": {
    "descriptive": "Monthly SaaS Subscription"
  },
  "retries": 3,
  "failover": true
}

Response:

{
  "id": "sub-123",
  "status": "active",
  "frequency": "1M",
  "value": 29.99,
  "start_time": "2024-02-01 00:00"
}

Subscription Types

Finite Subscriptions

End after a specific date or number of captures:

{
  "frequency": "1M",
  "value": 9.99,
  "start_time": "2024-01-01",
  "max_captures": 12  // 12 months
}

Or:

{
  "frequency": "1M",
  "value": 9.99,
  "start_time": "2024-01-01",
  "expiration_time": "2024-12-31 23:59"  // Specific end date
}

Unlimited Subscriptions

Continue until manually cancelled:

{
  "frequency": "1M",
  "value": 9.99,
  "start_time": "2024-01-01",
  "unlimited_payments": true  // No end date
}

Cycle Types

Each subscription creates payment cycles:

  • CAPTURE_NOW: Immediate payment when subscription created
  • RENEWABLE: Regular recurring cycles based on frequency
  • ONE_TIME_CHARGE: Single isolated payment

Managing Subscriptions

Get Subscription Details

GET /subscription/{id}

Update a Subscription

PATCH /subscription/{id}

{
  "value": 39.99,  // Update amount
  "frequency": "1Y"  // Change frequency
}

Pause a Subscription

PATCH /subscription/{id}

{
  "status": "inactive"
}

Effect: All pending cycles are deleted, no further payments.

Reactivate a Subscription

PATCH /subscription/{id}

{
  "status": "active"
}

Effect: New cycles created based on current configuration.

Cancel a Subscription

DELETE /subscription/{id}

Retry Logic

Configure automatic retries for failed payments:

{
  "retries": 3  // Retry up to 3 times
}

How it works:

  1. Initial charge attempt
  2. If failed, retry
  3. Continue until success or max retries reached
  4. Trigger fallback if configured

Fallback Payment Methods (Failover)

Enable fallback to provide alternative payment options:

{
  "method": "cc",  // Primary method
  "failover": true
}

How it works:

  1. Attempt payment with primary method
  2. If fails after all retries, a failover checkout is created
  3. The checkout includes all payment methods active for your account
  4. If payment succeeds through the checkout, subscription continues
  5. If no payment is made, the cycle is marked as failed

Use Cases

SaaS Subscription

Monthly software license:

{
  "frequency": "1M",
  "value": 49.99,
  "method": "cc",
  "start_time": "2024-01-01",
  "unlimited_payments": true,
  "retries": 3
}

Annual Membership

Yearly membership fee:

{
  "frequency": "1Y",
  "value": 199.99,
  "method": "cc",
  "start_time": "2024-01-01",
  "unlimited_payments": true
}

Installment Plan

12-month payment plan:

{
  "frequency": "1M",
  "value": 83.33,
  "method": "dd",
  "start_time": "2024-01-01",
  "max_captures": 12  // Total: €999.96
}

Quarterly Service

Quarterly billing:

{
  "frequency": "3M",
  "value": 299.99,
  "method": "cc",
  "start_time": "2024-01-01",
  "unlimited_payments": true
}

Webhooks

Receive notifications for subscription events:

  • subscription_created: Sent when the user inserts their card details and the subscription is created
  • subscription_capture: Sent after all retries are made for a payment attempt (whether successful or failed)

Best Practices

  1. Clear Communication: Inform customers about subscription terms upfront
  2. Grace Periods: Consider grace periods before canceling for failed payments
  3. Easy Cancellation: Make it simple for customers to cancel
  4. Update Payment Methods: Allow customers to update payment details
  5. Transparent Pricing: Clearly display total cost and billing frequency
  6. Trial Periods: Consider free trials before first charge
  7. Prorated Charges: Handle mid-cycle plan changes gracefully

Common Scenarios

Scenario 1: Monthly SaaS

Customer subscribes to monthly software, charged automatically on the 1st of each month, continues until cancelled.

Scenario 2: Annual Membership

Customer pays yearly membership fee, receives reminder 30 days before renewal, can cancel or update payment method.

Scenario 3: 12-Month Installment

Customer buys €1000 product, pays €83.33/month for 12 months, subscription automatically ends after final payment.

Scenario 4: Quarterly Service

Service billed every 3 months, customer receives invoice 7 days before charge, payment auto-processed.

Next Steps

Previous page
Next page
© 2026 easypay - Bank of Portugal N.º 8706