Billing & Subscriptions

Overview

Ionic provides comprehensive recurring billing and subscription management capabilities, allowing you to set up automatic payments, manage customer subscriptions, and process recurring charges without manual intervention.

Recurring billing integrates seamlessly with the Customer Vault to securely store payment methods and process automatic charges on schedule.

Key Features:

Flexible Scheduling - Daily, weekly, monthly, or custom frequency billing
Subscription Plans - Create and manage reusable billing plans
Automatic Retry - Smart retry logic for failed payments
Customer Management - Integrated with Customer Vault for payment storage
Real-Time Notifications - Webhook events for all subscription activities
Lifecycle Management - Add, update, pause, and cancel subscriptions via API

How Recurring Billing Works

Store Payment Method

Save customer payment information securely in the Customer Vault

Create Subscription

Set up a subscription with billing frequency, amount, and schedule

Automatic Charging

Ionic automatically charges the stored payment method on schedule

Webhook Notifications

Receive real-time notifications for successful charges, failures, and subscription changes

Manage Subscription

Update amounts, change frequency, pause, or cancel subscriptions as needed

Subscription Types

Plan-Based
Custom Subscriptions
Fixed Term
Ongoing

Pre-Defined Plans

Create reusable subscription plans with standard pricing and frequency.Use Cases:

SaaS subscriptions (Basic, Pro, Enterprise tiers)
Membership fees
Monthly service packages
Standard billing cycles

Benefits:

Consistent pricing across customers
Easy plan upgrades/downgrades
Simplified subscription management
Quick customer onboarding

recurring=add_subscription
plan_id=PRO_MONTHLY
customer_vault_id=CUST123
start_date=20251101

Flexible One-Off Subscriptions

Create custom subscriptions with unique amounts and frequencies per customer.Use Cases:

Variable pricing based on usage
Custom billing agreements
Tiered pricing by customer
Special promotional rates

Benefits:

Fully customizable per customer
Flexible frequency and amount
No plan setup required
Dynamic pricing support

recurring=add_subscription
plan_amount=99.99
plan_payments=12
day_frequency=30
customer_vault_id=CUST123

Limited-Duration Subscriptions

Subscriptions that automatically end after a set number of payments.Use Cases:

Payment plans
Fixed-term contracts
Seasonal subscriptions
Trial periods with auto-end

Configuration: Set plan_payments to the total number of charges:

recurring=add_subscription
plan_amount=49.99
plan_payments=6
month_frequency=1
# Automatically ends after 6 monthly payments

Continuous Until Canceled

Subscriptions that continue indefinitely until manually canceled.Use Cases:

Standard SaaS subscriptions
Ongoing memberships
Utility services
Continuous services

Configuration: Set plan_payments=0 for unlimited duration:

recurring=add_subscription
plan_amount=29.99
plan_payments=0
month_frequency=1
# Continues until canceled

Creating Subscriptions

API Variables

Variable	Description	Format	Required
`recurring`	Subscription action	`add_subscription`, `update_subscription`, `delete_subscription`	✅ Yes
`customer_vault_id`	Customer identifier	String	✅ Yes
`plan_id`	Plan identifier (for plan-based)	String	Optional
`plan_amount`	Recurring charge amount	x.xx	✅ Yes (if no plan_id)
`plan_payments`	Number of payments	Numeric (0=unlimited)	✅ Yes
`start_date`	First charge date	YYYYMMDD	Optional
`day_frequency`	Days between charges	Numeric	Optional*
`month_frequency`	Months between charges	Numeric	Optional*
`day_of_month`	Day to charge each month	1-31	Optional

*Either day_frequency or month_frequency is required to set billing frequency.

Implementation Examples

curl -X POST https://api.ionicfi.com/api/transact.php \
  -d "security_key=YOUR_API_KEY" \
  -d "recurring=add_subscription" \
  -d "customer_vault_id=CUST123" \
  -d "plan_amount=29.99" \
  -d "plan_payments=0" \
  -d "month_frequency=1" \
  -d "start_date=20251101"

Managing Subscriptions

Update Subscription

Change subscription amount, frequency, or plan:

curl -X POST https://api.ionicfi.com/api/transact.php \
  -d "security_key=YOUR_API_KEY" \
  -d "recurring=update_subscription" \
  -d "subscription_id=SUB123456" \
  -d "plan_amount=39.99" \
  -d "plan_id=PRO_PLAN"

