接入说明

  • 用户订单主要提供调用方两种请求接口的形式，分别为：

    • 查询用户在自身业务下支付订单流水：业务主动请求接口，返回该业务场景下用户的所有订单列表。仅支持其查询自身业务 bid 下的订单情况，不能查询其他非自身接入业务的订单情况。
    • 查询用户在指定业务下支付订单流水(特殊情况，经产品运营审核确认的团队使用)：平台业务主动请求接口，返回指定业务场景下（非自身业务）用户的所有订单列表。支持查询其传入的所有业务bid的订单情况，需公益产品运营进行审核确认。

  • 用户订单内容

    • 以列表的方式返回订单信息，信息包括如下：
      • 订单号
      • 金额，单位：分
      • 支付时间，RFC3339标准格式. eg:2023-11-30T16:27:42+08:00
      • 支付状态
      • 业务类型
      • 业务id
      • 业务订单号

  • 接入准备：

    • 接入方需要提供微信开放平台的AppID和负责人（用于申请互转权限时作为审批人），或者QQ互联的AppID，由公益侧提交互转权限的申请，微信/QQ审批通过后，才能使用。注意：如果是微信游戏，则需要通过微信帐号托管平台做接入，参考微信游戏帐号托管
    • 接口使用签名方式，如何生成签名以及用户信息的传递参考接口调用凭证
    • 以上方式涉及业务侧帐号与公益帐号的转换，需要满足以下条件：
      • 腾讯内部已开通帐号互转权限的业务（仅限微信或QQ帐号体系）
      • 外部已开通帐号互转权限的业务（仅限QQ帐号体系）

用户订单字段说明

数据格式： json回包

支持字段： 如下表所示

字段名 类型 含义 举例
transcode string 订单号 e.g. 1465188602202211011900000125
pid string 项目id e.g. 237449
money int 金额，单位：分 e.g. 100
trans_time string 支付时间，RFC3339标准格式 e.g. 2023-11-30T16:27:42+08:00
trans_state int 支付状态，11表示支付成功 e.g. 11
bt string 业务类型 e.g. WXDM, AXC
bid string 业务id e.g. 100000224
busi_code string 业务订单号 e.g. 7495
appid string 业务分配的appid e.g. gy_cd8b1ahcvmfgjk48hem0
proj_name string 项目名称 e.g. 为乡村孩子修图书角

接口协议

查询用户在自身业务下订单流水

使用场景： 用于腾讯公益合作的业务请求获取用户自身业务下的订单流水，正常情况场景下，根据接入方来源，只允许查询自身业务bid下的订单情况

调用凭证： 应用签名

请求地址： https://oapi.gongyi.qq.com/api/user_trans_query/GetUserOrderRecordByBid

请求方式： POST（HTTPS）

需要在header中带上业务所需的bid

参数 必填 说明
Gy-H-Request-Bid 是 业务ID

请求参数：

参数 类型 必填 说明
page int 是 分页数，取值范围 [1,10000]
count int 否 单页返回订单条数， 默认值10，取值范围 [1,30]
  • 请求示例
    {
  "page": 1, 
  "count": 5
}

返回参数：

参数 类型 说明
code int 返回码：0表示成功，其他值表示错误，请参考错误码说明
msg string 错误信息
data object 返回数据
data.order_record order_record 用户订单列表

返回示例：

{
  "code": 0,
  "data": {
    "order_record": [{
        "transcode": "1465188602202211011900000125",
        "pid": "237449",
        "money": 100,
        "trans_time": "2023-11-30T16:27:42+08:00",
        "trans_state": 11,
        "bt": "WXDM",
        "bid": "100000224",
        "busi_code": "7495"
      }, 
      {
        "transcode": "1465188602202211011900000304",
        "pid": "232349",
        "money": 2000,
        "trans_time": "2024-01-30T16:27:42+08:00",
        "trans_state": 11,
        "bt": "AXC",
        "bid": "100000224",
        "busi_code": "74355"
      }
    ]
  },
  "msg": "",
  "op_time": 1695028171,
  "trace_id": "41ec2010a17242c08a0208c5b040afb6"
}

