Introduction

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

• API reference
• OpenAPI specification

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.