Subscription overview

Explore Solidgate subscriptions for seamless recurring customer payments

Solidgate subscription feature connects customers to your product, defines recurring payment frequency, and outlines what they have 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 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 utilize 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.

Please note that among the APMs, only , , , and currently support subscription payments.

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
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 be also 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.

Our 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 , ensuring a single subscription per product.

Subscription with free trial

Merchants may choose to offer customers a trial period for their products at no cost at all. To facilitate 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 , Apple Pay API , or Google Pay API payment requests. This approach to charging customers does not work with recurring tokens through the Recurring API endpoint that allows tokenized payments.

Please be aware that if the transaction for recurring tokens is attempted to be processed as a zero-amount payment, it will be automatically switched to the auth-void flow.

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 and the type field to the auth value.
Merchants receive confirmation about the authorization.
If the zero-amount payment is successful, the final Guide
An order is a request to purchase goods or services. It is created by a customer as a record of what they want to buy. Orders can remain in the created state until a payment is attempted. Once a payment is attempted, the order moves to the processing state, where it stays until the payment is captured. Orders can also go through various other states, such as 3ds_verify , approved , declined , refunded , etc. order 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 Guide
An order is a request to purchase goods or services. It is created by a customer as a record of what they want to buy. Orders can remain in the created state until a payment is attempted. Once a payment is attempted, the order moves to the processing state, where it stays until the payment is captured. Orders can also go through various other states, such as 3ds_verify , approved , declined , refunded , etc. order status is set to void_ok.

These approaches help merchants offer trial periods effectively, providing a positive experience for customers and ensuring the merchant can verify payment methods without charging the customer upfront.

Subscription statuses

Status	Description
pending	Subscription is awaiting confirmation of successful payment. Depending on whether the initial payment is approved or declined, the pending subscription will transition 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 user 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 if 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 with retry strategies, 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 all retry attempts fail or the customer unsubscribes from the product or service, the subscription status changes to cancelled. However, if any retry attempt succeeds and the customer keeps the subscription, its status changes to active.

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

The new pending and expired statuses will be available starting October 21, 2024.
To start using them, contact us.

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 will not receive webhooks related to these statuses. However, once the new statuses are activated, you will still see the updated subscription statuses in the HUB and responses.

After performing a subscription status 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 .

Subscription invoice limit

There is a specific limit on the number of invoices that can be in a processing state for a single subscription.

When customers sign up for a subscription with the same customer_account_id and product_id combination, they can simultaneously have up to 3 invoices in processing for the subscription’s first payment.

The invoice limit aims to improve the conversion rate of the first sale. Moreover, it provides flexibility for customers to make payments using multiple payment methods while keeping the number of pending orders manageable.

For efficient invoice management and Guide
Improve customer experience and prevent fraud chargebacks. chargeback prevention , if an invoice is stuck in processing and another has been successfully completed, the update about the successful payment triggers an immediate refund for the invoice in the processing state. Similarly, if there is a duplicate charge on a subscription, such as from delayed order processing, the second invoice is refunded, which positively impacts the chargeback rate.

API Reference

Looking for help? Contact us

Stay informed with Changelog