查询用户在指定业务下订单流水

使用场景： 用于腾讯公益合作的特殊业务平台请求获取用户指定业务下的订单流水，在这种特殊情况场景下，经公益产品运营审核确认，才可支持查询其传入的所有业务bid的订单情况

调用凭证： 应用签名

请求方式： POST（HTTPS）

请求地址： https://oapi.gongyi.qq.com/api/user_trans_query/GetUserOrderRecordByMultiBid

请求参数：

参数 类型 必填 说明
page int 是 分页数，取值范围 [1,10000]
count int 否 单页返回订单条数， 默认值10，取值范围 [1,30]
bid string 是 传入查询指定的业务bid（传入的bid，都需要找产品配置调用权限审批，审批通过才能调用成功）
  • 请求示例
    {
"page": 1,
"count": 5,
"bid": "100000783"
}

返回参数：

参数 类型 说明
code int 返回码：0表示成功，其他值表示错误，请参考错误码说明
msg string 错误信息
data object 返回数据
data.order_record order_record 用户订单列表

返回示例：

{
  "code": 0,
  "data": {
    "order_record": [{
        "transcode": "1465188602202211011900000125",
        "pid": "237449",
        "money": 100,
        "trans_time": "2023-11-30T16:27:42+08:00",
        "trans_state": 11,
        "bt": "WXDM",
        "bid": "100000783",
        "busi_code": "7495"
      },
      {
        "transcode": "1465188602202211011900000304",
        "pid": "232349",
        "money": 2000,
        "trans_time": "2024-01-30T16:27:42+08:00",
        "trans_state": 11,
        "bt": "AXC",
        "bid": "100000783",
        "busi_code": "74355"
      }
    ]
  },
  "msg": "",
  "op_time": 1695029052,
  "trace_id": "5e7218f8a00f278c2071777b408f09cd"
}

查询用户在指定业务下累计捐款金额（新鉴权接口）

使用场景： 用于腾讯公益合作的特殊业务平台请求获取用户指定业务下的累计捐款金额

调用凭证： 应用签名

请求方式： POST（HTTPS）

需要在header中带上授权业务appid列表

参数 必填 说明
Gy-H-Api-Appids 是 授权业务appid列表

请求地址： https://oapi.gongyi.qq.com/api/user_trans_query/GetUserDonateMoneyByMultiAppid

请求参数：

参数 类型 必填 说明
start_time string 否 查询开始时间(与结束时间参数成对出现，规则左闭右开)
end_time string 否 查询结束时间(与开始时间参数成对出现，规则左闭右开)
  • 请求示例
    {
"start_time": "2023-09-17 00:00:00",
"end_time": "2023-09-18 00:00:00"
}

返回参数：

参数 类型 说明
code int 返回码：0表示成功，其他值表示错误，请参考错误码说明
msg string 错误信息
data object 返回数据
total_donate_money int 累计的捐款金额（单位：分）

返回示例：

{
  "code": 0,
  "data": {
    "total_donate_money": 356000
  },
  "msg": "",
  "op_time": 1695029052,
  "trace_id": "5e7218f8a00f278c2071777b408f09cd"
}

查询用户在指定业务下订单流水（新鉴权接口）

使用场景： 用于腾讯公益合作的特殊业务平台请求获取用户指定业务下的订单流水

调用凭证： 应用签名

请求方式： POST（HTTPS）

需要在header中带上授权业务appid列表

参数 必填 说明
Gy-H-Api-Appids 是 授权业务appid列表

请求地址： https://oapi.gongyi.qq.com/api/user_trans_query/GetUserOrderRecordByMultiAppid

请求参数：

参数 类型 必填 说明
start_time string 否 查询开始时间(与结束时间参数成对出现，规则左闭右开)
end_time string 否 查询结束时间(与开始时间参数成对出现，规则左闭右开)
page int 是 分页数，取值范围 [1,10000]
count int 否 单页返回订单条数， 默认值10，取值范围 [1,30]
proj_info bool 否 是否需要返回项目信息，默认不填为false，不返回项目信息
time_ascending bool 否 是否按照时间升序排列输出，默认不填为false，即倒序排列，反之正序排列
  • 请求示例
    {
"start_time": "2023-09-17 00:00:00",
"end_time": "2023-09-18 00:00:00",
"page": 1,
"count": 5,
"proj_info": true,
"time_ascending": true
}

