A Solidgate subscription connects customers to your product, defines recurring payment frequency, and outlines what they’ve signed up for.

In the initial stages of working with the Solidgate subscription system, merchants must manually create a product and its associated price following subscription rules within the HUB. This process is detailed in the Guide
Explore how to establish subscription products, handle customer data, process payments, and utilize the smart retry feature. product and price management section. After creating the product, a unique product_id is obtained as outlined in the same section, this identifier should be passed to initialize the subscription payment in the Guide
Understand how to integrate the payment form into your product. Payment form , Guide
Easily build a safe and simple payment page with our straightforward, step-by-step guide. Payment page , Card API , and APM API payments.

Create subscription

• The merchant creates and receives a product_id
• The merchant passes the product_id in the request. To create a subscription, the customer_account_id must also be passed as it is a required parameter for subscription initialization.
  • via Guide
    Understand how to integrate the payment form into your product. Payment form or Guide
    Easily build a safe and simple payment page with our straightforward, step-by-step guide. Payment page
  • via Card API or APM API
• We obtain the price and payment configurations from the product configuration, then send the payment for processing.
• When the payment is successfully processed, a subscription is created, and the subscription_id is returned to the merchant’s request. The merchant also receives a notification regarding the subscription’s creation, which can be found in the Guide
  Effortlessly receive automatic notifications by subscribing to updates. events section.
• The merchant can use the subscription_id to perform further operations on the subscription, such as changing the product, canceling or resuming the subscription. The specific subscription can also be found in the HUB using the subscription_id

It is important to note that the current limitations of our system do not allow for more than 1 active subscription to be created within a channel for the same customer_account_id paired with the same product_id. If a merchant attempts to create more than one such subscription in the Solidgate system, it will not be permitted or processed with Guide
This error indicates that the user already has a subscription to the product_id. 2.14 Subscription Error .

Subscription status

An Active subscription means that the customer will continue to be charged on a recurring basis. If the customer has unsubscribed, the subscription status is Cancelled . If the subscription product contains retries and a recurring payment is declined due to one of the error codes, the subscription goes into a Redemption period. If all retry attempts are declined, the subscription status will become Cancelled . However, if any of the retry attempts are successful, the subscription status will become Active again. However, if a subscription is put on hold, it enters a Paused status, during which customer charges are suspended until the designated pause duration concludes or a manual reactivation is triggered.

After performing the Subscription Status request, you will receive information about the last invoice for the subscription and an order status ID, which you can later use to verify the external order ID in the Solidgate HUB

Retry strategies

Solidgate provides a feature of smart retrying failed subscription payments, which helps our merchants to recover revenue and decrease the involuntary churn rate of the customers.

After the initial collection of the invoice failed, the retry mode would turn On, and the state of the subscription would change to redemption

While the subscription is in state redemption , we would retry the invoice collection four times. The interval between the retries is based on the customer, payment method, and card data features.

Moreover, we provide the option to automatically apply a Discount in % if we receive a decline Guide
Understand why the payment is declined and how you can resolve it. “Insufficient Funds” during the last payment attempt.

Configuration

You could select the predefined retry strategies in the Solidgate HUB while creating or editing Subscription Product details.

The description of all available retry strategies is provided below.

#1 Retry Strategy for Weekly Subscription

Name in Hub: “#1 - Weekly 0% /0% /0% /0%”

#	Retry Interval	Discount
1	1 day after initial collection	-
2	On the nearest Friday	-
3	2 days after the previous retry	-
4	5 days after the previous retry	-

#2 Retry Strategy for Weekly Subscription 25% Discount on the last retry

Name in Hub: “#2 - Weekly 0% /0% /0% /25%”

#	Retry Interval	Discount
1	1 day after initial collection	-
2	On the nearest Friday	-
3	2 days after the previous retry	-
4	5 days after the previous retry	25%

#3 Retry Strategy for Weekly Subscription 50% Discount on the last retry

Name in Hub: “#3 - Weekly 0% /0% /50% /0%”

#	Retry Interval	Discount
1	1 day after initial collection	-
2	On the nearest Friday	-
3	2 days after the previous retry	50%
4	5 days after the previous retry	-

#4 Retry Strategy for Weekly Subscription 75% Discount on the last retry

Name in Hub: “#4 - Weekly 0% /0% /0% /75%”

#	Retry Interval	Discount
1	1 day after initial collection	-
2	On the nearest Friday	-
3	2 days after the previous retry	-
4	5 days after the previous retry	75%

#5 Retry Strategy for Weekly Subscription 3-25%, 4 - 50%

Name in Hub: “#5 - Weekly 0% /0% /25% /50%”

#	Retry Interval	Discount
1	1 day after initial collection	-
2	On the nearest Friday	-
3	2 days after the previous retry	25%
4	5 days after the previous retry	50%

