> 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/zhi-fu-ye-mian-api-ji-cheng/fa-qi-zhi-fu-qing-qiu.md).

# 发起支付请求

## 前置条件

接入 Codapay API 前，请确保满足以下要求：

* 使用 HTTPS 协议。
* 支持 TLS 1.2 或更高版本。

Codapay API 提供两个版本，请查阅 [Codapay API 版本概览](/https-coda-payments.gitbook.io-zhong-wen-coda-private-technical-documentation/codapay/ji-cheng-zhi-nan/codapay-api-ban-ben-gai-lan.md) ，确保选择适合的版本进行接入。

## 详情

#### 沙盒环境

<table><thead><tr><th width="107">版本</th><th>接口 URL</th></tr></thead><tbody><tr><td>v2.0</td><td>https://sandbox.codapayments.com/airtime/api/restful/v2.0/Payment</td></tr><tr><td>v1.0</td><td>https://sandbox.codapayments.com/airtime/api/restful/v1.0/Payment</td></tr></tbody></table>

#### 正式环境

<table><thead><tr><th width="107">版本</th><th>接口 URL</th></tr></thead><tbody><tr><td>v2.0</td><td>https://airtime.codapayments.com/airtime/api/restful/v2.0/Payment</td></tr><tr><td>v1.0</td><td>https://airtime.codapayments.com/airtime/api/restful/v1.0/Payment</td></tr></tbody></table>

#### 接口地址

<mark style="color:green;">**POST**</mark> {Base URL}/init.json

{% hint style="info" %}
Codapay 的 API 支持 **REST** 接口服务，默认情况下，提供的端点均为 **RESTful**。
{% endhint %}

## 请求参数

<table><thead><tr><th width="282">参数</th><th width="93">类型</th><th>描述</th></tr></thead><tbody><tr><td>initRequest</td><td>Object</td><td><strong>必填</strong><br>必须是有效的JSON对象</td></tr><tr><td>initRequest.country</td><td>String</td><td><strong>必填</strong><br>ISO 3166 国家代码 - 请参阅 <a data-mention href="/pages/7B3qZnefeSwkSs84sKuB">/pages/7B3qZnefeSwkSs84sKuB</a></td></tr><tr><td>initRequest.payType</td><td>String</td><td><p><strong>必填</strong><br>您想使用的支付渠道ID - 请参阅 <a data-mention href="/pages/8bVyaK6v8yNIvctJBsuQ">/pages/8bVyaK6v8yNIvctJBsuQ</a> 。</p><p></p><p>支付渠道选择页面，可以设置为0；</p><p>运营商支付，可以设置为1 </p><p><br>详情请参考<a data-mention href="/pages/hvIA6r214lXhfMV3fC7i">/pages/hvIA6r214lXhfMV3fC7i</a></p></td></tr><tr><td>initRequest.apiKey</td><td>String</td><td><strong>必填</strong><br>Coda提供的API密钥 - 请参考 <a data-mention href="/pages/Knn2G4Gd1ZPSUbSS0PUS">/pages/Knn2G4Gd1ZPSUbSS0PUS</a> 了解如何获取。</td></tr><tr><td>initRequest.projectId</td><td>String</td><td><p>*<strong>此字段仅适用于v2.0 API</strong></p><p><strong>必填</strong><br>Coda提供的Project ID，专于每个标题产品。</p><p>请参考 <a data-mention href="/pages/Knn2G4Gd1ZPSUbSS0PUS">/pages/Knn2G4Gd1ZPSUbSS0PUS</a> 了解如何获取。</p></td></tr><tr><td>initRequest.isTaxInclusiveAmount</td><td>Boolean</td><td><p>*<strong>此字段仅适用于v2.0 API. 仅支持美国市场</strong><br></p><p>此参数影响<code>items[].price</code> 的总金额是否包含税费。此参数仅适用于 Coda 作为 MoR（Merchant of Record） 且支持税务的市场（目前仅支持美国）。</p><p></p><p>当设置为 true 时，商品总金额将视为含税价格，并按该金额直接收费。</p><p></p><p>当设置为 false（或未提供该参数）时，商品总金额将视为未含税价格，系统会在此基础上额外加收税费。</p><p></p><p>若未提供此参数，默认值为 false并保存原有配置</p><p></p><p>当 Coda 不是 MoR 时，此参数将被忽略。</p><p>→ 有关此参数如何影响响应结果及税费明细，请参阅 【<a href="/pages/YWwHCh2q0png17UKMwRg">查询订单-税务处理</a>】。</p></td></tr><tr><td>initRequest.orderId</td><td>String</td><td><strong>必填</strong><br>您在支付请求发起时传递的订单ID。长度必须在4到64个字符之间</td></tr><tr><td>initRequest.currency</td><td>String</td><td><strong>必填</strong><br>ISO 4217 货币代码 - 请参阅 <a data-mention href="/pages/7B3qZnefeSwkSs84sKuB">/pages/7B3qZnefeSwkSs84sKuB</a><br>仅支持<a href="https://coda-payments.gitbook.io/zhong-wen-coda-private-technical-documentation/codapay/zhi-fu-ye-mian-api-ji-cheng/fa-qi-usd-jiao-yi">本地货币或美元请求</a></td></tr><tr><td>initRequest.items</td><td>Array</td><td><strong>必填</strong><br>用户购买的商品列表。美国和加拿大仅支持单个商品</td></tr><tr><td>initRequest.items[].code</td><td>String</td><td><strong>可选</strong><br>商户商品关联的代码</td></tr><tr><td>initRequest.items[].price</td><td>Number</td><td><strong>必填</strong><br>商品价格，包括请求中指定货币的所有税费。</td></tr><tr><td>initRequest.items[].name</td><td>String</td><td><strong>必填</strong><br>购买的商品名称。仅支持拉丁字符（即英文）。</td></tr><tr><td>initRequest.profile</td><td>Object</td><td><strong>必填</strong><br>用户的个人资料信息（Profile）</td></tr><tr><td>initRequest.profile.entry</td><td>Array</td><td><strong>必填</strong><br>个人资料信息的键值对列表。目前可以用于处理的特定键值如下所示。</td></tr><tr><td>initRequest.profile.entry[].key</td><td>String</td><td>个人资料信息</td></tr><tr><td>initRequest.profile.entry[].value</td><td>String</td><td>个人资料信息</td></tr></tbody></table>

