微信支付API

产品介绍

开发指引

API列表

JSAPI/小程序下单

POST

JSAPI调起支付

微信支付订单号查询订单

GET

商户订单号查询订单

GET

关闭订单

POST

支付成功回调通知

退款申请

POST

查询单笔退款（通过商户退款单号）

GET

发起异常退款

POST

常见问题

附录

管理商户号绑定的APPID账号

配置JSAPI支付授权目录

退款申请开发中

POSThttps://api.mch.weixin.qq.com/v3/refund/domestic/refunds

创建时间: 2025-05-31 23:27

请求参数

Header 参数

参数名	示例值	是否必填	参数类型	描述说明
Authorization	WECHATPAY2-SHA256-RSA2048 mchid="1900000001",...	是	string	请参考签名认证生成认证信息
Accept	application/json	是	string	请设置为application/json
Content-Type	application/json	是	string	请设置为application/json

Body 参数application/json

数据结构

transaction_idstring

可选

【微信支付订单号】微信支付侧订单的唯一标识，订单支付成功后，查询订单和支付成功回调通知会返回该参数。 transaction_id和out_trade_no必须二选一进行传参。

out_trade_nostring

可选

【商户订单号】商户下单时传入的商户系统内部订单号。 transaction_id和out_trade_no必须二选一进行传参。

out_refund_nostring

必填

【商户退款单号】商户系统内部的退款单号，商户系统内部唯一，只能是数字、大小写字母_-|*@ ，同一商户退款单号多次请求只退一笔。不可超过64个字节数。

reasonstring

可选

【退款原因】若商户传了退款原因，该原因将在下发给用户的退款消息中显示，具体展示可参见退款通知UI示意图。请注意：1、该退款原因参数的长度不得超过80个字节；2、当订单退款金额小于等于1元且为部分退款时，退款原因将不会在消息中体现。

notify_urlstring

可选

【退款结果回调url】异步接收微信支付退款结果通知的回调地址，通知url必须为外网可访问的url，不能携带参数。如果传了该参数，则商户平台上配置的回调地址（商户平台-交易中心-退款管理-退款配置）将不会生效，优先回调当前传的这个地址。

funds_accountstring

可选

【退款资金来源】若传递此参数则使用对应的资金账户退款。可选取值： AVAILABLE: 仅对旧资金流商户适用(请参考旧资金流介绍区分)，传此枚举指定从可用余额账户出资，否则默认使用未结算资金退款。 UNSETTLED: 仅对出行预付押金退款适用，指定从未结算资金出资。

amountobject

必填

【金额信息】订单退款金额信息

refundinteger

可选

refund 　必填 integer 【退款金额】退款金额，币种的最小单位，只能为整数，不能超过原订单支付金额。

fromarray<object>

可选

【退款出资账户及金额】退款需从指定账户出资时，可传递该参数以指定出资金额（币种最小单位，仅限整数）。多账户出资退款需满足：1、未开通退款支出分离功能；2、订单为待分账或分账中的分账订单。传递参数需确保：1、基本账户可用与不可用余额之和等于退款金额；2、账户类型不重复。不符条件将返回错误。

totalinteger

必填

【原订单金额】原支付交易的订单总金额，币种的最小单位，只能为整数

currencystring

必填

【退款币种】符合ISO 4217标准的三位字母代码，固定传：CNY，代表人民币。

goods_detailarray<object>

可选

【退款商品】请填写需要指定退款的商品信息，所指定的商品信息需要与下单时传入的单品列表goods_detail中的对应商品信息一致，如无需按照指定商品退款，本字段不填。

merchant_goods_idstring

必填

【商户侧商品编码】订单下单时传入的商户侧商品编码。

wechatpay_goods_idstring

可选

【微信侧商品编码】订单下单时传入的微信侧商品编码（没有可不传）

goods_namestring

可选

【商品名称】订单下单时传入的商品名称。

unit_priceinteger

必填

【商品单价】订单下单时传入的商品单价。

refund_amountinteger

必填

【商品退款金额】商品退款金额，单位为分

refund_quantityinteger

必填

【商品退货数量】对应商品的退货数量

示例数据

{
  "transaction_id": "1217752501201407033233368018",
  "out_trade_no": "1217752501201407033233368018",
  "out_refund_no": "1217752501201407033233368018",
  "reason": "商品已售完",
  "notify_url": "https://weixin.qq.com",
  "funds_account": "AVAILABLE",
  "amount": {
    "refund": 888,
    "from": [
      {
        "account": "AVAILABLE",
        "amount": 444
      }
    ],
    "total": 888,
    "currency": "CNY"
  },
  "goods_detail": [
    {
      "merchant_goods_id": "1217752501201407033233368018",
      "wechatpay_goods_id": "1001",
      "goods_name": "iPhone6s 16G",
      "unit_price": 528800,
      "refund_amount": 528800,
      "refund_quantity": 1
    }
  ]
}

响应示例

成功

HTTP状态码：200

