Direct Checkout

Pre-release documentation

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

Overview

Direct Checkout is a streamlined checkout flow that allows customers to complete purchases without a traditional login process. Customers are identified by their email address, either associating the order with an existing customer record or creating a new one automatically. Best for fast, low-friction transactions where requiring a login would add unnecessary steps — such as general admission ticket sales or one-off purchases.

This flow is specifically for sessions without a logged in customer. If a customer is already logged in, use the Customer Checkout flow instead.

Customer record logic

Spektrix automatically manages customer identification and record creation during the Direct Checkout flow. You do not need to perform manual lookups or handle conditional "create vs update" logic.

Identification: Spektrix uses the email address provided in the initiate payment request to check for an existing customer record.
Existing customers: If a matching email is found, the order is automatically attached to that customer record upon successful payment.
- Data persistence: Providing different details (First Name, Last Name, or Billing Address) in the API request will not update or override the existing customer record.
- AVS requirements: You must provide the billing address in the API call as it is used strictly for Address Verification System (AVS) checks during the payment process.
New customers: If no matching email is found, Spektrix creates a new customer record using the details you provided once the payment is completed.
- A "New Account" creation email is not sent via this flow.

Integration steps

Working with custom domains

Below, links will be referenced as originating from system.spektrix.com. Whether you are working in System Owner or Web mode, you will need to replace system.spektrix.com with your chosen custom domain.

Prerequisites

You must add items to the basket first either via the API using POST /baskets item endpoints, Iframes, or Web Components.

1. Validate eligibility

Before directing the customer down this checkout flow, you should check if the current basket contents are eligible for Direct Checkout.

Pending endpoint rename

This endpoint name is subject to change. Do not deploy to your production environment until final naming is confirmed.

Endpoint:

Web / Public mode
System Owner mode

GET
 system.spektrix.com/{clientname}/basket/checkout-options

GET
system.spektrix.com/{clientname}/baskets/{id}/checkout-options

Response example:

{
    "checkoutTypes": {
        "direct": {
            "available": false,
            "reason": "CustomerOnBasket"
        }
    }
}

Reason codes:

Reason Code	Explanation
SpektrixPaymentsNotConfigured	Adyen is not configured as the primary payment service for the Web Payment Channel.
CustomerOnBasket	A customer is already logged in/present in the basket.
BasketHasPendingPayment	A pending payment exists that must be completed or cancelled.
MembershipOnBasket	A membership item is present (unsupported in Phase 1).
MerchandiseDeliveryNotSet	Delivery method for merchandise is missing.
TicketDeliveryNotSet	Delivery method for tickets is missing.
NoOutstandingBalance	The basket total is zero (unsupported in Phase 1).
CustomerEmailDeliveryOnGiftVoucher	Gift voucher delivery is set to "Customer Email".
NotAllowedForEventInstanceInBasket	An event instance in the Basket has been set in Spektrix to explicitly disallow Direct Checkout.
NotAllowedForStockItemInBasket	A merchandise item in the Basket has been set in Spektrix to explicitly disallow Direct Checkout.
NotAllowedForFundInBasket	A fund in the Basket has been set in Spektrix to explicitly disallow Direct Checkout.

info

The following reasons currently return available: false, but we plan to remove these blocks shortly. You may choose to ignore these specific codes if your UI handles delivery selection later in the flow:

MerchandiseDeliveryNotSet
TicketDeliveryNotSet

2. Set delivery method

Before initiating payment, you must set a delivery method for the basket.

Endpoint:

Web / Public mode
System Owner mode

PATCH
 system.spektrix.com/{clientname}/basket

PATCH
system.spektrix.com/{clientname}/baskets/{id}

Constraint: Only cobo (type 1) and PrintAtHome (type 2) are supported for Direct Checkout.
Timing: This must be performed prior to calling the initiate payment endpoint.

Sample request body:

[
    {
        "TicketDelivery": {
            "Type": 1
        }
    }
]

