> 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/codapay/hosted-payment-page-integration/get-notified-of-a-transaction-status-change.md).

# Get notified of a transaction status change

During the payment flow, the transaction status will be one of the following:

* Pending
* Successful
* Failed

You will be notified whenever a transaction is marked as 'Successful' or 'Failed' via the Transaction Completion Notification URL configured in the Publisher Portal.

### Pre-requisite

* The Transaction "Complete Notification URL" is configured in Publisher Portal. Refer to [Set up payments](/codapay/getting-started/set-up-payments.md) for detailed instructions. Changes will take effect immediately.

### Notification parameters

Notifications are sent to the configured transaction complete notification URL with the appended query parameters below.

<table><thead><tr><th width="209">Parameters</th><th>Description</th></tr></thead><tbody><tr><td>TxnId</td><td><strong>Always</strong><br>The transaction ID generated during the payment request initiation</td></tr><tr><td>OrderId</td><td><strong>Always</strong><br>Your Order ID, passed during the payment request initiation</td></tr><tr><td>*OriginAmount</td><td><p>*<strong>Always (v2.0 only)</strong></p><p>Original amount in OriginCurrency as provided in the initiation request</p></td></tr><tr><td>*OriginCurrency</td><td>*<strong>Always (v2.0 only)</strong><br>ISO 4217 alphabetic code (USD, IDR, etc). The original currency used in the initiation request to specify the item price. <br>OriginCurrency can be different from PayCurrency.</td></tr><tr><td>*PayAmount</td><td><p>*<strong>Always (v2.0 only)</strong></p><p>Final price in PayCurrency charged to the user.<br>Note: TotalPrice always = PayAmount</p></td></tr><tr><td>*PayCurrency</td><td>*<strong>Always (v2.0 only)</strong><br>ISO 4217 alphabetic code (USD, IDR, etc). Currency used for the actual payment charged to the user.</td></tr><tr><td>*SubTotalPrice</td><td><p>*<strong>Always (v2.0 only)</strong></p><p>The net amount of the transaction before taxes.</p><p></p><p>Calculated as: <code>totalPrice / (1 + payTaxRate)</code>. This represents the base item price excluding local service or digital taxes.</p></td></tr><tr><td>*PayTaxRate</td><td><p>*<strong>Always (v2.0 only)</strong></p><p>The tax percentage rate applied to the transaction (e.g., <code>0.08</code> for 8%). This value is dynamically determined based on the merchant configuration, regional tax laws, or the user’s specific location (Zip Code).</p></td></tr><tr><td>resultDesc</td><td><p><strong>Always</strong></p><p><br></p><p>The <code>resultDesc</code> parameter is designed to assist merchants in accurately analyzing and addressing the causes of transaction failures.</p><ul><li>If the <code>resultCode</code> equals <code>0</code>, the <code>resultDesc</code> will return <strong>Success</strong>.</li><li>If the <code>resultCode</code> indicates an error, the <code>resultDesc</code> will provide a detailed description of the error.</li></ul></td></tr><tr><td>ResultCode</td><td><p><strong>Always</strong><br>The ResultCode will help indicate the status of the transaction. </p><p></p><p><code>ResultCode = 0</code> means the transaction is successful.</p><p><code>ResultCode =</code> 431, 481 or 216 means that the transaction is pending. </p><p></p><p>All other ResultCode values mean that the transaction Failed. You can find the full list of error codes and their explanation <a href="/pages/Ijfanb3Eb2mtXRsbF81n">here</a>. </p></td></tr><tr><td>TotalPrice</td><td><strong>Always</strong><br>The total amount the user has paid for the transaction. This will always be in local currency.</td></tr><tr><td>PaymentType</td><td><p><strong>Always</strong><br>The PaymentType the user attempted to pay with. </p><p></p><p>PaymentType is equal to the payment channel ID or 1 in case the payment channel is a Carrier Billing.</p></td></tr><tr><td>Checksum</td><td><strong>Always</strong><br>The checksum helps verify that the message is sent by Codapay and has not been tampered with. Refer to the <a href="/pages/vilOzcm8mySaXwzmWIPn">Security section</a> for more information on how to use this value.</td></tr><tr><td>MnoId</td><td><strong>Optional</strong><br>If the need_mno_id parameter was used during payment channel initiation, this parameter will contain the payment channel ID</td></tr><tr><td>USDPrice</td><td><p><strong>Optional</strong><br>If a transaction is initiated in a country where USD is not the local currency, the Coda callback parameter (TotalPrice) will default display the user's local currency amount. </p><p></p><p>If you require adding the initial USDPrice to the callback, please configure it from the Publisher Portal. Refer to the <a href="/pages/TknzeuacF0MKmxEPUMBR">USD pricing section</a> for more details.</p></td></tr></tbody></table>

