Enroll a customer in card-on-file recurring debits

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//status.

POST /subscription-intents

Enroll a customer in card-on-file recurring debits

cURL

curl --request POST \
  --url https://api.example.com/subscription-intents \
  --header 'ApiKey: <apikey>' \
  --header 'Content-Type: application/json' \
  --header 'Environment: <environment>' \
  --header 'MerchantId: <merchantid>' \
  --data '
{
  "customerReference": "cust_01924059",
  "email": "[e-mail]",
  "currency": "XOF",
  "consent": {
    "given": true,
    "timestamp": "2026-07-03T10:00:00.000Z",
    "reference": "consent-01924059"
  },
  "amount": 5000,
  "frequency": "monthly",
  "startDate": "2026-08-01",
  "billingMode": "rbs_scheduled",
  "onSuccessRedirectionUrl": "<string>",
  "onFailedRedirectionUrl": "<string>"
}
'

201

{
  "paymentId": "<string>",
  "status": "successful",
  "action": {
    "type": "ussd",
    "message": "<string>",
    "data": {
      "url": "<string>",
      "urls": "<string>",
      "method": "post",
      "headers": {},
      "data": {}
    }
  }
}

Headers

ApiKey · string · 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.

MerchantId · string · 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 · enum<string> · required

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

Available options: live, sandbox

Body

application/json

customerReference · string · required

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

Maximum string length: 255

Example:

"cust_01924059"

email · string · required

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

Example:

"[e-mail]"

currency · string · required

Three-letter ISO currency code.

Example:

"XOF"

consent · object · required

Required — per the Visa Stored Credential Framework, no card-on-file enrollment can start without an explicit, timestamped consent. Absent or invalid consent causes the enrollment to be rejected.

Show child attributes

amount · number

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.

Required range: x <= 9999999999

Example:

5000

frequency · enum<string>

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

Available options: weekly, monthly

Example:

"monthly"

startDate · string

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

Example:

"2026-08-01"

billingMode · enum<string> · default: rbs_scheduled

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.

Available options: rbs_scheduled, merchant_initiated

Example:

"rbs_scheduled"

onSuccessRedirectionUrl · string

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

Maximum string length: 2084

onFailedRedirectionUrl · string

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

Maximum string length: 2084

Response

201

application/json

paymentId · string · required

Id of the underlying enrollment payment.

status · enum<string> · required

Available options: successful, failed, pending, action_required

action · object

Present when status is "action_required". Same shape as a regular payment's nextAction (see PaymentDto) — build and auto-submit a form from action.data.{url, method, data} to complete card enrollment on the hosted card page.

Show child attributes