|
**端点**
**POST {基本 URL}/inquiryPaymentResult.json**
Codapay 的 API 支持 REST Web 服务。默认情况下，显示的端点是 RESTful 的。
#### 请求参数
| inquiryPaymentRequest | Object | **必填：** 必须是有效的 JSON 对象 |
| ------------------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| inquiryPaymentRequest.apiKey | String | **必填：**Coda 提供的**API 密钥 - 请参阅**[入门指南](https://coda-payments.gitbook.io/coda-public-technical-documentation/codapay/getting-started)了解如何获取该密钥。 |
| inquiryPaymentRequest.txnId | Numeric | **必填：**个人资料条目的关键信息 |
| inquiryPaymentRequest.country | Numeric | 可选：
ISO 3166 国家代码 - 请参阅国家和货币代码
|
| inquiryPaymentRequest.projectId | String | \*此字段仅在 v2.0 API 中需要
必填：Coda 提供的 项目 ID，每个标题产品都有唯一的项目 ID - 请参阅入门指南了解如何获取。
|
| inquiryPaymentRequest.needStatusFinal | String | **可选** `true`用于在响应中获取一个标志，指示这是否是交易的最终状态。 |
#### 响应参数
\*OriginAmount、OriginCurrency、PayAmount、PayCurrency：仅在 v2.0 API 中返回，且仅在特殊请求时返回。请联系您的技术支持客户经理了解更多详情。
| paymentResult | Object | 包含发起请求的结果 |
| ------------------------------ | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| paymentResult.resultCode | Numeric | 结果代码将有助于指示交易状态。
ResultCode = 0表示交易成功。
ResultCode = 431或者216表示交易正在处理中。
所有其他 ResultCode 值均表示交易失败。您可以在此处找到完整的错误代码列表及其说明。
|
| paymentResult.txnId | String | 发起请求的交易 ID |
| paymentResult.orderId | String | 您在发起付款请求时提供的订单 ID |
| \*paymentResult.originAmount | Numeric | \*此字段仅在特殊请求下通过 v2.0 API 返回。
浮点数。原始金额，以发起请求中提供的原始货币表示。
|
| \*paymentResult.originCurrency | String | **\*此字段仅在 v2.0 API 中根据特殊请求返回。ISO** 4217 字母代码（USD、IDR 等）。用于在发起请求中指定商品价格的原始货币。 |
| \*paymentResult.payAmount | Numeric | \*此字段仅在特殊请求下通过 v2.0 API 返回。
浮点数。以支付货币形式向用户收取的最终价格。注意：总价始终等于支付金额。
|
| \*paymentResult.payCurrency | String | **\*此字段仅在 v2.0 API 中根据特殊请求返回。ISO** 4217 字母代码（USD、IDR 等）。用于向用户收取实际款项的货币。 |
| paymentResult.resultDesc | String | 如果 resultCode 为错误，则此值描述该错误。 |
| paymentResult.totalPrice | Numeric | 用户为本次交易支付的总金额。此金额始终以当地货币显示。 |
| paymentResult.profile | Object | 包含键值对列表的对象。下面列出了当前可用于处理的特定键值对。 |
**Profile 用户信息**
| 键 | 介绍 |
| ------------- | ------------------------------------------------------------------ |
| PaymentType | 用户尝试使用的支付类型。
PaymentType 等于支付渠道 ID，如果支付渠道是承运商计费，则为 1。
|
| isStatusFinal | 此标志指示交易是否已达到最终状态。 **注意**：失败的交易可能需要长达 12 小时才能反映其最终状态。 |
| status | 可能的值有：-“待处理”-“失败”-“成功”
|
#### 示例
{% tabs %}
{% tab title="请求" %}
```
{
"inquiryPaymentRequest":
{
"apiKey": "live_****************************",
"country": 702
"projectId": 21
"txnId" : "7144594637002072212",
"needStatusFinal": "true"
}
}
```
{% endtab %}
{% tab title="回复" %}
```
//Sample for non-USD payments initiated
{
"paymentResult": {
"orderId": 20230526063548,
"originAmount": 15298,
"originCurrency": IDR,
"payAmount": 15298,
"payCurrency": IDR,
"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, //Always the same as payAmount
"txnId": 7144594637002072212
}
}
//Sample for USD payments initiated
{
"paymentResult": {
"orderId": 20230526063548,
"originAmount": 1, //This field is only returned in v2.0 API
"originCurrency": USD, //This field is only returned in v2.0 API
"payAmount": 15298, //This field is only returned in v2.0 API
"payCurrency": IDR, //This field is only returned in v2.0 API
"profile": {
"entry": [
{
"key": "PaymentType",
"value": 236
},
{
"key": "isStatusFinal",
"value": true
},
{
"key": "status",
"value": "failed"
}
]
},
"resultCode": 213,
```
{% endtab %}
{% endtabs %}
### 税务处理 (仅支持美国市场)
#### 当 `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%）**
Copy
```
{
"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%）**
Copy
```
{
"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/tuo-guan-zu-jian-ji-cheng/qi-ta-zhi-fu-fang-shi/cha-kan-jiao-yi-zhuang-tai.md?ask=&goal=
```
`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.