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 for more details.

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

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

*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.

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.originAmount	Numeric	*This field is only returned for v2.0 API upon special request Float. Original amount in OriginCurrency as provided in the initiation request
*paymentResult.originCurrency	String	*This field is only returned for v2.0 API upon special request ISO 4217 alphabetic code (USD, IDR, etc). Original currency used in the initiation request to specify the item price.
*paymentResult.payAmount	Numeric	*This field is only returned for v2.0 API upon special request Float. Final price in PayCurrency charged to the user. Note: totalPrice always = payAmount
*paymentResult.payCurrency	String	*This field is only returned for v2.0 API upon special request ISO 4217 alphabetic code (USD, IDR, etc). Currency used for the actual payment charged to the user.
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

Request

{    
    "inquiryPaymentRequest":
    {
        "apiKey": "live_****************************",
        "country": 702
        "projectId": 21
        "txnId" : "7144594637002072212",
        "needStatusFinal": "true"
    }
}

Response

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

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