查询订单接口

正式前置条件

接入 Codapay API 前，请确保满足以下要求：

• 使用 HTTPS 协议。

• 支持 TLS 1.2 或更高版本。

Codapay API 提供两个版本，请查阅 Codapay API 版本概览 ，确保选择适合的版本进行接入。

详情

环境	v2.0 接口 URL
沙盒	https://sandbox.codapayments.com/airtime/api/restful/v2.0/Payment
正式	https://airtime.codapayments.com/airtime/api/restful/v2.0/Payment

Environment	v1.0 接口 URL
沙盒	https://sandbox.codapayments.com/airtime/api/restful/v1.0/Payment
正式	https://airtime.codapayments.com/airtime/api/restful/v1.0/Payment

接口地址

POST {Base URL}/inquiryPaymentResult.json

Codapay 的 API 支持 REST 接口服务，默认情况下，提供的端点均为 RESTful。

请求参数

参数	类型	描述
inquiryPaymentRequest	Object	必填 必须是有效的JSON对象
inquiryPaymentRequest.apiKey	String	必填 Coda提供的API密钥 - 请参考 Codapay 入门指南 了解如何获取。
inquiryPaymentRequest.txnId	Numeric	必填 您在发起支付后收集到的Coda订单ID
inquiryPaymentRequest.country	Numeric	*此字段仅适用于v2.0 API 可选 ISO 3166 国家代码 - 请参阅 国家和货币代码
inquiryPaymentRequest.projectId	String	*此字段仅适用于v2.0 API 必填 Coda提供的ProjectID，每个产品名称為独有- 请参考 Codapay 入门指南 了解如何获取。
inquiryPaymentRequest.needStatusFinal	String	可选 如果您希望在响应中获取指示此订单是否为最终状态，请将其设置为true。

响应参数

参数	类型	描述
paymentResult	Object	包含该接口的响应结果
paymentResult.resultCode	Numeric	ResultCode将帮助指示交易的状态。 ResultCode = 0 表示交易成功。 ResultCode = 431，481 或 216 表示交易待处理 所有其他ResultCode值表示交易失败。您可以在 常见错误代码 找到完整的错误代码及其解释。
paymentResult.txnId	String	从支付请求发起返回的Coda订单ID。
paymentResult.orderId	String	您在支付请求发起时传递的订单ID
paymentResult.country	Numeric	*此字段仅在 v2.0 API 版本中，根据特殊请求返回 ISO 3166 国家代码 - 请参阅 国家和货币代码
paymentResult.originAmount	Numeric	*此字段仅在 v2.0 API 版本中，根据特殊请求返回 在发起请求时提供的金额
paymentResult.originCurrency	String	*此字段仅在 v2.0 API 版本中，根据特殊请求返回 ISO 4217 字母代码（如 USD、IDR 等）。在发起请求时用于指定商品价格的货币。 OriginCurrency可能与PayCurrency不同。
paymentResult.payAmount	Numeric	*此字段仅在 v2.0 API 版本中，根据特殊请求返回 以PayCurrency为单位计费给用户的最终价格。 注意：TotalPrice始终等于PayAmount。
paymentResult.payCurrency	String	*此字段仅在 v2.0 API 版本中，根据特殊请求返回 ISO 4217字母代码（USD、IDR等）。用于实际支付并向用户收费的货币。
paymentResult.resultDesc	String	如果resultCode返回错误，则该值描述错误信息。
paymentResult.totalPrice	Numeric	用户为订单交易支付的总金额。此金额将始终以本地货币计算。
paymentResult.profile	Object	包含键值列表的对象。当前可以用于处理的具体键值如下所示。

Profile

参数	描述
PaymentType	用户选择的支付渠道。 PaymentType = 支付渠道ID，或者当支付渠道为运营商计费时，等于1
isStatusFinal	交易是否已达到最终状态的标志。 注意：失败的交易可能需要最多12小时才能反映其最终状态。
status	Possible values are: - "pending"（待处理） - "failed"（失败） - "success"（成功）

示例

v2.0 请求

    "inquiryPaymentRequest":
    {
        "apiKey" : "32774abe1cd7d8bae650ea48265e",
        "country" : 702 //此字段仅适用于 v2.0 API
        "projectId" : 21 //此字段仅适用于 v2.0 API
        "txnId" : "7144594637002072212",
        "needStatusFinal": "true"
    }
}

v2.0 响应

//Sample for non-USD payments initiated
{
    "paymentResult": {
        "orderId": 20230526063548,
        "originAmount": 15298, //此字段仅适用于 v2.0 API
        "originCurrency": IDR, //此字段仅适用于 v2.0 API
        "payAmount": 15298, //此字段仅适用于 v2.0 API
        "payCurrency": IDR, //此字段仅适用于 v2.0 API
        "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": 15298, //与 payAmount 相同
        "txnId": 7144594637002072212
    }
}

//Sample for USD payments initiated
{
    "paymentResult": {
        "orderId": 20230526063548,
        "originAmount": 1, //此字段仅适用于 v2.0 API
        "originCurrency": USD, //此字段仅适用于 v2.0 API
        "payAmount": 15298, //此字段仅适用于 v2.0 API
        "payCurrency": IDR, //此字段仅适用于 v2.0 API
        "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": 15298, //与 payAmount 相同
        "txnId": 7144594637002072212
    }
}

v1.0 请求

{
    "inquiryPaymentRequest":
    {
        "apiKey" : "32774abe1cd7d8bae650ea48265e",
        "txnId" : "7144594637002072212",
        "needStatusFinal": "true"
    }
}

v1.0 响应

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

税务处理 (仅支持美国市场)

当 isTaxInclusiveAmount 参数用于发起支付（Initiate Payment）接口时

此处显示的税务处理方式由发起支付时设置的 isTaxInclusiveAmount 参数决定。该参数用于定义您提交的商品价格应如何进行税务计算：

• isTaxInclusiveAmount: true

  • 商品总金额将被视为已包含税费。

  • 用户支付的金额不会发生变化。

  • subTotalPrice 将根据以下公式反向计算：

    subTotalPrice = itemTotal / (1 + payTaxRate / 100)

• isTaxInclusiveAmount: false（或未提供该参数）

  • 商品总金额将被视为未包含税费。

  • 系统会在商品金额基础上额外计算税费，因此：

    totalPrice = 商品总金额 + 税费

无论 isTaxInclusiveAmount 的值为何，接口返回的数据结构保持一致，只有 subTotalPrice、totalPrice 和 payAmount 的数值会有所不同。因此，调用方无需根据该参数判断如何解析响应。

可通过以下公式计算税额：

taxAmount = totalPrice − subTotalPrice

此功能仅适用于以下情况：

• Coda 为 MoR（Merchant of Record）

• 市场为 美国（US）

• 使用 v2.0 API

对于非美国市场或 Coda 非 MoR 的交易，subTotalPrice 和 payTaxRate 字段仍会返回，但 isTaxInclusiveAmount 参数不会产生任何影响。

---

字段说明

字段	isTaxInclusiveAmount: true	isTaxInclusiveAmount: false（或未提供）
subTotalPrice	itemTotal / (1 + payTaxRate / 100)	等于商品总金额（itemTotal）
totalPrice / payAmount	等于商品总金额（保持不变）	subTotalPrice + 税费
payTaxRate	实际适用税率	实际适用税率

---

响应示例

isTaxInclusiveAmount: true（商品总金额为 10.00，税率为 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 （商品总金额为 10.00，税率为 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
    }
}