Introduction
Integrating an external (third-party) billing system with Muvi allows you to seamlessly manage your content and user authentication from Muvi's platform while utilizing your own billing engine and user management system. This integration allows you to create subscription plans, pay-per-view (PPV) options, and other monetization models within the Muvi platform.
To get started, you can leverage Muvi's Login/Registration APIs to create users in your Muvi apps. This ensures a smooth user experience as users can easily sign up or log in using their credentials from your existing user management system. Once users are registered or logged in, you can utilize Muvi's comprehensive features to manage content and subscriptions.
| Note: The external billing feature cannot be enabled from the Muvi CMS. To enable this feature, add a Support Ticket. |
Understanding the Authorization Model
Before accessing any of the Muvi APIs, you need to understand about authorization model. For authentication, the Access token must always be passed in the header as an Authorization bearer token. For more details, please check the help article.
| Note: Before accessing the API, please make sure you have configured the External Gateway, Currency details, Subscription Plans, Cancellation Reasons, and PPV Plans in the Muvi CMS. |
APIs Used for the Integration
We are using two types of APIs.
1. REST API (used for data writing)
2. GraphQL API (used for data read access)
The following key points are applicable for both types of APIs.
API Endpoint: https://apigateway.muvi.com
Method: POST
Header: Content Type: application/json
Authorization: Bearer Token
Parameters with asterisk (*) marks are compulsory.
Body parameters should be passed in the JSON format.
In the case of REST API, you will have to pass the request parameters with key-value pair, whereas in GraphQl API, you will have to mention the response parameters in the query request.
We have the following global parameters:
app_token: This is a unique identification key for an application.
product_key: This is a unique identification key for a product.
store_key: This is a unique identification key for an account. This is only applicable (Mandatory) for the Muvi One product.
user_uuid: This is a unique identification key for a user.
In the case of GraphQL API, you must pass the value by appending a colon (:) like below...
Eg: app_token: \":app_token\". product_key: \":product_key\". store_key: \":store_key\". user_uuid: \":me\"
<domain>: Your frontend site URL
Integrating Subscription Model
The subscription model describes a user who must pay a fixed amount at regular intervals for access to content. This module covers the following events.
Onboarding
The Onboarding API facilitates a frictionless user initiation process by enabling seamless interaction between the external vendor's platform and the Muvi system. Developers can leverage the API to effortlessly onboard users onto their subscription service, ensuring a smooth and user-friendly experience.
Recurring
Automate the recurring billing process with Muvi's platform. This essential module synchronizes billing cycles between the external vendor's system and the Muvi platform, ensuring uninterrupted service for subscribers. Developers can integrate this API to streamline periodic transactions and maintain a seamless flow of subscription services. In this process, the payment will. 1) Success 2) Fail.
In case of Success payment, the billing date will be changed to another term that a user has taken, whereas in case of the failure of the payment, the subscription will terminate right away, and that user will not be able to access the content any longer.
Cancellation
The cancellation process provides a straightforward mechanism for users to discontinue their subscriptions. Developers can implement this API to facilitate a user-friendly cancellation process, ensuring synchronization between the external vendor's platform and the Muvi system.
The cancellations can happen in three ways.
- The user cancels himself/herself.
- Admin can cancel the user’s subscription.
- The system cancels when the recurring payment fails.
Integrating the Onetime Payment (PPV) Model
This model allows you to watch content for a limited period after taking a payment. In this case like a subscription, you need to handshake the billing detail of the user with Muvi’s ecosystem.
Authorize Content by Syncing the Payment Details with Muvi
In this scenario, the payment information will be exchanged between external vendors to Muvi and Muvi will authorize the user to watch the content. The following APIs are used for this use case.
API Details
Get Order Details
The purpose of this API is to retrieve order details for users attempting to make a purchase.
HTTP Method: POST
Auth header type: Required
| Endpoint | Type | Description | Example |
|---|
| <api-gateway-domain>/transactions/get-order-details | Post | This API retrieves order details for users attempting to make a purchase. | {"sst_token":"xxxx","gateway_type":"xxxxx"} |
Request Parameter(s)
| Name | Required | Type | Values | Description |
| sst_token* | Yes | String | | A valid sst token |
| gateway_type* | Yes | String | | A valid gateway type like external,hosted and nonhosted |
Example:
| { "sst_token":"170660207726429UUWUU", "gateway_type":"external" } |
Response Parameters
| Name | Type | Description |
| code | Int | Api status code |
| status | String | Status (SUCCESS, FAILED, ….) |
| message | String | Message of api response |
| amount | String | plan amount |
| plan_type | String | Plan type ppv or subscription |
| currency_symbol | String | Currency symbol, like ‘$’, ‘₹’ |
| currency_code | String | Currency Code , like ‘USD’, ‘INR’ |
| user_name | String | Go-Global user name |
| plan_name | String | Plan name |
| plan_price | String | Plan price |
| plan_interval | Int | Plan interval |
| planInterval_unit | String | Plan interval, for example ‘Day’, ‘Month’ and ‘Year’ |
| billing_type | Int | Billing type for PPV is 4, and for subscription, it is 2. |
| content_uuid | String | Content Uuid only when plan is ppv |
| gateway_order | Object | This field content includes 'subscription_pricing_uuid', 'subscription_plan_uuid', and 'email' specifically for subscriptions. For PPV, it includes 'pricing_uuid', and for general cases, it contains 'return_url', 'cancel_url', 'first_name', and 'last_name'. |
These parameter lists are used for gatewayOrder| subscription_pricing_uuid | String | Subscription pricing uuid | | subscription_plan_uuid | String | Subscription plan uuid | | email | String | User mail id | | pricing_uuid | String | Ppv pricing uuid | | first_name | String | User first name | | last_name | String | User last name | | return_url | String | Return url for payment success | | cancel_url | String | Cancel url for payment failed or cancel |
|
Example: For Subscription
| { "amount": "100.00", "plan_type": "Subscription Plan", "code": 200, "currency_symbol": "$", "user_name": "test", "plan_price": "100.00", "plan_interval_unit": "Month", "message": "Process Completed Successfully", "currency_code": "USD", "plan_name": "test", "gateway_order": { "subscription_pricing_uuid": "123abc", "subscription_plan_uuid": "123xyz", "plan_free_trial_interval": 0, "last_name": "test", "return_url": "<domain>/en/checkout-success?billing_type=2", "first_name": "test", "cancel_url": "<domain>/en/checkout-fail?callback_url=<domain>/en", "email": "test@yupmail.com" }, "billing_type": 2, "plan_interval": 1, "status": "SUCCESS" } |
Example: For PPV
| { "amount": "30.00", "plan_type": "PPV Plan", "code": 200, "currency_symbol": "$", "user_name": "test", "plan_price": "30.00", "message": "Process Completed Successfully", "currency_code": "USD", "plan_name": "test", "gateway_order": { "country_code": "US", "pricing_uuid": "abc123", "last_name": "test", "return_url": "<domain>/en/checkout-success?billing_type=4", "plan_amount": "30.00", "first_name": "test", "cancel_url": "<domain>/en/checkout-fail?callback_url=<domain>/users-last-referring-page", "plan_name": "test name", "currency_code": "USD", "plan_description": "test description" }, "content_uuid": "123abc", "billing_type": 4, "status": "SUCCESS" } |
| URL |
| Note: Modifying the SST token is not possible after generation. Therefore Muvi would send the return_url and cancel_url along with the 3rd party Gateway URL. Use the return_url and cancel_url as they are when you redirect to Muvi. |
| Format: https://<3rd-party-domain>?muvi_sst_token=<muvi_sst_token>&return_url=<return_url>&cancel_url=<cancel_url> |
| Example: https://<3rd-party-domain>?muvi_sst_token=1706082457582326XHA3&return_url=https%3A%2F%2Fsharijchurchill-dev.allthingsott.com%2Fen%2Fcheckout-success%3Fgateway_type%3Dexternal%26muvi_sst_token%3D1706085001878HS7GWF5%26billing_type%3D4&cancel_url=https%3A%2F%2Fsharijchurchill-dev.allthingsott.com%2Fen%2Fcheckout-fail%3Fmuvi_sst_token%3D1706085001878HS7GWF5%26callback_url%3Dhttps%3A%2F%2Fsharijchurchill-dev.allthingsott.com%2Fen |
| muvi_sst_token | One-time secure token with a validity of 10 minutes. |
| return_url | Example: Encoded Format: https%3A%2F%2Fsharijchurchill-dev.allthingsott.com%2Fen%2Fcheckout-success%3Fgateway_type%3Dexternal%26muvi_sst_token%3D1706085001878HS7GWF5%26billing_type%3D4 Decoded Format: <domain>/en/checkout-success?gateway_type=external&muvi_sst_token=1706085001878HS7GWF5&billing_type=4 Upon successful payment, it should be redirected to Muvi. |
| cancel_url | Example: Encoded Format: https%3A%2F%2Fsharijchurchill-dev.allthingsott.com%2Fen%2Fcheckout-fail%3Fmuvi_sst_token%3D1706085001878HS7GWF5%26callback_url%3Dhttps%3A%2F%2Fsharijchurchill-dev.allthingsott.com%2Fen Decoded Format: <domain>/en/checkout-fail?muvi_sst_token=1706085001878HS7GWF5&callback_url=<domain>/en Upon cancellation, or failed payment should be redirected to Muvi. |
Flow Diagram
Onboarding: