Subscriptions Providers
Businesses running on a subscription model — powered by providers such as Chargebee, Recurly, or Stripe Billing — can now augment their setup with OrchestratorX payments orchestration. By decoupling payments from the subscription provider, you use the provider purely for subscription ledger and scheduling while owning 100% of the card vaulting, payment attempts, and retry logic. This logic can be managed in-house or via an ensemble of specialized, payment-focused orchestrators and third parties that are modularized to work together.
Benefits
- Greater control over payments with direct integrations and commercials with a range of Acquirers and Payment Processors
- Improved reliability with a multi-PSP setup
- Intelligent Routing capabilities to improve Authorization Rates and minimize Processing costs
- Greater coverage of PMs, APMs and features offered by the PSPs
- Centralized tokenization of payment methods for PSP-agnostic payments
How does it work?
- Integrate your subscription provider as a billing processor on OrchestratorX
- Create and maintain plans on the subscription provider's dashboard
- During the checkout process use OrchestratorX for Payments
- OrchestratorX completes the payment, securely tokenises and stores the card
- Subscription is created at OrchestratorX and at the subscription provider's end
- First invoice is marked as paid and the subscription is activated
- Subsequent billing cycles are handled independently by OrchestratorX through MIT payments
- Failed MIT payments can be smartly retried by OrchestratorX (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 OrchestratorX Payments SDK
Configure your Subscription Provider with OrchestratorX 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>"
}'
Configure OrchestratorX Webhook endpoint for invoice events on the subscription provider's dashboard
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,
}]
}
]
Display the retrieved Plan and Price Details to the user to make their selection
Once the user selects a particular Plan, create a customer on OrchestratorX (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"
}
}'
Initiate the OrchestratorX unified checkout SDK using the client_secret returned in the /subscriptions/create API response
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
Sync with the subscription status for disbursement of services and future billing cycles
2. For PCI Compliant merchants handling the entire checkout experience
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
Once the user selects a particular Plan, create a customer on OrchestratorX (API Reference), initiate checkout and collect payment method details
After the user enter card/PM details and confirms the payment, hit the OrchestratorX Subscriptions API
curl --location 'http://localhost:8080/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"
}
}
Sync with the status of the Subscription API to disburse services to subscribed users
curl --location 'http://localhost:8080/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>"
}
Monitor incoming webhooks for renewal during subsequent cycles
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 OrchestratorX SDK?
We are planning to release a OrchestratorX Subscriptions SDK that will take care of the end-to-end experience. Check the OrchestratorX roadmap for the latest timeline.