Copy of Subscriptions

Augment your subscriptions with payments orchestration capabilities

Businesses that run on subscription model powered by providers viz. Chargebee, Recurly, Stripe Billing etc. can now augment it with payments orchestration by decoupling the payments from the subscription provider and using them purely for subscription ledger and scheduling, while owning 100% of the card vaulting, payment attempts, and retry logic (owned in-house, or via an ensemble of specialized payment-focused orchestrator and other focused third parties, modularized to work with each other)

Benefits

1. Greater control over payments with direct integrations and commercials with a range of Acquirers and Payment Processors

2. Improved reliability with a multi-PSP setup

3. Intelligent Routing capabilities to improve Authorization Rates and minimize Processing costs

4. Greater coverage of PMs, APMs and features offered by the PSPs

5. Centralised tokenisation of payment methods for PSP agnostic payments

How does it work?

1. Integrate your subscription provider as a billing processor on Juspay Hyperswitch

2. Create and maintain plans on the subscription provider's dashboard

3. During the checkout process use Hyperswitch for Payments

4. Hyperswitch completes the payment, securely tokenises and stores the card

5. Subscription is created at Hyperswitch and at the subscription provider's end

6. First invoice is marked as paid and the subscription is activated

7. Subsequent billing cycles are handled independently by Hyperswitch through MIT payments

8. Failed MIT payments can be smartly retried by Hyperswitch (read more) or by the solution provider of your choice.

Flow Diagram

Initial Subscription create flow (with CIT Payment)

MIT payment flow in subsequent billing cycle

Integration Guide

1. For non-PCI compliant merchants who wants to use Hyperswitch Payments SDK

Initial Subscription create flow (with CIT Payment)

1

Configure your Subscription Provider with Hyperswitch and set it as billing connector for the desired profile

Note: Dashboard support for this configuration will be available soon

curl --location 'http://<base_url>/account/<merchant_id>/connectors' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'api-key: <api_key>' \
--data '{
    "connector_type": "billing_processor",
    "connector_name": "chargebee",
    "connector_account_details": {
        "auth_type": "HeaderKey",
        "api_key": "<api_key>",
        "site": ""
    },
    "business_country": "US",
    "business_label": "default",
    "connector_webhook_details": {
        "merchant_secret": "hyperswitch", 
        "additional_secret": "hyperswitch" 
    },
    "metadata": {
        "site": "test"
    }
}'

SET AS BILLING CONNECTOR
curl --location 'http://<base_url>/account/<merchant_id>/business_profile/<profile_id' \
--header 'Content-Type: application/json' \
--header 'api-key: <api_key>' \
--data '{
  "billing_processor_id": "<mca_id>"
}'

2

Configure Hyperswitch Webhook endpoint for invoice events on the subscription provider's dashboard

3

Fetch the plan details (to be setup prior on subscription provider)

curl --location 'http://<base_url>/subscriptions/plans' \
--header 'Content-Type: application/json' \
--header 'api-key: <api_key>'

Response:
[
    {
        "plan_id": "cbdemo_enterprise-suite",
        "name": "Enterprise Suite",
        "description": "High-end customer support suite with enterprise-grade solutions.",
        "price_id": [
            {
                "id": "cbdemo_enterprise-suite-INR-Daily",
                "name": "Enterprise Suite INR Daily",
                "pricing_model": "flat_fee",
                "price": 10000,
                "period": 1,
                "currency_code": "INR",
                "period_unit": "day",
                "free_quantity": 0,
            }]
       }
]

4

Display the retrieved Plan and Price Details to the user to make their selection

5

Once the user selects a particular Plan, create a customer on Hyperswitch (API Reference) and create a subscription with the following API

curl --location '<baseurl>/subscriptions/create' \
--header 'Content-Type: application/json' \
--header 'X-Profile-Id: <profile_id>' \
--header 'api-key: <api-key>' \
--data '{
    "customer_id": "cus_uBtUJLSVSICr8ctmoL8i",
    "amount": 14100,
    "currency": "USD",
    "payment_details": {
        "authentication_type": "no_three_ds",
        "setup_future_usage": "off_session",
        "capture_method": "automatic",
        "return_url": "https://google.com"
    }
}'

6

Initiate the Hyperswitch unified checkout SDK using the client_secret returned in the /subscriptions/create API response

When setting up subscription there are two distinct implementation flows.

The correct flow depends on whether you intend to charge the customer immediately or simply validate their details for later use.

1. The Setup with Charge Flow

Use Case: Use this when you need to collect a payment immediately (e.g., the first month of a subscription or a setup fee) while simultaneously saving the card details for future automatic charges.

Configuration Parameters :

• setup_future_usage: "off_session"

• amount > 0

2. The Zero Dollar Authorization Flow

Use Case: Use this for free trials, pay-later models, or delayed billing. This flow validates the payment method details without charging the customer's card.

Configuration Parameters :

• Pass below parameters while calling payments API for Zero Dollar Auth

• setup_future_usage: "off_session"

• amount: 0

• payment_type: "setup_mandate"

7

Once the customer selects a payment method and enters the details and confirms the subscription, hit the /subscriptions/:id/confirm using a similar implementation as this

8

Sync with the subscription status for disbursement of services and future billing cycles

