> For the complete documentation index, see [llms.txt](https://coda-payments.gitbook.io/coda-public-technical-documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://coda-payments.gitbook.io/coda-public-technical-documentation/codapay/hosted-component-integration/cards/interact-with-the-codacard-sdk.md).

# Interact with the CodaCard SDK

The CodaCard SDK is a client-side JavaScript library that injects secure, PCI-compliant card input fields into your checkout page. Use this reference to manage the component's lifecycle and handle user-driven events.

### `CodaCard()`

*Creates a new CodaCard instance.*

**Code Example**

```javascript
const codaCard = CodaCard();
```

**Returns**

SDK Instance: An object containing the `components` function.

### `.components({ clientSecret, appearance })`

*Sets up the environment for payment elements and authorizes the session.*

**Parameters**

* `clientSecret` (string): Required. The JWT returned from the charge creation on your backend.
* `appearance` (object): *Optional*. Configuration object for customizing the visual style of the components. See more about styling options [here](/coda-public-technical-documentation/codapay/hosted-component-integration/cards/styling-and-customization.md).

**Code Example**

```javascript
const components = codaCard.components({
  clientSecret: 'eyJ...', 
  appearance: { 
    customStyle: { borderRadius: '12px' } 
  }
});
```

**Returns**

Components Factory: An object used to generate specific payment UI elements: `{ create: Function }`.

### `.create(type, options)`

*Generates a specific payment component instance, such as the card input form.*

**Parameters**

* `type` (string): Required. The type of component to create (currently supports `'charge'`).
* `options` (object): *Optional*. Form configuration options:
  * `withCardHolderName` (boolean): Show cardholder name field.
  * `withCardHolderEmail` (boolean): Show email field.
  * `prefillEmail` (string): Pre-fill email (invalid values are ignored).
  * `locale` (string): Language code (e.g., `'en'`, `'id'`, `'th'`).

**Code Example**

```javascript
const chargeComponent = components.create('charge', {
  withCardHolderName: true,
  withCardHolderEmail: false,
  prefillEmail: 'user@example.com',
  locale: 'en'
});
```

**Returns**

`CardChargeComponent`: The instance used for mounting and managing the payment form.

### `.mount(selector)`

*Injects the secure payment form into a specific DOM element on your page.*

**Parameters**

* `selector` (string): Required. A CSS selector identifying the container where the form should be rendered (e.g., `'#payment-form'`).

**Code Example**

```javascript
chargeComponent.mount('#payment-form');
```

### `.submit()`

*Triggers the secure data exchange and processes the payment information.*

**Code Example**

```javascript
chargeComponent.submit();
```

{% hint style="danger" %}
This method only works when the form is in a ready state (when the `readyStateChange` event has returned `true`).
{% endhint %}

### `.on(event, callback)`

*Registers a listener for specific component events to synchronize your UI with the payment state.*

**Available Events**

| **Event**                | **Callback Signature**              | **When Fired**                                                                    |
| ------------------------ | ----------------------------------- | --------------------------------------------------------------------------------- |
| `readyStateChange`       | `(isReady: boolean) => void`        | Form validity changes                                                             |
| `userLoaded`             | `() => void`                        | Form finishes loading                                                             |
| `savedCardSelected`      | `() => void`                        | Saved card selected                                                               |
| `savedCardLoaded`        | `() => void`                        | Saved cards loaded                                                                |
| `allSavedCardsRemoved`   | `() => void`                        | All saved cards removed                                                           |
| `savedCardLoadingFailed` | `() => void`                        | Failed to load saved cards                                                        |
| `processingCard`         | `(isSuccess, errorMessage) => void` | Card is processing                                                                |
| `shopperActionRequired`  | `(required) => void`                | After submission and indicates whether user will be taken through 3DS flow or not |
| `shopperActionCompleted` | `() => void`                        | After 3DS flow has been completed if the user has been taken through it           |

**Code Example**

```javascript
chargeComponent.on('readyStateChange', (isReady) => {
  console.log('Ready:', isReady);
});
```