### Expected Response

After sending the notification, Codapay expects an acknowledgment to confirm it has been received.

If your application processes the notification successfully, respond with 'ResultCode=0.' Otherwise, return an error code.&#x20;

If no response is received, the notification will be re-sent 3 times at 5-minute intervals. If all attempts fail, an email alert will be triggered.

> To subscribe to transaction notifications, go to the [Publisher Portal](https://portal.codapayments.com/).&#x20;
>
> Team > Manage Access > Tick "Transaction Notification" > Save Changes

### Sample&#x20;

{% tabs %}
{% tab title="v2.0 Notification" %}
{% code overflow="wrap" %}

```json5
// 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

```

{% endcode %}
{% endtab %}

{% tab title="v1.0 Notification" %}
{% code overflow="wrap" %}

```json5
// Sample for non-USD payments initiated
https://<your_webhook_url>?
  TxnId=7178589013775074766
  OrderId=12321312321314
  TotalPrice=100
  PaymentType=101
  ResultCode=0
  Checksum=e944d44f065eade8157737385a094a57
+ USDPrice=10.00

// Sample for non-USD payments initiated
https://<your_webhook_url>?
  TxnId=7178589013775038493
  OrderId=12321312321314
  TotalPrice=100
  PaymentType=101
  ResultCode=0
  Checksum=10741fa6be7e6f2b189f029b3f8a0963
```

{% endcode %}
{% endtab %}

{% tab title="Response" %}
{% code overflow="wrap" %}

```json5
ResultCode=0
```

{% endcode %}
{% endtab %}
{% endtabs %}

### Failed Transaction Notification

In addition to successful transaction notifications, Codapay also supports **failed transaction notifications**.

If a transaction does **not** reach a successful state, a notification will also be sent to the configured **Transaction Complete Notification URL** with the relevant transaction details.

**Enablement**\
Failed transaction notification is not enabled by default. To enable this feature, please contact your **Coda Account Manager** or the **Integration Support team** at **<codapay_integration@coda.co>**.

### Sample&#x20;

{% tabs %}
{% tab title="v2.0 Notification" %}

<pre class="language-json5"><code class="lang-json5"><strong>// Sample for failed transaction notification
</strong>https://&#x3C;your_webhook_url>?
  TxnId=7743322396792877759
  OrderId=20250611113402
  TotalPrice=2.00
  PaymentType=421
  ResultCode=750
  Checksum=ef631c0bef3249406cfe5c1350693195
  PayCurrency=MYR //This field is only returned in v2.0 API
  PayAmount=2.0 //This field is only returned in v2.0 API
  OriginAmount=2.0 //This field is only returned in v2.0 API
  OriginCurrency=MYR //This field is only returned in v2.0 API
</code></pre>

{% endtab %}

{% tab title="v1.0 Notification" %}

```json5
// Sample for failed transaction notification
https://<your_webhook_url>?
  TxnId=7743328618752877897
  OrderId=123
  TotalPrice=222222210.00
  PaymentType=237
  ResultCode=415
  Checksum=f3a06cf11a0244b0308c8d8acbf53add
  resultDesc=This transaction has been cancelled. No charges were made. (error:415)
```

{% endtab %}
{% endtabs %}

### Checking a transaction status

We highly recommend using the [InquiryPaymentResult API ](/codapay/hosted-payment-page-integration/check-a-transaction-status.md)call after receiving the purchase notification webhook. This will help reconcile the transaction status between your system and Coda's before releasing the purchased item.


---

# 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/codapay/hosted-payment-page-integration/get-notified-of-a-transaction-status-change.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.