> 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/ji-cheng-zhi-nan.md).
# 集成指南
本指南将引导您完成卡支付托管组件的部署。开始之前，请确保您已准备好所有必要的工具`apiKey`和资源`projectId`。
#### 先决条件
* HTTPS：您的结账页面必须通过 HTTPS 协议提供，并采用 TLS 1.2 或更高版本。
* 后端端点：您必须有一个能够接收 webhook 通知的服务器端端点。
* API 凭证：由 Coda 分配的有效`apiKey`凭证。`projectId`
#### 第一步：发起付款
生命周期从您的服务器开始。调用`/init.json`端点以生成所需的会话凭据。
终点： `POST /init.json`
```
curl --location 'https://sandbox.codapayments.com/airtime/api/restful/v2.0/Payment/Component/init.json' \
--header 'Content-Type: application/json' \
--data '{
"initRequest": {
"country": 702,
"payType": 427,
"apiKey": "test_32774abe1cd7d8bae650ea48265e",
"projectId": 21
"orderId": "12321312321314",
"currency": 702,
"items": [
{
"code": "1",
"price": 50.00,
"name": "Test Item"
}
],
"profile": {
"entry": [
{
"key": "user_id",
"value": "105"
}
]
}
}
}'
```
**回复**
Coda 返回一个交易 ID 和一个客户端密钥。
* 交易 ID：将此信息存储在您的数据库中，以便将 Coda 的付款与您的订单关联起来。
* 客户端密钥：请安全地将此密钥传递给您的前端。此密钥授权 SDK 加载此特定交易的卡片字段。
#### 步骤 2：初始化和挂载
前端收到数据后`clientSecret`，即可挂载安全卡字段。
**加载 SDK 和容器**
在您的结账页面引入 Coda 库并定义一个占位符`div`。此容器充当锚点，SDK 会将卡片输入字段安全地注入到该锚点。
```
```
**安装组件**
库加载完毕且容器准备就绪后，使用该方法`clientSecret`初始化会话。`mount()`然后，该方法会将空的会话替换`div`为功能齐全且安全的刷卡表单。
```
const codaCard = CodaCard();
// Initialize the components with your secret
const components = codaCard.components({
clientSecret: '{{CLIENT_SECRET_FROM_BACKEND}}',
appearance: {}
});
// Create and mount the 'charge' component into your #payment-form div
const chargeComponent = components.create('charge');
chargeComponent.mount('#payment-form');
```
CodaCard SDK 的完整文档请点击[此处查看](https://coda-payments.gitbook.io/coda-public-technical-documentation/codapay/hosted-component-integration/cards/interact-with-the-codacard-sdk)。
#### 步骤 3：处理提交
提交操作完全由您掌控。您负责管理按钮状态并触发提交操作。
**准备逻辑**
监听事件`readyStateChange`以确定何时启用“支付”按钮。只有当所有字段都填写完毕并通过 Luhn 算法和格式检查后，表单才被视为已准备就绪。
```
chargeComponent.on('readyStateChange', (isReady) => {
// isReady returns a boolean
document.getElementById('pay-button').disabled = !isReady;
});
```
**调用提交**
当用户点击您的按钮时，显式调用 SDK 的`submit()`方法，将敏感数据直接转发给 Coda。
```
document.getElementById('pay-button').addEventListener('click', () => {
// Trigger the payment flow
chargeComponent.submit();
});
```
CodaCard SDK 的完整文档请点击[此处查看](https://coda-payments.gitbook.io/coda-public-technical-documentation/codapay/hosted-component-integration/cards/interact-with-the-codacard-sdk)。
#### 第四步：处理付款结果
用户提交表单且付款成功后，Coda 会向您的后端发送异步通知。
Webhook 要求：
* 安全提示：您必须验证每条通知的校验和，以确保其源自 Coda。
* 服务器必须在`200 OK`X 秒内回复以确认收到消息。
完整的通知文档请点击[此处](https://coda-payments.gitbook.io/coda-public-technical-documentation/codapay/hosted-component-integration/cards/get-notified-of-a-transaction-status-change)。
---
# 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/ji-cheng-zhi-nan.md?ask=&goal=
```
`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.