> 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/cha-xun-ding-dan-jie-kou.md).

# 查询订单接口

## 正式前置条件 <a href="#qian-zhi-tiao-jian" id="qian-zhi-tiao-jian"></a>

接入 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="165">环境</th><th>v2.0 接口 URL</th></tr></thead><tbody><tr><td>沙盒</td><td>https://sandbox.codapayments.com/airtime/api/restful/v2.0/Payment</td></tr><tr><td>正式</td><td>https://airtime.codapayments.com/airtime/api/restful/v2.0/Payment</td></tr></tbody></table>

<table><thead><tr><th width="165">Environment</th><th>v1.0 接口 URL</th></tr></thead><tbody><tr><td>沙盒</td><td>https://sandbox.codapayments.com/airtime/api/restful/v1.0/Payment</td></tr><tr><td>正式</td><td>https://airtime.codapayments.com/airtime/api/restful/v1.0/Payment</td></tr></tbody></table>

### 接口地址

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

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

## 请求参数

<table><thead><tr><th width="351">参数</th><th width="102">类型</th><th>描述</th></tr></thead><tbody><tr><td>inquiryPaymentRequest</td><td>Object</td><td><strong>必填</strong><br>必须是有效的JSON对象</td></tr><tr><td>inquiryPaymentRequest.apiKey</td><td>String</td><td><strong>必填</strong><br>Coda提供的API密钥 - 请参考 <a data-mention href="/pages/Knn2G4Gd1ZPSUbSS0PUS">/pages/Knn2G4Gd1ZPSUbSS0PUS</a> 了解如何获取。</td></tr><tr><td>inquiryPaymentRequest.txnId</td><td>Numeric</td><td><p><strong>必填</strong></p><p>您在发起支付后收集到的Coda订单ID</p></td></tr><tr><td>inquiryPaymentRequest.country</td><td>Numeric</td><td><p>*<strong>此字段仅适用于v2.0 API</strong></p><p><strong>可选</strong></p><p>ISO 3166 国家代码 - 请参阅 <a data-mention href="/pages/7B3qZnefeSwkSs84sKuB">/pages/7B3qZnefeSwkSs84sKuB</a></p></td></tr><tr><td>inquiryPaymentRequest.projectId</td><td>String</td><td><p>*<strong>此字段仅适用于v2.0 API</strong></p><p><strong>必填</strong><br>Coda提供的ProjectID，每个产品名称為独有- 请参考 <a data-mention href="/pages/Knn2G4Gd1ZPSUbSS0PUS">/pages/Knn2G4Gd1ZPSUbSS0PUS</a> 了解如何获取。</p></td></tr><tr><td>inquiryPaymentRequest.needStatusFinal</td><td>String</td><td><strong>可选</strong><br>如果您希望在响应中获取指示此订单是否为最终状态，请将其设置为<code>true</code>。</td></tr></tbody></table>

### 响应参数

<table><thead><tr><th width="244">参数</th><th width="97">类型</th><th>描述</th></tr></thead><tbody><tr><td>paymentResult</td><td>Object</td><td>包含该接口的响应结果</td></tr><tr><td>paymentResult.resultCode</td><td>Numeric</td><td><p>ResultCode将帮助指示交易的状态。</p><p><code>ResultCode = 0</code> 表示交易成功。</p><p><code>ResultCode = 431，481 或 216</code> 表示交易待处理</p><p>所有其他ResultCode值表示交易失败。您可以在 <a data-mention href="/pages/Ijfanb3Eb2mtXRsbF81n">/pages/Ijfanb3Eb2mtXRsbF81n</a> 找到完整的错误代码及其解释。</p></td></tr><tr><td>paymentResult.txnId</td><td>String</td><td>从支付请求发起返回的Coda订单ID。</td></tr><tr><td>paymentResult.orderId</td><td>String</td><td>您在支付请求发起时传递的订单ID</td></tr><tr><td>paymentResult.country</td><td>Numeric</td><td><p><strong>*此字段仅在 v2.0 API 版本中，根据特殊请求返回</strong></p><p>ISO 3166 国家代码 - 请参阅 <a data-mention href="/pages/7B3qZnefeSwkSs84sKuB">/pages/7B3qZnefeSwkSs84sKuB</a></p></td></tr><tr><td>paymentResult.originAmount</td><td>Numeric</td><td><p><strong>*此字段仅在 v2.0 API 版本中，根据特殊请求返回</strong></p><p>在发起请求时提供的金额</p></td></tr><tr><td>paymentResult.originCurrency</td><td>String</td><td><p><strong>*此字段仅在 v2.0 API 版本中，根据特殊请求返回</strong></p><p>ISO 4217 字母代码（如 USD、IDR 等）。在发起请求时用于指定商品价格的货币。</p><p>OriginCurrency可能与PayCurrency不同。</p></td></tr><tr><td>paymentResult.payAmount</td><td>Numeric</td><td><p><strong>*此字段仅在 v2.0 API 版本中，根据特殊请求返回</strong></p><p>以PayCurrency为单位计费给用户的最终价格。 注意：TotalPrice始终等于PayAmount。</p></td></tr><tr><td>paymentResult.payCurrency</td><td>String</td><td><p><strong>*此字段仅在 v2.0 API 版本中，根据特殊请求返回</strong></p><p>ISO 4217字母代码（USD、IDR等）。用于实际支付并向用户收费的货币。</p></td></tr><tr><td>paymentResult.resultDesc</td><td>String</td><td>如果resultCode返回错误，则该值描述错误信息。</td></tr><tr><td>paymentResult.totalPrice</td><td>Numeric</td><td>用户为订单交易支付的总金额。此金额将始终以本地货币计算。</td></tr><tr><td>paymentResult.profile</td><td>Object</td><td>包含键值列表的对象。当前可以用于处理的具体键值如下所示。</td></tr></tbody></table>