Cancel Subscription

Delete a subscription to stop future charges:

curl -X POST https://api.ionicfi.com/api/transact.php \
  -d "security_key=YOUR_API_KEY" \
  -d "recurring=delete_subscription" \
  -d "subscription_id=SUB123456"

Pause and Resume

Pause Subscription

To temporarily pause a subscription, update it with a future start date:

recurring=update_subscription
subscription_id=SUB123456
start_date=20260101  # Resume January 1, 2026

Resume Subscription

To resume immediately, update with today’s or tomorrow’s date:

recurring=update_subscription
subscription_id=SUB123456
start_date=20251101  # Resume November 1, 2025

Billing Frequencies

Common Frequency Patterns

Daily
Monthly
Specific Day
Custom Intervals

day_frequency=1   # Every day
day_frequency=7   # Every week
day_frequency=14  # Every 2 weeks

month_frequency=1   # Every month
month_frequency=3   # Every quarter
month_frequency=6   # Every 6 months
month_frequency=12  # Every year

# Charge on the 1st of every month
month_frequency=1
day_of_month=1

# Charge on the 15th of every month
month_frequency=1
day_of_month=15

# Charge on last day of month
month_frequency=1
day_of_month=31  # Auto-adjusts for months with fewer days

# Every 10 days
day_frequency=10

# Every 2 months
month_frequency=2

# Every 45 days
day_frequency=45

Webhook Events

Monitor subscription activity with real-time webhook notifications:

Subscription Lifecycle Events

subscription.added
subscription.updated
subscription.deleted

Triggered when a new subscription is created.

{
  "event": "subscription.added",
  "subscription_id": "SUB123456",
  "customer_vault_id": "CUST123",
  "plan_id": "PLAN001",
  "amount": "29.99",
  "frequency": "monthly",
  "start_date": "2025-11-01",
  "total_payments": 0,
  "timestamp": "2025-10-30T10:30:00Z"
}

Use Cases:

Send welcome email
Provision account access
Update CRM records
Track subscription metrics

Triggered when subscription details are modified.

{
  "event": "subscription.updated",
  "subscription_id": "SUB123456",
  "customer_vault_id": "CUST123",
  "changes": {
    "amount": "39.99",
    "plan_id": "PLAN002"
  },
  "timestamp": "2025-10-30T11:00:00Z"
}

Use Cases:

Update account access levels
Send upgrade confirmation
Adjust billing records
Log plan changes

Triggered when a subscription is canceled.

{
  "event": "subscription.deleted",
  "subscription_id": "SUB123456",
  "customer_vault_id": "CUST123",
  "reason": "customer_request",
  "timestamp": "2025-10-30T12:00:00Z"
}

Use Cases:

Revoke account access
Send cancellation confirmation
Trigger retention workflow
Update subscription status

Payment Events

recurring.payment.success
recurring.payment.failed

Triggered when a recurring payment is processed successfully.

{
  "event": "recurring.payment.success",
  "subscription_id": "SUB123456",
  "transaction_id": "123456789",
  "customer_vault_id": "CUST123",
  "amount": "29.99",
  "payment_number": 3,
  "next_charge_date": "2025-12-01",
  "timestamp": "2025-10-30T10:30:00Z"
}

Use Cases:

Send payment receipt
Extend service access
Update billing history
Track successful charges

Triggered when a recurring payment fails.

{
  "event": "recurring.payment.failed",
  "subscription_id": "SUB123456",
  "customer_vault_id": "CUST123",
  "amount": "29.99",
  "failure_reason": "Card declined",
  "retry_attempt": 1,
  "next_retry": "2025-11-02",
  "timestamp": "2025-10-30T10:30:00Z"
}

Use Cases:

Send payment failure notification
Request payment method update
Pause account access
Trigger dunning workflow

Webhook Implementation

<?php
// Receive webhook
$payload = file_get_contents('php://input');
$data = json_decode($payload, true);

switch ($data['event']) {
    case 'subscription.added':
        handleNewSubscription($data);
        break;

    case 'subscription.updated':
        handleSubscriptionUpdate($data);
        break;

    case 'subscription.deleted':
        handleSubscriptionCancellation($data);
        break;

    case 'recurring.payment.success':
        handleSuccessfulPayment($data);
        break;

    case 'recurring.payment.failed':
        handleFailedPayment($data);
        break;
}

