腾讯出行服务·开放平台

# 微信直连支付代理

基础字段参数说明见: index.md

统一前缀：/open/v1/ 完整的Path:/open/v1/generalpay/unifiedorder

# 8.1 微信支付下单

  • 接口说明 本接口用于微信支付下单，业务侧发起支付时调用，返回微信支付参数。
  • 请求地址 /openpay/unifiedorder
  • 请求方式 POST
  • 请求参数 通用参数 + 业务参数
参数名称 类型 最大长度 必选 说明
user_code string 32 是 用户标识(同插件跳转的 openId 参数、车机小程序的openId)
app_id string 32 否 同插件跳转的 appId 参数(下单小程序的微信appId，小程序支付必填)
biz_order_id string 32 是 业务订单ID
user_id string 32 否 用户出行的用户userId
total_fee int 11 是 订单支付金额,单位分
description string 100 是 商品描述
client_ip string 45 是 用户的客户端IP，IPv4格式IP地址
trade_type int 11 是 交易类型 1:标识小程序支付，2:标识native支付
pay_channel int 11 是 来源渠道 1:小程序，2:车机
scense string 32 否 场景值，扩展用
wecar_id string 32 否 腾讯车联wecarId
expired_time long 20 是 订单过期时间，毫秒
goods_tag string 32 否 订单优惠标记，(微信代金券场景)
profit_sharing int 11 是 是否指定分账，枚举值1:分账，0:不分账
  • 返回数据
参数名称 类型 最大长度 必选 说明
code int 11 是 服务响应状态，参见错误码表
message string 64 是 服务响应状态说明，参见错误码表
data object - 否 -
data.trade_no string 32 否 交易订单号
  • 请求数据示例
{
  "api_key":"7ec26deb685c40249ffd",
  "seq_id":"136164a8-8939-437c-8fe3-1264c7ef488d",
  "timestamp":1633005812,
  "nonce":"157234207",
  "sign":"54C17EB339CE13E3A8D434EEE744225B",
  "scense":"scense",
  "user_code":"ou8xs5ftxmNOC9VzJf17xnXaoEkI",
  "app_id":"wx65cc950f42e8fff1",
  "biz_order_id":"1000000102",
  "user_id":"144802",
  "total_fee":10,
  "description":"C1111101",
  "client_ip":"111.206.145.56",
  "expired_time":1633004121000,
  "trade_type":2,
  "goods_tag":"",
  "profit_sharing":0,
  "pay_channel":2
}
  • 返回数据示例
{
  "code": 0,
  "message": "successful"
  "data":{
      "trade_no":""
  }
}

# 8.2 查询支付订单信息

  • 接口说明 本接口用于查询支付订单信息
  • 请求地址 /generalpay/orderquery
  • 请求方式 POST
  • 请求参数 通用参数 + 业务参数
参数名称 类型 最大长度 必选 说明
user_code string 32 是 用户标识(同插件跳转的 openId 参数、车机小程序的openId)
app_id string 32 否 同插件跳转的 appId 参数(下单小程序的微信appId，小程序支付必填)
biz_order_id string 32 是 业务订单ID
user_id string 32 否 用户出行的用户userId
pay_channel int 11 是 来源渠道 1:小程序，2:车机
  • 返回数据
