Custom Checkouts
The Payments API enables you to build custom checkout experiences using API endpoints combined with the <spektrix-payments> and <spektrix-one-click-payments> components. Unlike iframe-based checkout, this approach gives you full control over the checkout UI while Spektrix handles payment processing.
The API and components 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 | POST /baskets/{basketId}/initiate-one-click-payment | POST /basket/initiate-one-click-payment | Only available for Apple Pay |
Reference
Spektrix Payments Component for Customer and Direct Checkouts
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. |
Spektrix Payments Component for One-Click Checkout
To use the <spektrix-one-click-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-one-click-payments
id="paymentsComponent"
custom-domain="{tickets.yourdomain.com}"
system-name="{clientName}"
payment-token="{paymentToken}"
></spektrix-one-click-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. |
| top-level-domain | Conditional | Required only if embedding in an iframe. The top-level domain the iframe is embedded into (excluding https://). |
| language | No | Language code for localisation (e.g. "fr"). Default is English. French is the only other language currently supported. |
For 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}
Zero-value baskets
A basket can total £0 — for example, it contains only free items, or account credit covers the full amount. The <spektrix-payments> component won't render in this case, since there's nothing to pay.
Check the basket total before rendering your checkout UI. If it's £0, show a "Confirm" button, then call the initiate-payment endpoint (Direct or Customer Checkout) directly — this confirms the order and returns the order ID without any payment capture.
This applies to Direct and Customer Checkout only; zero-value baskets are not supported for One-Click Checkout.