内容格式：JSON

数据结构

refund_idstring

必填

【微信支付退款单号】申请退款受理成功时，该笔退款单在微信支付侧生成的唯一标识。

out_refund_nostring

必填

【商户退款单号】商户申请退款时传的商户系统内部退款单号。

transaction_idstring

必填

【微信支付订单号】微信支付侧订单的唯一标识。

out_trade_nostring

必填

【商户订单号】商户下单时传入的商户系统内部订单号。

channelstring

必填

退款渠道】订单退款渠道以下枚举： ORIGINAL: 原路退款 BALANCE: 退回到余额 OTHER_BALANCE: 原账户异常退到其他余额账户 OTHER_BANKCARD: 原银行卡异常退到其他银行卡(发起异常退款成功后返回)

user_received_accountstring

必填

【退款入账账户】取当前退款单的退款入账方，有以下几种情况： 1）退回银行卡：{银行名称}{卡类型}{卡尾号} 2）退回支付用户零钱:支付用户零钱 3）退还商户:商户基本账户商户结算银行账户 4）退回支付用户零钱通:支付用户零钱通 5）退回支付用户银行电子账户:支付用户银行电子账户 6）退回支付用户零花钱:支付用户零花钱 7）退回用户经营账户:用户经营账户 8）退回支付用户来华零钱包:支付用户来华零钱包 9）退回企业支付商户:企业支付商户

success_timestring

可选

【退款成功时间】 1、定义：退款成功的时间，该字段在退款状态status为SUCCESS（退款成功）时返回。 2、格式：遵循rfc3339标准格式：yyyy-MM-DDTHH:mm:ss+TIMEZONE。yyyy-MM-DD 表示年月日；T 字符用于分隔日期和时间部分；HH:mm:ss 表示具体的时分秒；TIMEZONE 表示时区（例如，+08:00 对应东八区时间，即北京时间）。示例：2015-05-20T13:29:35+08:00 表示北京时间2015年5月20日13点29分35秒。

create_timestring

必填

【退款创建时间】 1、定义：提交退款申请成功，微信受理退款申请单的时间。 2、格式：遵循rfc3339标准格式：yyyy-MM-DDTHH:mm:ss+TIMEZONE。yyyy-MM-DD 表示年月日；T 字符用于分隔日期和时间部分；HH:mm:ss 表示具体的时分秒；TIMEZONE 表示时区（例如，+08:00 对应东八区时间，即北京时间）。示例：2015-05-20T13:29:35+08:00 表示北京时间2015年5月20日13点29分35秒。

statusstring

必填

【退款状态】退款单的退款处理状态。 SUCCESS: 退款成功 CLOSED: 退款关闭 PROCESSING: 退款处理中 ABNORMAL: 退款异常，退款到银行发现用户的卡作废或者冻结了，导致原路退款银行卡失败，可前往商户平台-交易中心，手动处理此笔退款，可参考：退款异常的处理，或者通过发起异常退款接口进行处理。注：状态流转说明请参考状态流转图

funds_accountstring

必填

【资金账户】退款所使用资金对应的资金账户类型 UNSETTLED: 未结算资金 AVAILABLE: 可用余额 UNAVAILABLE: 不可用余额 OPERATION: 运营账户 BASIC: 基本账户（含可用余额和不可用余额） ECNY_BASIC: 数字人民币基本账户

amountobject

必填

【金额信息】订单退款金额信息

totalinteger

必填

【订单金额】订单总金额，单位为分

refundinteger

必填

【退款金额】退款金额，单位为分，只能为整数，可以做部分退款，不能超过原订单支付金额。

fromarray<object>

可选

【退款出资账户及金额】退款出资的账户类型及金额信息，若此接口请求时未传该参数，则不会返回。

payer_totalinteger

必填

【用户实际支付金额】用户现金支付金额，整型，单位为分，例如10元订单用户使用了2元全场代金券，则该金额为用户实际支付的8元。

payer_refundinteger

必填

【用户退款金额】指用户实际收到的现金退款金额，数据类型为整型，单位为分。例如在一个10元的订单中，用户使用了2元的全场代金券，若商户申请退款5元，则用户将收到4元的现金退款(即该字段所示金额)和1元的代金券退款。注：部分退款用户无法继续使用代金券，只有在订单全额退款且代金券未过期的情况下，且全场券属于银行立减金用户才能继续使用代金券。详情参考含优惠退款说明。

settlement_refundinteger

必填

【应结退款金额】去掉免充值代金券退款金额后的退款金额，整型，单位为分，例如10元订单用户使用了2元全场代金券(一张免充值1元 + 一张预充值1元)，商户申请退款5元，则该金额为退款金额5元 - 0.5元免充值代金券退款金额 = 4.5元。

settlement_totalinteger

必填

【应结订单金额】去除免充值代金券金额后的订单金额，整型，单位为分，例如10元订单用户使用了2元全场代金券(一张免充值1元 + 一张预充值1元)，则该金额为订单金额10元 - 免充值代金券金额1元 = 9元。

