There are several ways to set up subscriptions into your Hosted Payment Page integration. Depending on your needs, you can create a product in your Mportal Payment Page settings, pass product parameters as a Custom Subscription Product, or charge clients periodically using API. Here are all the ways you could set up your subscription flow:
1. Creating a Subscription product in Mportal
2. Custom Subscription Product API
4. Retry logic
Creating a Subscription product in Mportal
This flow works best for a subscription logic that has set amounts and defined periods (for example 4.99 EUR a month, 9.99 EUR a week)
- Log in to your Mportal account (or sign up if you haven't already)
- Go to Payment Pages section and create a payment page.
Fill out all sections (General, Payment Methods, Payment forms, Shop Hosts) with the valid information. - In the section Products click Create product
- Choose product type - Subscription and fill out the fields according to your business logic. Do not forget to switch the toggle below to activate the product.
Note! Example values Lenght - 1 and Period - Month will create a subscription that charges the user every month. If you select, for example, Lenght - 2 and Period - Week, the user will be charged every two weeks.
Note! Discount is applied only for the first payment - By clicking Show custom parameters, you can set up optional parameters for your subscription:
Product ID: by default ID is assigned automatically, but you can change it to the value you need.
Billing cycles: how many times your subscription will run. For example, Billing cycles = 2 means that the user will be charged once a month for 2 months total and then the subscription is automatically deactivated. Same logic applies to Billing cycles = 3, 4, 5 and so on.
Note! The exception to the rule is billing cycles = 1, the client will be charged 2 times total. This is because for a payment to be considered a Subscription in our system, it has to have an initial payment (first payment made by customer using card details) and rebill (automatic charge with saved card details).
Subscription end date: date of when you want the subscription to be deactivated. For example, if you set the end date to 2024/12/31, this will mean that the subscription will be deactivated that day and the client will no longer be charged past this date.
Note! It's best to either set billing cycles OR subscription end date, since they are two separate logics for subscription deactivation. If you do not restrict the subscription by any of these logics, Maxpay will charge the user until one of his payments fails, and then the subscription will become inactive automatically. See Retry logic section below.
Trial checkbox: allows to add Trial offer as a promotional strategy for a limited period of time. The Trial price will be active for users only during the time period that is set in these settings.
Note! If Trial offer is a part of your standard business model and should be available by default (not for a limited period of time), please skip these settings and refer to the section below.
Country availability: allows to sell the subscription only for certain locations.
If your subscription logic includes a default trial offer, you can create a Trial product in Products to sell section.
- Choose product type - Trial and fill out the fields according to your business logic. Do not forget to switch the toggle below to activate the product.
- In the section Post-trial product, select your Subscription product.
- By clicking Show custom parameters, you can set up optional parameters for your subscription:
- Product ID: by default ID is assigned automatically, but you can change it to the value you need.
- Country availability: allows to sell the subscription only for certain locations. - Press Create to finish the Product setup.
- Go to section Payment Forms and copy the Embed code value in the desired format: Pop-up, Iframe or Redirect.
- Integrate the Payment Form on your website and run the code when the client wants to pay for the subscription.
- After the first payment, Maxpay will charge the client for the subscription automatically based on the logic you've set. You will receive the callback with the final status for each payment after it is processed.
Custom Subscription Product API
This flow works best for multiple subscription logics that have set amounts and defined periods. For instance, if you have subscription options like 1.99 a day, 2.99 a month, 12.99 a year and so on, you can omit the step of creating multiple products in Mportal and instead pass the parameters in the Payment Form Code.
- Log in to your Mportal account (or sign up if you haven't already)
- Go to Payment Pages section and create a payment page.
Fill out all sections (General, Payment Methods, Payment forms, Shop Hosts) with the valid information. - Skip the step of creating product in the Products to sell section and fill out the rest of the sections with the valid data using this guide.
- Go to section Payment Forms and copy the Embed code value in the desired format: Pop-up, Iframe or Redirect.
- To the copied form code, add the Custom Subscription Product parameters from our Documentation
| Parameter | Requred | Type | Description |
| productId | yes | string | The product ID. |
| productName | yes | string | The name of the product. Will be displayed on the payment page. |
| productType | yes | string | The type of product which merchant is planning to sell. Values:
|
| productDescription | no | string | Description of the product. Will be displayed on the payment page. |
| currency | yes | string | ISo3 the currency of the product. If currency wasn’t passed, the default “EUR” currency will be applied. |
| amount | yes | float | The price of the product. |
| discount | no | float | The amount of discount. |
| discountType | no | string | Discount could be set in percent of original price or in fixed amount. Applicable only for ‘fixed’ and ‘subscription’ type products. Values:
Note! Discount is applied only for the first payment |
| subscriptionLength | yes | int | The length of subscription product. |
| subscriptionPeriod | yes | string | The period of subscription. Values:
Note! Lenght - 1 and Period - Month will create a subscription that charges the user every month. If you select, for example, Lenght - 2 and Period - Week, the user will be charged every two weeks. |
| subscriptionEndDate | no | string |
The end date of the subscription Note! Subscription will be automatically deactivated after this date |
| subscriptionBillingCycles | no | int | How many times your subscription will run. For example, Billing cycles = 2 means that the user will be charged once a month for 2 months total and then the subscription is automatically deactivated. Same logic applies to Billing cycles = 3, 4, 5 and so on. |
| subscriptionTrialPrice | no | float | The price of subscription’s trial period. This price will be charged only during ‘trialStart’, ‘trialEnd’ indicated periods. |
| subscriptionTrialStart | no | string | The start date of subscription’s trial price. |
| subscriptionTrialEnd | no | string |
The end date of subscription’s trial price. Note! If Trial offer is a part of your standard business model and should be available by default (not for a limited period of time), please skip these settings and refer to the section below. |
*Note! It's best to either set billing cycles OR subscription end date, since they are two separate logics for subscription deactivation. If you do not restrict the subscription by any of these logics, Maxpay will charge the user until one of his payments fails, and then the subscription will become inactive automatically. See Retry logic section below.
If your subscription logic includes a default trial offer, you can use a Custom Trial Product API. In that case, you should create a Subscription product in Mportal and use this product's ID as your postTrialProductId
| Parameter | Requred | Type | Description |
| productId | yes | string | The product ID. |
| productName | yes | string | The name of the product. Will be displayed on the payment page. |
| productType | yes | string | trialProduct - special trial product which will transform in the indicated product. |
| productDescription | no | string | Description of the product. Will be displayed on the payment page. |
| currency | yes | string | ISo3 the currency of the product. If currency wasn’t passed, the default “EUR” currency will be applied. |
| amount | yes | float | The price of the product. |
| discount | no | float | The amount of discount. |
| discountType | no | string | Discount could be set in percent of original price or in fixed amount. Applicable only for ‘fixed’ and ‘subscription’ type products. Values:
|
| trialLength | yes | int | The length of trial product, mandatory for trialProduct type. |
| trialPeriod | yes | string | The period of trial, mandatory for trialProduct type. Values:
|
| postTrialProductId | yes | string | The ID of post-trial product, mandatory for trialProduct type. The post-trial product should be created in merchant portal. |
- Integrate the Payment Form on your website and run the code when the client wants to pay for the subscription.
- After the first payment, Maxpay will charge the client for the subscription automatically based on the logic you've set. You will receive the callback with the final status for each payment after it is processed.
Rebilling API
This flow works best for a subscription logic that has floating amounts or time periods and you need maximum control over how you charge the client.
- Log in to your Mportal account (or sign up if you haven't already)
- Go to Payment Pages section and create a payment page
- Skip the step of creating product in the Products to sell section and fill out the rest of the sections with the valid data using this guide.
- Go to section Payment Forms and copy the Embed code value in the desired format: Pop-up, Iframe or Redirect.
- Save the Payment Form and make sure the toggle is set to activate the form.
- To the copied form code, add the Custom Fixed Product parameters from our Documentation.
| Parameter | Requred | Type | Description |
| productId | yes | string | The product ID. |
| productName | yes | string | The name of the product. Will be displayed on the payment page. |
| productType | yes | string | fixedProduct - simple one time product |
| productDescription | no | string | Description of the product. Will be displayed on the payment page. |
| currency | yes | string | ISo3 the currency of the product. If currency wasn’t passed, the default “EUR” currency will be applied. |
| amount | yes | float | The price of the product. |
| discount | no | float | The amount of discount. |
| discountType | no | string | Discount could be set in percent of original price or in fixed amount. Applicable only for ‘fixed’ and ‘subscription’ type products. Values:
|
Note! Product type - Fixed is required in this case in order to not create any automated charging logic from Maxpay's side.
- Integrate the Payment Form on your website and run the code when the client wants to pay for the subscription.
- You will receive the callback with the final status of this payment. The callback will include the parameter 'token' (hashed credit card details) which should be saved.
- Once you need to charge your client for a subscription, make a Rebilling request with Fixed product
| PARAMETER | REQUIRED | DESCRIPTION |
|---|---|---|
| publicKey | yes | The public key of the application. Could be found in the general settings of the application. |
| signature | yes | Signature of the payment page. The default value of the signature from Embed code. |
| uniqueUserId | yes | The unique id of the user in your system. |
| rebillToken | yes | The unique payment token which is received in callback data after a customer made the initial payment. |
| productId | yes | A unique ID of the product. Could be found in the “Product” settings of the application. In case product is created in Maxpay merchant portal you can simply send the ‘productId’, all other parameters Maxpay will handle for you. In case you’re sending the product from your database you should pass the product parameters below. |
| productName | yes | Name of the product. |
| productDescription | optional | Description of the product. |
| productType | yes | fixedProduct - simple one time product |
| currency | optional |
Default EUR string. ISO3 currencies. |
| amount | yes | The price of the product. |
Additional parameters that can be passed for this request can be found in the documentation.
- Send the Rebilling API with Fixed product request each time you need to charge the client for a subscription
- Once you need to cancel the subscription for the client, no additional actions are required on Maxpay's side. You may simply stop sending Rebilling API requests.
Retry logic
As mentioned previously, Maxpay charges the client until one of the payments gets rejected and then subscription gets deactivated. You can set up a Retry logic to manage these cases and allow the system to reprocess the transaction later or stop retries and cancel the subscription. Please follow the instructions here or in our guide to set up a Retry logic for your business.
Cancelling subscription
If the user wants to cancel his subscription, you can do it two ways:
Cancelling via Mportal
- Go to Mportal - Customers section and find the customer by ID, email, or any other identifier
- Click on the Actions - Details to see more information about the customer
- Click on the Cancel button to cancel the subscription. This action will also send a callback to your Callback URL with the updated status of the subscription
Cancelling via API
- Send Cancel Subscription API request:
PARAMETER REQUIRED DESCRIPTION publicKey yes The public key of the application. Could be found in the general settings of the application. transactionId yes The unique id of the transaction. uniqueUserId yes The unique id of the user in your system. signature yes Signature of the payment page from Embed code.
This action will also send a callback to your Callback URL regarding the updated status of the subscription
Note! Cancelling subscription is only required when you create a subscription product in Mportal or use Custom subscription product API. If you use Rebilling API with fixed product, cancelling is not required since Maxpay has no saved subscription logic. You can simply stop sending Rebilling API requests and users will not get charged.
If you have any additional questions on this topic, please contact us at support@maxpay.com.