Get started with Subscription

We currently support two subscription modes:

Automatic Billing by UseePay - UseePay automatically charges the customer at each billing cycle.

Merchant-Initiated Billing – When the billing period arrives, the merchant initiates the charge manually or through their own system.

Subscriptions allow you to charge a customer on a recurring basis.

How subscriptions work

Learn how to manage recurring payments and subscription lifecycles.

With Subscriptions, customers make recurring payments for access to a product. Subscriptions require you to retain more information about your customers than one-time purchases because you need to charge them in the future.

Subscription objects

Use the following core API resources to build and manage subscriptions:

Resource	Definition
Customer	Represents a customer who purchases a subscription. Use the Customer object associated with a subscription to make and track recurring charges and to manage the products that they subscribe to.
Subscription	Represents a customer’s scheduled recurring purchase of a product. Use a subscription to collect payments and provide repeated delivery of or continuous access to a product.
Invoice	A statement of amounts a customer owes that tracks payment statuses from draft through paid or otherwise finalized. Subscriptions automatically generate invoices.
PaymentIntent	A way to build dynamic payment flows. A PaymentIntent tracks the lifecycle of a customer checkout flow and triggers additional authentication steps when required by regulatory mandates, custom Radar fraud rules, or redirect-based payment methods. Invoices automatically create PaymentIntents.

Integration example

Landing page

On your frontend, the landing page collects the email address first. Your application might have other customer-specific information you want to collect like a username or address. Clicking the signup button sends the information collected on the landing page to your backend. This process creates a customer and displays the pricing page on your frontend.

Payment

The payment form collects a name and card information. UseePay hosts this form if you use Checkout. It’s one of the key features that allows you to collect payments and remain PCI compliant. Clicking Subscribe:

Creates a new subscription with your customer.

Generates an invoice for your initial subscription cycle.

Creates a new paymentIntent for your invoice.

Confirm the paymentIntent.

Sets the payment method as the default payment method for the subscription-a requirement for subsequent payments.

📌

Subscription with UseePay hosted checkout (First payment)

Subscription with UseePay hosted checkout (Second or later )

📌

In a UseePay hosted checkout subscription, if the collect_method parameter is not specified, it indicates that the subscription is merchant-initiated. The merchant is responsible for initiating the payment at each billing cycle via system API or backend operations.

If you want charge automaticallly, you can refer to Auto-Charge Subscription Guide

How payments work with subscriptions

To simplify the handling of failed payments and to create subscriptions before attempting payment:

If your subscription requires payment, it’s created with an incomplete status, otherwise your subscription immediately becomes active.

Activate an incomplete subscription by paying the first invoice.

Pass the payment intent identifier from the invoice to your user interface to collect payment information and confirm the payment intent.

Payment status

The payment process differs across payment methods and geographical locations. Payments can also fail initially (for example, a customer might enter the wrong card number or have insufficient funds), so various payment outcomes are possible.

A PaymentIntent tracks the lifecycle of every payment. Whenever a payment is due for a subscription, UseePay generates an invoice and a PaymentIntent. The PaymentIntent ID attaches to the invoice and you can access it from the Invoice and Subscription objects. The state of the PaymentIntent affects the state of the invoice and the subscription. Here’s how the different outcomes of a payment map to the different statuses:

Payment outcome	PaymentIntent status	Invoice status	Subsription status
Success	succeeded	paid	active
Fails because of a card error	requires_payment_method	open	incomplete
Fails because of authentication	requires_action	open	incomplete

Payment succeeded

When your payment succeeds, the status of the PaymentIntent is succeeded, and the subscription becomes active. For payment methods with longer processing periods, subscriptions are immediately activated. In these cases, the status of the PaymentIntent may be processing for an active subscription until the payment succeeds.

{
  "id": "sub_1ELI8bClCIKljWvsvK36TXlC",
  "object": "subscription",
  "status": "incomplete",
  ...
  "latest_invoice": {
    "id": "in_EmGqfJMYy3Nt9M",
    "status": "open",
    ...
    "payment_intent": {
      "status": "requires_payment_method",
      ...
    }
  }
}

To resolve these scenarios:

Notify the customer.

Collect new payment information and confirm the payment intent.

Update the default payment method on the subscription.

Requires action

Some payment methods require customer authentication with 3D Secure (3DS) to complete the payment process. If you use the Payment Intents API, the value of latest_invoice.payment_intent.status is requires_action when a customer needs to authenticate a payment. 3DS completes the authentication process. Whether a payment method requires authentication depends on your Radar rules and the issuing bank for the card.

{
  "id": "sub_1ELI8bClCIKljWvsvK36TXlC",
  "object": "subscription",
  "status": "incomplete",
  ...
  "latest_invoice": {
    "id": "in_EmGqfJMYy3Nt9M",
    "status": "open",
    ...
    "payment_intent": {
      "status": "requires_action",
      "client_secret": "pi_91_secret_W9",
      "next_action": {
        "type": "redirect",
        ...
      },
      ...
    }
  }
}

The subscription lifecycle

This is what the recommended subscription flow looks like:

You create the subscription. The status of the subscription is incomplete.

An invoice is created for the subscription. The status of the invoice is open.

The customer pays the first invoice.

When the payment succeeds:

The subscription status moves to active

The invoice status is set to paid

UseePay sends an invoice.paid event to your configured event destinations.

You provision access to your product. You can confirm whether the invoice has been paid by:

Setting up an event destination and listening for the invoice.paid event.

Manually checking the subscription object and looking for subscription.status=active. The status becomes active when the invoice has been paid either through an automatic charge or having the customer pay manually.

Renewal payment failure handling

For merchant-initiated subscriptions (non-auto_charge mode), the recommended lifecycle is as follows:

The merchant creates the subscription, and the initial subscription status is incomplete.

The system generates the first invoice for the subscription, and the invoice status is open.

Once the first invoice is paid successfully, the invoice status becomes paid, and the subscription status becomes active.

In subsequent billing cycles, the system generates a new renewal invoice.

If the renewal invoice is paid successfully, the invoice status becomes paid, and the subscription remains active.

If the renewal invoice payment fails, the invoice status becomes payment_failed, and the subscription status becomes paused.

While the subscription is in the paused state, the merchant does not need to create a new subscription or a new invoice.

Instead, the merchant can retry the payment using the original failed invoice.

If the original failed invoice is paid successfully on retry, the invoice status becomes paid, and the subscription returns to active.

10.

If the retry fails again, the invoice remains payment_failed, and the subscription stays paused.

If event destinations are configured, merchants can also track these changes through events such as invoice.paid, invoice.payment_failed, subscription.active, and subscription.paused.

Get started with Subscription

How subscriptions work#

Subscription objects#

Integration example#

Landing page#

Payment#

How payments work with subscriptions#

Payment status#

Payment succeeded#

Requires action#

The subscription lifecycle#

Renewal payment failure handling#

Sequence Diagram#