Guides
helcim.com

Recurring API

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

Overview

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 Use Cases

  • Integrate your existing website or software with HelcimPay.js and the Recurring API to capture customer credit card or bank details, then set up recurring payments for your products and services.
  • Integrate your existing systems with the Recurring API to allow full end to end management of your Recurring payment plans, subscribers, and add-ons, without having to log in to the Helcim system.

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 about 1 month ago