Recurring Payment API

The recurring payment endpoint is used for charging a card regularly (for example, subscriptions
or installment payments). Typically, you would use this after you have already processed an initial payment with the card (often with 3D Secure if required) or have a token for the card. Recurring payments are usually merchant-initiated (without direct customer action each time), and may be exempt from 3D Secure depending on the scenario.

Overview

Use this endpoint to create, update, retrieve, and cancel subscription plans. Each plan is tied to a cardToken from the Tokenization API and reuses your existing billing, order, and device contexts.

Create a new subscription
Retrieve details of an existing subscription
Update plan parameters or pause/cancel
Cancel to immediately deactivate

1. Create Subscription

Endpoint

Live

POST https://live.facilero.com/api/v1/payments/card/recurring

Sandbox

POST https://sandbox.facilero.com/api/v1/payments/card/recurring

Request Headers

Content-Type: application/json
Authorization: Bearer <AUTH_TOKEN>

Request Body

Field	Type	Required	Description
`requestId`	String	Yes	Unique identifier for this subscription creation.
`mid`	String	Yes	Merchant account ID.
`cardToken`	String	Yes	Vaulted token obtained from the Tokenization API.
`plan`	Object (Plan)	Yes	Subscription schedule (amount, currency, frequency, interval, dates). See Plan Object below.
`billingDetails`	Object (BillingDetails)	Yes	As in `/payments/card`: customer’s name, address, contact, KYC.
`order`	Object (Order)	No	Optional order context to associate with each charge.
`device`	Object (Device)	No	Optional device/browser info for risk scoring on initial authorization.
`callbackUrl`	String	Yes	URL to receive subscription event webhooks (success/failure of each charge attempt).
`metadata`	Map<String,String>	No	Free-form key/value pairs for your own reference.

Plan Object

Field	Type	Required	Description
`amount`	String	Yes	Decimal amount per billing cycle (precision per-currency).
`currency`	String	Yes	ISO 4217 code (e.g. `EUR`, `USD`).
`frequency`	String	Yes	Billing cadence. One of: `DAILY`, `WEEKLY`, `BIWEEKLY`, `MONTHLY`, `QUARTERLY`, `SEMIANNUAL`, `ANNUAL`.
`interval`	Integer	Yes	Multiplier for frequency (e.g. `interval=2` + `frequency=WEEKLY` = every 2 weeks).
`startDate`	String	Yes	ISO 8601 date when billing begins (e.g. `2025-08-01`).
`endDate`	String	No	ISO 8601 date when billing ends. Omit for open-ended subscriptions.

Example Request Body

{
  "requestId":      "req-sub-001",
  "mid":            "merchant456",
  "cardToken":      "tok_abc123xyz",
  "plan": {
    "amount":       "19.99",
    "currency":     "EUR",
    "frequency":    "MONTHLY",
    "interval":     1,
    "startDate":    "2025-08-01",
    "endDate":      "2026-07-31"
  },
  "billingDetails": {
    "firstName":     "Jane",
    "lastName":      "Doe",
    "address1":      "123 Main St",
    "city":           "Dublin",
    "state":         "Leinster",
    "country":       "IE",
    "postalCode":    "D01X0F5",
    "phone":         "+353851234567",
    "email":         "[email protected]",
    "dateOfBirth":   "1990-05-20"
  },
  "callbackUrl": "https://yourserver.com/subscription-webhook",
  "metadata": {
    "subscriptionName": "PremiumPlan"
  }
}

Response Body

Field	Type	Description
`subscriptionId`	String	Unique identifier for this subscription plan.
`status`	String	`PENDING`, `ACTIVE`, `PAUSED` or `CANCELED`.
`nextChargeDate`	String	ISO 8601 date of the upcoming scheduled charge.
`createdAt`	String	ISO 8601 timestamp when the subscription was created.

Example Response

{
  "subscriptionId": "sub_3344",
  "status":         "ACTIVE",
  "nextChargeDate": "2025-09-01",
  "createdAt":      "2025-07-14T10:20:00Z"
}

2. Retrieve Subscription

Endpoint

Live

GET https://live.facilero.com/api/v1/payments/card/recurring/{subscriptionId}

Sandbox

GET https://sandbox.facilero.com/api/v1/payments/card/recurring/{subscriptionId}

Request Headers

Authorization: Bearer <AUTH_TOKEN>

Response Body

Same fields as Create Subscription response, plus echo of the original plan, billingDetails, and metadata.

Example Response Body