http_response_code(200);
?>

Failed Payment Handling

Automatic Retry Logic

Ionic automatically retries failed recurring payments:

Attempt	Timing	Action
1	Immediate	First charge attempt
2	3 days later	First retry
3	3 days later	Second retry
4	3 days later	Final retry

After all retry attempts fail, the subscription remains active but requires manual intervention. Monitor recurring.payment.failed webhooks to implement your own retry or cancellation logic.

Dunning Management

Implement dunning workflows to recover failed payments:

Detect Failed Payment

Receive recurring.payment.failed webhook notification

Notify Customer

Send email requesting payment method update

Subject: Payment Failed - Action Required

Your payment of $29.99 failed. Please update your payment
method to continue your subscription.

Restrict Access

Optionally pause service access until payment succeeds

Allow Update

Provide customer portal to update payment method via Customer Vault

Cancel if Unresolved

Cancel subscription after grace period if payment not recovered

Testing Subscriptions

Test Scenarios

Successful Recurring
Failed Payment
Expired Card

Test standard subscription flow:

curl -X POST https://api.ionicfi.com/api/transact.php \
  -d "security_key=YOUR_API_KEY" \
  -d "test_mode=1" \
  -d "recurring=add_subscription" \
  -d "customer_vault_id=TEST_CUST_1" \
  -d "plan_amount=29.99" \
  -d "plan_payments=3" \
  -d "day_frequency=1" \
  -d "start_date=20251031"

# Creates subscription charging $29.99 for 3 days
# Day 1: First charge
# Day 2: Second charge
# Day 3: Final charge (subscription completes)

Test payment failure handling:

# Create subscription with amount ending in .01 to trigger decline
curl -X POST https://api.ionicfi.com/api/transact.php \
  -d "security_key=YOUR_API_KEY" \
  -d "test_mode=1" \
  -d "recurring=add_subscription" \
  -d "customer_vault_id=TEST_CUST_1" \
  -d "plan_amount=25.01" \
  -d "plan_payments=0" \
  -d "day_frequency=1"

# First charge will fail, triggering recurring.payment.failed webhook

Test expired card handling:

# Use past expiration date
curl -X POST https://api.ionicfi.com/api/transact.php \
  -d "security_key=YOUR_API_KEY" \
  -d "test_mode=1" \
  -d "customer_vault=add_customer" \
  -d "ccnumber=4111111111111111" \
  -d "ccexp=1020" \
  -d "first_name=John" \
  -d "last_name=Doe"

# Then create subscription with this customer
# Charges will fail due to expired card

Testing Checklist

Subscription Creation

Create monthly subscription
Create weekly subscription
Create annual subscription
Create fixed-term subscription (6 payments)
Create ongoing subscription (unlimited)
Verify subscription_id returned
Verify start_date handling

Subscription Updates

Payment Processing

Webhooks

subscription.added received
subscription.updated received
subscription.deleted received
recurring.payment.success received
recurring.payment.failed received
Webhook signature verification

Lifecycle Management

Cancel subscription
Reactivate canceled subscription
Subscription completion (fixed-term)
Handle customer vault deletion
Prorated charges (if applicable)

Best Practices

Use Customer Vault

Always store payment methods in Customer Vault before creating subscriptions for PCI compliance

Set Start Dates

Specify start_date to control when first charge occurs, allowing time for account setup

Monitor Webhooks

Implement webhook handlers for all subscription events to keep your system in sync

Handle Failures Gracefully

Build dunning workflows to recover failed payments and reduce involuntary churn

Test Thoroughly

Test all subscription scenarios in test mode before going live

Provide Self-Service

Allow customers to update payment methods and manage subscriptions themselves

Communicate Clearly

Send confirmation emails for subscription changes and upcoming charges

Plan for Edge Cases

Handle expired cards, failed payments, and subscription upgrades/downgrades

Common Use Cases

SaaS Subscription Tiers

# Basic Plan - $9/month
recurring=add_subscription
plan_id=BASIC_MONTHLY
plan_amount=9.00
plan_payments=0
month_frequency=1
customer_vault_id=CUST123

# Pro Plan - $29/month
recurring=add_subscription
plan_id=PRO_MONTHLY
plan_amount=29.00
plan_payments=0
month_frequency=1
customer_vault_id=CUST456

