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. |
| [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. |
| [PaymentMethod] | A customer’s payment instruments that they use to pay for your products. For example, you can store a credit card on a Customer object and use it to make recurring payments for that customer. Typically used with the Payment Intents APIs. |
| [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. |
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:1.
Creates a new subscription with your customer.
2.
Generates an invoice for your initial subscription cycle.
3.
Collects payment details and pays your invoice.
4.
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 )
How payments work with subscriptions#
To simplify the handling of failed payments and to create subscriptions before attempting payment:1.
If your subscription requires payment, it’s created with an incomplete status, otherwise your subscription immediately becomes active.
2.
Activate an incomplete subscription by paying the first invoice.
3.
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",
...
}
}
}
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:1.
You create the subscription. The status of the subscription is incomplete.
2.
An invoice is created for the subscription. The status of the invoice is open.
3.
The customer pays the first invoice.
4.
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.
5.
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.
