> 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/ji-cheng-zhi-nan/codapay-api-ban-ben-gai-lan.md).

# 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

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

### 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 中为必填项）：

   ```json
   "initRequest": {
     "projectId": "YOUR_PROJECT_ID",
     ...
   }
   ```
4. **保留现有字段逻辑**\
   除新增 `projectId` 外，其他字段（如 `country`、`payType`、`currency`、`items`、`profile` 等）保持不变，可沿用原有交易逻辑。
5. **测试与上线**\
   请先在 v2.0 沙盒环境中完成测试验证。验证通过后，可切换至正式接口正式上线。

### 请求示例对比

#### v1.0 示例

```java
{
    "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 示例

```javascript
{
    "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"
                }
            ]
        }
    }
}
```


---

# 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/ji-cheng-zhi-nan/codapay-api-ban-ben-gai-lan.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.