返回参数：

参数 类型 说明
code int 返回码：0表示成功，其他值表示错误，请参考错误码说明
msg string 错误信息
data object 返回数据
record_total int 记录总条数
data.order_record order_record 用户订单列表

返回示例：

{
  "code": 0,
  "data": {
    "record_total": 2,
    "order_record": [{
        "transcode": "1465188602202211011900000125",
        "pid": "237449",
        "money": 100,
        "trans_time": "2023-11-30T16:27:42+08:00",
        "trans_state": 11,
        "bt": "WXDM",
        "busi_code": "7495",
        "appid": "gy_cd8b1ahcvmfgjk48hem0",
        "proj_info": "为乡村孩子修图书角"
      },
      {
        "transcode": "1465188602202211011900000304",
        "pid": "232349",
        "money": 2000,
        "trans_time": "2024-01-30T16:27:42+08:00",
        "trans_state": 11,
        "bt": "AXC",
        "busi_code": "74355",
        "appid": "gy_cd8b1ahcvmfgjk48hem0",
        "proj_info": "为乡村孩子修图书角"
      }
    ]
  },
  "msg": "",
  "op_time": 1695029052,
  "trace_id": "5e7218f8a00f278c2071777b408f09cd"
}

查询用户在指定业务下参与捐款项目列表（新鉴权接口）

使用场景： 用于腾讯公益合作的特殊业务平台请求获取用户指定业务下参与捐款项目列表

调用凭证： 应用签名

请求方式： POST（HTTPS）

需要在header中带上授权业务appid列表

参数 必填 说明
Gy-H-Api-Appids 是 授权业务appid列表

请求地址： https://oapi.gongyi.qq.com/api/user_trans_query/GetUserProjListByMultiAppid

请求参数：

参数 类型 必填 说明
start_time string 否 查询开始时间(与结束时间参数成对出现，规则左闭右开)
end_time string 否 查询结束时间(与开始时间参数成对出现，规则左闭右开)
page int 是 分页数，取值范围 [1,10000]
count int 否 单页返回订单条数， 默认值10，取值范围 [1,30]
proj_info bool 否 是否需要返回项目信息，默认不填为false，不返回项目信息
time_ascending bool 否 是否按照时间升序排列输出，默认不填为false，即倒序排列，反之正序排列
  • 请求示例
    {
"start_time": "2023-09-17 00:00:00",
"end_time": "2023-09-18 00:00:00",
"page": 1,
"count": 5,
"proj_info": true,
"time_ascending": true
}

返回参数：

参数 类型 说明
code int 返回码：0表示成功，其他值表示错误，请参考错误码说明
msg string 错误信息
data object 返回数据
list_total int 项目列表总条数
data.proj_list proj_list 项目列表

返回示例：

{
  "code": 0,
  "data": {
    "list_total": 2,
    "proj_list": [{
        "appid": "gy_cd8b1ahcvmfgjk48hem0",
        "pid": "237449",
        "proj_info": "为乡村孩子修图书角",
        "proj_image": "",
        "last_time": "2023-11-30T16:27:42+08:00"
      },
      {
        "appid": "gy_cd8b1ahcvmfgjk48hem0",
        "pid": "237450",
        "proj_info": "为乡村孩子捐赠书桌",
        "proj_image": "",
        "last_time": "2024-01-30T16:27:42+08:00"
      }
    ]
  },
  "msg": "",
  "op_time": 1695029052,
  "trace_id": "5e7218f8a00f278c2071777b408f09cd"
}

查询用户在指定机构下项目维度的捐款统计信息

使用场景： 用于腾讯公益合作业务平台请求获取用户指定机构下项目维度参与的捐款统计信息

调用凭证： 应用签名

请求方式： POST（HTTPS）

