Handle billing events

Solidgate notifies you about billing activity through webhook events. A billing integration requires a webhook endpoint that handles these events. Most billing activity, such as subscription renewals, payment failures, retries, cancellations, and updates to customer or payment instrument records, happens on Solidgate’s side without a direct API call from you.

Set up your webhook endpoint

You can build logic to verify webhook signaturesAPI v2 and handle Solidgate events. To start receiving notifications, you need to configure a webhook endpoint.

Test webhook endpoint

To test your webhook endpoint, you can:

• Perform actions in a sandbox environment that trigger real events to your endpoint. For example, to trigger SUBSCRIPTION_ACTIVATED, create a subscription and complete the first payment using a test card.
• Create a subscription with a short billing period to observe the full renewal cycle (SUBSCRIPTION_RENEWED, INVOICE_PAID) in a compressed timeline.
• Use the recurring decline test card (4123212486997559) to trigger INVOICE_PAYMENT_FAILED, SUBSCRIPTION_REDEMPTION_STARTED, and eventually SUBSCRIPTION_UNPAID.

Track active subscriptions

Subscriptions require coordination between your system and Solidgate. The success or failure of a customer’s recurring payments determines whether they can continue to access your product or service.

A common pattern is to store an access expiration date for each customer and use it to determine whether their subscription is still active.

When the subscription renews, Solidgate charges the saved payment instrument and notifies your system by sending webhook events:

1. Receive SUBSCRIPTION_RENEWED and INVOICE_PAID.

   • SUBSCRIPTION_RENEWED is a subscription-specific signal for renewals, not for one-time invoices.
   • INVOICE_PAID fires for all invoices. Use billing_reason:subscription_cycle to identify renewals.
2. Find the customer the payment was made for on your side.
3. Update the customer’s access expiration date to the end of the new billing period.

Use both subscription status and invoice status to determine the right access action:

Signal	Subscription status	Invoice status	Recommended action
SUBSCRIPTION_ACTIVATED	ACTIVE	PAID	Grant access.
SUBSCRIPTION_RENEWED or INVOICE_PAID	ACTIVE	PAID	Extend access to the new period.
SUBSCRIPTION_REDEMPTION_STARTED or INVOICE_DUNNING_STARTED	REDEMPTION	DUNNING	Recovery in progress. Decide whether to keep or restrict access. Solidgate does not enforce a timing rule here.
Retry succeeds	ACTIVE	PAID	Restore access if you restricted it during the retry window.
SUBSCRIPTION_UNPAID or INVOICE_UNPAID	UNPAID	UNPAID	Revoke access. The subscription no longer auto-charges but is not yet cancelled.
Retries exhausted, invoice setting is Voided	CANCELLED	VOIDED	Revoke access. The subscription is cancelled automatically.
SUBSCRIPTION_CANCELLED	CANCELLED	Not applicable	Revoke access.

Track subscription status changes

Make sure that your integration properly monitors and handles transitions between the subscription statuses described in the following table.

Some status changes require special attention:

• When a subscription changes to REDEMPTION, a renewal payment has failed and Solidgate is retrying. Decide whether to keep or restrict access during this window. Listen for SUBSCRIPTION_REDEMPTION_STARTED. If the customer confirms they resolved the issue that caused the decline, collect payment at once through manual recovery instead of waiting for the next retry.
• When a subscription changes to UNPAID, all automatic retries are exhausted. Revoke access and consider notifying the customer. Solidgate offers revenue recovery features that help automate this process.
• When a subscription changes to CANCELLED, revoke access to your product.

Status	Description
CREATED	The subscription record exists, and the first invoice has been generated. No payment collected yet.
PENDING	The first invoice is finalized and waiting for payment.
TRIALING	The subscription is in a trial period. You can safely provision your product for the customer. The subscription transitions automatically to ACTIVE when the first regular payment is collected.
ACTIVE	The subscription is in good standing. The first invoice has been paid and renewals generate invoices automatically. For subscriptions recovering from REDEMPTION, a successful retry payment returns the subscription to ACTIVE.
REDEMPTION	A renewal payment failed. Solidgate is retrying using smart retries. Whether to keep or restrict access during this window is your decision.
UNPAID	All automatic payment retries are exhausted. No further automatic attempts. The subscription remains in place. If the outstanding invoice is paid, the subscription returns to ACTIVE. Revoke access when a subscription moves to this status.
CANCELLED	The subscription is stopped. No further invoices are generated. This is a terminal state. To resubscribe, create a new subscription.
EXPIRED	The first invoice was voided and the subscription never activated. No access was ever granted.

Handle payment failures

Events provide a reliable way for Solidgate to notify you of payment failures on subscription invoices. Some payment failures are temporary. For example, a card issuer might decline the initial charge but allow an automatic retry. Other payment failures are final and require action, like the customer’s payment method expiring.

Event	Description
INVOICE_PAYMENT_FAILED	A payment for an invoice failed. This event fires on every failed attempt, but only the first failure moves the subscription to REDEMPTION. If a payment fails, there are several possible actions to take: Notify the customer. Prompt the customer to update the payment instrument on the subscription. Configure smart retries to enable automatic recovery.
SUBSCRIPTION_REDEMPTION_STARTED	The recovery period has started. The subscription is in REDEMPTION and Solidgate begins retrying the charge based on your smart retries configuration. Depending on your business logic, restrict or keep access during this window. If the customer confirms they resolved the issue that caused the decline, you can collect payment through manual recovery.
SUBSCRIPTION_RENEWED or INVOICE_PAID	A retry succeeded. The subscription returns to ACTIVE. Restore access if you restricted it during redemption.
SUBSCRIPTION_UNPAID or INVOICE_UNPAID	All retries exhausted. The subscription moves to the UNPAID status. You can revoke the customer access. No further automatic charges are attempted, but you can still collect payment through manual recovery.

Handle disputes and chargebacks

Solidgate monitors subscriptions for fraud signals, disputes, and chargebacks. When one of these signals arrives, Solidgate can cancel the affected subscription automatically, independent of the dunning flow. You do not need to trace a dispute back to the subscription yourself.

Event	Description
SUBSCRIPTION_CANCELLED	Sent when Solidgate cancels a subscription in response to a dispute, chargeback, or fraud signal. The cancellation_info.reason field identifies the trigger. SolidgateHub, you can set up the alert-based cancellation flow for subscription in the Billing settings.

Match invoices to payments

Each invoice payment has its own identifier, separate from the payment that processed the charge. Use the invoice_payment object’s payment_id field to link the invoice back to that payment.

Event	Description
INVOICE_PAID	The payment_id field identifies the payment that successfully charged the invoice.
INVOICE_PAYMENT_FAILED	The payment_id field identifies the payment attempt that failed.

To match invoice payments in bulk, generate the INVOICE_PAYMENTS reportAPI v2.

Webhook event reference

Solidgate triggers events every time a subscription or invoice changes state. Some events are sent immediately when a subscription is created, while others are sent on regular billing periods.

Make sure that your integration properly the events listed below. For example, you might want to notify a customer when a payment fails, restrict access when the subscription enters redemption, or revoke access when a subscription is cancelled.

Subscription events

Invoice events

Because invoices can be created for both subscriptions and one-time purchases, invoice events fire independently of subscription events. For subscription billing, the most important invoice events are:

Customer events

Solidgate sends customer events when a customer record is created or updated. Since subscriptions and invoices rely on customer records for billing and tax information, these events help keep your local database in sync.

Payment instrument events

Solidgate sends payment instrument events when a saved payment method (like a credit card) is added, removed, or expires.