Customer Checkout

This endpoint can be used to build a checkout flow for when a customer logs in before completing the transaction. It does not have the same constraints as Direct Checkout, so it can be used when the customer needs to be known — for example, purchasing memberships, receiving membership benefits, using ticket vouchers, or collecting gift aid declarations. Best for transactions that require an authenticated customer, such as applying member discounts, redeeming vouchers, or collecting gift aid declarations.

This requires a customer to be authenticated (applicable to both web and system owner modes) or by adding a customer directly to the basket (applicable to system owner mode only).

Working with custom domains

Below, links will be referenced as originating from system.spektrix.com. Whether you are working in system owner or web / public mode, replace system.spektrix.com with your chosen custom domain. Use client-side requests in Web/Public mode, and server-side requests in System Owner mode.

Initiate payment

Endpoint

Web / Public mode

POST

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

System Owner mode

POST

system.spektrix.com/{clientname}/baskets/{basketId}/initiate-customer-payment

Request body

{
    "originDomain": "tickets.mytheatre.com",
    "billingAddressId": "12345ABCDTGGQPPPTRVGVMSDRVTUVWXYZ",
    "storeCard": "false",
    "useAvailableCredit": false
}

Field	Type	Required	Description
originDomain	string	Yes	The domain where your web component is hosted (e.g. tickets.mytheatre.com)
billingAddressId	string	Yes	The ID of the customer's billing address
storeCard	string	No	"true" or "false" - whether to save the card for future use
useAvailableCredit	boolean	No	Whether to apply the customer's available account credit to the basket. Defaults to false if omitted — see Paying with Account Credit below.

Response

{
    "paymentToken": "<short-lived-token>"
}

Returns a paymentToken string. This token is short-lived and specific to the current basket total and state. This payment token must be passed into the web component payment-token attribute.

Basket state persistence

Any change to a basket (e.g. updating delivery methods, adding/removing items) requires a new payment token to be generated. Therefore, initiate-customer-payment should always be the last step prior to the customer completing a payment.

Render the payment component

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

Web component sample for Customer Checkout

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

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

For managing a customer's stored cards, see Card Management

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

Paying with Account Credit

Customers with a positive account credit balance — for example from a redeemed gift voucher — can apply that credit toward a basket during Customer Checkout. This works with the existing Initiate Payment request and requires only the useAvailableCredit field described above; no separate endpoint is needed. To check customer account credit, check the value of creditBalance in the response of GET v3/customer or GET v3/customers/{id}.

Credit is calculated when you call Initiate Payment, but it is only deducted from the customer's balance once the order is confirmed. This means applying credit doesn't reserve or lock it — if the customer abandons the transaction or the payment fails, their credit balance is left untouched.

Credit application scenarios

When useAvailableCredit: true is sent, one of three scenarios applies depending on the customer's available credit relative to the basket total:

Scenario	Payment component
Sufficient credit (credit ≥ total)	Doesn't render — no capture required. The initiate-customer-payment will confirm the order.
Partial credit (credit < total)	Renders for the remainder
No credit (credit = £0)	Renders as normal

Credit is only deducted, and any remaining amount only captured, once the order is confirmed.

Basket modification after payment initiation

Any basket change after calling Initiate Payment (items, delivery method, discounts, etc.) invalidates the existing paymentToken. Call Initiate Payment again with useAvailableCredit: true to get a fresh token — credit is recalculated against the new basket total, so the remaining amount to pay may change.