发起转账

更新时间:2025.03.21

商家转账用户确认模式下,商户可通过此接口申请创建转账单

  • 接口返回的HTTP状态码及错误码,仅代表本次请求的结果。当HTTP状态码是200时,可通过返回参数中的“单据状态”字段来判断当前转账单据状态。

  • 接口返回的HTTP状态码为200,且状态为WAIT_USER_CONFIRM时,可认为创建转账单成功,可引导用户确认收款。其余状态请参考商家转账开发指引中的订单状态流转图进行处理。

  • 接口返回的HTTP状态码不为200时,请务必不要立即更换商户订单单号重试可根据错误码列表中的描述和接口返回的信息进行处理,并通过商户单号查询转账单微信单号查询转账单API接口查询订单结果。当查询原订单结果明确为“失败”时再更换商户订单号进行重试。否则会有重复转账的资金风险。

  • 如果发起转账接口遇到新的错误码,请务必不要换单重试,需通过商户单号查询转账单API接口或微信单号查询转账单API接口查询订单结果,当查询原订单结果明确为"失败"时,再更换商户订单号进行重试。否则会有重复转账的资金风险。

注:单个商户的接口频率限制为100次/s

接口说明

支持商户:【普通商户】

请求方式:【POST】/v3/fund-app/mch-transfer/transfer-bills

请求域名:【主域名】https://api.mch.weixin.qq.com 使用该域名将访问就近的接入点

     【备域名】https://api2.mch.weixin.qq.com 使用该域名将访问异地的接入点 ,指引点击查看

请求参数

Header  HTTP头参数

 Authorization  必填 string

请参考签名认证生成认证信息


 Accept  必填 string

请设置为application/json


 Content-Type  必填 string

请设置为application/json


 Wechatpay-Serial  选填 string

【微信支付公钥ID】或【微信支付平台证书序列号】  请求参数中的敏感字段,需要使用微信支付公钥加密(推荐),请参考获取微信支付公钥ID说明以及微信支付公钥加密敏感信息指引;也可以使用微信支付平台证书公钥加密,参考获取平台证书序列号平台证书加密敏感信息指引


body  包体参数

 appid  必填   string(32)

【商户AppID】 是微信开放平台和微信公众平台为开发者的应用程序(APP、小程序、公众号、企业号corpid即为此AppID)提供的一个唯一标识。此处,可以填写这四种类型中的任意一种APPID,但请确保该appid与商户号有绑定关系。参考 微信支付普通商户与AppID账号关联管理


 out_bill_no  必填   string(32)

【商户单号】 商户系统内部的商家单号,要求此参数只能由数字、大小写字母组成,在商户系统内部唯一


 transfer_scene_id  必填   string(36)

【转账场景ID】 该笔转账使用的转账场景,可前往“商户平台-产品中心-商家转账”中申请。如:1000(现金营销),1006(企业报销)等


 openid  必填   string(64)

【收款用户OpenID】 用户在商户appid下的唯一标识。发起转账前需获取到用户的OpenID,参考接口参数说明


 user_name  选填   string

【收款用户姓名】 收款方真实姓名。若传入收款用户姓名,微信支付会校验收款用户与输入姓名是否一致。转账金额>=2,000元时,必须传入该值。
该字段需要加密传入,参考微信支付公钥加密敏感信息指引(推荐)、平台证书加密敏感信息指引


 transfer_amount  必填   integer

【转账金额】 转账金额,单位为“分”。参考转账额度说明


 transfer_remark  必填   string(32)

【转账备注】 转账备注,用户收款时可见该备注信息,UTF8编码,最多允许32个字符


 notify_url  选填   string(256)

【通知地址】 异步接收微信支付结果通知的回调地址,通知url必须为公网可访问的URL,必须为HTTPS,不能携带参数。


 user_recv_perception  选填   string

【用户收款感知】 用户收款时感知的收款原因。不填或填空,将展示转账场景的默认内容。如有其他展示需求,参考 商家转账产品介绍


 transfer_scene_report_infos  必填   array[object]

【转账场景报备信息】 需按转账场景准确填写报备信息,参考 转账场景报备信息字段说明

属性

请求示例

curl
Java
Go

POST

发起转账-请求示例