参数名称 类型 最大长度 必选 说明
code int 11 是 服务响应状态，参见错误码表
message string 64 是 服务响应状态说明，参见错误码表
data object - 否 -
data.trade_status int 11 否 支付状态
data.trade_type int 11 否 交易类型， 1:标识小程序支付，2:标识native支付
data.total_fee int 11 否 订单总金额，单位为分
data.biz_order_id string 32 否 业务侧订单id
data.trade_no string 32 否 交易侧订单id
data.transaction_id string 64 否 微信支付订单号
data.cash_fee int 11 否 现金支付金额订单现金支付金额
data.payed_time long 20 否 订单支付时间,单位毫秒
data.trade_state_desc string 256 否 对当前查询订单状态的描述和下一步操作的指引
data.coupon_fee int 11 否 “代金券”金额<=订单金额，订单金额-“代金券”金额=现金支付金额，
data.coupon_info array - 否 代金券信息
data.coupon_info.coupon_type string - 否 CASH：充值代金券NO_CASH：非充值优惠券
data.coupon_info.coupon_id string 20 否 代金券ID
data.coupon_info.coupon_fee int 11 否 代金券支付金额
 trade_status说明:
    PS_DEFAULT=0,//默认
    PS_SUCCESS=1,//支付成功
    PS_REFUND=2,//转入退款
    PS_NOTPAY=3,//未支付
    PS_CLOSED=4,//已关闭
    PS_REVOKED=5,//已撤销（付款码支付）
    PS_USERPAYING=6,//用户支付中（付款码支付）
    PS_PAYERROR=7,//支付失败
    PS_ACCEPT=8,//已接收，等待扣款
  • 请求数据示例
{
    "api_key":"7ec26deb685c40249ffd",
    "seq_id":"136164a8-8939-437c-8fe3-1264c7ef488d",
    "timestamp":1633245377,
    "nonce":"157234207",
    "sign":"6C9AE8972E55B1341D94167843629A11",
    "user_code":"ou8xs5ftxmNOC9VzJf17xnXaoEkI",
    "app_id":"wx65cc950f42e8fff1",
    "biz_order_id":"1000000101",
    "user_id":"144802",
    "pay_channel":1
}
  • 返回数据示例
{
  "code": 0,
  "message": "successful"
  "data":{ 
    "cash_fee": 1400, 
    "coupon_fee": 0,  
    "biz_order_id": "854309568367386632",
    "trade_status": 1,
    "payed_time": 1623727067000,
    "total_fee": 1400,
    "trade_state_desc": "支付成功",
    "trade_type": 1,
    "transactionId": "4200001228202106155230856416",
    "vCouponInfo": [
        {
            "coupon_fee": 3000,
            "coupon_id": "24498233520",
            "coupon_type": "NO_CASH"
        }
    ]
}
}

# 8.3 关闭订单

  • 接口说明 以下情况需要调用关单接口：商户订单支付失败需要生成新单号重新发起支付，要对原订单号调用关单，避免重复支付；系统下单后，用户支付超时，系统退出不再受理，避免用户继续，请调用关单接口。

注意：订单生成后不能马上调用关单接口，最短调用时间间隔为5分钟。

  • 请求地址 /generalpay/closeorder
  • 请求方式 POST
  • 请求参数 通用参数 + 业务参数
参数名称 类型 最大长度 必选 说明
user_code string 32 是 用户标识(同插件跳转的 openId 参数、车机小程序的openId)
app_id string 32 否 同插件跳转的 appId 参数(下单小程序的微信appId，小程序支付必填)
biz_order_id string 32 是 业务订单ID
user_id string 32 否 用户出行的用户userId
pay_channel int 11 是 来源渠道 1:小程序，2:车机
reason string 50 是 关闭原因
  • 返回数据
参数名称 类型 最大长度 必选 说明
code int 11 是 服务响应状态，参见错误码表
message string 64 是 服务响应状态说明，参见错误码表
data object - 否 -
  • 请求数据示例
{
    "api_key":"7ec26deb685c40249ffd",
    "seq_id":"136164a8-8939-437c-8fe3-1264c7ef488d",
    "timestamp":1633010512,
    "nonce":"157234207",
    "sign":"E5687D9056264437C4B77273B4A0E010",
    "user_code":"ou8xs5ftxmNOC9VzJf17xnXaoEkI",
    "app_id":"wx65cc950f42e8fff1",
    "biz_order_id":"1000000101",
    "user_id":"144802",
    "pay_channel":1,
    "reason":"test"
}
  • 返回数据示例
{
  "code": 0,
  "message": "successful"
}

# 8.4 申请退款

  • 接口说明 当交易发生之后一段时间内，由于买家或者卖家的原因需要退款时，卖家可以通过退款接口将支付款退还给买家，微信支付将在收到退款请求并且验证成功之后，按照退款规则将支付款按原路退到买家账号上。 1、交易时间超过一年的订单无法提交退款 2、微信支付退款支持单笔交易分多次退款，多次退款需要提交原支付订单的商户订单号和设置不同的退款单号。申请退款总金额不能超过订单金额。 一笔退款失败后重新提交，请不要更换退款单号，请使用原商户退款单号
  • 请求地址 /generalpay/refund
  • 请求方式 POST
  • 请求参数 通用参数 + 业务参数
