Subscriptions

Subscriptions allow you to automate recurring billing for a customer on a defined schedule. This guide covers the prerequisites, API flow, and how to create and manage subscription plans.

Prerequisites

Before creating a subscription, two things must be in place:

Stored Customer: The customer must exist in the Ecrypt system with a populated customer wallet containing at least one stored payment token (wallet payment method).
Reusable Payment Token: When capturing the initial payment method (via iFrame or checkout page), oneTimePayment must be set to false. This ensures the generated token can be stored to the customer wallet and used for future recurring charges. Setting this to true will prevent the token from being reused.

API Flows

iFrame and Direct API

For a first-time customer using the iFrame or direct API integration, the typical sequence is:

Create Token — Tokenize the customer’s payment method via the iFrame or checkout page with oneTimePayment: false.
Create Customer — POST /v1/customers
Create Customer Wallet — POST /v1/customers/{Customer}/wallet — Store the token to the customer’s wallet.
Create Subscription Plan — POST /v1/subscriptions — Define the billing plan (cycle, amount, label).
Create Customer Subscription — POST /v1/customers/{Customer}/subscriptions — Link the customer and their wallet to the subscription plan.

Dynamic Checkout Page

The Dynamic Checkout page simplifies this considerably. By including a subscription object in the POST /v1/dynamiccheckout request body, the checkout page handles the entire flow in a single session:

Tokenization > create customer > store payment method > subscription enrollment.

You simply select a pre-defined billing cycle and a billing date (start date) within the pages subscription object, and the checkout page takes care of the rest.

Create a Subscription Plan

POST /v1/subscriptions This endpoint defines a reusable subscription plan that can then be assigned to one or more customers.

Required Fields

label (string, required) — A human-readable name for the subscription plan. Must be between 1 and 100 characters. cycle (object, required) — Defines the billing frequency and timing.

Field	Type	Description
`unit`	string	The base time unit: `day`, `week`, `month`, or `year`
`interval`	int32	How often the cycle repeats within that unit. For `day`: 1-365 (1 = daily, 2 = every other day). For `week`: 1-52 (1 = every week, 2 = every other week — defaults to Monday if no `dayOfCycle` is set). For `month`: 1-12 (1 = every month, 2 = every other month — defaults to the subscription activation date if no `dayOfCycle` is set). For `year`: 1-500.
`day_of_cycle`	int32	The specific day within the cycle to charge. For `week` unit: 1-7 (1 = Monday, 7 = Sunday). For `month` unit: 1-31 (31 defaults to the last day of the month for shorter months). For `year` unit: 1-365. Not applicable for `day` unit.

amount (object, required) — The billing amount for each cycle occurrence.

Field	Type	Description
`currency`	integer	ISO 4217 numeric currency code. Example: `840` = USD.
`value`	decimal	The full charge amount per cycle, inclusive of all taxes, fees, and discounts. Range: `0.01` to `999999999.99`. Example: `49.99`

Example Request

{
  "label": "Monthly Premium Plan",
  "cycle": {
    "unit": "month",
    "interval": 1,
    "day_of_cycle": 1
  },
  "amount": {
    "currency": "USD",
    "value": 49.99
  }
}

Enrolling a Customer in a Subscription

POST /v1/customers/{Customer}/subscriptions Once a subscription plan exists and the customer has a populated wallet, use this endpoint to activate the subscription for a specific customer.

Field	Type	Description
`subscription_id`	string	The ID of the subscription plan to assign.
`start`	date-time	The billing start date — when the first charge will occur.
`skip_first_payment`	boolean	If `true`, the first scheduled billing cycle is skipped.
`wallet`	string (required)	The wallet ID of the stored payment method to charge.
`initiated_by`	string	Indicates who initiated the transaction.

Checkout Page Subscription Object

When using the Dynamic Checkout page (POST /v1/dynamiccheckout), include the subscription object to handle the full enrollment flow automatically. This is the simpler path for new customers.

Field	Type	Description
`billing_cycle`	integer	Pre-defined billing cycle. See values below.
`billing_date`	date-time	The start date for the subscription and first charge is scheduled.
`label`	string	A label for the subscription.

Billing Cycle Values

Value	Cycle
`10`	Daily
`20`	Weekly
`30`	BiWeekly
`50`	SemiMonthly (1st and 15th)
`52`	SemiMonthly (15th and Last)
`70`	Monthly
`71`	Monthly (1st)
`73`	Quarterly
`79`	Monthly (Last)
`90`	SemiAnnually
`95`	Annually

Subscription Management

Once active, a customer subscription can be managed via the following endpoints. See the Customer Subscription section in the API reference.

Modify Price — PUT /v1/customers/{Customer}/subscriptions/{Subscription}
Suspend — PUT /v1/customers/{Customer}/subscriptions/{Subscription}/suspend
Resume — PUT /v1/customers/{Customer}/subscriptions/{Subscription}/resume
Cancel — DELETE /v1/customers/{Customer}/subscriptions/{Subscription}
Delete Plan — DELETE /v1/subscriptions/{Subscription}

Getting Started

Accept Payments

Payment Operations

Customers

Reporting

Developer Resources

Prerequisites

API Flows

iFrame and Direct API

Dynamic Checkout Page

Create a Subscription Plan

Required Fields

Example Request

Enrolling a Customer in a Subscription

Checkout Page Subscription Object

Subscription Management

​Prerequisites

​API Flows

​iFrame and Direct API

​Dynamic Checkout Page

​Create a Subscription Plan

​Required Fields

​Example Request

​Enrolling a Customer in a Subscription

​Checkout Page Subscription Object

​Subscription Management

Prerequisites

API Flows

iFrame and Direct API

Dynamic Checkout Page

Create a Subscription Plan

Required Fields

Example Request

Enrolling a Customer in a Subscription

Checkout Page Subscription Object

Subscription Management