#6 Retry Strategy for Weekly Subscription 1-10%, 2 - 25%, 3 - 50%, 4 - 75%

Name in Hub: “#6 - Weekly 10% /25% /50% /75%”

#	Retry Interval	Discount
1	1 day after initial collection	10%
2	On the nearest Friday	25%
3	2 days after the previous retry	50%
4	5 days after the previous retry	75%

#7 Retry Strategy for Weekly Subscription 1 - 25%, 2 - 50%, 3 - 75%, 4 - 75%

Name in Hub: “#7 - Weekly 25% /50% /75% /75%”

#	Retry Interval	Discount
1	1 day after initial collection	25%
2	On the nearest Friday	50%
3	2 days after the previous retry	75%
4	5 days after the previous retry	75%

#8 Retry Strategy for Weekly Subscription 2 - 15%, 3 - 40%, 4 - 65%

Name in Hub: “#8 - Weekly 0% /15% /40% /65%”

#	Retry Interval	Discount
1	1 day after initial collection	-
2	On the nearest Friday	15%
3	2 days after the previous retry	40%
4	5 days after the previous retry	65%

#9 Retry Strategy for Monthly Subscription w/o Discounts

Name in Hub: “#9 - Monthly 0% /0% /0% /0%”

#	Retry Interval	Discount
1	1 day after initial collection	-
2	On the nearest Friday	-
3	9 days after the previous retry	-
4	19 days after the previous retry	-

#10 Retry Strategy for Monthly Subscription with 25% Discount on the last retry

Name in Hub: “#10 - Monthly 0% /0% /0% /25%”

#	Retry Interval	Discount
1	1 day after initial collection	-
2	On the nearest Friday	-
3	9 days after the previous retry	-
4	19 days after the previous retry	25%

#11 Retry Strategy for Monthly Subscription with 50% Discount on the last retry

Name in Hub: “#11 - Monthly 0% /0% /0% /50%”

#	Retry Interval	Discount
1	1 day after initial collection	-
2	On the nearest Friday	-
3	9 days after the previous retry	-
4	19 days after the previous retry	50%

#12 Retry Strategy for Monthly Subscription with 75% Discount on the last retry

Name in Hub: “#12 - Monthly 0% /0% /0% /75%”

#	Retry Interval	Discount
1	1 day after initial collection	-
2	On the nearest Friday	-
3	9 days after the previous retry	-
4	19 days after the previous retry	75%

#13 Retry Strategy for Monthly Subscription 3 - 25%, 4 - 50%

Name in Hub: “#13 - Monthly 0% /0% /25% /50%”

#	Retry Interval	Discount
1	1 day after initial collection	-
2	On the nearest Friday	-
3	9 days after the previous retry	25%
4	19 days after the previous retry	50%

#14 Retry Strategy for Monthly Subscription 2 - 25%, 3 - 50%, 4 - 75%

Name in Hub: “#14 - Monthly 0% /25% /50% /75%”

#	Retry Interval	Discount
1	1 day after initial collection	-
2	On the nearest Friday	25%
3	9 days after the previous retry	50%
4	19 days after the previous retry	75%

#15 Retry Strategy for Monthly Subscription 1 - 25%, 2 - 50%, 3 - 50%, 4 - 75%

Name in Hub: “#15 - Monthly 25% /50% /50% /75%”

#	Retry Interval	Discount
1	1 day after initial collection	25%
2	On the nearest Friday	50%
3	9 days after the previous retry	50%
4	19 days after the previous retry	75%

#16 Retry Strategy for Monthly Subscription 2 - 15%, 3 - 40%, 4 - 65%

Name in Hub: “#16 - Monthly 0% /15% /40% /65%”

#	Retry Interval	Discount
1	1 day after initial collection	-
2	On the nearest Friday	15%
3	9 days after the previous retry	40%
4	19 days after the previous retry	65%

#17 Retry Strategy for Monthly Subscription 4 - 30%

Name in Hub: “#17 - Monthly 0% /0% /0% /30%”

#	Retry Interval	Discount
1	1 day after initial collection	-
2	On the nearest Friday	-
3	9 days after the previous retry	-
4	19 days after the previous retry	30%

#18 Retry Strategy for Monthly Subscription 3 - 50%

Name in Hub: “#18 - Monthly 0% /0% /50% /0%”

#	Retry Interval	Discount
1	1 day after initial collection	-
2	On the nearest Friday	-
3	9 days after the previous retry	50%
4	19 days after the previous retry	-

Subscription events

For all changes of the subscription, we would asynchronously notify you via subscription Webhook , similar to payments. You could find in Webhook section how to enable notifications and define your server url.

The webhook structure is similar to the subscription/status method, but the callback_type parameter will be added to the response object. Four types of callbacks are - init , renew , update , pause , resume and cancel .

Cancel codes

A subscriptions cancellation code is used to describe the reason the subscription was cancelled. You could use this code to analyze you subscription lifecycle and reduce your churn ratio.

