> 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/check-a-transaction-status.md).

# Check a transaction status

### Pre-requisite

When integrating with Codapay APIs, ensure you adhere to the following standards:

1. Use HTTPS protocol.
2. TLS 1.2 or higher

Note that Codapay APIs have two versions, please refer to [Codapay API Versions](/codapay/integration-guides/codapay-api-versions.md) for more details. 

* If you have integrated with v2.0 Initiate Payment API, you must use v2.0 Inquiry Payment Result API
* If you have integrated with v1.0 Initiate Payment API, you must use v1.0 Inquiry Payment Result API

### Reference

<table><thead><tr><th width="165">Environment</th><th>v2.0 Base URL</th></tr></thead><tbody><tr><td>Sandbox</td><td>https://sandbox.codapayments.com/airtime/api/restful/v2.0/Payment</td></tr><tr><td>Production</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 Base URL</th></tr></thead><tbody><tr><td>Sandbox</td><td>https://sandbox.codapayments.com/airtime/api/restful/v1.0/Payment</td></tr><tr><td>Production</td><td>https://airtime.codapayments.com/airtime/api/restful/v1.0/Payment</td></tr></tbody></table>

#### Endpoint

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

{% hint style="info" %}
Codapay's APIs support REST web services. By default, the endpoints displayed are RESTful.&#x20;
{% endhint %}

### Request Parameters

<table><thead><tr><th width="351">Parameter</th><th width="102">Type</th><th>Description</th></tr></thead><tbody><tr><td>inquiryPaymentRequest</td><td>Object</td><td><strong>Mandatory</strong><br>Must be a valid JSON object</td></tr><tr><td>inquiryPaymentRequest.apiKey</td><td>String</td><td><strong>Mandatory</strong><br>API key provided by Coda - Refer to <a data-mention href="/pages/SJ2KtFdcmUYgMDiplZT1">/pages/SJ2KtFdcmUYgMDiplZT1</a> to find out how to get it.</td></tr><tr><td>inquiryPaymentRequest.txnId</td><td>Numeric</td><td><p><strong>Mandatory</strong></p><p>Key for the profile entry</p></td></tr><tr><td>inquiryPaymentRequest.country</td><td>Numeric</td><td><p>*<strong>This field is only needed for v2.0 API</strong></p><p><strong>Optional</strong></p><p>ISO 3166 country code - refer to <a data-mention href="/pages/7B3qZnefeSwkSs84sKuB">/pages/7B3qZnefeSwkSs84sKuB</a></p></td></tr><tr><td>inquiryPaymentRequest.projectId</td><td>String</td><td><p>*<strong>This field is only needed for v2.0 API</strong></p><p><strong>Mandatory</strong><br>Project ID provided by Coda, unique for each title product - Refer to <a data-mention href="/pages/SJ2KtFdcmUYgMDiplZT1">/pages/SJ2KtFdcmUYgMDiplZT1</a> to find out how to get it.</p></td></tr><tr><td>inquiryPaymentRequest.needStatusFinal</td><td>String</td><td><strong>Optional</strong><br>Set as <code>true</code> if you want to get a flag indicating if this is the final status of the transaction or not in the response</td></tr></tbody></table>

### Response Parameters

<table><thead><tr><th width="244">Parameter</th><th width="97">Type</th><th>Description</th></tr></thead><tbody><tr><td>paymentResult</td><td>Object</td><td>Contains the result of the initiation request</td></tr><tr><td>paymentResult.resultCode</td><td>Numeric</td><td><p>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 = 431</code> or <code>216</code> 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>paymentResult.txnId</td><td>String</td><td>Transaction ID for the initiated request</td></tr><tr><td>paymentResult.orderId</td><td>String</td><td>The order ID your provided in the payment request initiation</td></tr><tr><td>*paymentResult.country</td><td>Numeric</td><td><p>*<strong>Always (v2.0 only)</strong></p><p>ISO 3166 country code - refer to <a data-mention href="/pages/7B3qZnefeSwkSs84sKuB">/pages/7B3qZnefeSwkSs84sKuB</a></p></td></tr><tr><td>*paymentResult.originAmount</td><td>Numeric</td><td><p>*<strong>Always (v2.0 only)</strong></p><p>Float. Original amount in OriginCurrency as provided in the initiation request</p></td></tr><tr><td>*paymentResult.originCurrency</td><td>String</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>*paymentResult.payAmount</td><td>Numeric</td><td><p>*<strong>Always (v2.0 only)</strong></p><p>Float. Final price in PayCurrency charged to the user.<br>Note: totalPrice always = payAmount</p></td></tr><tr><td>*paymentResult.payCurrency</td><td>String</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>Numeric</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>Numeric</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>paymentResult.items</td><td>Array</td><td><p>*<strong>Always (v2.0 only)</strong></p><p>List of items being purchased by the users</p></td></tr><tr><td>paymentResult.resultDesc</td><td>String</td><td>If the resultCode is an error, this value describes the error</td></tr><tr><td>paymentResult.totalPrice</td><td>Numeric</td><td>The total amount the user has paid for the transaction. This will always be in local currency</td></tr><tr><td>paymentResult.profile</td><td>Object</td><td>Object with a list of key values. Specific key-values that can be used to process currently are listed below.</td></tr></tbody></table>

#### Profile

