Codapay API 版本概览

Codapay 提供两个版本的 API：v1.0 和 v2.0。

虽然两个版本均完全支持，但建议所有新接入使用 v2.0 版本。该版本包含多项优化，旨在简化集成流程、提升可维护性，并支持访问新功能（如卡片保存）。

为什么选择 v2.0

v2.0 引入了 全局 API 密钥（Global API Key） 的概念，替代了原本需针对不同国家与产品配置多个 API 密钥的模式。这简化了复杂性，并优化了集成和凭证管理流程。

此外，v2.0 增加了 Project ID 字段，用于区分不同的产品或标题，从而实现更精准的交易分段和报告功能。

⚠️ 注意：部分高级功能（如卡片信息保存）仅支持在使用 v2.0 API 密钥的环境中启用。

关键差异：v1.0 与 v2.0

功能项	v1.0	v2.0
API 密钥	「每个国家 × 每款 App」 配置独立密钥	同一商户主体 (Settlement Entity) 统一密钥管理
Project ID	不需要	所有请求必须包含
卡片信息保存功能	不支持	支持
接口地址	/v1.0/Payment	/v2.0/Payment
请求内容格式	不包含 projectId 字段	请求中必须包含 projectId 字段

v1.0 升级至 v2.0

如果您已接入 Codapay API v1.0，我们建议您升级至 v2.0 以享受简化的集成流程和新功能。升级过程轻量级且与您现有的交易逻辑兼容。

升级至 v2.0 的步骤

1. 申请 v2.0 API 密钥 请联系 Codapay 技术支持团队，申请您的 v2 API 密钥（Global API Key）及对应的 Project ID。

2. 更新 API 接口地址 将原本的 /v1.0/ 接口路径更新为 /v2.0/，适用于沙盒与正式环境：

   • 沙盒环境： https://sandbox.codapayments.com/airtime/api/restful/v2.0/Payment

   • 正式环境： https://airtime.codapayments.com/airtime/api/restful/v2.0/Payment

3. 新增 projectId 字段 在初始化请求（initRequest）中添加 projectId 字段（v2.0 中为必填项）：

   "initRequest": {
     "projectId": "YOUR_PROJECT_ID",
     ...
   }

4. 保留现有字段逻辑 除新增 projectId 外，其他字段（如 country、payType、currency、items、profile 等）保持不变，可沿用原有交易逻辑。

5. 测试与上线 请先在 v2.0 沙盒环境中完成测试验证。验证通过后，可切换至正式接口正式上线。

请求示例对比

v1.0 示例

{
    "initRequest": {
        "country": 158,
        "payType": 82,
        "apiKey": "e944d44f065eade8157737385a094a",
        "orderId": "12321312321314",
        "currency": 901,
        "items": [
            {
                "code": "1",
                "price": 1000.00,
                "name": "Test Item"
            }
        ],
        "profile": {
            "entry": [
                {
                    "key": "user_id",
                    "value": "105"
                }
            ]
        }
    }
}

v2.0 示例

{
    "initRequest": {
        "country": 158,
        "payType": 82,
        "apiKey": "e944d44f065eade8157737385a094a",
        "projectId": 21, //此字段仅适用于 v2.0 API
        "orderId": "12321312321314",
        "currency": 901,
        "items": [
            {
                "code": "1",
                "price": 1000.00,
                "name": "Test Item"
            }
        ],
        "profile": {
            "entry": [
                {
                    "key": "user_id",
                    "value": "105"
                }
            ]
        }
    }
}