3. Initiate payment

Call the endpoint to generate a secure transaction token.

Pending endpoint rename

The endpoint listed below is subject to change. You should not deploy this integration to a production environment until the final name is confirmed.

Endpoint:

Web / Public mode
System Owner mode

POST
 system.spektrix.com/{clientname}/basket/initiate-direct-payment

POST
system.spektrix.com/{clientname}/baskets/{id}/initiate-direct-payment

Request schema:

Field	Type	Required	Description
originDomain	string	Yes	The domain where your web component is hosted (e.g. tickets.mytheatre.com)
firstName	string	Yes	Customer's first name
lastName	string	Yes	Customer's last name
email	string	Yes	Unique identifier to look up or create a customer record
billingAddress	object	Yes	Object containing billing details
billingAddress.line1	string	Yes	First line of address
billingAddress.line2	string	No	Optional additional address line
billingAddress.line3	string	No	Optional additional address line
billingAddress.line4	string	No	Optional additional address line
billingAddress.line5	string	No	Optional additional address line
billingAddress.town	string	Yes	City or town
billingAddress.country	string	Yes	ISO 3166-1 alpha-2 country code (e.g. GB, US)
billingAddress.postcode	string	Conditional	Mandatory if the selected country requires it. Use the postcodeRequired from the `/countries` API to determine for a specific country.
billingAddress.administrativeDivision	string	Conditional	Mandatory if the country has defined divisions. Use the name from the `/countries` API. Leave empty if the country does not have defined divisions.

Sample request body:

{
    "originDomain": "tickets.mytheatre.com",
    "firstName": "Jane",
    "lastName": "Smith",
    "email": "jane.smith@example.com",
    "billingAddress": {
        "line1": "221 Ealing Street",
        "town": "New Haven",
        "country": "US",
        "postcode": "01165",
        "administrativeDivision": "Connecticut"
    }
}

Response:

Returns a paymentToken string. This token is short-lived and specific to the current basket total and state.

Basket state persistence

If you make any change to the basket (e.g. updating delivery methods, adding/removing items) after getting a payment token, you must call the initiate payment endpoint again to retrieve a new paymentToken.

4. Implement the web component and handle events

Once you have the payment token, render the <spektrix-payments> web component and listen for payment events.

See Payments API — Web Component for full component setup, attribute reference, and event handling.

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

Constraints and considerations

Feature constraints

Feature	Status	Note
Memberships	Not Supported	Memberships cannot be purchased nor can membership benefits be applied — they require an authenticated customer.
Ticket Subscriptions	Not Supported	Ticket subscriptions cannot be purchased.
Ticket Vouchers	Not Supported	Ticket vouchers cannot be redeemed.
Fixed Series	Not Supported	Fixed Series cannot be purchased.
Stored Cards	Not Supported	Cards cannot be saved or existing stored cards retrieved.
Gift Aid	Not Supported	Declarations remain unchanged for existing customers. New customers will have no declaration set.
Contact Preferences	Not Supported	Preferences remain unchanged for existing customers. New customers will have no preferences set.
Donations	Limited	`GET /v3/basket/donations-to-prompt` returns `401 Unauthorized` as this requires a customer.
Zero-Value Baskets	Not Supported	Baskets totalling 0.00 are currently not supported.

Customer eligibility criteria constraints

The following features act as constraints if they are configured based on customer eligibility criteria. Because the customer is not authenticated or known at this stage of the journey, Spektrix cannot verify eligibility for:

Customer-specific offer limits (e.g. Per Customer, Per Membership Period)
Priority booking periods
Lock Types
Waiving Commissions
Inactive customer blocking

Overview​

Customer record logic​

Integration steps​

Prerequisites​

1. Validate eligibility​

2. Set delivery method​

3. Initiate payment​

4. Implement the web component and handle events​

Constraints and considerations​

Feature constraints​

Customer eligibility criteria constraints​