Elements Guide

What Elements is

CityPay Elements is a hosted checkout SDK for collecting card details securely in the browser.

It gives you:

  • hosted card fields and hosted payment flows
  • client-side tokenisation
  • built-in 3D Secure handling
  • a Payment Intent based integration model
  • a cleaner PCI DSS scope than collecting raw card data yourself

Sensitive cardholder data stays inside CityPay-hosted iframes. Your backend still remains responsible for creating the payment intent, authorising the payment, and applying your own business rules around capture and fulfilment.

Typical integration path

For most card integrations, the flow is:

  1. Your backend creates a Payment Intent and returns a PaymentIntentSession to the browser.
  2. The frontend loads @citypay/sdk and initialises citypay.elements(...).
  3. You mount either a cardElement() or a prebuilt Flow.
  4. The browser tokenises the payment details and attaches the payment method to the intent.
  5. Elements confirms the intent and handles 3DS if required.
  6. Your backend authorises the payment and decides whether to capture immediately or later.

Apple Pay integration path

For Apple Pay, the flow is simplified:

  1. Your backend creates a Payment Intent.
  2. The frontend loads the SDK and initialises citypay.elements(...).
  3. You mount the applePay() element.
  4. The user completes the payment via the Apple Pay sheet.
  5. Elements provides a callback (onAuthoriseEnd) with the result of the session.
  6. Your backend authorises the payment.

If you want the detailed implementation steps, start with the Elements overview and then the Quick Start.

Choose your integration style

Use cardElement() or cardFieldsElement() when you want full control over the checkout layout, buttons, and step-by-step orchestration.

Use applePay() to integrate a secure Apple Pay button into your custom checkout.

Use paymentFlow() or verifyFlow() when you want a faster integration with a built-in action button and hosted result states.

For transport, you have two common options:

  • Direct: the SDK uses session-backed CityPay intent routes for browser-side attach() and confirm() calls
  • Middleware: your backend exposes routes such as attach, confirm, and authorise when you want more control, logging, or policy enforcement

For a first implementation, Direct is usually the easiest way to understand the flow. Middleware is usually the better production choice when you want stronger backend control.

Apple Pay

CityPay Elements supports Apple Pay as a payment method. It allows customers to pay securely using their Apple Pay wallet, providing a fast and secure checkout experience.

To integrate Apple Pay:

  • Configure your domain: You must register and verify your domain in the CityPay Merchant Panel.
  • Initialise Apple Pay: Use elements.applePay(options) to create the element.
  • Handle the result: Listen for the onAuthoriseEnd event to know when the payment has been processed.

For detailed instructions, see the Apple Pay integration guide.

Where to go next