> 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/tuo-guan-zu-jian-ji-cheng/ka-pian/huo-qu-jiao-yi-zhuang-tai-bian-geng-tong-zhi.md).

# 获取交易状态变更通知

在支付流程中，交易状态将为以下几种之一：

* 待办的
* 成功的
* 失败的

当交易被标记为“成功”或“失败”时，您将通过发布商门户中配置的交易完成通知 URL 收到通知。

#### 先决条件 <a href="#pre-requisite" id="pre-requisite"></a>

* 交易“完成通知 URL”已在发布商门户中配置。有关详细说明，请参阅“[设置付款”](https://coda-payments.gitbook.io/coda-public-technical-documentation/codapay/getting-started/set-up-payments)。更改将立即生效。

#### 通知参数 <a href="#notification-parameters" id="notification-parameters"></a>

通知将发送到配置的交易完成通知 URL，并附加以下查询参数。

| TxnId            | <p><br><strong>始终</strong> 支付请求发起期间生成的交易 ID</p>                                                                                                                                                                                                                                                                                      |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| OrderId          | **始终** 是您的订单 ID，该 ID 在发起付款请求时传递。                                                                                                                                                                                                                                                                                                     |
| \*OriginAmount   | <p>\*<strong>始终（仅限 v2.0）</strong></p><p>初始请求中提供的以原币种计价的原始金额</p>                                                                                                                                                                                                                                                                      |
| \*OriginCurrency | \***始终（仅限 v2.0）** ISO 4217 字母代码（USD、IDR 等）。用于在发起请求中指定商品价格的原始货币。OriginCurrency 可以与 PayCurrency 不同。                                                                                                                                                                                                                                    |
| \*PayAmount      | <p>\*<strong>始终（仅限 v2.0）</strong></p><p>以支付货币形式向用户收取的最终价格。注意：总价始终等于支付金额。</p>                                                                                                                                                                                                                                                         |
| \*PayCurrency    | \***始终（仅限 v2.0）** ISO 4217 字母代码（USD、IDR 等）。用于向用户收取实际款项的货币。                                                                                                                                                                                                                                                                           |
| \*SubTotalPrice  | <p>\*<strong>始终（仅限 v2.0）</strong></p><p>税前交易净额。</p><p>计算方法如下：<code>totalPrice / (1 + payTaxRate)</code>。这代表商品的基本价格，不包括当地服务费或数字税。</p>                                                                                                                                                                                                 |
| \*PayTaxRate     | <p>\*<strong>始终（仅限 v2.0）</strong></p><p>适用于交易的税率（例如，<code>0.08</code>为8%）。该值根据商家配置、地区税法或用户的具体位置（邮政编码）动态确定。</p>                                                                                                                                                                                                                       |
| resultDesc       | <p><strong>始终</strong></p><p>该<code>resultDesc</code>参数旨在帮助商家准确分析和解决交易失败的原因。</p><ul><li>如果<code>resultCode</code>相等<code>0</code>，则<code>resultDesc</code>返回<strong>成功</strong>。</li><li>如果指示<code>resultCode</code>出现错误，<code>resultDesc</code>则会提供错误的详细描述。</li></ul>                                                               |
| ResultCode       | <p><strong>始终</strong> <br><strong>ResultCode</strong> 有助于指示交易状态。</p><p><code>ResultCode = 0</code>表示交易成功。</p><p><code>ResultCode =</code> 431、481 或 216 表示交易正在处理中。</p><p><a href="https://coda-payments.gitbook.io/coda-public-technical-documentation/codapay/error-codes">所有其他 ResultCode 值均表示交易失败。您可以在此处</a>找到完整的错误代码列表及其说明。</p> |
| TotalPrice       | **始终** 显示用户为此次交易支付的总金额。此金额始终以当地货币显示                                                                                                                                                                                                                                                                                                  |
| PaymentType      | <p><strong>始终</strong> 是用户尝试使用的付款类型。</p><p>PaymentType 等于支付通道 ID，如果支付通道是运营商计费，则为 1。</p>                                                                                                                                                                                                                                              |
| Checksum         | <p><strong>始终</strong><br><strong>校验和</strong> 用于验证消息是否由 Codapay 发送且未被篡改。有关如何使用此值的更多信息，请参阅<a href="https://coda-payments.gitbook.io/coda-public-technical-documentation/codapay/integration-guides/security-guidelines">“安全”部分。</a></p>                                                                                              |
| MnoId            | **可选：** 如果在支付通道初始化期间使用了 need\_mno\_id 参数，则此参数将包含支付通道 ID。                                                                                                                                                                                                                                                                             |
| USDPrice         | <p><strong>可选：</strong> 如果在美元不是当地货币的国家/地区发起交易，Coda 回调参数（TotalPrice）默认显示用户的当地货币金额。</p><p>如果您需要在回调函数中添加初始美元价格，请在发布商门户中进行配置。更多详情请参阅<a href="https://coda-payments.gitbook.io/coda-public-technical-documentation/codapay/hosted-payment-page-integration/initiate-usd-transactions">美元定价部分。</a></p>                                     |

#### 预期回应 <a href="#expected-response" id="expected-response"></a>

Codapay 发送通知后，希望收到确认收到的回复。

如果您的应用程序成功处理了通知，则返回“ResultCode=0”。否则，返回错误代码。

如果未收到回复，通知将以 5 分钟的间隔重新发送 3 次。如果所有尝试均失败，系统将发送电子邮件提醒。

> 要订阅交易通知，请前往[发布商门户](https://portal.codapayments.com/)。
>
> 团队 > 管理访问权限 > 勾选“交易通知” > 保存更改

#### 样本 <a href="#sample" id="sample"></a>

{% tabs %}
{% tab title="v2.0 通知" %}

```
// Sample for non-USD payments initiated
https://<your_webhook_url>?
  TxnId=7715121708032676249
  OrderId=365f5Z619951c1a4b8
  TotalPrice=1.00
  PaymentType=237
  ResultCode=0
  Checksum=6b6c5e0f835f9f1442726bed3aedc3c9
  PayTaxRate=8.00 //This field is only returned in v2.0 API
  PayCurrency=MYR //This field is only returned in v2.0 API
  PayAmount=1.00 //This field is only returned in v2.0 API
  OriginAmount=1.00 //This field is only returned in v2.0 API
  OriginCurrency=MYR //This field is only returned in v2.0 API
  SubTotalPrice=0.93 //This field is only returned in v2.0 API

// Sample for USD payments initiated
https://<your_webhook_url>?
  TxnId=7715122576202672831
  OrderId=365f5Z619951c1a4b8
  TotalPrice=1.17
  PaymentType=237
  ResultCode=0
  Checksum=10741fa6be7e6f2b189f029b3f8a0963
+ USDPrice=0.30
  PayTaxRate=8.00 //This field is only returned in v2.0 API
  PayCurrency=MYR //This field is only returned in v2.0 API
  PayAmount=1.17 //This field is only returned in v2.0 API
  OriginAmount=0.30 //This field is only returned in v2.0 API
  OriginCurrency=USD //This field is only returned in v2.0 API
  SubTotalPrice=1.08 //This field is only returned in v2.0 API
```

{% endtab %}

{% tab title="回复" %}

```
ResultCode=0
```

{% endtab %}
{% endtabs %}

#### 检查交易状态 <a href="#checking-a-transaction-status" id="checking-a-transaction-status"></a>

我们强烈建议您在收到购买通知 webhook 后调用[InquiryPaymentResult API](https://coda-payments.gitbook.io/coda-public-technical-documentation/codapay/hosted-payment-page-integration/check-a-transaction-status)。这有助于在释放购买的商品之前，核对您的系统和 Coda 系统中的交易状态。


---

# 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/ka-pian/huo-qu-jiao-yi-zhuang-tai-bian-geng-tong-zhi.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.