参数名称 类型 最大长度 必选 说明
user_code string 32 是 用户标识(同插件跳转的 openId 参数、车机小程序的openId)
app_id string 32 否 同插件跳转的 appId 参数(下单小程序的微信appId，小程序支付必填)
biz_order_id string 32 是 业务订单ID
user_id string 32 否 用户出行的用户userId
pay_channel int 11 是 来源渠道 1:小程序，2:车机
biz_order_id string 32 否 业务侧订单id
trade_no string 32 否 交易侧订单id
biz_refund_id string 64 是 商户系统内部的退款单号，商户系统内部唯一,同一退款单号多次请求只退一笔。
total_fee int 11 是 订单金额
refund_fee int 11 是 申请退款金额，单位为分
refund_desc string 100 是 退款原因
client_ip string 45 是 用户的客户端IP，IPv4格式IP地址
  • 返回数据
参数名称 类型 最大长度 必选 说明
code int 11 是 服务响应状态，参见错误码表
message string 64 是 服务响应状态说明，参见错误码表
data object - 否 -
data.trade_no string 32 否 交易侧订单id
data.refund_id string 32 否 微信退款单号
data.refund_no string 32 否 交易侧退款单号
  • 请求数据示例
{
  "api_key": "PSUBZLHOKUO6HV52A5CAUSSE5KSB6Y",
  "seq_id": "38d42bd9-9f5a-415e-89d9-ea4ff9cffdf2",
  "timestamp": "1572342076",
  "nonce": "157234207",
  "sign": "8A983278E5366EB93FEB0D4143E1C522",
  "user_code": "udxbxd",
  "biz_order_id": "193839494",
  "transaction_id": "2",
  "refund_no": "2",
  "total_fee": 2,
  "refund_fee": 2,
  "refund_desc": "退款原因",
}
  • 返回数据示例
{
  "code": 0,
  "message": "successful",
  "data": {
      "refund_id","50301108462021061509759819015"
  }
}

# 8.5查询退款

  • 接口说明 提交退款申请后，通过调用该接口查询退款状态。退款有一定延时，用零钱支付的退款20分钟内到账，银行卡支付的退款3个工作日后重新查询退款状态。

注意：如果单个支付订单部分退款次数超过20次请使用退款单号查询

  • 请求地址 /generalpay/refundquery
  • 请求方式 POST
  • 请求参数 通用参数 + 业务参数
参数名称 类型 最大长度 必选 说明
user_code string 32 是 用户标识(同插件跳转的 openId 参数、车机小程序的openId)
app_id string 32 否 同插件跳转的 appId 参数(下单小程序的微信appId，小程序支付必填)
biz_order_id string 32 是 业务订单ID
user_id string 32 否 用户出行的用户userId
pay_channel int 11 是 来源渠道 1:小程序，2:车机
trade_no string 32 否 交易侧订单id
biz_refund_id string 64 是 商户系统内部的退款单号，商户系统内部唯一,同一退款单号多次请求只退一笔。
refund_no string 64 是 交易侧退款单号
  • 返回数据
参数名称 类型 最大长度 必选 说明
code int 11 是 服务响应状态，参见错误码表
message string 64 是 服务响应状态说明，参见错误码表
data object - 否 -
data.refund_status int 11 否 退款状态
data.biz_order_id string 32 否 商户侧订单id
data.transaction_id string 32 否 微信支付订单号
data.total_fee int 11 否 订单总金额，单位为分
data.cash_fee int 11 否 现金支付金额，单位为分
data.refund_fee int 11 否 申请退款金额，单位分
data.settlement_refund_fee int 11 否 退款金额=申请退款金额-非充值代金券退款金额，退款金额<=申请退款金额
data.refunded_time long 20 否 订单退款完成时间,单位毫秒
data.refund_account string 30 否 退款资金来源
data.refund_recv_accout string 64 否 退款入账账户
data.coupon_info Array - 否 代金券信息
data.coupon_info.coupon_type string - 否 CASH：充值代金券、NO_CASH：非充值优惠券
data.coupon_info.coupon_id string 20 否 代金券ID
data.coupon_info.coupon_fee int 11 否 代金券支付金额
 退款状态
        RS_DEFAULT=0,//默认
        RS_SUCCESS=1,//退款成功
        RS_REFUNDCLOSE=2,//退款关闭
        RS_PROCESSING=3,//退款处理中
        RS_CHANGE=4//退款异常

 退款资金来源
