集成指南

本指南将引导您完成托管组件的实现。开始之前，请确保您已准备好所有必要的文件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 会将卡片输入字段安全地注入到该锚点。

<script src="https://hosted-component.codapayments.com/1.0.0/hosted-component.min.js"></script>

<div id="payment-form"></div>

安装组件

库加载完毕且容器准备就绪后，使用该方法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的完整文档。

步骤 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 参考文档。

第四步：处理付款结果

用户提交表单且付款成功后，Coda 会向您的后端发送异步通知。

Webhook 要求：

• 安全提示：您必须验证每条通知的校验和，以确保其源自 Coda。

• 服务器必须在200 OKX 秒内回复以确认收到消息。

通知的完整文档。