[
{
"title":"Access to API",
"link":"https://docs.solidgate.com/payments/integrate/access-to-api/",
"text":"Understand how Solidgate authenticates your API requests and provides validation errors.",
"imgSrc":"https://solidgate.com/wp-content/uploads/2022/08/One-time.svg"
}
,
{
"title":"Integrate",
"link":"https://docs.solidgate.com/payments/integrate",
"text":"Explore Solidgate integration options, payment methods, and merchant website integration methods.",
"imgSrc":"https://solidgate.com/wp-content/uploads/2022/08/Custom-Built-Rules.svg"
}
,
{
"title":"Testing",
"link":"https://docs.solidgate.com/payments/testing/",
"text":"Simulate payments to test your integration before launching in production.",
"imgSrc":"https://solidgate.com/wp-content/uploads/2022/07/integration.svg"
}
]
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
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
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
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.
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.