Subscription process overview
Subscription process overview
Unveil the process of Solidgate subscriptions, from creation to management, empowering merchants to offer seamless recurring payments to customers

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.

Please note that among the APMs, only Guide
PayPal is a global online payment system that enables users to securely send and receive money for goods and services.
PayPal
and Guide
Mercado Pago is a popular online payment platform in Latin America, supporting various payment methods like credit/debit cards, cash payments, and bank transfers.
Mercado Pago
currently support subscription 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
warning
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

Status Description
Active Subscription is active and the customer will be charged on the recurring interval.
Paused Charges for the subscription are suspended during the specified pause period or until manual reactivation.
Cancelled Subscription is cancelled and the user unsubscribed.
Redemption If the subscription product contains retries, then if the recurring payment was declined due to one of the error codes, the subscription goes into the redemption period. If all retry attempts are declined, the subscription status will become Cancelled . If any of the attempts on the retry are successful, the subscription status will become Active .

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.

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

-

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%

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

-

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%

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%

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%

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%

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%

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

-

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%

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%

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%

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%

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%

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%

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%

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%

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 .

Condition Parameters
The user has successfully started the subscription. callback_type: init and status: active
The user has successfully paid for the renewal of the subscription or restored the specific subscription in case it was cancelled. callback_type: renew and status: active
The user came to the support service and asked to unsubscribe - the support employee cancelled the subscription (the subscription will still be active until the end of the period). callback_type: update , status: active

and subscription: cancelled_at
(Note: this parameter is required, but in other cases, for example in refunds, this parameter is null)
The user has successfully paused the subscription. callback_type: pause and status: paused
The user has successfully resumed the subscription. callback_type: resume and status: active
When a subscription reaches its expiration date at the end of the billing period, a webhook notification is sent, informing you that the subscription has been terminated due to the expiration. callback_type: cancel and status: cancelled

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.

For example, if the payment was blocked by the bank's anti-fraud system or the card was added to the bank's blacklist (code 8.12 ), the system will automatically unsubscribe the user.

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.

Additional, smart Guide
Solidgate's retry strategies recover revenue and reduce churn by customizing retries and discounts for failed subscription payments.
retry strategies
for failed subscription payments help merchants recover revenue and reduce involuntary customer churn rates by customizing retry intervals, discounts, and other features based on the customer and payment method.

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.