Profile

<table><thead><tr><th width="178">参数</th><th>描述</th></tr></thead><tbody><tr><td>PaymentType</td><td><p>用户选择的支付渠道。</p><p>PaymentType = 支付渠道ID，或者当支付渠道为运营商计费时，等于1</p></td></tr><tr><td>isStatusFinal</td><td><p>交易是否已达到最终状态的标志。</p><p></p><p><strong>注意：</strong>失败的交易可能需要最多12小时才能反映其最终状态。</p></td></tr><tr><td>status</td><td>Possible values are:<br>- "pending"（待处理）<br>- "failed"（失败）<br>- "success"（成功）</td></tr></tbody></table>

示例

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

```javascript
    "inquiryPaymentRequest":
    {
        "apiKey" : "32774abe1cd7d8bae650ea48265e",
        "country" : 702 //此字段仅适用于 v2.0 API
        "projectId" : 21 //此字段仅适用于 v2.0 API
        "txnId" : "7144594637002072212",
        "needStatusFinal": "true"
    }
}
```

{% endtab %}

{% tab title="v2.0 响应" %}

```json
//Sample for non-USD payments initiated
{
    "paymentResult": {
        "orderId": 20230526063548,
        "originAmount": 15298, //此字段仅适用于 v2.0 API
        "originCurrency": IDR, //此字段仅适用于 v2.0 API
        "payAmount": 15298, //此字段仅适用于 v2.0 API
        "payCurrency": IDR, //此字段仅适用于 v2.0 API
        "profile": {
            "entry": [
                {
                    "key": "PaymentType",
                    "value": 236
                },
                {
                    "key": "isStatusFinal",
                    "value": true
                },
                {
                    "key": "status",
                    "value": "failed"
                }
            ]
        },
        "resultCode": 213,
        "resultDesc": "This transaction has been cancelled. No charges were made. (error:213)",
        "totalPrice": 15298, //与 payAmount 相同
        "txnId": 7144594637002072212
    }
}

//Sample for USD payments initiated
{
    "paymentResult": {
        "orderId": 20230526063548,
        "originAmount": 1, //此字段仅适用于 v2.0 API
        "originCurrency": USD, //此字段仅适用于 v2.0 API
        "payAmount": 15298, //此字段仅适用于 v2.0 API
        "payCurrency": IDR, //此字段仅适用于 v2.0 API
        "profile": {
            "entry": [
                {
                    "key": "PaymentType",
                    "value": 236
                },
                {
                    "key": "isStatusFinal",
                    "value": true
                },
                {
                    "key": "status",
                    "value": "failed"
                }
            ]
        },
        "resultCode": 213,
        "resultDesc": "This transaction has been cancelled. No charges were made. (error:213)",
        "totalPrice": 15298, //与 payAmount 相同
        "txnId": 7144594637002072212
    }
}
```

{% endtab %}

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

