Check a transaction status

Check a transaction's 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 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

Environment	v2.0 Base URL
Sandbox	https://sandbox.codapayments.com/airtime/api/restful/v2.0/Payment
Production	https://airtime.codapayments.com/airtime/api/restful/v2.0/Payment

Environment	v1.0 Base URL
Sandbox	https://sandbox.codapayments.com/airtime/api/restful/v1.0/Payment
Production	https://airtime.codapayments.com/airtime/api/restful/v1.0/Payment

Endpoint

POST {Base URL}/inquiryPaymentResult.json

Codapay's APIs support REST web services. By default, the endpoints displayed are RESTful.

Request Parameters

Parameter	Type	Description
inquiryPaymentRequest	Object	Mandatory Must be a valid JSON object
inquiryPaymentRequest.apiKey	String	Mandatory API key provided by Coda - Refer to Getting started to find out how to get it.
inquiryPaymentRequest.txnId	Numeric	Mandatory Key for the profile entry
inquiryPaymentRequest.country	Numeric	*This field is only needed for v2.0 API Optional ISO 3166 country code - refer to Country and Currency Codes
inquiryPaymentRequest.projectId	String	*This field is only needed for v2.0 API Mandatory Project ID provided by Coda, unique for each title product - Refer to Getting started to find out how to get it.
inquiryPaymentRequest.needStatusFinal	String	Optional Set as true if you want to get a flag indicating if this is the final status of the transaction or not in the response

Response Parameters

Parameter	Type	Description
paymentResult	Object	Contains the result of the initiation request
paymentResult.resultCode	Numeric	The ResultCode will help indicate the status of the transaction. ResultCode = 0 means the transaction is successful. ResultCode = 431 or 216 means that the transaction is pending. All other ResultCode values mean that the transaction Failed. You can find the full list of error codes and their explanation here.
paymentResult.txnId	String	Transaction ID for the initiated request
paymentResult.orderId	String	The order ID your provided in the payment request initiation
*paymentResult.country	Numeric	*Always (v2.0 only) ISO 3166 country code - refer to Country and Currency Codes
*paymentResult.originAmount	Numeric	*Always (v2.0 only) Float. Original amount in OriginCurrency as provided in the initiation request
*paymentResult.originCurrency	String	*Always (v2.0 only) ISO 4217 alphabetic code (USD, IDR, etc). The original currency used in the initiation request to specify the item price. OriginCurrency can be different from PayCurrency.
*paymentResult.payAmount	Numeric	*Always (v2.0 only) Float. Final price in PayCurrency charged to the user. Note: totalPrice always = payAmount
*paymentResult.payCurrency	String	*Always (v2.0 only) ISO 4217 alphabetic code (USD, IDR, etc). Currency used for the actual payment charged to the user.
*SubTotalPrice	Numeric	*Always (v2.0 only) The net amount of the transaction before taxes. Calculated as: totalPrice / (1 + payTaxRate). This represents the base item price excluding local service or digital taxes.
*PayTaxRate	Numeric	*Always (v2.0 only) The tax percentage rate applied to the transaction (e.g., 0.08 for 8%). This value is dynamically determined based on the merchant configuration, regional tax laws, or the user’s specific location (Zip Code).
paymentResult.items	Array	*Always (v2.0 only) List of items being purchased by the users
paymentResult.resultDesc	String	If the resultCode is an error, this value describes the error
paymentResult.totalPrice	Numeric	The total amount the user has paid for the transaction. This will always be in local currency
paymentResult.profile	Object	Object with a list of key values. Specific key-values that can be used to process currently are listed below.

Profile

Key	Description
PaymentType	The PaymentType the user attempted to pay with. PaymentType is equal to the payment channel ID or 1 in case the payment channel is a Carier Billing.
isStatusFinal	Flag that indicates whether the transaction has reached a final status or not. Note: Failed transactions may require up to 12 hours to reflect their final status
status	Possible values are: - "pending" - "failed" - "success"

Samples

v2.0 Request

{    
    "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"
    }
}

v2.0 Response

//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
    }
}

v1.0 Request

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

v1.0 Response

{
    "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
    }
}

Tax handling (Applicable in the US Market Only)

When the flag isTaxInclusiveAmount is used in the initiate payment endpoint

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

isTaxInclusiveAmount: true (item total 10.00, rate 8.88%)

{
    "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%)

{
    "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
    }
}