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-currency. This aspect will make it possible to add additional currencies for definite locations. 

To add this feature to the required Product you will need to open its details by clicking on it.  
On the Product Details page, there is an "Add currency" button. Clicking on it opens 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 Auth. What does this achieve - the funds are frozen in the client's account for the specified period. In case the client is unsatisfied with the product or service provided, there are two options:


- contact the issuer bank and ask to unfreeze the funds, which will be forwarded to merchant support;

- contact merchant's support for a refund (Void).




Our observations show that a client applies for a refund during the first week after payment. Hence, you will bypass chargeback since funds are frozen at the cardholder's account, meaning it can't 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).


 

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.




Diescount 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.



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