<table><thead><tr><th width="178">Key</th><th>Description</th></tr></thead><tbody><tr><td>PaymentType</td><td><p>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 Carier Billing.</p></td></tr><tr><td>isStatusFinal</td><td>Flag that indicates whether the transaction has reached a final status or not.<br><br><strong>Note</strong>: Failed transactions may require up to 12 hours to reflect their final status</td></tr><tr><td>status</td><td>Possible values are:<br>- "pending"<br>- "failed"<br>- "success"</td></tr></tbody></table>

### Samples

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

```json
{    
    "inquiryPaymentRequest":
    {
        "apiKey": "live_****************************",
        "country": 702 //This field is only needed for v2.0 API
        "projectId": 21 //This field is only needed for v2.0 API
        "txnId" : "7144594637002072212",
        "needStatusFinal": "true"
    }
}
```

{% endtab %}

{% tab title="v2.0 Response" %}

```json
//Sample for non-USD payments initiated
{
    "paymentResult": {
        "orderId": "365f5Z619951c1a4b8",
        "originAmount": 1, //This field is only returned in v2.0 API
        "originCurrency": "MYR", //This field is only returned in v2.0 API
        "payAmount": 1, //This field is only returned in v2.0 API
        "payCurrency": "MYR", //This field is only returned in v2.0 API
        "payTaxRate": 8, //This field is only returned in v2.0 API
        "items": [ //This field is only returned in v2.0 API
            {
                "code": "123456",
                "name": "Star Diamond",
                "price": 10
            }
        ],
        "profile": {
            "entry": [
                {
                    "key": "PaymentType",
                    "value": 237
                },
                {
                    "key": "isStatusFinal",
                    "value": true
                },
                {
                    "key": "channelId",
                    "value": 237
                },
                {
                    "key": "status",
                    "value": "success"
                }
            ]
        },
        "resultCode": 0,
        "resultDesc": "Success",
        "subTotalPrice": 0.93, //This field is only returned in v2.0 API
        "totalPrice": 1, //Always the same as payAmount
        "txnId": 7715121708032676249
    }
}

//Sample for USD payments initiated
{
    "paymentResult": {
        "orderId": "365f5Z619951c1a4b8",
        "originAmount": 0.3, //This field is only returned in v2.0 API
        "originCurrency": "USD", //This field is only returned in v2.0 API
        "payAmount": 1.17, //This field is only returned in v2.0 API
        "payCurrency": "MYR", //This field is only returned in v2.0 API
        "payTaxRate": 8, //This field is only returned in v2.0 API
        "items": [ //This field is only returned in v2.0 API
            {
                "code": "123456",
                "name": "Star Diamond",
                "price": 10
            }
        ],
        "profile": {
            "entry": [
                {
                    "key": "PaymentType",
                    "value": 237
                },
                {
                    "key": "isStatusFinal",
                    "value": true
                },
                {
                    "key": "channelId",
                    "value": 237
                },
                {
                    "key": "status",
                    "value": "success"
                }
            ]
        },
        "resultCode": 0,
        "subTotalPrice": 1.08, //This field is only returned in v2.0 API
        "totalPrice": 1.17, //Always the same as payAmount
        "txnId": 7715122576202672831
    }
}
```

{% endtab %}

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

```json
{
    "inquiryPaymentRequest":
    {
        "apiKey" : "e944d4*****************",
        "txnId" : "7144594637002072212",
        "needStatusFinal": "true"
    }
}
```

{% endtab %}

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

```json
{
    "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 %}

### Tax handling (Applicable in the US Market Only)&#x20;

**When the flag** `isTaxInclusiveAmount` **is used in the** [**initiate payment endpoint**](/codapay/hosted-payment-page-integration/initiate-a-payment-request.md)

The tax behavior shown here is controlled by the `isTaxInclusiveAmount` flag set at initiation. It determines how the item prices you sent are interpreted for tax:

* **`isTaxInclusiveAmount: true`** — The item total is treated as **already including tax**. The user is charged that amount unchanged, and `subTotalPrice` is back-calculated as `itemTotal / (1 + payTaxRate/100)`.
* **`isTaxInclusiveAmount: false` (or omitted)** — The item total is treated as **excluding tax**. Tax is added on top, so `totalPrice` = item total + tax.

The response shape is identical in both cases — only the values of `subTotalPrice`, `totalPrice`, and `payAmount` differ. Consumers don't need to branch on the flag to parse the response.

Derive the tax amount from the response: `taxAmount = totalPrice − subTotalPrice`.

**Applies only when** Coda is MoR, the market is US, and the v2.0 API is used. For non-US or non-MoR transactions, `subTotalPrice` and `payTaxRate` still populate, but the flag has no effect.

| Field                  | isTaxInclusiveAmount: true       | isTaxInclusiveAmount: false / Omitted |
| ---------------------- | -------------------------------- | ------------------------------------- |
| subTotalPrice          | itemTotal / (1 + payTaxRate/100) | `payTaxRate/100)`= item total         |
| totalPrice / payAmount | = item total, unchanged          | `subTotalPrice` + tax                 |
| payTaxRate             | applied rate                     | applied rate                          |

#### Samples Response

&#x20;**`isTaxInclusiveAmount: true`** *(item total 10.00, rate 8.88%)*

```json
{
    "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`** *(item total 10.00, rate 8.88%)*

```json
{
    "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/codapay/hosted-payment-page-integration/check-a-transaction-status.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.