discount_refundinteger

必填

【优惠退款金额】申请退款后用户收到的代金券退款金额，整型，单位为分，例如10元订单用户使用了2元全场代金券，商户申请退款5元，用户收到的是4元现金 + 1元代金券退款金额(该字段) 。

currencystring

必填

【退款币种】固定返回：CNY，代表人民币。

refund_feeinteger

可选

【手续费退款金额】订单退款时退还的手续费金额，整型，单位为分，例如一笔100元的订单收了0.6元手续费，商户申请退款50元，该金额为等比退还的0.3元手续费。

promotion_detailarray<object>

可选

【优惠功能】代金券信息，当订单有使用代金券时，该字段将返回所使用的代金券信息。

coupon_idstring

可选

【券ID】代金券id，微信为代金券分配的唯一标识，创券商户调用发放指定批次的代金券时返回的代金券ID coupon_id。

namestring

必填

【优惠名称】优惠名称，创券商户创建代金券批次时传入的批次名称stock_name。

scopestring

可选

【优惠范围】优惠活动中代金券的适用范围，分为两种类型： 1、GLOBAL：全场代金券-以订单整体可优惠的金额为优惠门槛的代金券； 2、SINGLE：单品优惠-以订单中具体某个单品的总金额为优惠门槛的代金券

typestring

可选

【优惠类型】代金券资金类型，优惠活动中代金券的结算资金类型，分为两种类型： 1、CASH：预充值-带有结算资金的代金券，会随订单结算给订单收款商户； 2、NOCASH：免充值-不带有结算资金的代金券，无资金结算给订单收款商户。

amountinteger

必填

【优惠券面额】代金券优惠的金额。

stock_idstring

可选

【活动ID】单张代金券所对应的批次号

wechatpay_contributeinteger

可选

【微信出资】代金券有三种出资类型：微信出资、商户出资和其他出资。本参数将返回选择“微信出资类型”时的优惠券面额。 1、创建代金券后默认为商户出资类型。如需使用其他两种类型，请与相关行业运营进行沟通。 2、在 wechatpay_contribute、merchant_contribute 和 other_contribute 这三个字段中，仅有一个字段会返回出资金额。具体返回哪个字段取决于代金券批次的配置。

merchant_contributeinteger

可选

【商户出资】代金券有三种出资类型：微信出资、商户出资和其他出资。本参数将返回选择“商户出资类型”时的优惠券面额。 1、创建代金券后默认为商户出资类型。如需使用其他两种类型，请与相关行业运营进行沟通。 2、在 wechatpay_contribute、merchant_contribute 和 other_contribute 这三个字段中，仅有一个字段会返回出资金额。具体返回哪个字段取决于代金券批次的配置。

other_contributeinteger

可选

【其他出资】代金券有三种出资类型：微信出资、商户出资和其他出资。本参数将返回选择“其他出资类型”时的优惠券面额。 1、创建代金券后默认为商户出资类型。如需使用其他两种类型，请与相关行业运营进行沟通。 2、在 wechatpay_contribute、merchant_contribute 和 other_contribute 这三个字段中，仅有一个字段会返回出资金额。具体返回哪个字段取决于代金券批次的配置。

currencystring

可选

【优惠币种】代金券金额所对应的货币种类：固定为：CNY，人民币。

goods_detailarray<object>

可选

【单品列表】单品列表。scope为SINGLE（单品优惠）时返回该参数

响应示例

{
  "refund_id": "50000000382019052709732678859",
  "out_refund_no": "1217752501201407033233368018",
  "transaction_id": "1217752501201407033233368018",
  "out_trade_no": "1217752501201407033233368018",
  "channel": "ORIGINAL",
  "user_received_account": "招商银行信用卡0403",
  "success_time": "2020-12-01T16:18:12+08:00",
  "create_time": "2020-12-01T16:18:12+08:00",
  "status": "SUCCESS",
  "funds_account": "UNSETTLED",
  "amount": {
    "total": 100,
    "refund": 100,
    "from": [
      {
        "account": "AVAILABLE",
        "amount": 444
      }
    ],
    "payer_total": 90,
    "payer_refund": 90,
    "settlement_refund": 100,
    "settlement_total": 100,
    "discount_refund": 10,
    "currency": "CNY",
    "refund_fee": 100
  },
  "promotion_detail": [
    {
      "promotion_id": "109519",
      "scope": "GLOBAL",
      "type": "COUPON",
      "amount": 5,
      "refund_amount": 100,
      "goods_detail": [
        {
          "merchant_goods_id": "1217752501201407033233368018",
          "wechatpay_goods_id": "1001",
          "goods_name": "iPhone6s 16G",
          "unit_price": 528800,
          "refund_amount": 528800,
          "refund_quantity": 1
        }
      ]
    }
  ]
}

最后更新: 2 个月前

支付成功回调通知

GET查询单笔退款（通过商户退款单号）