#### Profile

<table><thead><tr><th width="178">参数</th><th width="155">类型</th><th>描述</th></tr></thead><tbody><tr><td>user_id</td><td>String</td><td><strong>必填</strong><br>您用户的独有标识的 ID</td></tr><tr><td>in_frame_redirect</td><td>True or False</td><td><p><strong>可选</strong><br>如果您在网站的iframe中使用支付页面，您可以使用此参数控制支付流程完成后的行为。</p><p></p><p>True - 当用户尝试关闭Codapay窗口时，用户将被重定向到iframe中的重定向地址。</p><p></p><p>False - 当用户尝试关闭Codapay窗口时，用户将被重定向到新标签页中重定向到已配置的重定向地址。</p></td></tr><tr><td>return_url</td><td>String</td><td><p><strong>可选</strong><br>这允许您动态传递支付完成后用户将被重定向到的返回网址。此URL可以包含以下查询字符串占位符</p><ul><li><code>{transactionId}</code> 即Coda订单ID</li><li><code>{orderId}</code> 即商家订单ID</li></ul><p>如果未使用此键值对，Codapay将使用商户在Coda后台中配置的重定向地址。</p></td></tr><tr><td>need_mno_id</td><td>Any value or null</td><td>如果您使用payType = 0 / 1 或运营商支付发起了支付，并且希望知道用户选择了哪个支付渠道，可以在此字段中传递任意非空值。</td></tr></tbody></table>

响应参数

<table><thead><tr><th width="250">参数</th><th width="91">类型</th><th>描述</th></tr></thead><tbody><tr><td>initResult</td><td>Object</td><td>包含发起请求的结果</td></tr><tr><td>initResult.resultCode</td><td>Integer</td><td><p>请求成功将返回 resultCode = 0。</p><p>其余 resultCode值为错误代码。<br>错误代码的完整列表，请参阅 <a data-mention href="/pages/Ijfanb3Eb2mtXRsbF81n">/pages/Ijfanb3Eb2mtXRsbF81n</a></p></td></tr><tr><td>initResult.resultDesc</td><td>String</td><td>错误描述</td></tr><tr><td>initResult.txnId</td><td>Integer</td><td>发起请求的订单ID。如果订单发起失败，此值将为0。</td></tr></tbody></table>

## 示例

{% tabs %}
{% tab title="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"
                }
            ]
        }
    }
}
```

{% endtab %}

{% tab title="v1.0 请求" %}

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

```

{% endtab %}

{% tab title="成功响应" %}

```ruby
{
    "initResult": {
        "resultCode": 0,
        "txnId": 7177415887085060516
    }
}
```

{% endtab %}

{% tab title="失败响应" %}

```
{
    "initResult": {
        "resultCode": 103,
        "resultDesc": "This transaction has been cancelled. No charges were made. (error:103)",
        "txnId": 0
    }
}
```

{% endtab %}
{% endtabs %}

### [Profile ](#profile)示例

{% tabs %}
{% tab title="请求" %}

```javascript
"profile": {
            "entry": [
                {
                    "key": "user_id",
                    "value": "test105"
                },
                {
                    "key": "in_frame_redirect",
                    "value": "true"
                },
                {
                    "key": "return_url",
                    "value": "https://www.example.com/{transactionId}/{orderId}/return"
                },
                {
                    "key": "need_mno_id",
                    "value": "YES"
                }
            ]
        }
```

{% endtab %}
{% endtabs %}


---

# 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/zhi-fu-ye-mian-api-ji-cheng/fa-qi-zhi-fu-qing-qiu.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.