Recurring Payments

Summary

Recurring Payments (Subscriptions) allow merchants to set up automated billing cycles for customers. Merchants can create open-ended subscriptions or fixed installment plans with configurable frequencies ranging from weekly to annual. The card can be entered by the merchant or by the customer via a hosted payment page.

Subscription Lifecycle

1. Create — Merchant creates a subscription with amount, customer, frequency, start date, and optionally a card. If the merchant enters the card, the subscription is active immediately.
2. Customer Activation — If the customer enters the card, they receive an email with a link to the hosted page. The customer enters card details and the subscription becomes active.
3. Scheduled Billing — The billing engine runs daily, identifies subscriptions due for charging, and adds them to the payment queue.
4. Charge — The payment queue processor charges the stored card. On success, the bill count increments and notifications are sent. On decline, a retry is scheduled.
5. Completion / Cancellation — Installment plans complete after the specified number of bills. Subscriptions continue until manually cancelled.

Subscription Statuses

Processing Flow

Merchant-Entered Card

Customer-Entered Card

Authentication

Merchant API (Private)

Authorization: Bearer {access_token}
Content-Type: application/json

Base URL pattern: /api/{business_id}/recurring_payments

Customer API (Public)

Public endpoints do not require authentication:

GET  /api/recurring_payments/{subscription_id}/subscribe
POST /api/recurring_payments/{subscription_id}/subscribe
PUT  /api/recurring/cancel

Create Subscription

POST /api/{business}/recurring_payments

Request Body

Card Data (when merchant enters a new card)

POST /api/{business}/recurring_payments
Content-Type: application/json
Authorization: Bearer {token}

{
  "amount": 99.99,
  "customerId": "customer-uuid",
  "startDate": "2026-03-01",
  "sequence": 3,
  "cardEntryByMerchant": false,
  "merchant_description": "Monthly membership",
  "threeDSecure": true
}

{
  "ok": true,
  "message": "Subscription created successfully",
  "subscription": {
    "id": "subscription-uuid",
    "amount": 99.99,
    "is_active": 0,
    "sequence": 3,
    "start_date": "2026-03-01"
  }
}

List Subscriptions

GET /api/{business}/recurring_payments

Returns a paginated list of all subscriptions for the business.

{
  "ok": true,
  "recurring_payments": { /* paginated collection */ },
  "filters": {
    "fromDate": "2026-01-01",
    "toDate": "2026-02-19",
    "perPage": 10
  }
}

Get Subscription Details

GET /api/{business}/recurring_payments/{subscription}

Update Subscription

PUT /api/{business}/recurring_payments/{subscription}

Updates subscription details such as amount, frequency, or description.

Delete Subscription

DELETE /api/{business}/recurring_payments/{subscription}

Resend Notification

POST /api/{business}/recurring_payments/{subscription}/resend

Re-sends the subscription activation email to the customer.

Export Subscriptions

GET /api/{business}/recurring_payments/export

Returns all subscriptions matching the filter criteria for export purposes.

View Subscription (Public)

GET /api/recurring_payments/{subscription}/subscribe

Loads the subscription details for the customer to view and activate by entering card details.

{
  "ok": true,
  "payload": {
    "reoccurringPayment": {
      "id": "subscription-uuid",
      "amount": 99.99,
      "sequence": 3,
      "start_date": "2026-03-01"
    },
    "invoice": null,
    "business": {
      "dbaName": "Acme Corp",
      "address": { /* ... */ }
    },
    "customerEmail": "[email protected]",
    "logo": "https://s3.amazonaws.com/..."
  }
}

Activate Subscription (Public)

POST /api/recurring_payments/{subscription}/subscribe

Customer submits card details to activate the subscription. The card is stored securely and the subscription becomes active.

Request Body

{
  "ok": true,
  "payload": {
    "subscription": {
      "id": "subscription-uuid",
      "is_active": 1,
      "card_id": "stored-card-uuid"
    }
  }
}

Cancel Subscription (Public)

PUT /api/recurring/cancel

Request Body

{
  "ok": true,
  "message": "Subscription cancelled successfully"
}

Frequency Options

Scheduling & Payment Queue

RapidCents uses a two-stage billing engine to process recurring payments:

Stage 1 — Subscription Scheduler

The handle:subscriptions command runs daily and evaluates all active subscriptions. For each subscription:

• Calculates the next billing date from last_transaction_date (or start_date) and sequence
• If today is the billing date and no queue entry exists, creates a PaymentQueue record with status PENDING
• Skips subscriptions that have reached their installment limit

Stage 2 — Payment Queue Processor

The app:handle-payment-queue command processes all pending queue items:

• Charges the stored card via Visa, Mastercard, Discover, or Amex
• On success: marks the queue item as FULFILLED, increments number_of_paid_bills, sends success notification
• On decline: increments the retry counter, updates last_failed_attempt_at, sends decline notification

Retry Logic

When a payment is declined, the system automatically retries based on a configurable strategy.

Card on File

Recurring payments use securely stored card tokens. The card can be stored in two ways:

• Merchant-entered card: The card is tokenized at subscription creation time and linked to the subscription.
• Customer-entered card: The customer enters card details via the hosted page, which are tokenized and stored.
• Existing saved card: The merchant can select a previously stored card using selectedCardId.

All subsequent charges use the stored card token — the raw card data is never stored or re-transmitted.

All Endpoints

Merchant Endpoints (Authenticated)

Public Endpoints (No Authentication)

Notifications

Error Handling