# Enterprise Plan - $99/month
recurring=add_subscription
plan_id=ENTERPRISE_MONTHLY
plan_amount=99.00
plan_payments=0
month_frequency=1
customer_vault_id=CUST789

Membership Fees

# Annual gym membership
recurring=add_subscription
plan_amount=599.00
plan_payments=0
month_frequency=12
start_date=20251101
customer_vault_id=MEMBER001

Payment Plans

# $1,200 product paid over 12 months
recurring=add_subscription
plan_amount=100.00
plan_payments=12
month_frequency=1
start_date=20251101
customer_vault_id=CUST555

Installment Billing

# 4 quarterly payments
recurring=add_subscription
plan_amount=250.00
plan_payments=4
month_frequency=3
start_date=20251101
customer_vault_id=CUST777

Troubleshooting

Subscription Not Creating

Common Causes:

Invalid customer_vault_id
Missing required fields (plan_amount, plan_payments, frequency)
Invalid date format for start_date
Customer vault payment method expired

Solution:

Verify customer exists in vault
Check all required fields are present
Use YYYYMMDD format for dates
Verify payment method is valid

Payments Not Processing

Common Causes:

Subscription paused (future start_date)
Payment method expired
Customer vault deleted
Subscription completed (reached plan_payments)

Solution:

Check subscription status via Query API
Verify payment method in Customer Vault
Review subscription configuration

Webhooks Not Received

Common Causes:

Webhook URL not configured
Endpoint returning errors
Firewall blocking requests
SSL certificate issues

Solution:

Verify webhook URL in merchant portal
Test endpoint returns 200 OK
Check webhook logs in portal
Verify SSL certificate is valid

Failed Payment Retries

Common Causes:

Insufficient funds
Expired card
Card declined by issuer
Account closed

Solution:

Implement dunning workflow
Request updated payment method
Send customer notifications
Provide self-service update option

API Endpoint

All subscription operations use the Transaction API:

POST https://api.ionicfi.com/api/transact.php

Authentication: Include security_key parameter in all requests

Next Steps

Customer Vault

Store payment methods for recurring billing

Webhooks

Set up subscription event notifications

Payment API

Complete API reference for transactions

Testing Guide

Test your subscription implementation

Payment Variables

Full list of API parameters

Query API

Look up subscription details

Getting Started

Integration Methods

Partners

API Reference

​Overview

​How Recurring Billing Works

​Subscription Types

​Pre-Defined Plans

​Flexible One-Off Subscriptions

​Limited-Duration Subscriptions

​Continuous Until Canceled

​Creating Subscriptions

​API Variables

​Implementation Examples

​Managing Subscriptions

​Update Subscription

​Cancel Subscription

​Pause and Resume

​Billing Frequencies

​Common Frequency Patterns

​Webhook Events

​Subscription Lifecycle Events

​Payment Events

​Webhook Implementation

​Failed Payment Handling

​Automatic Retry Logic

​Dunning Management

​Testing Subscriptions

​Test Scenarios

​Testing Checklist

​Best Practices

Use Customer Vault

Set Start Dates

Monitor Webhooks

Handle Failures Gracefully

Test Thoroughly

Provide Self-Service

Communicate Clearly

Plan for Edge Cases

​Common Use Cases

​SaaS Subscription Tiers

​Membership Fees

​Payment Plans

​Installment Billing

​Troubleshooting

​API Endpoint

​Next Steps

Customer Vault

Webhooks

Payment API

Testing Guide

Payment Variables

Query API

Overview

How Recurring Billing Works

Subscription Types

Pre-Defined Plans

Flexible One-Off Subscriptions

Limited-Duration Subscriptions

Continuous Until Canceled

Creating Subscriptions

API Variables

Implementation Examples

Managing Subscriptions

Update Subscription

Cancel Subscription

Pause and Resume

Billing Frequencies

Common Frequency Patterns

Webhook Events

Subscription Lifecycle Events

Payment Events

Webhook Implementation

Failed Payment Handling

Automatic Retry Logic

Dunning Management

Testing Subscriptions

Test Scenarios

Testing Checklist

Best Practices

Common Use Cases

SaaS Subscription Tiers

Membership Fees

Payment Plans

Installment Billing

Troubleshooting

API Endpoint

Next Steps