Subscription overview

Explore Solidgate subscriptions for seamless recurring customer payments

Solidgate subscription feature connects customers to your product or service, defines recurring payment frequency, and specifies what they are subscribing to.

In the initial stages of working with the Solidgate subscription feature, merchants must manually create a product and its associated price following the subscription rules in the Solidgate Hub . This process is detailed in the Guide
Explore how to establish subscription products, handle customer data, process payments, and use the smart retry feature. product and price management section. After creating the product, it gets a unique product_id . The unique identifier should be passed to initialize the subscription payment via one of the Solidgate’s Guide
Solidgate Payment Page, Payment Link, and Payment Form offer flexibility to cater to different integration needs for seamless checkout experiences. checkout solutions, Card API , and APM API payments.

Solidgate subscription logs are stored for the last 60 days. If you need older data, contact us.

Please note that only the following APMs support subscription payments:
and

When creating your subscription product, you can choose to offer it with or without a trial. This helps you meet customer needs and shape their first experience. Solidgate provides the following options:

Without trial
Subscription starts immediately with regular billing. You define the recurring amount, currency, and payment frequency.

Example: A video streaming service charges $9.99 monthly with no trial period.
With a free trial
Subscription includes a zero-cost trial period before regular billing begins. You specify the recurring amount, currency, and payment frequency to apply after the trial ends.

Example: A fitness app offers a 14-day free trial and a $19.99 monthly fee after the trial.
With a paid trial
Subscription starts with a one-time charge for the trial period before transitioning to regular billing. You define the trial amount, currency, and details of recurring charges that apply after the trial.

Example: An online course platform offers a 7-day paid trial for $5, followed by a recurring fee of $29.99 monthly.

Trial settings can be modified via Hub or by the update a product API method after a subscription is active, but you cannot add or remove a trial once the subscription has started.

Subscription process

To initiate a subscription for a customer, merchants follow a streamlined process that involves product creation, payment processing, and subscription initialization.

The merchant creates a product and receives a product_id .
The merchant passes the product_id in the request. To create a subscription, include customer_account_id , a required parameter for subscription initialization.
- via one of the Guide
  Solidgate Payment Page, Payment Link, and Payment Form offer flexibility to cater to different integration needs for seamless checkout experiences. checkout solutions
- via Card API or APM API
- via Guide
  Resign enables one-click payments using a saved recurring token from a previous transaction. Available for PCI DSS certified merchants. resign using an existing recurring token
Solidgate obtains the price and payment configurations from the product configuration and sends the payment for processing.
After successful payment processing and subscription creation, the merchant receives the subscription_id and a notification regarding the subscription creation, which can also be viewed 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, cancelling, or resuming the subscription. The subscription_id also serves as a key to locating the specific subscription in the Hub.

Solidgate system restricts the creation of multiple active subscriptions for the same customer_account_id and product_id within a channel. To prevent double charging, Solidgate disallows duplicate subscriptions by declining these attempts with a Subscription error, ensuring a single subscription per product.

To track the number of passed billing periods, each subscription has a term number, subscription_term_number, representing the sequential billing period excluding trial periods. This number increments when a new billing period begins or when the subscription is upgraded or downgraded with a billing period change.

For example, if a customer upgrades from a monthly to a yearly plan, the term number increments and a new billing period starts, with any unused credit from the previous period applied. However, upgrading from one monthly product to another monthly product keeps the same term number, as the billing period length remains unchanged.

Billing period

Solidgate subscription billing follows calendar billing. A billing period of one month equals one calendar month and may contain 28, 29, 30, or 31 days, depending on the month.

Recurring charges are processed on the day of the month that matches the subscription start date, taking into account the number of days in the current month.

For example:

If a customer subscribes on January 1, the next charge occurs on February 1.
If a customer subscribes on January 31, the next charge occurs on February 28 (or 29 in a leap year).

Subscription with free trial

Merchants may choose to offer customers a trial period for their products at no cost at all. To provide free trials, they can use zero-amount authorization or the auth-void process. Understanding the nuances of these approaches helps manage customer expectations and ensure a smooth start to the trial period.

Zero-amount authorization

Zero-amount charges can be initiated for charge API , recurring API , resign API , Google Pay API or Apple Pay API payment requests.

The payment is processed as a one-step payment, where merchants can verify a customer’s payment method without charging any funds.

As a result of this process:

The payment request is configured on the merchant side and sent with the amount field set to 0 .
Merchants receive confirmation about the authorization.
If the zero-amount payment is successful, the final order Guide
An order is a customer’s request to purchase goods or services, progressing through various states based on payment status. status displays the auth_ok value. Otherwise, the final order status shows the auth_failed value.

Auth-void process

When choosing the auth-void process, specify product_id associated with a trial product setting, which applies to Apple Pay API , Google Pay API , or recurring API payment requests. In such cases, Solidgate’s subscription service processes a trial payment by executing two transactions of the auth-void process:

