Custom Checkouts

Pre-release documentation

This functionality is currently not available for general release. While you can reference this guide to begin your integration with early access, please be aware that all endpoints, logic, and component attributes are subject to change. Known pending changes are flagged throughout this document.

The Payments API enables you to build custom checkout experiences using API endpoints combined with the <spektrix-payments> web component. Unlike iframe-based checkout, this approach gives you full control over the checkout UI while Spektrix handles payment processing.

The API and web component are only supported for web flows. A basket will be confirmed on successful payment - the payment must be in full, as partial payments are not supported.

If you are looking for information on setting up a standard iframe checkout with Spektrix Payments, please see Iframes: Spektrix Payments. For further information on Payment Component Styling and setup, please see Payments Component.

Possible checkout flows

Flow	System Owner mode endpoint - server side	Web / Public mode endpoint - client side	When to use
Direct Checkout	`POST /baskets/{basketId}/initiate-direct-payment`	`POST /basket/initiate-direct-payment`	Customer is not logged in. Identified by email only after payment is confirmed.
Customer Checkout	`POST /baskets/{basketId}/initiate-customer-payment`	`POST /basket/initiate-customer-payment`	Customer is logged in or added to the basket.
One-Click Checkout (pending)	`POST /baskets/{basketId}/initiate-one-click-payment`	`POST /basket/initiate-one-click-payment`	Not yet available.

Reference

Spektrix Payments Component

To use the <spektrix-payments> component, include the necessary styles and script in the <head> section of your page:

<link rel="stylesheet" href="https://webcomponents.spektrix.com/stable/spektrix-payments.css" />
<script src="https://webcomponents.spektrix.com/stable/spektrix-payments.js"></script>

Then insert the component into your checkout page:

<spektrix-payments
    id="paymentsComponent"
    custom-domain="{tickets.yourdomain.com}"
    system-name="{clientName}"
    payment-token="{paymentToken}"
></spektrix-payments>

Component attributes

Attribute	Required	Description
custom-domain	Yes	The custom domain that points to Spektrix (excluding `https://`).
system-name	Yes	The client's Spektrix system name.
payment-token	Yes	The secure token received from the initiate payment endpoint.
billing-address-id	Conditional	The customer's billing address ID. Required for Customer Checkout.
store-card	Conditional	`"true"` or `"false"` — whether to offer saving the card. Required for Customer Checkout.
top-level-domain	Conditional	Required only if embedding in an iframe. The top-level domain the iframe is embedded into (excluding `https://`). Necessary for Apple Pay.
language	No	Language code for localisation (e.g. `"fr"`). Default is English. French is the only other language currently supported.

For component styling and Apple Pay domain setup, see Payments Component.

Event handling

Listen for the following events to manage the customer journey after a payment attempt:

Event Name	Description
`onPaymentCompleted`	Triggered when the payment is successful. Access the order ID via `event.detail.orderId`.
`onPaymentRefused`	Triggered if the payment is refused.
`onPaymentNotFound`	Triggered if the session or token has expired (when a Basket has timed out).
`onError`	Triggered if any other unanticpated error occurs. More likely to be a transient system error and less likely to be an integration issue.

Card Management

`<spektrix-add-card>` component

This component is for a wallet in a My Account type page, allowing a customer to add a card to their wallet. It requires a customer to be authenticated. No payment token or API request is required.

<spektrix-add-card
    id="spektrixDropin"
    custom-domain="tickets.mytheatre.com"
    system-name="clienta"
    billing-address-id="12345"
></spektrix-add-card>

Component Attributes

Attribute	Description
language	Optional. Language code for localisation (e.g. `"fr"`). Default is English.

API Endpoints

The following endpoints can be used to view and manage cards in a customer's wallet.

Web / Public mode
System Owner mode

GET /v3/customer/stored-cards?includePending={includePending}
DELETE /v3/customer/stored-cards/{cardId}

GET /v3/customers/{id}/stored-cards?includePending={includePending}
DELETE /v3/customers/{id}/stored-cards/{cardId}

Possible checkout flows​

Reference​

Spektrix Payments Component​

Component attributes​

Event handling​

Card Management​

<spektrix-add-card> component​

Component Attributes​

API Endpoints​