> For the complete documentation index, see [llms.txt](https://docs.coda.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.coda.co/https-coda-payments.gitbook.io-zhong-wen-coda-private-technical-documentation/codapay/tuo-guan-zu-jian-ji-cheng/ka-pian/yu-codacard-sdk-jiao-hu.md).

# 与 CodaCard SDK 交互

CodaCard SDK 是一个客户端 JavaScript 库，可将符合 PCI 标准的安全卡片输入字段注入到您的结账页面。使用此参考文档可以管理组件的生命周期并处理用户驱动的事件。

#### `CodaCard()` <a href="#codacard" id="codacard"></a>

*创建一个新的 CodaCard 实例。*

**代码示例**

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

**返回**

SDK实例：包含该函数的对象`components`。

#### `.components({ clientSecret, appearance })` <a href="#components-clientsecret-appearance" id="components-clientsecret-appearance"></a>

*设置支付元素的环境并授权会话。*

**参数**

* `clientSecret`（字符串）：必填项。后端创建收费时返回的 JWT。
* `appearance`（对象）：*可选*。用于自定义组件视觉样式的配置对象。点击[此处](https://coda-payments.gitbook.io/coda-public-technical-documentation/codapay/hosted-component-integration/cards/styling-and-customization)了解更多样式选项。

**代码示例**

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

**返回**

组件工厂：用于生成特定支付 UI 元素的对象：`{ create: Function }`。

#### `.create(type, options)` <a href="#create-type-options" id="create-type-options"></a>

*生成特定的支付组件实例，例如卡片输入表单。*

**参数**

* `type`（字符串）：必填项。要创建的组件类型（目前支持`'charge'`）。
* `options`（对象）：*可选*。表单配置选项：
  * `withCardHolderName`（布尔值）：显示持卡人姓名字段。
  * `withCardHolderEmail`（布尔值）：显示电子邮件字段。
  * `prefillEmail`（字符串）：预填充电子邮件地址（无效值将被忽略）。
  * `locale`（字符串）：语言代码（例如`'en'`，，，`'id'`）`'th'`。

**代码示例**

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

**返回**

`CardChargeComponent`用于挂载和管理支付表单的实例。

#### `.mount(selector)` <a href="#mount-selector" id="mount-selector"></a>

*将安全支付表单注入到页面上的特定 DOM 元素中。*

**参数**

* `selector`（字符串）：必需。用于标识表单应渲染到的容器的 CSS 选择器（例如，`'#payment-form'`）。

**代码示例**

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

#### `.submit()` <a href="#submit" id="submit"></a>

*触发安全数据交换并处理支付信息。*

**代码示例**

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

此方法仅在表单处于就绪状态（`readyStateChange`事件已返回`true`）时有效。

#### `.on(event, callback)` <a href="#on-event-callback" id="on-event-callback"></a>

*注册特定组件事件的监听器，以使 UI 与支付状态同步。*

事件类型如下

| `readyStateChange`       | `(isReady: boolean) => void`        | 表单有效期变更                |
| ------------------------ | ----------------------------------- | ---------------------- |
| `userLoaded`             | `() => void`                        | 表单加载完成                 |
| `savedCardSelected`      | `() => void`                        | 已保存卡片已选中               |
| `savedCardLoaded`        | `() => void`                        | 已加载已保存的卡片              |
| `allSavedCardsRemoved`   | `() => void`                        | 所有已保存的卡片已移除            |
| `savedCardLoadingFailed` | `() => void`                        | 加载已保存的卡片失败             |
| `processingCard`         | `(isSuccess, errorMessage) => void` | 卡片正在处理中                |
| `shopperActionRequired`  | `(required) => void`                | 提交后，会指示用户是否会进入3DS验证流程。 |
| `shopperActionCompleted` | `() => void`                        | 3DS流程完成后，如果用户已完成整个流程。  |

**代码示例**

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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.coda.co/https-coda-payments.gitbook.io-zhong-wen-coda-private-technical-documentation/codapay/tuo-guan-zu-jian-ji-cheng/ka-pian/yu-codacard-sdk-jiao-hu.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.