{
  "subscriptionId":  "sub_3344",
  "status":          "ACTIVE",
  "nextChargeDate":  "2025-09-01",
  "createdAt":       "2025-07-14T10:20:00Z",
  "plan": {
    "amount":       "19.99",
    "currency":     "EUR",
    "frequency":    "MONTHLY",
    "interval":     1,
    "startDate":    "2025-08-01",
    "endDate":      "2026-07-31"
  },
  "billingDetails": {
    "firstName":    "Jane",
    "lastName":     "Doe",
    "address1":     "123 Main St",
    "city":         "Dublin",
    "state":        "Leinster",
    "country":      "IE",
    "postalCode":   "D01X0F5",
    "phone":        "+353851234567",
    "email":        "[email protected]",
    "dateOfBirth":  "1990-05-20"
  },
  "metadata": {
    "subscriptionName": "PremiumPlan",
    "customerId":       "cust-789"
  }
}

3. Update or Pause Subscription

Endpoint

PUT https://live.facilero.com/api/v1/payments/card/recurring/{subscriptionId}

Request Headers

Content-Type: application/json
Authorization: Bearer <AUTH_TOKEN>

Request Body

Include any of the mutable fields from the Plan Object or set:

Request Body DTO

Field	Type	Required	Description
`plan.amount`	String	No	Update the subscription’s amount per billing cycle (precision per-currency).
`plan.currency`	String	No	Update the ISO 4217 currency code (e.g. `EUR`, `USD`).
`plan.frequency`	String	No	Update the billing cadence (`DAILY`, `WEEKLY`, `BIWEEKLY`, `MONTHLY`, `QUARTERLY`, `SEMIANNUAL`, `ANNUAL`).
`plan.interval`	Integer	No	Update the multiplier for `frequency` (e.g. `2` + `WEEKLY` = every 2 weeks).
`plan.startDate`	String	No	Change the ISO 8601 start date (e.g. `2025-08-01`).
`plan.endDate`	String	No	Change or add the ISO 8601 end date; omit to leave open-ended.
`status`	String	No	Transition the subscription state: `PENDING`, `ACTIVE`, `PAUSED`, or `CANCELED`.

Example JSON

PUT https://live.facilero.com/api/v1/payments/card/recurring/sub_3344
Content-Type: application/json
Authorization: Bearer <AUTH_TOKEN>

{
  "plan": {
    "amount":    "24.99",
    "frequency": "MONTHLY",
    "interval":  1
  },
  "status": "PAUSED"
}

4. Cancel Subscription

Endpoint

DELETE https://live.facilero.com/api/v1/payments/card/recurring/{subscriptionId}

Request Headers

Authorization: Bearer <AUTH_TOKEN>

Response:

204 No Content on success

Subscription Webhook Callback DTO

When a scheduled charge attempt occurs, Facilero sends a POST to your callbackUrl. Below is the schema for that payload:

Field	Type	Required	Description
`subscriptionId`	String	Yes	Identifier of the subscription plan.
`transactionId`	String	Yes	Identifier of the individual charge transaction.
`chargeDate`	String	Yes	ISO-8601 date when this charge was attempted (e.g. `2025-09-01`).
`amount`	Number	Yes	Amount attempted in this cycle.
`currency`	String	Yes	ISO 4217 currency code for this charge.
`transactionStatus`	String	Yes	`SUCCEED` or `FAILED`.
`declineCode`	Int	No	Scheme-specific decline code, if the charge failed.
`declineReason`	String	No	Human-readable explanation of failure, if any.
`failureCount`	Integer	Yes	Number of consecutive failed attempts on this subscription.
`nextChargeDate`	String	Yes	ISO-8601 date of the next scheduled attempt (e.g. `2025-10-01`).
`metadata`	Map<String,String>	No	Echo of your subscription’s metadata, if provided on create.

Example JSON Payload

{
  "subscriptionId":   "sub_3344",
  "transactionId":    "txn9012",
  "chargeDate":       "2025-09-01",
  "amount":           19.99,
  "currency":         "EUR",
  "transactionStatus":"SUCCEED",
  "declineCode":      null,
  "declineReason":    null,
  "failureCount":     0,
  "nextChargeDate":   "2025-10-01",
  "metadata": {
    "subscriptionName": "PremiumPlan",
    "customerId":       "cust-789"
  }
}

Explanation:
This Recurring API leverages your existing data models and flows—simply supply a cardToken and define a plan. Facilero handles scheduling, retries, and webhooks, while you retain full control over subscription lifecycle.