Subscription Payment (hidden)

This guide explains how customers can view and update their recurring payment method by integrating the Payment Subscription Web Component (<scayle-payment-subscription>) into your shop.

When a customer has an active subscription, this component displays their current payment method and lets them replace it with a new one.

What to expect

By the end of this guide, you will be able to:

Load and initialize the Payment Subscription Component
Handle successful payment method updates
Handle payment method update failures
Configure optional display settings

Prerequisites

To implement the Subscription Payment Web Component into your page the following steps are required:

Define Entry Point for Subscription Payment

Choose a dedicated location in the customer account area where users can update the payment method for an active subscription. For example, a subscription details page or a dedicated payment settings section. This page should only be accessible to authenticated customers and only when the customer has an active subscription.

Obtain the subscription payment reference

When rendering the component, you need to pass the subscription payment reference, which is the unique identifier for the subscription whose payment method you want to manage.

Obtain a customer access token

The component requires a valid token for the authenticated customer. Make sure the customer is logged in and that a current access token is available before mounting the component.

Add Checkout JavaScript Bundle

Before using the Subscription Payment Web Component, make sure to include the necessary Checkout Web Component JavaScript bundle.

You can find more details in the initial checkout setup section.

<!-- Include the script before initializing Subscription Payment Component -->
<script src="https://{tenant-space}}.checkout.api.scayle.cloud/frontend/checkout-wc/js?appId={{shop}}"></script>

Initialization

Mount the component by placing it in your HTML. Two attributes are required:

subscription-payment-reference – the subscription whose payment method is being managed

access-token – a valid customer bearer token for authenticated API calls

<scayle-payment-subscription
  subscription-payment-reference="sub_abc123"
  access-token="eyJhbGci..."
></scayle-payment-subscription>

Verify Component Is Mounted

Use the following emitted event to listen for a successful mounting of the <scayle-payment-subscription> web component:

const paymentSubscriptionWebComponent = document.querySelector('scayle-payment-subscription');

const handleComponentReady = () => {
  // Your solution after the payment subscription web component is mounted
}

paymentSubscriptionWebComponent.addEventListener('scayle-payment-subscription:ready', handleComponentReady)

Handle Success

Listen for the scayle-payment-subscription:updated event to detect when a customer has successfully updated their recurring payment method.

The event scayle-payment-subscription:updated is emitted after the payment method is successfully updated

Use this event to refresh your UI, close a modal, or confirm the change to the customer.

Handle Errors

The component displays an inline error notification to the customer automatically. The shop should still listen for the failure event to perform any additional actions such as logging or analytics.

The event scayle-payment-subscription:failed is emitted when the payment method update fails

Configuration

The Payment Subscription Web Component uses the same configuration system as the SCAYLE Checkout. All configuration including styles, display options, and assets are loaded from your shops config.json and can be configured in SCAYLE Panel. If you have already set up configuration for the Checkout, it will carry over to the Subscription Payment web component automatically with no additional work required.

CSS Variables

All visual styling (colors, typography, borders, button appearance, and input fields) is driven by CSS variables defined in the styles section of your shops config.json. There are no component-specific CSS variables. Any variable you configure for the Checkout (e.g. buttonPrimaryBackground, borderRadius, font, dangerColor) will apply automatically to the Payment Subscription Component as well.

The component also loads your shop's overwrites.css from the CDN, the same file used by the Checkout. Any CSS overrides you have already defined there will apply to the Payment Subscription Component automatically.

Payment method descriptions

The following display options can be configured via the SCAYLE Panel. The component will automatically retrieve the necessary configuration.

Two optional description types can be enabled per payment option:

Short description (paymentOptions.descriptions.short) - displays a short description text below the payment option label. Disabled by default.
Tooltip (paymentOptions.descriptions.toolTip) - displays an info tooltip next to the payment option. Enabled by default.

Payment method icons

Hide payment icons (paymentOptions.hidePaymentIcons) — hides the payment method icon next to the active recurring payment method display. Disabled by default (icons are shown).

Payment method icons (e.g. Visa, Mastercard) are served from the SCAYLE asset distribution by default. You can replace individual icons by providing a custom URL via externalAssets or customizedAssets .