Learn about 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.
Solidgate subscription logs are stored for 30 days.
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
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, 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, 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 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
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 of
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.
For all changes to the subscription, we would asynchronously notify you via
subscription
Webhook
, similar to payments. You can find in the 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
and
status:
active
subscription:
cancelled_at
(Note: this parameter is required, but in other cases, for example in refunds, this parameter is null)
The subscription goes into the redemption period due to declined recurring payments with retry attempts.
If all retries fail, the subscription status becomes cancelled; if any retry attempt is successful, the status becomes active.
callback_type:
update
and
status:
redemption
The user has successfully paused the subscription.
callback_type:
pause
and
status:
paused
The event occurs when a subscription resumes according to its schedule or is in a paused status.
If a pause is planned but not yet started, no webhook will be generated. However, if a pause has started and a remove request is made, the subscription is resumed and a webhook is generated.
callback_type:
resume
and
status:
active
or
paused
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 subscription cancellation code is used to describe the reason the subscription was cancelled. You could use this code to analyze your subscription lifecycle and reduce your churn ratio.
The transition to the status of cancellation in Solidgate can occur due to customer-initiated cancellations 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 antifraud system or the card was added to the bank's blacklist (code 8.12
), the system will automatically unsubscribe
the user.
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 a 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 antifraud system or the card associated with the payment is added to the bank’s blacklist.
Banks use antifraud 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. In addition, working closely with banks and other financial institutions ensures 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.