2. For PCI Compliant merchants handling the entire checkout experience

1

Follow the same steps as above to create a billing connector, fetch plan details and display the retrieved Plan and Price Details to the user to make their selection

2

Once the user selects a particular Plan, create a customer on Hyperswitch (API Reference), initiate checkout and collect payment method details

3

After the user enter card/PM details and confirms the payment, hit the Hyperswitch Subscriptions API

When setting up subscription there are two distinct implementation flows.

The correct flow depends on whether you intend to charge the customer immediately or simply validate their details for later use.

1. The Setup with Charge Flow

Use Case: Use this when you need to collect a payment immediately (e.g., the first month of a subscription or a setup fee) while simultaneously saving the card details for future automatic charges.

Configuration Parameters :

• setup_future_usage: "off_session"

• amount > 0

2. The Zero Dollar Authorization Flow

Use Case: Use this for free trials, pay-later models, or delayed billing. This flow validates the payment method details without charging the customer's card.

Configuration Parameters :

• Pass below parameters while calling payments API for Zero Dollar Auth

• setup_future_usage: "off_session"

• amount: 0

• payment_type: "setup_mandate"

curl --location 'http://<baseurl>/subscriptions/' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'X-Profile-Id: pro_2WzEeiNyj8fSCObXqo36' \
--header 'api-key: dev_Ske75Nx2J7qtHsP8cc7pFx5k4dccYBedM6UAExaLOdHCkji3uVWSqfmZ0Qz0Tnyj' \
--data '{
    "item_price_id": "cbdemo_enterprise-suite-INR-Daily",
    "customer_id": "cus_NdHhw4wwWyYXSldO9oYE",
    "billing_address": {
        "address": {
            "line1": "1467",
            "line2": "Harrison Street",
            "line3": "Harrison Street",
            "city": "San Fransico",
            "state": "California",
            "zip": "94122",
            "country": "US",
            "first_name": "joseph",
            "last_name": "Doe"
        },
        "phone": {
            "number": "8056594427",
            "country_code": "+91"
        }
    },
    "payment_details": {
        "payment_method": "card",
        "payment_method_type": "credit",
        "payment_method_data": {
            "card": {
                "card_number": "4242424242424242",
                "card_exp_month": "10",
                "card_exp_year": "25",
                "card_holder_name": "joseph Doe",
                "card_cvc": "123"
            }
        },
        "setup_future_usage": "off_session",
        "customer_acceptance": {
            "acceptance_type": "online",
            "accepted_at": "1963-05-03T04:07:52.723Z",
            "online": {
                "ip_address": "127.0.0.1",
                "user_agent": "amet irure esse"
            }
        }
    }
}'

Response:

{
  "id": "subscription_wBV1G9dhh6EBhTOTXRBA",
  "merchant_reference_id": null,
  "status": "active",
  "plan_id": null,
  "price_id": null,
  "coupon": null,
  "profile_id": "profile_id",
  "payment": null,
  "customer_id": "customer_id",
  "invoice": {
    "id": "invoice_0XANlbhMp2V7wUvWRhhJ",
    "subscription_id": "subscription_wBV1G9dhh6EBhTOTXRBA",
    "merchant_id": "merchant_id",
    "profile_id": "profile_id",
    "merchant_connector_id": "mac_id",
    "payment_intent_id": null,
    "payment_method_id": null,
    "customer_id": "cus_id",
    "amount": 14100,
    "currency": "INR",
    "status": "InvoiceCreated"
  }
}

4

Sync with the status of the Subscription API to disburse services to subscribed users

curl --location 'http://<baseurl>/subscriptions/<subscripion_id>' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'X-Profile-Id: <profile_id>' \
--header 'api-key: <api_key>'

RESPONSE:
{
    "id": "<subcription_id>",
    "merchant_reference_id": "mer_ref_id",
    "status": "active",
    "plan_id": null,
    "profile_id": "<profile_id>",
    "merchant_id": "<merchant_id>",
    "coupon_code": null,
    "customer_id": "<customer_id>"
}

5

Monitor incoming webhooks for renewal during subsequent cycles

Decoupled CIT and MIT Flow

Hyperswitch supports decoupled transaction flows, allowing Merchant-Initiated Transactions (MITs) to be processed independently of the original Customer-Initiated Transaction (CIT), even when the CIT was completed outside the Hyperswitch platform.

MITs are initiated by invoking the /payments API with off_session: true and providing the available reference data in the recurring_details object. Depending on the artifacts available in your system, one of the following approaches can be used:

Processor Payment Token : Submit a processor-issued token that represents the previously authorized payment instrument.

Network Transaction ID with Card Data : Provide the original network transaction identifier along with the associated primary card data required for authorization.

Network Transaction ID with Network Token : Submit the network transaction identifier in combination with the corresponding network tokenized card credentials.

Limited Card Data : Use a reduced card data set captured at the time of subscription creation to authorize subsequent MITs.

FAQs

1. What are subscriptions providers that are currently supported?

Currently we support Chargebee integration. In the upcoming roadmap we are planning to extend support for Recurly, Stripe Billing and Zuora

2. Can the entire experience from plan display, price estimation to payments be handled by Hyperswitch SDK?

We are planning to release a Hyperswitch Subscriptions SDK that will take care of the end-to-end experience.