查看交易状态

先决条件

在与 Codapay API 集成时，请确保遵守以下标准：

1. 请使用HTTPS协议。

2. TLS 1.2 或更高版本

请注意，Codapay API 有两个版本，请参阅Codapay API 版本了解更多详情。

参考

沙盒	https://sandbox.codapayments.com/airtime/api/restful/v2.0/Payment
生产	https://airtime.codapayments.com/airtime/api/restful/v2.0/Payment

端点

POST {基本 URL}/inquiryPaymentResult.json

Codapay 的 API 支持 REST Web 服务。默认情况下，显示的端点是 RESTful 的。

请求参数

inquiryPaymentRequest	Object	必填： 必须是有效的 JSON 对象
inquiryPaymentRequest.apiKey	String	必填：Coda 提供的API 密钥 - 请参阅入门指南了解如何获取该密钥。
inquiryPaymentRequest.txnId	Numeric	必填：个人资料条目的关键信息
inquiryPaymentRequest.country	Numeric	可选： ISO 3166 国家代码 - 请参阅国家和货币代码
inquiryPaymentRequest.projectId	String	*此字段仅在 v2.0 API 中需要 必填：Coda 提供的 项目 ID，每个标题产品都有唯一的项目 ID - 请参阅入门指南了解如何获取。
inquiryPaymentRequest.needStatusFinal	String	可选 true用于在响应中获取一个标志，指示这是否是交易的最终状态。

响应参数

*OriginAmount、OriginCurrency、PayAmount、PayCurrency：仅在 v2.0 API 中返回，且仅在特殊请求时返回。请联系您的技术支持客户经理了解更多详情。

paymentResult	Object	包含发起请求的结果
paymentResult.resultCode	Numeric	结果代码将有助于指示交易状态。 ResultCode = 0表示交易成功。 ResultCode = 431或者216表示交易正在处理中。 所有其他 ResultCode 值均表示交易失败。您可以在此处找到完整的错误代码列表及其说明。
paymentResult.txnId	String	发起请求的交易 ID
paymentResult.orderId	String	您在发起付款请求时提供的订单 ID
*paymentResult.originAmount	Numeric	*此字段仅在特殊请求下通过 v2.0 API 返回。 浮点数。原始金额，以发起请求中提供的原始货币表示。
*paymentResult.originCurrency	String	*此字段仅在 v2.0 API 中根据特殊请求返回。ISO 4217 字母代码（USD、IDR 等）。用于在发起请求中指定商品价格的原始货币。
*paymentResult.payAmount	Numeric	*此字段仅在特殊请求下通过 v2.0 API 返回。 浮点数。以支付货币形式向用户收取的最终价格。注意：总价始终等于支付金额。
*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	可能的值有：-“待处理”-“失败”-“成功”

示例

请求

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

回复

//Sample for non-USD payments initiated
{
    "paymentResult": {
        "orderId": 20230526063548,
        "originAmount": 15298,
        "originCurrency": IDR,
        "payAmount": 15298,
        "payCurrency": IDR,
        "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, //Always the same as payAmount
        "txnId": 7144594637002072212
    }
}

//Sample for USD payments initiated
{
    "paymentResult": {
        "orderId": 20230526063548,
        "originAmount": 1, //This field is only returned in v2.0 API
        "originCurrency": USD, //This field is only returned in v2.0 API
        "payAmount": 15298, //This field is only returned in v2.0 API
        "payCurrency": IDR, //This field is only returned in v2.0 API
        "profile": {
            "entry": [
                {
                    "key": "PaymentType",
                    "value": 236
                },
                {
                    "key": "isStatusFinal",
                    "value": true
                },
                {
                    "key": "status",
                    "value": "failed"
                }
            ]
        },
        "resultCode": 213,

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

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