REFUND_SOURCE_RECHARGE_FUNDS---可用余额退款/基本账户
REFUND_SOURCE_UNSETTLED_FUNDS---未结算资金退款
  • 请求数据示例
{
  "api_key": "PSUBZLHOKUO6HV52A5CAUSSE5KSB6Y",
  "seq_id": "38d42bd9-9f5a-415e-89d9-ea4ff9cffdf2",
  "timestamp": "1572342076",
  "nonce": "157234207",
  "sign": "8A983278E5366EB93FEB0D4143E1C522",
  "user_code": "udxbxd",
  "biz_order_id": "193839494",
  "refund_no": "2",
  "refund_id": "2"
}
  • 返回数据示例
{
  "code": 0,
  "message": "successful",
  "data":{

  }
}

# 8.6 支付成功通知

  • 接口说明 通过支付通知接口将用户支付成功消息通知给商户

  • 请求地址 接入商提供

  • 请求方式 POST

  • 请求参数 通用参数 + 业务参数

参数名称 类型 最大长度 必选 说明
biz_order_id string 32 是 业务订单ID
trade_no string 32 否 交易侧订单id
transaction_id string 32 是 微信支付订单号
trade_type int 11 是 交易类型
trade_state int 11 是 交易状态
trade_state_desc string 256 是 交易状态描述
bank_type string 16 是 银行类型
payed_time long 20 是 支付完成时间
total int 11 是 总金额
payer_total int 11 是 用户支付金额
  • 返回数据
参数名称 类型 最大长度 必选 说明
code int 11 是 服务响应状态，参见错误码表
message string 64 是 服务响应状态说明，参见错误码表
data object - 否 -
  • 请求数据示例
{
  "api_key": "PSUBZLHOKUO6HV52A5CAUSSE5KSB6Y",
  "seq_id": "38d42bd9-9f5a-415e-89d9-ea4ff9cffdf2",
  "timestamp": "1572342076",
  "nonce": "157234207",
  "sign": "8A983278E5366EB93FEB0D4143E1C522",
  "user_code": "udxbxd",
  "biz_order_id": "193839494",
  "refund_no": "2",
  "refund_id": "2"
}
  • 返回数据示例
{
  "code": 0,
  "message": "successful",
  "data":{

  }
}

# 8.7 退款成功通知

  • 接口说明 退款状态改变后，微信会把相关退款结果发送给商户

  • 请求地址 接入商提供

  • 请求方式 POST

  • 请求参数 通用参数 + 业务参数

参数名称 类型 最大长度 必选 说明
biz_order_id string 32 是 业务订单ID
trade_no string 32 否 交易侧订单id
biz_refund_id string 64 是 微信支付退款单号
refund_id string 32 是 微信退款单号
refund_status int 11 是 退款状态
user_received_account string 64 是 退款入账账户
refunded_time long 20 是 完成时间
total int 11 是 总金额
payer_total int 11 是 用户支付金额
refund int 11 是 退款金额
payer_refund int 11 是 用户退款金额,退款给用户的金额，不包含所有优惠券金额
  • 返回数据
参数名称 类型 最大长度 必选 说明
code int 11 是 服务响应状态，参见错误码表
message string 64 是 服务响应状态说明，参见错误码表
data object - 否 -
  • 请求数据示例
{
  "api_key": "PSUBZLHOKUO6HV52A5CAUSSE5KSB6Y",
  "seq_id": "38d42bd9-9f5a-415e-89d9-ea4ff9cffdf2",
  "timestamp": "1572342076",
  "nonce": "157234207",
  "sign": "8A983278E5366EB93FEB0D4143E1C522",
  "user_code": "udxbxd",
  "biz_order_id": "193839494",
  "refund_no": "2",
  "refund_id": "2"
}
  • 返回数据示例
{
  "code": 0,
  "message": "successful",
  "data":{

  }
}

附录一、code错误码

UNKNOWN_EXCEPTION(-2, "未知异常"),
SERVER_ERROR(-1, "服务端异常"),
SUCCESS(0, "成功"),
HTTP_NOT_FOUND(404, "请求路径错误"),
HTTP_BAD_METHOD(405, "不支持该请求方法"),
PARAMETER_ERROR(1001, "参数错误"),
AUTH_FAILED(1002, "鉴权错误"),
ILLEGAL_API_KEY(1003, "api_key不合法"),

