> For the complete documentation index, see [llms.txt](https://coda-payments.gitbook.io/coda-public-technical-documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://coda-payments.gitbook.io/coda-public-technical-documentation/codapay/hosted-component-integration/cards/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](/coda-public-technical-documentation/codapay/integration-guides/codapay-api-versions.md) for more details. 

### 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>

#### 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="/coda-public-technical-documentation/codapay/getting-started.md">Getting started</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>Optional</strong></p><p>ISO 3166 country code - refer to <a data-mention href="/coda-public-technical-documentation/general-information/payment-directory/country-codes.md">Country Codes</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="/coda-public-technical-documentation/codapay/getting-started.md">Getting started</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

\*OriginAmount, OriginCurrency, PayAmount, PayCurrency: Only returned for v2.0 API, and only upon special request. Please contact your account manager of our technical support team for more details.&#x20;

<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="/coda-public-technical-documentation/codapay/error-codes.md">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.originAmount</td><td>Numeric</td><td><p><strong>*This field is only returned for v2.0 API upon special request</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>*This field is only returned for v2.0 API upon special request</strong><br>ISO 4217 alphabetic code (USD, IDR, etc). Original currency used in the initiation request to specify the item price.</td></tr><tr><td>*paymentResult.payAmount</td><td>Numeric</td><td><p><strong>*This field is only returned for v2.0 API upon special request</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>*This field is only returned for v2.0 API upon special request</strong><br>ISO 4217 alphabetic code (USD, IDR, etc). Currency used for the actual payment charged to the user.</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="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="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 %}
{% endtabs %}

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

**When the flag** `isTaxInclusiveAmount` **is used in the** [**initiate payment endpoint**](/coda-public-technical-documentation/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
    }
}
```