```ruby
{
    "inquiryPaymentRequest":
    {
        "apiKey" : "32774abe1cd7d8bae650ea48265e",
        "txnId" : "7144594637002072212",
        "needStatusFinal": "true"
    }
}
```

{% endtab %}

{% tab title="v1.0 响应" %}

```
{
    "paymentResult": {
        "orderId": 20230526063548,
        "profile": {
            "entry": [
                {
                    "key": "PaymentType",
                    "value": 236
                },
                {
                    "key": "isStatusFinal",
                    "value": true
                },
                {
                    "key": "status",
                    "value": "failed"
                }
            ]
        },
        "resultCode": 213,
        "resultDesc": "This transaction has been cancelled. No charges were made. (error:213)",
        "totalPrice": 50,
        "txnId": 7144594637002072212
    }
}
```

{% endtab %}
{% endtabs %}

### 税务处理 (仅支持美国市场) <a href="#tax-handling-applicable-in-the-us-market-only" id="tax-handling-applicable-in-the-us-market-only"></a>

#### 当 `isTaxInclusiveAmount` 参数用于发起支付（Initiate Payment）接口时

此处显示的税务处理方式由发起支付时设置的 `isTaxInclusiveAmount` 参数决定。该参数用于定义您提交的商品价格应如何进行税务计算：

* **`isTaxInclusiveAmount: true`**
  * 商品总金额将被视为**已包含税费**。
  * 用户支付的金额不会发生变化。
  * `subTotalPrice` 将根据以下公式反向计算：

    ```
    subTotalPrice = itemTotal / (1 + payTaxRate / 100)
    ```
* **`isTaxInclusiveAmount: false`（或未提供该参数）**
  * 商品总金额将被视为**未包含税费**。
  * 系统会在商品金额基础上额外计算税费，因此：

    ```
    totalPrice = 商品总金额 + 税费
    ```

无论 `isTaxInclusiveAmount` 的值为何，**接口返回的数据结构保持一致**，只有 `subTotalPrice`、`totalPrice` 和 `payAmount` 的数值会有所不同。因此，调用方无需根据该参数判断如何解析响应。

可通过以下公式计算税额：

```
taxAmount = totalPrice − subTotalPrice
```

此功能仅适用于以下情况：

* Coda 为 **MoR（Merchant of Record）**
* 市场为 **美国（US）**
* 使用 **v2.0 API**

对于**非美国市场**或 **Coda 非 MoR** 的交易，`subTotalPrice` 和 `payTaxRate` 字段仍会返回，但 `isTaxInclusiveAmount` 参数不会产生任何影响。

***

#### 字段说明

| 字段                         | `isTaxInclusiveAmount: true`         | `isTaxInclusiveAmount: false`（或未提供） |
| -------------------------- | ------------------------------------ | ----------------------------------- |
| **subTotalPrice**          | `itemTotal / (1 + payTaxRate / 100)` | 等于商品总金额（itemTotal）                  |
| **totalPrice / payAmount** | 等于商品总金额（保持不变）                        | `subTotalPrice + 税费`                |
| **payTaxRate**             | 实际适用税率                               | 实际适用税率                              |

***

#### 响应示例

**`isTaxInclusiveAmount: true`（商品总金额为 10.00，税率为 8.88%）**

<a class="button secondary">Copy</a>

```
{
    "paymentResult": {
        "orderId": "365f5Z619951c1a4b8",
        "originAmount": 10.00,
        "originCurrency": "USD",
        "payAmount": 10.00,
        "payCurrency": "USD",
        "payTaxRate": 8.88,
        "subTotalPrice": 9.18,
        "totalPrice": 10.00,
        "resultCode": 0,
        "resultDesc": "Success",
        "txnId": 7841151540188018969
    }
}
```

**`isTaxInclusiveAmount: false`** **（商品总金额为 10.00，税率为 8.88%）**

<a class="button secondary">Copy</a>

```
{
    "paymentResult": {
        "orderId": "365f5Z619951c1a4b8",
        "originAmount": 10.00,
        "originCurrency": "USD",
        "payAmount": 10.89,
        "payCurrency": "USD",
        "payTaxRate": 8.88,
        "subTotalPrice": 10.00,
        "totalPrice": 10.89,
        "resultCode": 0,
        "resultDesc": "Success",
        "txnId": 7841152468648018909
    }
}
```


---

# 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/cha-xun-ding-dan-jie-kou.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.