USER_CODE_FORMAT_ERROR(1209, "userCode格式错误"),
APP_ID_FORMAT_ERROR(1210, "appId格式错误"),
MCH_ID_FORMAT_ERROR(1211, "mchId格式错误"),
MCH_ID_MUST_NOT_BLANK(1212, "mchId不能为空"),
OPEN_ID_FORMAT_ERROR(1213, "openId格式错误"),
OPEN_ID_MUST_NOT_BLANK(1214, "openId不能为空"),
DESC_MUST_NOT_BLANK(1215, "description不能为空或者超长"),
CLIENT_IP_MUST_NOT_BLANK(1216, "client_ip不能为空或者超长"),
BUFF_TIME_MUST_NOT_BLANK(1217, "支付参数有效期，不能为空或者超2小时或小于1分钟"),
PROFIT_SHARING_MUST_NOT_BLANK(1218, "分账标识格式错误.{0,1}"),
TRANSACTION_ID_FORMAT_ERROR(1219, "transaction_id格式错误"),
TRANSACTION_ID_MUST_NOT_BLANK(1220, "transaction_id不能为空"),
REFUND_NO_MUST_NOT_BLANK(1221, "refund_no不能为空或者超长"),
REFUND_ID_MUST_NOT_BLANK(1222, "refund_id不能为空或者超长"),

PAY_CLOSE_FAILED(90001, "支付关闭失败"),
PAY_UNIFIED_FAILED(90002, "支付下单失败"),
PAY_QUERY_FAILED(90003, "支付查询失败"),
PAY_REFUND_FAILED(90004, "支付申请退款失败"),
PAY_REFUND_QUERY_FAILED(90005, "支付查询退款失败"),
PAY_API_KEY_AUTH_FAILED(90006, "api_key没有相应权限"),
PAY_INVALID_USER_ID(91000, "userid 为空"),
PAY_INVALID_MCH_ID(91001, "mchid 为空"),
PAY_INVALID_APP_ID(91004, "appid 为空"),
PAY_INVALID_CLIENT_IP(91005, "clientIp 为空"),
PAY_INVALID_ORDER_ID(91006, "orderId 为空"),
PAY_ERR_ORDER_NOT_EXIST(91050, "orderId 为空"),
PAY_ERR_WX_SYSTEM_FAIL(91051, "微信支付系统异常"),
PAY_ERR_INVALID_REQUEST(91052, "订单重入时，要求参数值与原请求一致，请确认参数问题"),
PAY_ERR_NOT_ENOUGH(91053, "余额不足"),
PAY_ERR_ORDER_PAID(91054, "订单已支付"),
PAY_ERR_ORDER_CLOSED(91055, "订单已关闭"),
PAY_ERR_SYSTEM_ERROR(91056, "系统错误"),
PAY_ERR_APPID_NOT_EXIST(91057, "APPID不存在"),
PAY_ERR_MCHID_NOT_EXIST(91058, "MCHID不存在"),
PAY_ERR_APPID_MCHID_NOT_MATCH(91059, "appid和mch_id不匹配"),
PAY_ERR_LACK_PARAMS(91060, "缺少参数"),
PAY_ERR_OUT_TRADE_NO_USED(91061, "商户订单号重复"),
PAY_ERR_BIZERR_NEED_RETRY(91062, "退款业务流程错误，需要商户触发重试来解决"),
PAY_ERR_TRADE_OVERDUE(91063, "订单已经超过退款期限"),
PAY_ERR_ERROR(91064, "业务错误"),
PAY_ERR_USER_ACCOUNT_ABNORMAL(91065, "退款请求失败"),
PAY_ERR_INVALID_REQ_TOO_MUCH(91066, "无效请求过多"),
PAY_ERR_INVALID_TRANSACTIONID(91068, "无效transaction_id"),
PAY_ERR_REFUND_NOTEXIST(91069, "退款订单查询失败"),
PAY_ERR_FREQUENCY_LIMITED(91070, "2个月之前的订单申请退款有频率限制 "),
PAY_ERR_NOAUTH(91071, "商户未开通此接口权限"),

← 微信开放平台代理 →