This page is no longer supported. Please refer to the current guide for up-to-date information.

TABLE OF CONTENTS

 Subscription Service provided by Solid allows you to create and maintain a stable and healthy subscription model for your business. 



Create a subscription


Kindly note, you will not be able to edit product properties(except for the "Settle interval") after the 1st subscription payment. However, you can create multiple products and switch customers between them.


Create a Product

To start working with Solid Subscription Services, you need to create a Product in our admin panel->subscription tab with the following parameters: 



  • Price (cents); 
  • Currency; 
  • Retry strategy;
  • Billing Period; 
  • Duration of a Billing Period; 
  • Settle interval.



Add a currency to the created Product

In the created Product there is also a possibility to make it multi-currencyallowing for the addition of extra currencies for specific locations. 

To add this feature, the product details must be opened by clicking on it, and then selecting the "Add currency" button on the product details page, which opens up the options menu.



While adding the currency there is an option to choose:
  • Currency (you can find all the options connected to your account).

  • Location (there is a possibility to choose more than one option. For instance while choosing currency "euro", you are able to choose all Euro area member countries).


After adding the newly created option it will be displayed in the list "PRODUCT CURRENCIES AND LOCATIONS" In this list, there is also a possibility to edit already added currency options or delete them.

Settle Interval

We process recurrent subscription payments in two stages Auth + Settle, and the statuses can be: 

  • auth_ok - funds were successfully reserved;
  • auth_failed - reservation of the funds failed;
  • settle_ok    - funds were successfully settled;
  • void_ok - operation of fund reservation was voided;


You can adjust the time lag up to 6 days on Settle after authorization. This delay serves to temporarily freeze the funds in the client's account for the specified period. In the event that the client is dissatisfied with the product or service provided, there are two options available

- contact the issuing bank and request that the funds be unfrozen, after which they will be transferred to merchant support$

- contact the merchant's support team to initiate a refund (Void) for the transaction.




Based on our observations, clients tend to request refunds within the first week after making a payment. As a result, by freezing the funds in the cardholder's account, chargebacks can be avoided since the transaction cannot be disputed.



Create a Trial


Now, when we have the product ready, you can set up product Trial parameters: 


  • Price;    
  • Currency; 
  • Billing Period; 
  • Payment Action (charge, auth + void, charge + refund, auth + settle). 




Charge: we will charge a customer with a subsctripion trial cost. 
Auth + Void: we will authorise and then void (same day) the transaction, so that we will get the needed card token from the action yet keep the trial subsctiption cost-free. 
Charge + Refund: we will charge a customer with a subscription trial cost and refund it after (up to few days).
Auth + Settle: we will authorise and then after the time interval stipulated we will make settle of subscription trial cost.



Kindly note: smallest price for the trial period can be 0.1 USD (10 cents) but we highly recommend to use the price from $0.60 to $1.


 

Retry payment logic

You can choose a payments retry strategy to increase the success rate of recurrent payments. Retry will act when we receive a decline for recurrent payment. The goal here is to find a point in time when a customer has funds and to perform a successful payment. Therefore it is a good practice to set up a few Retry iterations for one product.




Discount Amount works for Insufficient Funds error code. Hence we can decrease the subscription cost to try to find the amount we can charge



Initiate a Subscription


    Please find a detailed description of the request to initiate a subscription to card payment methods or ApplePay / GooglePay and PayPal can be found here. 



Subscription status


There are two options to receive subscription status:

  1. Notification to subscirption_callback_url;
  2. Subscription status request.


    If you passed the subscription_callback_url parameter to the subscription creation request, callbacks will start to arrive at the specified URL.


You can request the subscription status by subscription_id.

All customers subscriptions are available by customer_account_id.

All changed subscriptions by the specified period can be requested by Subscription reconciliation.



Kindly note, callback_type available only in callback notifications. There is no such field in Subscription status requests.



Subscription flow


  1. First of all, you need to make an init request;
  2. Display the card form to the customer;
  3. If the user does not submit the form, then the subscription is not created, and the order remains in the created status for 24 hours, then it gets deleted from the system.
  4. If a customer declines payment, the order moves to declined status. Consequently, a subscription was not created. 
  5. If a customer approves payment, the payment is successful, and the order moves to approved status. From this point subscription is active. The subscirption_callback_url receives a notification. 
  6. You can identify subscription by Order_ID (should be included in Init request at your end) and customer_account_id (should be included in init request at your end).
  7. Following interactions by subscription_id.



