Custom Checkouts
Direct Checkout and One-Click Checkout is currently not available for general release. While you can reference this guide to begin your integration with early access, please be aware that it is not enabled for all clients yet. If you are working with a client and are building direct or one-click checkout flows, please get in touch with support@spektrix.com to ask us to enable this functionality for the client.
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}