The transition to the status of cancellation in Solidgate can occur due to customer-initiated cancellation or declined recurring payments with retries that ultimately fail. In either case, the subscription status will change to Cancelled , indicating that the customer will no longer be charged on a recurring basis.

The method for restoring a cancelled subscription API requires the merchant to provide the subscription_id and the desired subscription expiration date in the format of yyyy-MM-dd HH:mm:ss

However, it’s important to note that restoration of a cancelled subscription may not always be possible, especially if the reason for cancellation was due to a breach of terms and conditions or other legal issues.

8.01 Card brand is not supported

This cancel code is used when the customer attempts to use a card brand that is not supported or whether his payment instrument does not support recurring payments.

8.02 Fraud Chargeback received

This cancel code is used when a chargeback for a fraudulent transaction is received for one of the user’s invoices.

8.03 Dispute Received

This cancel code is used when a dispute or chargeback is received for one of the user’s invoices through PayPal.

When a dispute or chargeback is received, it means that the customer has disputed the transaction with their bank or credit card issuer via PayPal, for reasons such as product or service not received, product or service not as described, or other reasons. In such cases, the merchant or payment processor may be required to refund the transaction amount to the customer, and the subscription service will be cancelled.

8.04 Fraud Alert received

This cancel code is used when a fraudulent alert is received for one of the user’s invoices.

A fraudulent alert is a notification that a transaction may be fraudulent or unauthorized. In this case, the user is immediately unsubscribed from further recurring payments. This is done to prevent any further fraudulent activity from occurring and to protect both the customer and the merchant from any potential losses.

8.05 Fraud Decline received

This cancel code is used when a fraudulent decline is received for one of the user’s invoices.

A fraudulent decline occurs when a transaction is declined due to suspected fraudulent activity or unauthorized use of a card. This may occur if a card has been reported lost or stolen, or if there is suspicious activity on the card.

8.06 Cancellation by support

This cancel code is used when the support team has cancelled a subscription due to customer inquiry or other internal reasons.

For example, if a customer is not using the merchant’s product and wishes to cancel the subscription, the support team can process the cancellation upon the customer’s request.

8.07 Recurring payment is blocked by Antifraud

This cancel code is used when the Solidgate antifraud system has blocked the conduct of a recurrent payment due to a decline Guide
An antifraud rule was triggered. 4.09 .

8.08 Subscription has expired

This cancel code is used when a subscription is created for a limited time and has reached its expiration date.

8.09 Cancellation after redemption period

This cancel code is used when a decline occurs on a recurring payment, and retries during the redemption period have been activated but were unsuccessful, resulting in the automatic cancellation of the user’s subscription.

The redemption period refers to the timeframe during which the payment processor attempts to collect payment for a declined transaction or a transaction that was not authorized by the cardholder. During this period, the payment processor will typically attempt to retry the transaction several times before considering it a failure and canceling the subscription.

8.10 Card Token has expired

This cancel code is used when a user’s subscription is canceled because their card token has expired and, they have not reissued their card.

A card token, generated by the payment processor, enables automatic recurring payments in subscription services. When a card token expires, the processor can’t use it for transactions, and the customer must update their payment information.

8.11 Token revoked by customer

This cancel code is used when a user’s billing token has been revoked by the customer on PayPal’s side.

Customers have the ability to revoke billing agreements with merchants or payment processors, either through their PayPal account or by contacting customer support. If a customer revokes a billing agreement that is associated with a user’s subscription service, the subscription will be automatically cancelled with this cancel code.

8.12 Bank antifraud system

This cancel code is used when a payment for a subscription is blocked by the bank’s anti-fraud system or the card associated with the payment is added to the bank’s blacklist.

Banks use anti-fraud systems to detect and prevent fraudulent transactions. These systems may use a variety of techniques, including machine learning algorithms and rule-based systems, to analyze transactions and identify suspicious activity. Overall, the use of this cancel code highlights the importance of maintaining strong security and fraud prevention measures in subscription services, and working closely with banks and other financial institutions to ensure that transactions are secure and legitimate.

8.13 Invalid amount

Solidgate sets a limit on discounts, and if a discount applied to a payment goes beyond this limit, the final amount might become invalid.

This cancellation code helps maintain the fairness and integrity of subscription services by ensuring discounts are used reasonably. By having a discount limit, Solidgate prevents customers from exploiting overly generous discounts that could negatively impact the merchant or the subscription service over time.

8.14 Cancellation by customer

This code indicates that the cancellation was initiated by the customer themselves, rather than by Solidgate or the merchant.

Customers may choose to cancel their subscription for a variety of reasons, such as changes in their financial situation, dissatisfaction with the service, or simply no longer needing the subscription.Using this cancel code allows Solidgate and the merchant to track the number and reasons for cancellations, and to identify any patterns or trends that may be affecting customer retention or satisfaction.