Subscription prolongation flow


  • In case a customer subscribed to a Trial, after the 1st payment, we send to subscription_callback_url:


        {

         "callback_type": "init", 

         "status": "active" 

        }

  • When the Trial has ended, and it was prolonged to the subscription:

        {

         "callback_type": "renew", 

         "status": "active" 

        }

  • If a customer reached out, your customer support with a request to unsubscribe, but his subscription remains active till the end of the billing period (soft cancel):

        {

         "callback_type": "update", 

         "status": "active" 

        }

  • In case a customer has reached the end date of the subscription period: 

        {

         "callback_type": "cancel", 

         "status": "cancelled" 

        }



Redemption period


For cases where you implemented a retry flow in your subscription product: 

  • After the unsuccessful recurrent payment,  you will receive notification to a subscription_callback_url about the subscription status change from active to redemption. In such cases, you should restrict the product functionality for the customer because, during the redemption period, the customer uses your product for free. Hence we can overcome declines partially. 

        {

          "callback_type": "update",

         "status": "redemtion" 

        } 


  • In case retry for recurrent payment was successful, the subscription goes back to the active status. You will receive a notification to the subscription_callback_url. 

        {

         "callback_type": "renew", 

         "status": "active" 

        }

  • If all retries attempts failed to succeed, the subscription status changes to cancel. After the following notification, you should terminate access to the product for the user. 

        {

         "callback_type": "cancel", 

         "status": "cancelled" 

        }


Subscription cancel flow


Manual cancel


    

    Via Solid Hub

    

    You can restore a subscription via our in our admin panel->subscription tab->list:

  • Go to the subscription tab.
  • Filter subscriptions by customer's email address. 
  • Click "Cancel" to cancel at the end of the billing period (soft cancel). 
  • Click "Cancel now" to cancel the subscription immediately (force cancel).



    Via Solid API


 You can cancel a subscription via my.solidgate.com or by API. 


There are 2 options:

  • Cancel subscription instantly (force cancel). In this case, we send the following notification: 

        {

         "callback_type": "cancel", 

         "status": "cancelled" 

        }

  • Cancel subscription after the end of the billing period (soft cancel). For this case we send the next notification:

        {

         "callback_type": "update", 

         "status": "active" 

        }


    As you can see, subscription status remains active till the end of the billing period. After the end of the period, we send another notification, cancel in this time: 

        {

         "callback_type": "cancel", 

         "status": "cancelled" 

        }


Automatic cancel


A subscription can be automatically cancelled in the following instances:

  • During retry payment, antifraud triggered, and the order was cancelled with decline code 4.09. As a result, we will not perform the next retry payments.
  • We received a chargeback for one of the subscription orders. As s result, we will stop all customer's subscriptions and all following retries. 
  • For the first subscription payment, the customer used a Maestro card. We will notify you regarding the matter and unsubscribe the user from all recurrent subscription payments. 


You can check a complete list in our documentation in the Available Subscription Cancel Codes paragraph.


Restore a subscription


Via Solid Hub

    

    You can restore a subscription via our in our admin panel->subscription tab->list:

  • Go to the subscription tab.
  • Filter subscriptions by customer's email address. 
  • Click "Restore". 



Via Solid API


    By using this method, you can restore your client's specific subscription via API.




Subscription Pause


In certain situations, customers might choose to pause their subscription temporarily. This decision can be driven by various factors, such as:


  • inability to use the product for a specific period
  • temporary absence from their usual location


You have the option to pause the subscription via the API, and such paused subscriptions are identified by a distinct status - paused.


Subscriptions can be put on hold for a defined period, but it is important to specify a resume date and time for them. It is not possible to pause the subscription indefinitely.


The API provides functionalities to create, update, delete, and manage the paused status for customer subscriptions. This allows you to set a pause period from a specific point to a designated date and make changes or cancel the pause if needed.


Manage subscription pause