Authorization of $1: This is a temporary hold to verify the payment method.
Automatic voiding: Once authorized, this $1 payment is immediately voided, and the amount is returned to the customer.

As a result of this process:

The amount value is replaced with 1 and the currency value is set to USD .
Merchants receive confirmation about both the authorization and void transactions.
If a void transaction is not successful, Solidgate automatically retries it.
The final order Guide
An order is a customer’s request to purchase goods or services, progressing through various states based on payment status. status is set to void_ok.

These approaches help merchants offer trial periods effectively. They create a positive customer experience and let merchants verify payment methods without charging customers upfront.

Subscription statuses

Value	Description
pending	Subscription is awaiting confirmation of successful payment. Depending on whether the initial payment is approved or declined, the pending subscription transitions to either an active or expired status.
active	Payment is successful, the subscription is active, and the customer is billed according to its set interval.
paused	Billing for the subscription is halted during the specified pause period or until manual reactivation.
cancelled	Subscription is cancelled, and the customer is unsubscribed.
redemption	For subscription products with retry strategies applied, if a recurring payment is declined due to a certain error code, the subscription enters a redemption period. If all retries fail, the subscription is cancelled . However, if any of the attempts on the retry are successful, the subscription status changes to active .
expired	Subscription is inactive due to payment failure or lack of gateway response within the expected timeframe.

A pending subscription signifies awaiting confirmation of a successful initial payment. Depending on whether the initial payment is approved or declined, the subscription transitions to either an active or expired status.

An expired status means the initial payment for a pending subscription has failed. Subscriptions can also move from pending to expired . It happens when Solidgate receives no response from the gateways within a defined timeout to determine if the order is successful or failed.

An active subscription indicates that the customer continues to pay for the product on a recurring basis.

For subscription products in retry mode, if a recurring payment is declined due to a specific error code, the subscription enters a redemption period. During this period, retry attempts are made to collect the invoice. If retry attempts fail or the customer unsubscribes, the subscription status changes to cancelled . However, if the retry attempt succeeds and the customer keeps the subscription, its status changes to active . Subscriptions also get the cancelled status automatically when you set up the alert-based cancellation rules, which allow merchants to balance risk management.

If a subscription is paused , billing is halted during the specified pause period or until manual reactivation. This means no charges are applied to the customer until the pause period ends or the subscription is manually reactivated.

To use the new pending and expired statuses, activate them in the Solidgate Hub. Navigate to Billing > Billing settings > General settings and enable Extended subscription statuses and webhooks.

Please note that the new statuses are activated at the account level, not per individual channel. Additionally, if you activate the new statuses without subscribing to the extended Subscription updates event, you do not receive webhooks related to these statuses. However, once the new statuses are activated, you still see the updated subscription statuses in the Hub and responses.

After performing a subscription status API request, you receive information about the last invoice for the subscription and the order status ID. This information can later be used to verify the external order ID in the Solidgate Hub .

Invoice statuses

An invoice status reflects the current state of the payment for the customer’s subscription. It shows whether the payment is being processed, completed, or failed.

Value	Description
processing	The invoice has been generated, and the customer's payment is in progress.
retry	A payment attempt has resulted in a failure, and another attempt is in progress.
success	The payment was successfully received, and the invoice is paid.
fail	All payment attempts were unsuccessful, resulting in an unpaid invoice and either a cancelled or expired subscription.

Payment attempt limit

There is a specific limit on the number of payment attempts that can be in a processing state for a single subscription. The purpose of the payment attempt limit is to give customers more flexibility when signing up for a subscription and ensure effective subscription management.

When customers sign up using the same customer_account_id and product_id combination, they can have up to three payment attempts in the processing state at once. This means they can try up to three payment methods for the first charge. For example, if a customer’s preferred payment method is temporarily unavailable, they can easily try an alternative without being limited to a single attempt.

This approach ensures:

Better conversion rates for the initial payment while keeping the number of pending charges manageable.
Prevention of unnecessary pending charges and potential chargebacks. If one payment attempt is stuck in processing while another is successfully completed, the stuck payment attempt is automatically refunded.
Handling of duplicate charges, such as those due to delayed order processing. Any extra payment is identified and refunded, which mitigates the probability of chargebacks and confirms only one successful charge per subscription sign-up.

Enforcing this limit enhances the overall subscription experience and reduces potential payment issues for both customers and businesses.

Handle errors

Identify common errors related to subscriptions, understand their causes, and learn how to resolve them.

Error	Reasons	Recommended action
2.14 Subscription error	Customer already has an active subscription for this product, multiple invoices are in a processing state, or product ID is incorrect.	Check the customer's active subscriptions for duplicate product IDs. Review the number of invoices in the processing state.
3.11 Recurring payment cancelled	The customer or card issuer has cancelled recurring payments for this payment method.	Do not retry payments and contact the customer for subscription cancellation reason.

Looking for help? Contact us

Stay informed with Changelog