Skip to main content

Recurring Payment Service

Overview​

The Recurring Payment Service enables you to process subscription billing and manage recurring payment mandates using the Node.js SDK. Once a customer has set up a mandate (through the Payment Service's setupRecurring), this service handles subsequent charges without requiring customer interaction.

Business Use Cases:

  • SaaS subscriptions - Charge customers monthly/yearly for software subscriptions
  • Membership fees - Process recurring membership dues for clubs and organizations
  • Utility billing - Automate monthly utility and service bill payments
  • Installment payments - Collect scheduled payments for large purchases over time
  • Donation subscriptions - Process recurring charitable donations

Operations​

OperationDescriptionUse When
chargeProcess a recurring payment using an existing mandate. Charges customer's stored payment method for subscription renewal without requiring their presence.Subscription renewal, recurring billing cycle, automated payment collection
revokeCancel an existing recurring payment mandate. Stops future automatic charges when customers end their subscription or cancel service.Subscription cancellation, customer churn, mandate revocation

SDK Setup​

const { RecurringPaymentClient } = require('hyperswitch-prism');

const recurringClient = new RecurringPaymentClient({
    connector: 'stripe',
    apiKey: 'YOUR_API_KEY',
    environment: 'SANDBOX'
});

Common Patterns​

SaaS Subscription Billing Cycle​

Process monthly subscription renewals using stored mandates.

sequenceDiagram
    participant App as Your App
    participant CS as Prism
    participant PP as Payment Provider

    Note over App: Initial setup (already done)
    Note over App: mandateReference stored from setupRecurring
    Note over App: Billing cycle (e.g., 30 days later)
    App->>CS: 1. charge (with mandateReference)
    CS->>PP: Create recurring charge using mandate
    PP-->>CS: Return charge confirmation
    CS-->>App: Return status: CHARGED
    Note over App: Next billing cycle
    App->>CS: 2. charge (with same mandateReference)
    CS->>PP: Create recurring charge using mandate
    PP-->>CS: Return charge confirmation
    CS-->>App: Return status: CHARGED
    Note over App: Customer cancels subscription
    App->>CS: 3. revoke (mandateReference)
    CS->>PP: Cancel mandate
    PP-->>CS: Return revocation confirmation
    CS-->>App: Return status: REVOKED

Flow Explanation:

  1. charge (recurring) - When a subscription billing cycle triggers, call the charge method with the stored mandateReference from the initial setupRecurring.

  2. Subsequent charges - For each subsequent billing cycle, repeat the charge method call with the same mandateReference.

  3. revoke on cancellation - When a customer cancels their subscription, call the revoke method with the mandateReference to cancel the mandate.

Next Steps​