The subscription pause functionality provides businesses with the ability to temporarily halt an active subscription, allowing customers to suspend their subscription for a defined period. This functionality facilitates a seamless transition between the active status and pause status, giving customers the option to reactivate their subscription or proceed with a permanent cancellation. The subscription details include essential fields such as start_point:date and stop_point:date, which accurately track the duration of the pause period.



Via Solid Hub



To pause the subscription:

  • Go to Subscriptions > List.
  • Filter subscriptions by the active status to find the needed one.
  • Click on the ➡️ icon to go to the Subscription details page.
  • In the Pause subscription section, click on the date picker to set the pause period.
  • Click on Create Pause to confirm changes.










To modify the pause interval


  • Go to Subscriptions > List.
  • Filter subscriptions by the paused status to find the needed one.
  • Click on the ➡️ icon to go to the Subscription details page.
  • In the Pause subscription section, modify the pause interval considering the following:
  • If the pause is not activated, you can edit both the start and end dates of the pause.
  • If the pause is already activated, you can only edit the end date of the pause.
  • Click on Update pause to confirm changes.





During the subscription pause, no renewals or charges occur, and notifications about status changes are sent with the paused type.

Via Solid API


Use the subscription pause API request to pause the subscription, and modify the pause interval with the change subscription pause API request. If the pause has already started, only the stop_point:date can be modified. Otherwise, both the start_point:date and stop_point: date are available for changes.


Subscription renewals and next charges


When a subscription is paused, it does not renew on its scheduled date.


  • The next charge date is equal to the expired_at field in subscription status + days of (pause:from_date - pause:to_date).
  • In case of resuming the paused subscription manually, Solidgate recalculates the next charge date as expired_at field in subscription status  + days of (now date - pause:from_date).


The next charge date is now calculated with precision down to seconds in addition to days, ensuring a higher level of accuracy in the calculation.


Subscription cancellation


When a subscription is paused, only the option to hard cancel is available. The option for a soft cancel is not applicable.


The functionality to pause a subscription is not accessible if the subscription is in a soft cancel status.


The functionality to pause a subscription is no accessible if the subscription is in a soft cancel status.



Subscription resume


Only subscriptions in the paused status can be resumed.



Via Solid Hub


To resume a subscription:


  • Go to Subscriptions > List.
  • Filter subscriptions by the paused status to find the needed one.
  • Click on the ➡️ icon to go to the Subscription details page.
  • In the Pause subscription section, click on Delete pause to resume the subscription.





Via Solid API


Use the remove subscription pause request functionality to delete a scheduled pause and revert the subscription to its previous active state.



Constraints and limitations


If the settings required for the subscription pause are incomplete or do not meet the pause conditions, an error occurs, and you receive a response with the  2.01 error code. The error takes place when:


1) pause from/to date is:

  • absent in the request
  • lower than now date

2) pause period is lower than 1 day


3) subscription:

  • does not exist
  • status is not equal to active
  • is planned to be cancelled or paused
  • pause:from_date is greater than the subscription expired_at date
  • pause schedule does not exist (start_point:date is null)



Switch Subscription Product



If you would like to provide a discount, change a product or change the billing period for any given user, you should create a new Product with the needed parameters. 


You can switch the products used in the active subscription with any from the list of your products.

1. You can do it manually. For this you need to login to your account. 

Then go to Order details > Subscription > Switch subscription product > Choose the product you need > Change product.


2. There is another option to do this via API using this instruction. 


After the request to switch the product has been completed, a callback will be sent with the corresponding update (new product name for the subscription). The new product settings will be applied after the next debiting date.



Matching Subscription entities


In order to efficiently match and update the Subscription-related entities, we recommend:

  1. Sending a Request containing the mandatory parameters:
    {
    …
    product_id:"product-id-XXXX",
    order_id:"order-id-NNNN",
    customer_account_id:"account-id-1111",
    ...
    }

  2. Receiving a Response with the following related parameters:
    {
    …
    product_id:"product-id-XXXX",
    subscription_id:"subscription-id",
    invoice_id:"invoice-id",
    order_id:"order-id-NNNN",
    customer_account_id:"account-id-1111",
    ...
    }

  3. Match the received subscription_id with the customer_account_id sent in the request

  4. All notifications can be tracked using the subscription_id