HUhub2
Subscription Intents

Enroll a customer in card-on-file recurring debits

Changed on

Starts a card-on-file enrollment and returns the enrollment payment with the action the customer must complete. Poll its outcome with GET /subscription-intents/{id}/status.

post/subscription-intents

Request

  • The document declares no server URL.
  • Auth
    none declared. Required headers: ApiKey, MerchantId, Environment

Headers

ApiKeystring required

Your api key. To create a key, please get into our dashboard. If you don't have access to it, please reach the Support team.

MerchantIdstring required

Your merchant ID. This information is available in our dashboard. If you don't have access to it, please reach the Support team.

Environment'live' | 'sandbox' required

Allow you to choose between the sandbox mode to perform some tests or the live mode for real world transactions.

Request body

customerReferencestring required

Your reference for the customer being enrolled in card-on-file.

emailstring required

Customer email, to which the enrollment and recurring-debit notifications are sent.

amountnumber

For a rbs_scheduled enrollment: the recurring debit amount, in the smallest currency unit (e.g. 100 cents to charge €1.00) — distinct from any amount charged at enrollment time. For merchant_initiated: not a recurring amount (ignored in live), and in sandbox it selects the simulated enrollment outcome like any enrollment amount would — omit it to simulate success.

currencystring required

Three-letter ISO currency code.

frequency'weekly' | 'monthly'

Recurring debit frequency. Required for a rbs_scheduled enrollment (the default). Not accepted for a merchant_initiated enrollment.

startDatestring

ISO-8601 date of the first recurring debit. Required for a rbs_scheduled enrollment (the default). Not accepted for a merchant_initiated enrollment.

billingMode'rbs_scheduled' | 'merchant_initiated'

rbs_scheduled (default) — the customer is debited automatically on frequency/startDate/amount. merchant_initiated — the card is stored for on-demand charges via POST /subscriptions/{id}/charge; frequency and startDate are not accepted, and amount is not a recurring amount.

onSuccessRedirectionUrlstring

The url used to redirect the user when the enrollment is successful. You must provide a fully-qualified address using https as the scheme.

onFailedRedirectionUrlstring

The url used to redirect the user when the enrollment fails. You must provide a fully-qualified address using https as the scheme.

Example request

{
  "customerReference": "cust_01924059",
  "email": "customer@example.com",
  "amount": 5000,
  "currency": "XOF",
  "frequency": "monthly",
  "startDate": "2026-08-01",
  "billingMode": "rbs_scheduled",
  "consent": {
    "given": true,
    "timestamp": "2026-07-03T10:00:00.000Z",
    "reference": "consent-01924059"
  }
}

Response

paymentIdstring required

Id of the underlying enrollment payment.

status'successful' | 'failed' | 'pending' | 'action_required' required

Example response

{
  "action": {
    "data": {
      "method": "post"
    }
  }
}

Changes