Guides
helcim.com
Start typing to search…

Recurring API

Set up recurring payments for your customers using the Recurring API.

The Recurring API allows you to create, retrieve, update, and delete a range of payment plan, subscription, and add-on objects in the Helcim system.

With the Recurring API, you can create recurring payment plans, subscribe customers to these plans, and manage your subscribers add-ons and payments.

Recurring API benefits

The Helcim Recurring API is designed to grow with your business. Whether you're offering subscription services, membership programs, or installment payments for goods and services, it allows for different models to enable your business to scale payments seamlessly.

Integrate with the Recurring API today and create a stream of steady cash flow that it predictable and reliable, while reducing the overheads of managing other more manual payment methods. When the flexibility of our payment plans, you can set up subscriptions for recurring payments for a range of different billing frequencies and payment terms, while making doing business with you even more convenient for your customers.

Recurring API implementation recommendation

When integrating recurring payments into your existing systems, there are some standard recommendations that we would make for all merchants to ensure a seamless integration.

Step 1: Create your payment plans

The foundation of all recurring payments in the Helcim system is your payment plan. Whether you create these through the Recurring tool in your Helcim dashboard, or via an API call to the Create payment plans endpoint, you'll have access to update and subscribe customers to these plans through the API.

The payment plan object controls the billing behaviour that you would like your customers subscriptions to adhere to, including whether there are set up fees, the billing frequency and dates, whether the plan expires, and how tax should be applied.

Step 2: Create your customers and capture their payment information

After creating your payment plans, you'll want to create your customers in the Helcim system and capture their payment information. Because recurring payments are automatic, to subscribe a customer to a payment plan you'll want to create the customer object and collect their payment information first.

The recommendation for creating customers and capturing their payment information up front, is to integrate with HelcimPay.js and use the paymentType of verify and the customerRequest object to pass us the required customers information.

Step 3: Subscribe your customers to the right payment plan

Now that you have your payment plans set up and you have customers with stored payment information, you're ready to make your call to the Create subscriptions endpoint to subscribe your customer to the payment plan they chose.

This is where you can make the final decision on the recurring amount be billed to your customer, when their subscription should activate and whether it has any add-ons, how many cycles it should bill for, and what payment method they chose to pay for their subscription.

Recurring API functionality

The Recurring API allows you to manage all of the required objects needed to set your customers up for recurring billing in the Helcim system.

Payment plans

A payment plan object represents the core element of a recurring service that one or more customers can be subscribed to through a subscription.

The payment plan stores a number of the core attributes that apply to subscribers to that plan, including:

  • Basic information such as the unique name for the plan and plan description.
  • Whether the payment plan has a trial period and whether subscriptions to that plan expire.
  • Pricing information such as the one-time set up fees, the recurring amount to be charged, and the billing period.
  • Billing schedule information such as the billing day and and how many billing periods the plan should bill for.
  • Payment method and tax information that determines what payment methods subscribers can use to pay for that plan and how the Helcim system will calculate tax for the payments when they are processed.

Subscribers

A subscription object represents a subscribers unique subscription to a payment plan. A single subscriber can be subscribed to multiple different payment plans and can even have multiple subscriptions to the same payment plan.

The subscription stores a number of core attributes to apply to that subscribers unique subscription to a plan, including:

  • Subscription information such as recurring amount for that subscription and the customer that subscription is for.
  • Subscription schedule information such as the number of billing cycles that subscriber will be charged and when their subscription will activate.
  • Payment method information that determines whether the subscriber will pay using their default credit card or default ACH bank payment details.
  • Payments and add-ons sub-objects for each payment processed or add-on linked for the subscription, returned in an array.

🚧

Payment methods

A subscription will always charge the subscribers default credit card or bank account, depending on the payment method selected for them when setting them up as a subscriber to a payment plan.

To capture credit card or bank payment details for a new customer, we recommend utilizing HelcimPay.js initialized with a paymentType of verify. This allows you to capture payment details in an easy and secure manner while also setting those details as default for the customer.

To change the default payment method for the subscriber, utilize the following endpoints to update their customer object, or update the customers profile manually in the Customers section of your Helcim account.

Add-ons

An add-on object represents an optional additional charge that can be made available on specific payment plans, then applied to subscriptions for your subscribers. An add-on can only be applied to a subscription if it is available on the payment plan the subscriber is being subscribed to.

The add-on stores a number of core attributes that apply to that additional optional charge for a subscriber to a payment plan, including:

  • Basic information such as the name and description of the add-on.
  • Whether the add-on has singular or multiple quantity functionality.
  • Pricing information that determines the price for the add-on and whether the add-on is a one time or recurring charge.

Procedures

A procedure allows you to complete unique actions that assist in managing subscriptions created through the Recurring API.

Process a subscription payment

While all one-time and recurring charges for subscribers are automated and processed during object creation or on scheduled billing dates, there are situations where a charge may fail. This is often due to a declined payment.

The Process a subscription payment procedure will allow you to process a failed payment and can be actioned after correcting the cause of the original failure, such as changing default banking or updating credit card details for the customer.

Recurring API endpoints

Payment plans

Create, retrieve, update, and delete payment plan objects using the following endpoints.

Subscribers

Create, retrieve, update, and delete subscription objects, mark declined payments as paid, or link, update, and delete subscription add-ons using the following endpoints.

Add-ons

Create, retrieve, update, and delete add-on objects using the following endpoints.

Procedures

Manage your subscriptions using the following procedure endpoints.

Updated 26 days ago