CheckoutComponents

Last updated: September 2, 2026

Initializes a CheckoutComponentConfiguration instance.


1/**
2   Initializes a new instance of `Configuration`.
3   - Parameter paymentSession: Payment session details (optional for sessionless components)
4   - Parameter publicKey: Public key to submit payment session
5   - Parameter environment: Environment selection to interact with
6   - Parameter appearance: Design token for the user interface elements
7   - Parameter locale: Locale to be used by the SDK
8   - Parameter translations: Custom translation override strings
9   - Parameter callbacks: Callbacks to handle the component lifecycle
10   */
11  public init(paymentSession: PaymentSession?,
12              publicKey: String,
13              environment: Environment,
14              appearance: DesignTokens = .init(),
15              locale: String? = nil,
16              translations: [String: [TranslationKey: String]] = [:],
17              callbacks: Callbacks) async throws(CheckoutComponents.Error)

Initializes a CheckoutComponent instance.


1// Initialize with a payment session
2let configuration = try await CheckoutComponents.Configuration(
3  paymentSession: paymentSession,
4  publicKey: "YOUR_PUBLIC_KEY",
5  environment: .sandbox,
6  callbacks: initialiseCallbacks())
7
8return CheckoutComponents(configuration: configuration)
9
10// Or initialize for sessionless components (no payment session)
11let sessionlessConfiguration = try await CheckoutComponents.Configuration(
12  paymentSession: nil,
13  publicKey: "YOUR_PUBLIC_KEY",
14  environment: .sandbox,
15  callbacks: initialiseCallbacks())
16
17return CheckoutComponents(configuration: sessionlessConfiguration)


1func initialiseCallbacks() -> CheckoutComponents.Callbacks {
2  .init(
3    onSuccess: { paymentMethod, paymentID in
4      // Handle payment success
5    },
6    onError: { paymentMethod in
7      // Handle payment error
8    }
9  )
10}

Initializes an Actionable instance for payment flow.


1// Create a `flow component` with multiple options
2try checkoutComponentsSDK.create(
3  .flow(options: [
4    .card(showPayButton: true, // show your own pay button when set to false
5          paymentButtonAction: .payment, // or `.tokenization`
6          cardConfiguration: cardConfiguration, // Configuration options for customizing the Card component
7          addressConfiguration: addressConfiguration,
8          rememberMeConfiguration: rememberMeConfiguration),
9    .applePay(merchantIdentifier: "YOUR_MERCHANT_ID_HERE",
10              showPayButton: Bool = true, // show your own pay button when set to false
11              applePayConfiguration: applePayConfiguration // Configuration options for customizing the ApplePay component
12             )
13  ])
14)
15
16// Create a specific payment method
17try checkoutComponentsSDK.create(
18  .card(showPayButton: true,
19        paymentButtonAction: .payment,
20        cardConfiguration: cardConfiguration,
21        addressConfiguration: addressConfiguration,
22        rememberMeConfiguration: rememberMeConfiguration)
23)

If the payment session carries a stored_card payment method and Remember Me is not available on that session, create(.flow(...)) returns the stored card component instead of the regular Flow list. You can also render the stored card component on its own:


1// Create a stored card component with configuration options
2try checkoutComponentsSDK.create(
3  .storedCard(
4    storedCardConfiguration: .init(
5      showPayButton: true,
6      captureCVV: true,
7      displayMode: .all,
8      acceptedCardSchemes: [.visa, .mastercard],
9      acceptedCardTypes: [.credit]
10    ),
11    cardConfiguration: cardConfiguration
12  )
13)

For more information, see Accept payments with stored card credentials.

Tip

If you use Apple Pay as a standalone component with your custom payment button, ensure you follow Apple's guidelines for showing Apple Pay logo.

Initialize a sessionless component that does not require a payment session.


1// Create a sessionless address component
2typealias ContactData = CheckoutComponents.ContactData
3typealias Address = CheckoutComponents.Address
4typealias Configuration = CheckoutComponents.AddressConfiguration
5
6let prefilledAddress = ContactData(address: .init(country: .unitedKingdom,
7                                                   addressLine1:  "Wenlock Works",
8                                                   addressLine2: "Shepherdess Walk",
9                                                   city: "London",
10                                                   zip: "N1 7BQ"),
11                                    phone: .init(countryCode: "+$4",
12                                                    number: "1234567890"),
13                                    name: .init(firstName: "John",
14                                                   lastName: "Doe"))
15
16let addressConfiguration = Configuration.init(data: prefilledAddress,
17                                              fields: CheckoutComponents.AddressField.billing
18                                                         + [.phone(isOptional: false)]) { collectedAddress in
19   debugPrint("Collected address: \(collectedAddress)")
20}
21
22try checkoutComponentsSDK.create(
23  .address(configuration: addressConfiguration)
24)

You can also create a sessionless CVV component to collect a security code for a card you hold on your file-on-card system, with no payment session. The component tokenizes on demand and hands the token back to you, rather than submitting a payment request:


1import CheckoutComponents
2
3// No payment session is needed for a sessionless component.
4let sdk = try await CheckoutComponents(configuration: configuration)
5
6let cvv = try sdk.create(.cvv(configuration: .init(cvvLength: [3, 4])))
7
8// Render it
9cvv.render()
10
11// Tokenize when the customer is ready. `isValid` reports whether the entered
12// code matches one of the accepted lengths.
13guard cvv.isValid else { return }
14
15switch await cvv.tokenize() {
16case .success(let response):
17  // Send response.token to your backend as the CVV for your own payment request.
18  print(response.token)
19case .failure(let error):
20  print(error.errorCode)
21case .none:
22  break // Not reachable for the CVV component.
23}

CardCVVConfiguration.cvvLength accepts the security code lengths, in digits: [3], [4], or [3, 4]. Pass [3] for most schemes, [4] for American Express, or [3, 4] to accept either. An empty array, or any value other than 3 or 4, falls back to [3, 4].

The field is valid once its length matches one of the accepted values, and it stops accepting characters at the largest accepted value.

Updates a FlowComponent instance.


1if component.isAvailable {
2  component.render()
3}

This method only updates the UI. To update the payment session, use the handleSubmit callback.

The update() method takes the updateDetails object as a parameter, which contains the values to update. This object uses the amount property to update the purchase amount. This value must be:

Greater than zero
Expressed in the minor currency unit


1let callbacks = CheckoutComponents.Callbacks(handleSubmit: { sessionData in
2    submitPaymentSession(sessionData)
3  })
4let configuration = CheckoutComponents.Configuration(..., callbacks: callbacks)
5
6try checkoutComponentsSDK.update(with: UpdateDetails(amount: 100))

CheckoutComponents

CheckoutComponentConfiguration

Initialization

Callbacks

Methods

create(_:)

Tip

update(updateDetails)