1curl -X POST \
2  https://api.mch.weixin.qq.com/v3/fund-app/mch-transfer/transfer-bills \
3  -H "Authorization: WECHATPAY2-SHA256-RSA2048 mchid=\"1900000001\",..." \
4  -H "Accept: application/json" \
5  -H "Wechatpay-Serial: 5157F09EFDC096DE15EBE81A47057A7232F1B8E1"  \
6  -H "Content-Type: application/json" \
7  -d '{
8    "transfer_scene_report_infos" : [
9      {
10        "info_type" : "活动名称",
11        "info_content" : "新会员有礼"
12      },
13      {
14        "info_type" : "奖励说明",
15        "info_content" : "注册会员抽奖一等奖"
16      }
17    ],
18    "transfer_amount" : 400000,
19    "openid" : "o-MYE42l80oelYMDE34nYD456Xoy",
20    "user_name" : "757b340b45ebef5467rter35gf464344v3542sdf4t6re4tb4f54ty45t4yyry45",
21    "appid" : "wxf636efh567hg4356",
22    "out_bill_no" : "plfk2020042013",
23    "user_recv_perception" : "现金奖励",
24    "notify_url" : "https://www.weixin.qq.com/wxpay/pay.php",
25    "transfer_scene_id" : "1000",
26    "transfer_remark" : "新会员开通有礼"
27  }'
28

应答参数

200 OK

 out_bill_no  必填   string(32)

【商户单号】 商户系统内部的商家单号,要求此参数只能由数字、大小写字母组成,在商户系统内部唯一


 transfer_bill_no  必填   string(64)

【微信转账单号】 微信转账单号,微信商家转账系统返回的唯一标识


 create_time  必填   string

【单据创建时间】 单据受理成功时返回,按照使用rfc3339所定义的格式,格式为yyyy-MM-DDThh:mm:ss+TIMEZONE


 state  必填   string

【单据状态】 商家转账订单状态

可选取值

  • ACCEPTED:  转账已受理,可原单重试(非终态)。

  • PROCESSING:  转账锁定资金中。如果一直停留在该状态,建议检查账户余额是否足够,如余额不足,可充值后再原单重试(非终态)。

  • WAIT_USER_CONFIRM:  待收款用户确认,当前转账单据资金已锁定,可拉起微信收款确认页面进行收款确认(非终态)。

  • TRANSFERING:  转账中,可拉起微信收款确认页面再次重试确认收款(非终态)。

  • SUCCESS:  转账成功,表示转账单据已成功(终态)。

  • FAIL:  转账失败,表示该笔转账单据已失败。若需重新向用户转账,请重新生成单据并再次发起(终态)。

  • CANCELING:  转账撤销中,商户撤销请求受理成功,该笔转账正在撤销中,需查单确认撤销的转账单据状态(非终态)。

  • CANCELLED:  转账撤销完成,代表转账单据已撤销成功(终态)。


 package_info  选填   string

【跳转领取页面的package信息】 跳转微信支付收款页的package信息,APP调起用户确认收款或者JSAPI调起用户确认收款 时需要使用的参数。仅当转账单据状态为WAIT_USER_CONFIRM时返回。

单据创建后,用户24小时内不领取将过期关闭,建议拉起用户确认收款页面前,先查单据状态:如单据状态为WAIT_USER_CONFIRM,可用之前的package信息拉起;单据到终态时需更换单号重新发起转账。

应答示例

200 OK

1{
2  "out_bill_no" : "plfk2020042013",
3  "transfer_bill_no" : "1330000071100999991182020050700019480001",
4  "create_time" : "2015-05-20T13:29:35.120+08:00",
5  "state" : "ACCEPTED",
6  "package_info" : "affffddafdfafddffda=="
7}
8

 

错误码

公共错误码

状态码

错误码

描述

解决方案

400

PARAM_ERROR

参数错误

请根据错误提示正确传入参数

400

INVALID_REQUEST

请求不符合业务规则

请参阅 产品介绍开发指引 和 接口规则

403

NO_AUTH

没有相关权限

请参阅 产品介绍开发指引

401

SIGN_ERROR

签名验证不通过

请参阅 签名常见问题

500

SYSTEM_ERROR

系统异常,请稍后重试

请稍后重试

业务错误码

状态码

错误码

描述

解决方案

403

NOT_ENOUGH

资金不足

确认出资商户余额充足

429

FREQUENCY_LIMIT_EXCEED

频率超限

接口请求频率超限,当前请求结果不明确,请降低请求接口频率后,使用相同参数重试

429

RATELIMIT_EXCEEDED

频率超限

接口或同一单号请求频率超限,当前请求结果不明确,请降低请求接口频率,使用相同参数重试

429

FREQUENCY_LIMIT

频率超限

接口或同一单号请求频率超限,当前请求结果不明确,请降低请求接口频率,使用相同参数重试

400

ALREADY_EXISTS

订单已存在

单据状态已经到终态,无法发起转账,请通过查单接口确认转账结果