交易查询

用于主动查询某笔支付订单的当前状态。

请求说明

• 方法：POST
• 路径：/api/v1/payin/payment/orderQuery
• Content-Type：application/json
• 鉴权：参考 接入准备 中参数以及签名算法说明，按照要求携带必须的鉴权信息

请求字段（Request Body）

参数名	类型	必填	说明
paymentId	string	否	Velora 平台支付单号，即支付结果通知中返回的 paymentId
merchantOrderId	string	否	商户订单号（创建交易时传入的 merchantOrderId）

paymentId 与 merchantOrderId 二选一即可发起查询。

请求示例

{
  "paymentId": "payin_20260331145719282948882"
}

或

{
  "merchantOrderId": "M202512180001"
}

响应参数

响应体为统一结构：result 表示支付结果，data 表示订单数据。

result 对象

字段	类型	说明
code	string	返回码（成功/失败标识）
msg	string	返回信息说明

data 对象

字段	类型	长度 / 限制	必返	说明
paymentId	string	/	是	Velora 平台支付单号
merchantOrderId	string	/	否	商户订单号
psp	string	/	否	实际承接订单的 PSP 标识
channelOrderId	string	/	否	PSP / 渠道侧订单号
channelMerchantOrderId	string	/	否	PSP / 渠道侧商户订单号
status	string	/	是	当前支付状态，详见 订单状态说明
amount	object	/	否	金额，见下表
paymentMethod	object	/	否	支付方式，见下表
createdAt	string	/	否	创建时间
updatedAt	string	/	否	更新时间

data.amount 对象

字段	类型	长度 / 限制	必返	说明
value	string	/	是（随 amount 出现）	金额（字符串格式，如 "29.00"）
currency	string	/	是（随 amount 出现）	币种

data.paymentMethod 对象

字段	类型	长度 / 限制	必返	说明
type	string	/	否	支付方式类型
paymentBrand	string	/	否	支付品牌

响应示例

{
  "result": {
    "code": "S0000",
    "msg": "Payment query successfully"
  },
  "data": {
    "paymentId": "payin_20260331145719282948882",
    "merchantOrderId": "ORDER_20260331_145711_1LOQON",
    "psp": "gcash_partner",
    "channelOrderId": "GCASH20260331145719282948882",
    "channelMerchantOrderId": "ORDER_20260331_145711_1LOQON",
    "status": "Success",
    "amount": {
      "value": "29.00",
      "currency": "PHP"
    },
    "paymentMethod": {
      "type": "e-wallet",
      "paymentBrand": "gcash"
    },
    "createdAt": "2026-03-31T14:57:19+08:00",
    "updatedAt": "2026-03-31T15:00:12+08:00"
  }
}

加密货币查询返回结构说明

加密货币收款场景下，交易查询的返回结构与普通支付相比，主要区别在于 paymentMethod 中会额外返回 crypto 对象，用于描述链上交易信息。

data.paymentMethod.crypto 对象

字段	类型	必返	说明
chain	string	是	链类型，如 ETH、BSC、TRON
fromAddress	string	是	用户发起转账的钱包地址
toAddress	string	是	商户收款钱包地址
logIndex	string	是	链上事件日志索引
txHash	string	是	链上交易哈希

加密货币查询响应示例

提示：商户不需要严格使用该查询返回的全部字段数据，可以基于 crypto 字段的 JSON 结构实现自身通用业务信息处理。

{
  "result": {
    "code": "S0000",
    "msg": "Payment query successfully"
  },
  "data": {
    "psp": "cryptopay",
    "status": "Success",
    "paymentId": "payin_20260528104200903337225",
    "channelOrderId": "0xd9ca31dd9f6f12077fd3525acb6706de610ae0c2c30315300e51f74f0cbd91b6_0",
    "channelMerchantOrderId": "0xd9ca31dd9f6f12077fd3525acb6706de610ae0c2c30315300e51f74f0cbd91b6_0",
    "merchantOrderId": "0xd9ca31dd9f6f12077fd3525acb6706de610ae0c2c30315300e51f74f0cbd91b6",
    "amount": {
      "value": "1.36000",
      "currency": "USDT"
    },
    "paymentMethod": {
      "type": "crypto",
      "paymentBrand": "BSC",
      "crypto": {
        "chain": "BSC",
        "fromAddress": "0x38c9e15b7a28038f74290187e2747954ee507411",
        "toAddress": "0x8be0f2577b0018844ff19b675f387cc36605f1b7",
        "logIndex": "0",
        "txHash": "0xd9ca31dd9f6f12077fd3525acb6706de610ae0c2c30315300e51f74f0cbd91b6"
      }
    },
    "createdAt": "2026-05-28T10:42:00+08:00",
    "updatedAt": "2026-05-28T10:42:00+08:00"
  }
}

相关链接

• 订单状态说明：各状态含义及出现场景
• 创建交易：发起支付
• 支付结果通知：异步通知与验签