# CheckoutComponents

## CheckoutComponentConfiguration

Initializes a `CheckoutComponentConfiguration` instance.

```kotlin
/**
 * Common configurations for all payment components
 *
 * @property [Context] represents the application context
 * @property [PaymentSessionResponse] paymentSession represents the payment session response
 * @property publicKey represents the public API key, prefixed with pk_
 * @property [Environment] represents the environment that the library points to, and sends requests to
 * @property locale represents the customer’s locale and preferred language, used to localize the CheckoutComponents
 * @property componentOptions [ComponentOptions] configures the component's behavior for different payment methods
 * @property componentCallback [ComponentCallback] is a generic ComponentCallback for all payment methods
 * @property translations contains translations for the component, including a map of Locale, with the value of another map of ComponentTranslationKey and the translation string
 * @property flowCoordinators is a map containing all flow coordinators
 * @property appearance contains the design tokens for customizing the component's appearance
 */
public data class CheckoutComponentConfiguration @JvmOverloads constructor(
  val context: Context,
  val paymentSession: PaymentSessionResponse,
  val publicKey: String,
  val environment: Environment,
  val locale: Locale?,
  val componentOptions: ComponentOptions,
  val componentCallback: ComponentCallback?,
  val translations: Translations?,
  val flowCoordinators: Map<PaymentMethodName, FlowCoordinator>,
  val appearance: DesignTokens? = null,
)
```

## Initialization

Initializes a `CheckoutComponent` instance.

```kotlin
val configuration = CheckoutComponentConfiguration(
  context = context,
  paymentSession = PaymentSessionResponse(
  paymentSessionId,
  paymentSessionToken,
  paymentSessionSecret,
  ),
  publicKey = "YOUR_PUBLIC_KEY",
  environment = Environment.SANDBOX,
)

// Create CheckoutComponents
CoroutineScope(Dispatchers.IO).launch {
  try {
    val checkoutComponents = CheckoutComponentsFactory(config = configuration).create()
  } catch (checkoutError: CheckoutError) {
    handleError(checkoutError)
  }
}
```

### Methods

#### create(paymentMethodName, checkoutOption)

Initializes a `PaymentMethodComponent` instance.

```kotlin
val options = ComponentOption(
  callback = ComponentCallback(
    onSuccess = {
      // Handle payment success
    },
  ),
  addressConfiguration = AddressConfiguration(
    // optional, prefilled address
    data = ContactData(
      address = Address(
        addressLine1 = "123 Main St",
        addressLine2 = "Sakura apartments",
        city = "Tokyo",
        state = "Shanghai",
        country = Country.JAPAN,
        zip = "100-0001",
      ),
      phone = Phone(country = Country.UNITED_KINGDOM, number = "7425125181"),
      name = Name(firstName = "John", lastName = "Doe"),
      email = "johndoe@email.com"
    ),
    // optional, what address fields to collect. Defaults to billing address
    fields = listOf(
      AddressField.Country,
      AddressField.AddressLine1(),
      AddressField.AddressLine2(),
      AddressField.City(),
      AddressField.State()
    ),
    // optional, handle when contact data is saved
    onComplete = { contactData -> handleContactData(contactData) }
  ),
  // optional, enable Remember Me functionality
  rememberMeConfiguration = RememberMeConfiguration(
    data = RememberMeConfiguration.Data(
      email = "jia.tsang@example.com",
      phone = Phone(countryCode = "44", number = "7700900000")
    ),
    showPayButton = true,
    acceptedCardSchemes = listOf(CardSchemeName.Visa, CardSchemeName.AmericanExpress),
    acceptedCardTypes = listOf(CardTypeName.Debit, CardTypeName.Credit, CardTypeName.Prepaid)
  )
)


try {
  val flowComponent = checkoutComponents.create(ComponentName.Flow, options)

  val cardComponent = checkoutComponents.create(PaymentMethodName.Card, options)
} catch (checkoutError: CheckoutError) {
  handleError(error = checkoutError)
}
```

#### create(Component.Address)

Initializes an `address` component instance.

```kotlin
// Step 1: Create a configuration
val configuration = CheckoutComponentConfiguration(
    context = context,
    publicKey = "PUBLIC KEY",
    environment = environment,
    locale = Locale.EN,
)

// Step 2: Initialize an instance of Checkout Components SDK
val checkoutComponents = CheckoutComponentsFactory(config = configuration).create()

// Step 3: Initialize an instance of prefilled address data (optional)
val prefilledData = ContactData(
    address = Address(
        country = Country.UNITED_KINGDOM,
        addressLine1 = "Checkout.com",
    ),
    phone = Phone(
        countryCode = "+44",
        number = "12345678",
    ),
    name = Name(
        firstName = "John",
        lastName = "Doe",
    ),
    email = "johnDoe@domain.com",
)

// Step 4: Create address with fields (optional)
val fields = listOf(
    AddressField.Country,
    AddressField.AddressLine1(),
    AddressField.AddressLine2(isOptional = true),
    AddressField.City(isOptional = false),
)

// Step 5: Create an address configuration
val configuration = AddressConfiguration(
  data = data,
  fields = fields,
  onComplete = { contactData ->
    handleContactData(contactData)
  }
)

// Step 6: Create address component
val addressComponent = checkoutComponent.create(
  ComponentName.Address(configuration)
)

// Step 7: Render the address component
addressComponent.Render()
```

#### create(Component.CardCvv)

Initializes a sessionless CVV component to collect a security code for a card you hold yourself, with no payment session. The component tokenizes on demand and returns the token to you, rather than submitting anything to Checkout.com.

Unlike other components, `card-cvv` is not pulled in by the main `checkout-android-components` artifact, so you must add the dependency explicitly:

```kotlin
dependencies {
    implementation("com.checkout:checkout-android-components:$latest_version")
    implementation("com.checkout:checkout-android-components-card-cvv:$latest_version")
}
```

No payment session is needed, so use the `CheckoutComponentConfiguration` overload that takes no `paymentSession`:

```kotlin
val configuration = CheckoutComponentConfiguration(
  context = this,
  publicKey = "pk_sbox_...",
  environment = Environment.SANDBOX,
)

val checkoutComponents = CheckoutComponentsFactory(config = configuration).create()

val cvvComponent = checkoutComponents.create(
  ComponentName.CardCvv(
    configuration = CardCvvConfiguration(
      cardCvvLength = setOf(3, 4),
      callback = CardCvvComponentCallback(
        onReady = { component ->
          /* component is ready */
        },
        onChange = { component ->
          /* re-read component.isValid() */
        },
      ),
    ),
  ),
)

// Render in Compose UI with cvvComponent.Render(), or in a View container
// with cvvComponent.provideView(container).

// Tokenize when the customer is ready.
when (val result = cvvComponent.tokenize()) {
  is CardCvvTokenizeResult.Success ->
    // Send result.token to your backend as the CVV for your own payment request.
    Log.d("cvv", result.token)
  is CardCvvTokenizeResult.Failure ->
    Log.e("cvv", result.error.code.toString())
}
```

`cardCvvLength` accepts any combination of 3 and 4. Unsupported values are dropped, so `setOf(3, 5)` validates against `setOf(3)`. When null, empty, or holding no supported length, both 3 and 4 are accepted, so the SDK never produces a field that cannot be satisfied.