> 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/qi-ta-zhi-fu-fang-shi/ji-cheng-zhi-nan.md).
# 集成指南
本指南将引导您完成托管组件的实现。开始之前，请确保您已准备好所有必要的文件`apiKey`和`projectId`资源。
#### 先决条件
* **HTTPS：**您的结账页面必须通过 HTTPS 协议提供，且必须使用 TLS 1.2 或更高版本。
* **后端端点：**您必须拥有一个能够接收 Webhook 通知的服务器端端点。
* **API凭证：**由Coda分配的有效`apiKey`凭证`projectId`
* **支持的支付渠道：**请确认`payType`您要集成的支付渠道。目前仅支持 Google Pay 和 Apple Pay，但我们会迅速扩展到更多支付渠道。
* **配置请求：**请向您的实施经理提供要为 APM 托管组件配置的 MID 列表
#### 第一步：发起付款
生命周期从您的服务器开始。调用`/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,
"walletFilter": "google_pay",
"items": [
{
"code": "1",
"price": 50.00,
"name": "Test Item"
}
],
"profile": {
"entry": [
{
"key": "user_id",
"value": "105"
}
]
}
}
}'
```
> **注意：**此`payType`值决定组件将渲染哪个支付渠道。请参阅支持的支付渠道列表以获取正确的值。
> **钱包渠道：**对于支持同一账户下多个钱包的支付渠道`payType`（例如 Google Pay 和 Apple Pay），您可以选择性地传递`walletFilter`参数，以仅显示特定的钱包按钮。如果省略此参数，`payType`则会显示所有可用的钱包按钮。
**回复**
Coda 返回一个交易 ID 和一个客户端密钥。
* 交易 ID：将此信息存储在您的数据库中，以便将 Coda 的付款与您的订单关联起来。
* 客户端密钥：请安全地将此密钥传递给您的前端。此密钥授权 SDK 加载此特定交易的卡片字段。
#### 步骤 2：初始化和挂载
前端收到数据后`clientSecret`，即可挂载安全卡字段。
**加载 SDK 和容器**
在您的结账页面引入 Coda 库并定义一个占位符`div`。此容器充当锚点，SDK 会将卡片输入字段安全地注入到该锚点。
```
```
**安装组件**
库加载完毕且容器准备就绪后，使用该方法`clientSecret`初始化会话。然后，该`mount()`方法会将空的会话替换`div`为功能齐全且安全的刷卡表单。
```
const codaComponent = CodaComponent();
// Initialize the components with your secret
const components = codaComponent.components({
clientSecret: '{{CLIENT_SECRET_FROM_BACKEND}}'
});
// Create and mount the 'charge' component into your #payment-form div
const chargeComponent = components.create('charge');
chargeComponent.mount('#payment-form');
```
[codaComponent SDK](https://coda-payments.gitbook.io/coda-public-technical-documentation/codapay/hosted-component-integration/alternative-payment-methods/interact-with-the-codacomponent-sdk)的完整文档。
#### 步骤 3：处理支付状态
该组件会发出事件来传达支付流程的当前步骤。您的前端应该监听这些事件，以管理相关的用户体验——例如，显示加载状态、显示成功消息或处理错误。
**聆听事件**
使用以下`.on()`方法注册事件监听器：
```
chargeComponent.on('userLoaded', () => {
// Component has finished loading and is ready for user interaction
console.log('Component loaded');
});
chargeComponent.on('success', () => {
// Payment completed successfully — show confirmation in your UI
console.log('Payment successful');
});
chargeComponent.on('failed', () => {
// Payment failed — show appropriate messaging
console.log('Payment failed');
});
```
> 有关可用事件及其签名的完整列表，请参阅[CodaComponent SDK 参考文档。](https://coda-payments.gitbook.io/coda-public-technical-documentation/codapay/hosted-component-integration/alternative-payment-methods/interact-with-the-codacomponent-sdk)
#### 第四步：处理付款结果
用户提交表单且付款成功后，Coda 会向您的后端发送异步通知。
Webhook 要求：
* 安全提示：您必须验证每条通知的校验和，以确保其源自 Coda。
* 服务器必须在`200 OK`X 秒内回复以确认收到消息。
[通知的完整文档](https://coda-payments.gitbook.io/coda-public-technical-documentation/codapay/hosted-component-integration/alternative-payment-methods/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/qi-ta-zhi-fu-fang-shi/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.