Recurring Payment API

Recurring Payment API

Create and manage recurring subscriptions tied to a saved card token. The first charge can be executed immediately on creation, or deferred for free trials and future-dated billing. 3D Secure verification may be initiated on the subscription creation request to authenticate the cardholder — subsequent scheduled charges are merchant-initiated and typically exempt from 3DS.

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

⚠️

Important — 3D Secure on subscription creation

3DS verification may be initiated when the subscription is created, regardless of the skipFirstCharge flag.

When 3DS is triggered, the response returns:

• transactionStatus: "CUSTOMER_VERIFICATION"
• challengeUrl

Redirect the customer to challengeUrl to complete the challenge.

After completion, they are sent to:

• successRedirectUrl
• failureRedirectUrl

Both redirect URLs are required on every subscription request.

Plan Object

Example Request Body (immediate charge)

{
  "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",
  "successRedirectUrl": "https://yoursite.com/subscription/success",
  "failureRedirectUrl": "https://yoursite.com/subscription/failure",
  "metadata": {
    "subscriptionName": "PremiumPlan"
  }
}

Example Request Body (free trial / deferred start)

{
  "requestId":        "req-sub-002",
  "mid":              "merchant456",
  "cardToken":        "tok_abc123xyz",
  "skipFirstCharge":  true,
  "plan": {
    "amount":       "19.99",
    "currency":     "EUR",
    "frequency":    "MONTHLY",
    "interval":     1,
    "startDate":    "2025-08-01",
    "endDate":      "2026-07-31"
  },
  "callbackUrl": "https://yourserver.com/subscription-webhook",
  "successRedirectUrl": "https://yoursite.com/subscription/success",
  "failureRedirectUrl": "https://yoursite.com/subscription/failure",
  "metadata": {
    "subscriptionName": "FreeTrial"
  }
}

Response Body

POST /recurring creates the subscription and (by default) performs the first charge immediately. When skipFirstCharge=true, no charge is executed and the subscription starts as TRIALING.

Example Response (immediate charge)

{
  "subscriptionId":    "sub_839201748291034",
  "transactionId":     "839201748291035",
  "transactionStatus": "SUCCEED",
  "declineCode":       null,
  "nextChargeDate":    "2025-09-01"
}

Example Response (first charge declined)

When the first charge fails, no subscription is created. You can safely retry the same request.

{
  "subscriptionId":    null,
  "transactionId":     "839201748291036",
  "transactionStatus": "FAILED",
  "declineCode":       203,
  "nextChargeDate":    null
}

Example Response (first charge requires 3DS)

When the first charge triggers 3D Secure, redirect the customer to challengeUrl. After the customer completes the challenge, they are redirected to your successRedirectUrl or failureRedirectUrl.

{
  "subscriptionId":    "sub_839201748291037",
  "transactionId":     "839201748291038",
  "transactionStatus": "CUSTOMER_VERIFICATION",
  "declineCode":       null,
  "challengeUrl":      "https://sandbox.api.facilero.com/api/v1/3ds/mock/839201748291038",
  "challengeUrlIframe":"https://sandbox.api.facilero.com/api/v1/3ds/mock/839201748291038?iframe=true",
  "nextChargeDate":    "2025-09-01"
}

Example Response (skipFirstCharge=true)

{
  "subscriptionId":    "sub_839201748291035",
  "transactionId":     null,
  "transactionStatus": null,
  "declineCode":       null,
  "nextChargeDate":    "2025-08-01"
}

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

Live

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

Sandbox

PUT https://sandbox.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

Example JSON

PUT https://sandbox.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

Live

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

Sandbox

DELETE https://sandbox.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:

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.

Error Responses

Implementation Notes

• POST /v1/payments/card/recurring performs the first charge immediately (default behavior). The subscription is only created if the charge is not declined (FAILED/BLOCKED). If declined, subscriptionId and nextChargeDate are null — retry the request safely
• With skipFirstCharge: true, the subscription is created in TRIALING status with no initial charge. The first charge occurs on plan.startDate. After the first successful charge, the status transitions to ACTIVE
• Subsequent charges are automatic — the scheduler runs every 5 minutes and processes due subscriptions (ACTIVE and TRIALING)
• DELETE /v1/payments/card/recurring/{subscriptionId} returns 204 No Content — immediately cancels the subscription (no more charges)
• GET /v1/payments/card/recurring/{subscriptionId} — returns current subscription status, plan details, next charge date, failure count
• PUT /v1/payments/card/recurring/{subscriptionId} — update plan parameters or transition subscription state (ACTIVE, PAUSED, CANCELLED)
• After maxRetries (default 3) consecutive failures, the subscription is automatically paused
• When endDate is reached, the subscription is automatically cancelled
• The subscription callback webhook (SubscriptionCallbackDto) includes real nextChargeDate and failureCount values

Sandbox Testing

Test Card Behavior

Verifying Scheduled Charges

In sandbox, the recurring scheduler runs every 5 minutes. To verify:

1. Create a subscription with frequency: "DAILY" and startDate set to today
2. The first charge happens immediately on POST /recurring (or is deferred if skipFirstCharge: true)
3. The next charge fires within 5 minutes (sandbox accelerates the schedule)
4. Check your callbackUrl for the webhook, or poll GET /v1/payments/card/recurring/{subscriptionId} to see updated nextChargeDate and failureCount
5. For skipFirstCharge: true, verify the subscription starts as TRIALING and transitions to ACTIVE after the first scheduled charge

Note: In production, charges fire on the actual scheduled date. The 5-minute sandbox cycle is for testing convenience only.