> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hub2.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

> Discover Subscriptions, the HUB2 solution for debiting a customer card on a recurring basis, on a schedule or on demand.

> [!NOTE]
>
> * [API reference](https://docs.hub2.io/api-reference/subscriptions/create-a-subscription-link.md)
> * [OpenAPI specification](https://api.hub2.io/docs-json)

## Overview

**Subscriptions** let you debit the same customer card several times without asking the customer to enter it again. The customer enrolls their card once, gives an explicit consent and authenticates with 3D Secure. HUB2 then keeps a reference to the card, never the card number, and uses it for every later debit. This mechanism is called card-on-file.

Enrolling a card does not charge the customer. The first debit happens on the start date you define for a scheduled subscription, or when you request it for an on-demand subscription.

## Two types of subscription

You choose the type of subscription when you enroll the customer. The type is the `billingMode` of the subscription and cannot be changed afterwards.

| | Scheduled | On demand |
| :- | :- | :- |
| `billingMode` | `rbs_scheduled` (default) | `merchant_initiated` |
| Who triggers each debit | HUB2, automatically | You, with an API call |
| Amount | Fixed, defined at enrollment | Chosen for each charge |
| Frequency | `weekly` or `monthly`, from a start date | None |
| Typical use | Memberships, installments, fixed monthly fees | Usage-based billing, variable invoices, top-ups |
| Result of a debit | `payment.succeeded` or `payment.failed` webhook, and the charge history | Response of the charge call, and the charge history |

## How it works

1. **Create an API key** with the subscription permissions.
2. **Ask HUB2 to enable card-on-file** for your merchant account.
3. **Enroll the customer**, either by sending a subscription link or by starting a subscription intent from your own page.
4. **Follow the enrollment** with the `subscription.created` webhook or by polling the enrollment status.
5. **Let HUB2 debit the customer** (scheduled), or **charge the customer** when you need to (on demand).
6. **Manage the subscription**: list, suspend, cancel and review the charges.

## Two ways to enroll a customer

* **Subscription link**: one API call returns a link to a page hosted by HUB2. You share the link by e-mail, SMS or in your application. The page collects the customer e-mail address and consent, then sends the customer to the card page. You build no interface.
* **Subscription intent**: you collect the consent in your own interface and start the enrollment through the API. HUB2 returns the action to perform to open the card page. You control the full customer journey, and you can create on-demand subscriptions.

## Key points

* **Explicit consent**: no enrollment starts without a consent given by the customer and timestamped.
* **3D Secure**: every enrollment is authenticated by the card issuer.
* **No card data on your side**: HUB2 stores the reference of the card. You only handle the subscription identifier.
* **Cancellation is final**: a cancelled subscription stops all future debits. HUB2 does not refund or prorate anything when you cancel.
* **Notifications**: HUB2 e-mails the customer about the enrollment, upcoming debits, successful and failed debits, and when a subscription is suspended or cancelled.

## Availability

Card-on-file is available to merchants registered in Côte d'Ivoire, and it must be enabled for your merchant account by HUB2. Until then, enrollment requests are refused with a `403` error. Contact HUB2 Support to request it.

## Use cases

Subscriptions are ideal for:

* **Telecom and internet providers:** debit the monthly fee of a plan without sending a payment request every month.
* **Insurance companies:** collect premiums weekly or monthly.
* **Gyms, schools and associations:** bill memberships and tuition installments on a fixed schedule.
* **Marketplaces and utilities:** store the card once, then charge each invoice when its amount is known.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.