Skip to content
Process Payments/
/
Subscriptions
Last updated

Subscriptions

Overview

Subscriptions allows merchants to set up recurring payments for their customers, enabling a seamless and automated billing process.

This page will guide you throgh the steps to process Subscriptions using Ryft.

Requirements

Before proceeding, you must ensure that you have completed the Subscription initial setup as described in the Initial Setup page.

Once the initial setup is complete, you will need the subscription details that you will use to process the payment:

  • If you have created a Subscription using the API, you should have already available the response payload to use in the next steps. If not, you can retrieve the Subscription details using the subscriptionGetById endpoint.
  • If you have created a Subscription using the Ryft Portal, you can retrieve the Subscription details using the subscriptionGetById endpoint. The Subscription ID can be found in the Portal under the Subscriptions section.

You can view an example of a Subscription object in the Subscription page of the Initiate Payments section.

Configuring the Embedded SDK

To process a payment for a Subscription, you will need to configure the embedded SDK accordingly by providing the following parameters:

  1. the clientSecret option with the paymentSessions.initial.clientSecret value returned from the API
  2. the paymentType option to Recurring, and
  3. if you want to show your customer the details of the Subscription (which is highly recommended, unless you have a custom UI to display the Subscription details outside of the embedded SDK payment form), you can provide the subscription.rawJson option with an object containing the raw JSON obtained following the steps described in the Requirements section. This will allow the embedded SDK to display the Subscription details to the customer during the payment process. Please note you can use the JSON.stringify() method to convert the Subscription object into a JSON string.

Below is an example of how to configure the embedded SDK for processing a Subscription payment:

Process Subscription Payment Example
const clientSecret = "ps_XXXXXXXXXXXXXXXXXXXX"; // Replace with your actual client secret returned from the API
const subscriptionPayload = {  // Replace with your actual Subscription object (copy-paste from the API response)
    "id": "sub_XXXXXXXXXXXXXXXXX",
    "status": "PastDue",
    "customer": {
        "id": "cus_XXXXXXXXXXXXXXXXX"
    },
    "paymentSessions": {
        "initial": {
            "id": "ps_XXXXXXXXXXXXX",
            "clientSecret": "ps_XXXXXXXXXXXXXXXXXXXX"
        },
        "latest": {
            "id": "ps_XXXXXXXXXXXXX",
            "clientSecret": "ps_XXXXXXXXXXXXXXXXXXXX"
        }
    },
    ... // Rest of the Subscription object
}

Ryft.init({
    publicKey,
    clientSecret,
    paymentType: 'Recurring',
    subscription: {  // Optional but recommended
        rawJson: JSON.stringify(subscriptionPayload)
    }
});

Provided that the embedded SDK is correctly configured, the embedded payment form will be rendered, allowing the customer to complete the payment for the Subscription.

Once the customer submits the payment form, the embedded SDK will handle the payment processing and start the recurring billing cycle as defined in the Subscription details.

Handling Failed Payments

Some payments made throughout the Subscription lifecycle may fail. This can happen for various reasons, such as insufficient funds, expired payment methods, or network issues.

In order to handle these failures, you should:

  • Ensure you listen to the relevant webhooks to be notified when a payment fails.
  • Bring the failed payment to the customer's attention, and request them to update their payment method or take any necessary actions to resolve the issue.

Please note: Ryft will automatically retry failed payments in which the decline code is considered as retryiable. Typically you can just wait until all the retries are exhausted before reaching out to the customer. If a retry in the current cycle succeeds, no further action is required and the subscription will transition back to an Active status.

However, in case of hard declines (e.g., insufficient funds), you should contact the customer immediately to update their payment method. In such cases, you should use the clientSecret and requiredAction values from the latest paymentSessions object in the Subscription to re-initiate the payment process. See the Required Actions page for more information on how to handle this scenario.

Next Steps

After successfully processing a payment for a Subscription, you can manage and monitor the Subscription through the Ryft Portal or by using the Ryft API. You can view details such as payment history, upcoming billing dates, and customer information.

There may be situations where you need to update the Subscription details, such as changing the billing amount, updating the payment method, pausing or cancelling a Subscription. Please refer to the Manage Subscriptions section of the Ryft API documentation for more information on how to make these updates.

Additionally, as mentioned earlier, make sure to register for the relevant webhooks to stay informed about important events related to Subscriptions, such as payment failures, cancellations, or updates.

Previous page
Next page