# CheckoutComponents

## CheckoutComponentConfiguration

Initializes a `CheckoutComponentConfiguration` instance.

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

## Initialization

Initializes a `CheckoutComponent` instance.

```swift
// Initialize with a payment session
let configuration = try await CheckoutComponents.Configuration(
  paymentSession: paymentSession,
  publicKey: "YOUR_PUBLIC_KEY",
  environment: .sandbox,
  callbacks: initialiseCallbacks())

return CheckoutComponents(configuration: configuration)

// Or initialize for sessionless components (no payment session)
let sessionlessConfiguration = try await CheckoutComponents.Configuration(
  paymentSession: nil,
  publicKey: "YOUR_PUBLIC_KEY",
  environment: .sandbox,
  callbacks: initialiseCallbacks())

return CheckoutComponents(configuration: sessionlessConfiguration)
```

## Callbacks

```swift
func initialiseCallbacks() -> CheckoutComponents.Callbacks {
  .init(
    onSuccess: { paymentMethod, paymentID in
      // Handle payment success
    },
    onError: { paymentMethod in
      // Handle payment error
    }
  )
}
```

## Methods

### create(_:)

Initializes an `Actionable` instance for payment flow.

```swift
// Create a `flow component` with multiple options
try checkoutComponentsSDK.create(
  .flow(options: [
    .card(showPayButton: true, // show your own pay button when set to false
          paymentButtonAction: .payment, // or `.tokenization`
          cardConfiguration: cardConfiguration, // Configuration options for customizing the Card component
          addressConfiguration: addressConfiguration,
          rememberMeConfiguration: rememberMeConfiguration),
    .applePay(merchantIdentifier: "YOUR_MERCHANT_ID_HERE",
              showPayButton: Bool = true, // show your own pay button when set to false
              applePayConfiguration: applePayConfiguration // Configuration options for customizing the ApplePay component
             )
  ])
)

// Create a specific payment method
try checkoutComponentsSDK.create(
  .card(showPayButton: true,
        paymentButtonAction: .payment,
        cardConfiguration: cardConfiguration,
        addressConfiguration: addressConfiguration,
        rememberMeConfiguration: rememberMeConfiguration)
)
```

If the payment session carries a `stored_card` payment method and [Remember Me](https://www.checkout.com/docs/payments/accept-payments/accept-a-payment-on-your-mobile-app/extend-your-flow-for-mobile-integration/enable-remember-me.md) 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:

```swift
// Create a stored card component with configuration options
try checkoutComponentsSDK.create(
  .storedCard(
    storedCardConfiguration: .init(
      showPayButton: true,
      captureCVV: true,
      displayMode: .all,
      acceptedCardSchemes: [.visa, .mastercard],
      acceptedCardTypes: [.credit]
    ),
    cardConfiguration: cardConfiguration
  )
)
```

For more information, see [Accept payments with stored card credentials](https://www.checkout.com/docs/payments/accept-payments/accept-a-payment-on-your-mobile-app/extend-your-flow-for-mobile-integration/accept-payments-with-stored-card-credentials.md).

> **Information**
>
> 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](https://developer.apple.com/design/human-interface-guidelines/apple-pay).

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

```swift
// Create a sessionless address component
typealias ContactData = CheckoutComponents.ContactData
typealias Address = CheckoutComponents.Address
typealias Configuration = CheckoutComponents.AddressConfiguration

let prefilledAddress = ContactData(address: .init(country: .unitedKingdom,
                                                   addressLine1:  "Wenlock Works",
                                                   addressLine2: "Shepherdess Walk",
                                                   city: "London",
                                                   zip: "N1 7BQ"),
                                    phone: .init(countryCode: "+$4",
                                                    number: "1234567890"),
                                    name: .init(firstName: "John",
                                                   lastName: "Doe"))

let addressConfiguration = Configuration.init(data: prefilledAddress,
                                              fields: CheckoutComponents.AddressField.billing
                                                         + [.phone(isOptional: false)]) { collectedAddress in
   debugPrint("Collected address: \(collectedAddress)")
}

try checkoutComponentsSDK.create(
  .address(configuration: addressConfiguration)
)
```

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:

```swift
import CheckoutComponents

// No payment session is needed for a sessionless component.
let sdk = try await CheckoutComponents(configuration: configuration)

let cvv = try sdk.create(.cvv(configuration: .init(cvvLength: [3, 4])))

// Render it
cvv.render()

// Tokenize when the customer is ready. `isValid` reports whether the entered
// code matches one of the accepted lengths.
guard cvv.isValid else { return }

switch await cvv.tokenize() {
case .success(let response):
  // Send response.token to your backend as the CVV for your own payment request.
  print(response.token)
case .failure(let error):
  print(error.errorCode)
case .none:
  break // Not reachable for the CVV component.
}
```

`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.

### update(updateDetails)

Updates a `FlowComponent` instance.

```swift
if component.isAvailable {
  component.render()
}
```

This method only updates the UI. To update the payment session, use the `handleSubmit` [callback](https://www.checkout.com/docs/payments/accept-payments/accept-a-payment-on-your-mobile-app/flow-for-mobile-library-reference/ios/componentcallback.md#handleSubmit(SessionData)_:_APICallResult).

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](https://www.checkout.com/docs/payments/accept-payments/format-the-amount-value.md)

```swift
let callbacks = CheckoutComponents.Callbacks(handleSubmit: { sessionData in
    submitPaymentSession(sessionData)
  })
let configuration = CheckoutComponents.Configuration(..., callbacks: callbacks)

try checkoutComponentsSDK.update(with: UpdateDetails(amount: 100))
```