Subscriptions allow merchants to automatically charge customers in monthly/daily cycles for a service or product. The sections details how to create and manage subscriptions.
For more information about Subscriptions, please refer to this page.
A subscription typically follows a lifecycle that includes the following stages:
- Pending: The subscription is created but not yet active. This stage allows for any necessary setup or configuration before the first payment is processed. For example, subscriptions created with a billing cycle that starts in the future will be in a pending state until the start date is reached.
- Active: The subscription is active, and recurring payments are processed according to the defined schedule (e.g., weekly, monthly, annually). Tipically, a subscription will become active after the first payment is successfully processed.
- PastDue: If a payment fails or is not processed on time, the subscription may enter a past due state. This indicates that the customer needs to take action to resolve the payment issue, such as updating their payment method or making a manual payment. This can happen if the payment method is declined or if there are insufficient funds. When a payment fails:
- the subscription will immediately enter the PastDue state;
- the balance of the subscription will be incremented to represent the customer's outstanding balance; Note that PastDue subscriptions which subsequently have a successful payment (and brings the balance owed back to zero) will automatically return to the Active state.
- Paused: The subscription is temporarily paused, meaning that no further payments will be processed until the subscription is resumed. Unlike Cancelled subscriptions, paused subscriptions can be resumed at a later date without losing the subscription history or configuration.
- Cancelled: The subscription is cancelled, meaning that no further payments will be processed, and the subscription will not be resumed.
- Ended: The subscription's billing cycle has ended, and no further payments will be processed. This status is terminal. Note that subscriptions set to run indefinitely will not enter this state unless explicitly cancelled or updated to end after a certain number of cycles.
Let's consider the use case of a customer who loves coffee but wants the convenience of not having to remember to buy new beans every week.
A coffee vendor can offer this customer a platform where they select their product, subscription frequency and duration of the subscription.
The vendor, acting as the Main Account, then initiates a Payment Session with these details. The customer can then securely enter their payment information and agree to a recurring charge.
Subsequently, on the agreed-upon date each month, the merchant's payment system (powered by Ryft) automatically charges the customer's card for the subscription amount.
To initiate a Subscription, you first need to have a Customer ID.
You can obtain this ID by creating a new Customer entity using the customerCreate endpoint or via the Ryft Portal. Alternatively, if the customer already exists, you can retrieve their ID using the same methods.
Request Example:
{
"email": "abc@ryftpay.com",
"firstName": "Nathan",
"lastName": "Drake"
}Response Example:
{
"id": "cus_XXXXXXX",
"email": "abc@ryftpay.com",
"firstName": "Nathan",
"lastName": "Drake",
"createdTimestamp": 1470989538
}Take note of the id value to use it for next step.
To create a new customer using the Ryft Portal, navigate to the Customers page and click the Create Customer button. A new window will appear where you can enter the customer's details.
Once the customer is created, they will be added to the top of the Customers table. You can easily obtain their Customer ID by clicking on that entry.
Once a Customer ID is available, and the details of the subscription have been collected from your platform (e.g.: quantity/costs, frequency and duration) a Subscription can be created using the subscriptionCreate endpoint.
Request Example:
{
"customer": {
"id": "cus_XXXXXXXX" // Customer ID
},
"description": "Coffee beans (12 months)",
"price": {
"amount": 500, // £5.00
"currency": "GBP",
"interval": {
"unit": "Days",
"count": 7, // Every 7 days
"times": 52 // Repeat for 52 times (1 year)
}
}
}This configuration will result in the Customer being charged a recurring amount of £20.50, specified in the price.amount field. This charge will occur every 7 days for 52 cycles, completing a one-year subscription.
Provided the request was successful, the following response will be returned:
Response Example:
{
"id": "sub_XXXXXXXX",
"status": "PastDue",
"customer": {
"id": "cus_XXXXXXXX"
},
"paymentSessions": {
"initial": {
"id": "ps_XXXXXXXX",
"clientSecret": "ps_XXXXX_secret_XXXXX"
},
"latest": {
"id": "ps_XXXXXXXX",
"clientSecret": "ps_XXXXX_secret_XXXXX"
}
},
... (see API reference for full response)
}At this point the subscription is in status PastDue, meaning payment is due. You are now ready to collect the payment details from the customer using the payload response.
Here is a list of few examples that illustrate how to setup various prices/plans.
{
"customer": {
"id": "cus_XXXXXXXX" // Customer ID
},
"description": "Coffee beans (12 months)",
"price": {
"amount": 500, // £5.00
"currency": "GBP",
"interval": {
"unit": "Months",
"count": 1, // Every 1 month
}
}
}With this setup, the customer will be charged £5.00 each month on an indefinite basis. Note that this is achieved by not including the price.interval.times parameter.
New subscriptions can also be created from the Subscriptions page within the Ryft Portal by clicking the Create Subscription button. This will open a new window where the user can define all the necessary subscription details.
Please note that, although the portal allows you to create a subscription, you will still need to collect the customer's payment details using the SDK or API in order to activate it.
Subscriptions can be visualised on the Subscriptions page, where details such as their status, amount, interval, and cycle can be found.