请求地址： https://oapi.gongyi.qq.com/api/user_trans_query/GetUserProjTransStatByOrgId

请求参数：

参数 类型 必填 说明
page int 否 分页数，默认值1，取值范围 [1,10000]
count int 否 单页返回条数， 默认值10，取值范围 [1,30]
proj_info bool 否 是否需要返回项目信息，默认不填为false，不返回项目信息
sort_state SortState 否 返回统计列表的排序状态，按照支付时间进行排序，仅支持预定义的取值范围 [0,2]。0-默认不排序，1-降序，2-升序
  • 请求示例
    {
"page": 1,
"count": 10,
"proj_info": true,
"sort_state": 1
}

返回参数：

参数 类型 说明
code int 返回码：0表示成功，其他值表示错误，请参考错误码说明
msg string 错误信息
data object 返回数据
list_total int 统计列表总条数
data.proj_trans_stat proj_trans_stat 项目维度统计信息
data.proj_trans_stat.pid string 项目id
data.proj_trans_stat.sum_money int 捐款总金额
data.proj_trans_stat.sum_times int 捐款总笔数
data.proj_trans_stat.proj_info proj_info 项目信息
data.proj_trans_stat.proj_info.proj_name string 项目名称
data.proj_trans_stat.proj_info.proj_image string 项目头图
data.proj_trans_stat.month_sum_money int 月捐总金额
data.proj_trans_stat.month_sum_times int 月捐总次数
data.proj_trans_stat.once_sum_money int 次捐总金额
data.proj_trans_stat.once_sum_times int 次捐总次数
data.proj_trans_stat.month_info string 月捐信息, json格式返回。包括：
month_status—项目下的月捐开通状态(0:未开通, 1:已开通, 2:开通后取消(有月捐状态记录且有关闭时间))

返回示例：

{
  "code": 0,
  "data": {
    "list_total": 2,
    "proj_trans_stat": [{
        "pid": "224328",
        "proj_info": {
          "proj_image": "https://test-orgcdn.gongyi.qq.com/orgv2/imgcdn/gongyi/6a335576a1d92cb01c2187607d43c7c9df74784d731374d7ce4312fb1903642acaf7c90553c5ce61.png",
          "proj_name": "枫叶定向加倍金"
        },
        "sum_money": 39,
        "sum_times": 5,
        "month_sum_money": 20,
        "month_sum_times": 2,
        "once_sum_money": 19,
        "once_sum_times": 3,
        "month_info": "{\"month_status\": 1}"
      },
      {
        "pid": "50000649",
        "proj_info": {
          "proj_image": "https://test-orgcdn.gongyi.qq.com/login_1718094665853/d9390b8a19ea88260156b0bb6d911254.png",
          "proj_name": "为乡村孩子修图书角"
        },
        "sum_money": 100,
        "sum_times": 2,
        "month_sum_money": 0,
        "month_sum_times": 0,
        "once_sum_money": 100,
        "once_sum_times": 2,
        "month_info": "{\"month_status\": 0}"
      }
    ]
  },
  "msg": "",
  "op_time": 1695029052,
  "trace_id": "5e7218f8a00f278c2071777b408f09cd"
}

错误码

错误码 名称 含义
31630001 ErrUTQParamValidate 传入参数校验失败
31630002 ErrUTQGetUserOrderRecordByBid 获取自身业务用户订单记录失败
31630003 ErrUTQAuthcheckReqBid 授权认证请求参数Bid失败
31630004 ErrUTQGetUserOrderRecordByMultiBid 获取指定业务用户订单失败
31630005 ErrUTQGetUserDonateMoneyByMultiBid 获取指定业务用户累计捐款金额失败
31630006 ErrUTQGetUserProjListByMultiBid 获取指定业务用户参与项目列表失败
31630007 ErrUTQAuthBidsEmpty 业务下所有授权的bids为空
© 1998 - 2022 Tencent Inc. all right reserved，powered by tencent.更新时间： 2025-03-06 17:00:45

results matching ""

    No results matching ""

    results matching ""

      No results matching ""