> 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/codapay-ru-men-zhi-nan/kai-shi-jie-ru-zhi-fu-ye-mian-api.md).

# 开始接入支付页面 API

{% hint style="info" %}
本教程仅展示如何测试特定支付方式。如果您对我们的其他支付选择页面感兴趣，可以参考 [支付渠道接入方式](/https-coda-payments.gitbook.io-zhong-wen-coda-private-technical-documentation/codapay/zhi-fu-ye-mian-api-ji-cheng/zhi-fu-qu-dao-jie-ru-fang-shi.md)
{% endhint %}

<figure><img src="/files/2A8H1ieRtJfua1D0xNRI" alt=""><figcaption></figcaption></figure>

## **您将了解到的内容**

* 发起支付请求
* 您的客户在发起支付请求时的体验
* 您的客户在成功支付通知时的体验

本教程假设您已设置开发环境并具备调用 API 的工具（如 Postman 等）。如果尚未设置，您也可以通过我们 Coda 后台的“[沙盒测试](https://portal.codapayments.com/integration/codapay/sandbox-testing?_gl=1%2ainmxb0%2a_ga%2aMTM5MDk5NDE5NS4xNzM0MTg4Njg2%2a_ga_CSGEPL99WN%2aMTczNDM0NDE5OS43LjEuMTczNDM0NDQ3OS40Ny4wLjA.)”（集成->Codapay->Sandbox Testing)部分测试此流程。

***

## 步骤 1：发起支付请求

通过调用 <mark style="color:red;">`/init`</mark> 接口发起支付请求，以获取Coda订单 ID。使用以下参数并填写相应内容：

<table><thead><tr><th width="145"> 参数</th><th width="304">Placeholder text</th><th>描述</th></tr></thead><tbody><tr><td>country</td><td><pre><code>[SELECTED_COUNTRY]
</code></pre></td><td>您想要测试的国家/地区。查看 <a data-mention href="/pages/7B3qZnefeSwkSs84sKuB">/pages/7B3qZnefeSwkSs84sKuB</a></td></tr><tr><td>currency</td><td><pre><code>[SELECTED_CURRENCY]
</code></pre></td><td>您想要使用的货币代码。查看<a data-mention href="/pages/7B3qZnefeSwkSs84sKuB">/pages/7B3qZnefeSwkSs84sKuB</a></td></tr><tr><td>payType</td><td><pre><code>[SELECTED_PAYMENT_CHANNEL_ID]
</code></pre></td><td>您想要使用的支付方式。查看 <a data-mention href="/pages/8bVyaK6v8yNIvctJBsuQ">/pages/8bVyaK6v8yNIvctJBsuQ</a></td></tr><tr><td>apiKey</td><td><pre><code>[API_KEY]
</code></pre></td><td>从 <a href="https://coda-payments.gitbook.io/zhong-wen-coda-private-technical-documentation/codapay/codapay-ru-men-zhi-nan/kai-shi-coda-hou-tai-she-zhi">Coda 后台</a>获取您的 API 密钥。</td></tr><tr><td>projectId</td><td><pre><code>[PROJECT_ID]
</code></pre></td><td>*此字段仅适用于 v2.0 API 从 <a href="https://coda-payments.gitbook.io/zhong-wen-coda-private-technical-documentation/codapay/codapay-ru-men-zhi-nan/kai-shi-coda-hou-tai-she-zhi">Coda 后台</a>获取每个标题的 projectId。</td></tr></tbody></table>

{% hint style="warning" %}
确保价格在您选择的支付渠道的交易限额范围内，您可以在 [各渠道金额及限制](/https-coda-payments.gitbook.io-zhong-wen-coda-private-technical-documentation/codapay/ji-cheng-zhi-nan/ge-qu-dao-jineji-xian-zhi.md) 查看交易限额。
{% endhint %}

{% hint style="info" %}
以下参数已填写为测试用的虚拟数据，可以根据您的集成需求进行更改和正确填写。有关 <mark style="color:red;">`/init`</mark> 接口参数的更多详细信息，请参阅 [支付页面API集成](/https-coda-payments.gitbook.io-zhong-wen-coda-private-technical-documentation/codapay/zhi-fu-ye-mian-api-ji-cheng.md)。

Codapay 提供两个 API 版本 - v1.0 和 v2.0，v2.0 为升级版。**如果您是新商户，请使用 v2.0**。更多详情 - [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)
{% endhint %}

{% tabs %}
{% tab title="v2.0 请求" %}

```javascript
curl --location 'https://sandbox.codapayments.com/airtime/api/restful/v2.0/Payment/init.json' \
--header 'Content-Type: application/json' \
--data '{
    "initRequest": {
        "country": [SELECTED_COUNTRY],
        "payType": [SELECTED_PAYMENT_CHANNEL_ID],
        "apiKey": [API_KEY],
        "projectId": [PROJECT_ID] //此字段仅适用于 v2.0 API
        "currency": [SELECTED_CURRENCY],
        "items": [
            {
                "code": "1",
                "price": 50.00,
                "name": "Test Item"
            }
        ],
        "profile": {
            "entry": [
                {
                    "key": "user_id",
                    "value": "105"
                }
            ]
        }
    }
}
```

{% endtab %}

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

```python
curl --location 'https://sandbox.codapayments.com/airtime/api/restful/v1.0/Payment/init.json' \
--header 'Content-Type: application/json' \
--data '{
    "initRequest": {
        "country": [SELECTED_COUNTRY],
        "payType": [SELECTED_PAYMENT_CHANNEL_ID],
        "apiKey": [COUNTRY_API_KEY],
        "orderId": "12321312321314",
        "currency": [SELECTED_CURRENCY],
        "items": [
            {
                "code": "1",
                "price": 50.00,
                "name": "Test Item"
            }
        ],
        "profile": {
            "entry": [
                {
                    "key": "user_id",
                    "value": "105"
                }
            ]
        }
    }
}
```

{% endtab %}
{% endtabs %}

以下示例使用**新加坡**沙盒 API 密钥，**新加坡元 (SGD)** 作为货币，支付方式为**卡支付**。

{% tabs %}
{% tab title="v2.0 请求" %}

```javascript
curl --location 'https://sandbox.codapayments.com/airtime/api/restful/v2.0/Payment/init.json' \
--header 'Content-Type: application/json' \
--data '{
    "initRequest": {
        "country": 702,
        "payType": 427,
        "apiKey": "test_32774abe1cd7d8bae650ea48265e",
        "projectId": 21 //此字段仅适用于 v2.0 API
        "orderId": "12321312321314",
        "currency": 702,
        "items": [
            {
                "code": "1",
                "price": 50.00,
                "name": "Test Item"
            }
        ],
        "profile": {
            "entry": [
                {
                    "key": "user_id",
                    "value": "105"
                }
            ]
        }
    }
}'
```

{% endtab %}

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

```python
curl --location 'https://sandbox.codapayments.com/airtime/api/restful/v1.0/Payment/init.json' \
--header 'Content-Type: application/json' \
--data '{
    "initRequest": {
        "country": 702,
        "payType": 427,
        "apiKey": "32774abe1cd7d8bae650ea48265e",
        "orderId": "12321312321314",
        "currency": 702,
        "items": [
            {
                "code": "1",
                "price": 50.00,
                "name": "Test Item"
            }
        ],
        "profile": {
            "entry": [
                {
                    "key": "user_id",
                    "value": "105"
                }
            ]
        }
    }
}'
```

{% endtab %}

{% tab title="响应" %}

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

{% endtab %}
{% endtabs %}

***

## 步骤 2：将用户重定向至支付页面完成支付

1. 使用[步骤 1](#bu-zhou-1-fa-qi-zhi-fu-qing-qiu) 中获得的 <mark style="color:red;">txnId</mark>，将用户重定向至以下 URL：

{% hint style="info" %}
点击[此处](/https-coda-payments.gitbook.io-zhong-wen-coda-private-technical-documentation/codapay/zhi-fu-ye-mian-api-ji-cheng/zhan-shi-zhi-fu-ye-mian.md)查看 URL 中可传递的所有参数。
{% endhint %}

{% tabs %}
{% tab title="🖥️ 桌面端" %}

```
https://sandbox.codapayments.com/airtime/begin?type=3&txn_id=[txnId]
```

{% endtab %}

{% tab title="📱移动端" %}

```
https://sandbox.codapayments.com/airtime/begin?type=3&txn_id=[txnId]&browser_type=mobile-web
```

{% endtab %}
{% endtabs %}

以下是上述在新加坡使用卡支付发起的交易示例：

{% tabs %}
{% tab title="🖥️ 桌面端" %}

<figure><img src="/files/LHN1LyiHEFIaPsWQED41" alt=""><figcaption><p>https://sandbox.codapayments.com/airtime/begin?type=3&#x26;txn_id=7122167282516076304</p></figcaption></figure>
{% endtab %}

{% tab title="📱移动端" %}

<figure><img src="/files/3gJD1LMX0lYZ9ydkSR01" alt="" width="187"><figcaption><p>https://sandbox.codapayments.com/airtime/begin?type=3&#x26;txn_id=7122167282516076304&#x26;browser_type=mobile-web</p></figcaption></figure>
{% endtab %}
{% endtabs %}

2. 在沙盒环境中，您可以按照 [支付渠道测试说明](/https-coda-payments.gitbook.io-zhong-wen-coda-private-technical-documentation/codapay/ji-cheng-zhi-nan/sha-he-huan-jing-ce-shi-zhi-nan/zhi-fu-qu-dao-ce-shi-shuo-ming.md) 提供的测试说明完成支付。

{% hint style="info" %}
完成一笔新加坡的卡支付测试交易订单，可以使用以下测试卡信息
{% endhint %}

<table><thead><tr><th width="321">卡号</th><th>有效期</th><th>CVC</th></tr></thead><tbody><tr><td><pre><code>4242 4242 4242 4242
</code></pre></td><td><pre data-full-width="false"><code>01/35
</code></pre></td><td><pre><code>123
</code></pre></td></tr></tbody></table>

{% hint style="warning" %}
备注：在沙盒环境中，支付可能需要几分钟才能完成。
{% endhint %}

***

## 步骤 3：接收订单成功付款通知

您会在配置的回调 URL 上收到Coda的回调通知，通知中将包含以下字段作为查询参数：

<table><thead><tr><th width="170">参数</th><th>描述</th></tr></thead><tbody><tr><td>TxnId</td><td>Coda 订单 ID</td></tr><tr><td>OrderId</td><td>您在 init 请求中传递的 OrderId</td></tr><tr><td>ResultCode</td><td>支付状态（例如：success = 0）</td></tr><tr><td>TotalPrice</td><td>用户为该订单交易支付的总金额</td></tr><tr><td>PaymentType</td><td>用户选择的支付渠道 ID</td></tr><tr><td>Checksum</td><td>用于验证消息未被篡改的校验和</td></tr></tbody></table>

{% hint style="danger" %}
❗️**商家收到Coda订单回调成功支付通知，成功发货后需回复字符串&#x20;**<mark style="color:red;">**ResultCode=0**</mark>

例： NotifyURL="商家回调地址TxnId=Coda订单号\&OrderId=商家orderID\&TotalPrice=金额\&PaymentType=渠道号\&ResultCode=0\&Checksum=xxxxx", MResp="ResultCode=0"
{% endhint %}

{% hint style="danger" %}
❗️**若 Coda 未收到&#x20;**<mark style="color:red;">**`ResultCode=0`**</mark>**&#x20;的回复，将启动重试机制：**

* 系统会每隔 5 分钟重试一次，总共重试 3 次。
* 若重试机制失败，将通过邮件通知商家。
  {% endhint %}

***

## 步骤 4：调用 InquiryPaymentResult API 确认订单的支付状态

{% hint style="warning" %}
**我们强烈建议商家使用此接口做双重确认 (回调通知 + 订单状态结果成功), 以确保订单成功后才发货**
{% endhint %}

使用以下 InquiryPaymentResult API 调用查询您的订单支付状态。

{% hint style="info" %}
点击[此处](/https-coda-payments.gitbook.io-zhong-wen-coda-private-technical-documentation/codapay/zhi-fu-ye-mian-api-ji-cheng/cha-xun-ding-dan-jie-kou.md)查看所有可用参数。
{% endhint %}

{% tabs %}
{% tab title="v2.0 请求" %}

```javascript
curl --location 'https://sandbox.codapayments.com/airtime/api/restful/v2.0/Payment/inquiryPaymentResult.json' \
--header 'Content-Type: application/json' \
--data '{
    "inquiryPaymentRequest":
    {
        "apiKey" : "test_32774abe1cd7d8bae650ea48265e",
        "country": 702 //此字段仅适用于 v2.0 API
        "projectId" : 21 //此字段仅适用于 v2.0 API
        "txnId" : "7144594637002072212",
        "needStatusFinal": "true"
    }
}'
```

{% endtab %}

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

```python
curl --location 'https://sandbox.codapayments.com/airtime/api/restful/v1.0/Payment/inquiryPaymentResult.json' \
--header 'Content-Type: application/json' \
--data '{
    "inquiryPaymentRequest":
    {
        "apiKey" : "32774abe1cd7d8bae650ea48265e",
        "txnId" : "7144594637002072212",
        "needStatusFinal": "true"
    }
}'
```

{% endtab %}

{% tab title="响应" %}

```ruby
{
    "paymentResult": {
        "orderId": 12321312321314,
        "profile": {
            "entry": [
                {
                    "key": "PaymentType",
                    "value": 427
                },
                {
                    "key": "isStatusFinal",
                    "value": true
                },
                {
                    "key": "status",
                    "value": "success"
                }
            ]
        },
        "resultCode": 0,
        "resultDesc": "",
        "totalPrice": 50,
        "txnId": 7144594637002072212
    }
}
```

{% endtab %}
{% endtabs %}

## **接下来的步骤**

* 深入了解[支付页面 API](/https-coda-payments.gitbook.io-zhong-wen-coda-private-technical-documentation/codapay/zhi-fu-ye-mian-api-ji-cheng.md)，了解更多关于支付页面和[支付渠道选择页面](/https-coda-payments.gitbook.io-zhong-wen-coda-private-technical-documentation/codapay/zhi-fu-ye-mian-api-ji-cheng/zhi-fu-qu-dao-jie-ru-fang-shi.md)的内容。
* 进一步探索我们的[后端API](/https-coda-payments.gitbook.io-zhong-wen-coda-private-technical-documentation/codapay/hou-duan-api-ji-cheng.md) 功能。


---

# 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/codapay-ru-men-zhi-nan/kai-shi-jie-ru-zhi-fu-ye-mian-api.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.