Batch Refunds 批量退款

batch_refund 对象允许你对已经支付的多个 charge 对象发起批量退款请求。 以下是该接口的注意事项:

  • 需要发起退款的 charge 列表,不可以有重复的 charge id,必须全部是已支付并且未全额退款的状态;
  • 批量退款中,任意一笔订单信息不符合以上规则,则批量请求中的所有订单退款均会失败,抛出首个报错的 charge 信息;
  • 批量退款对象创建成功后,退款 Charge 会进入退款队列,若 Charge ID 包含渠道 alipay、alipay_wap、alipay_pc_direct 的订单,且商户是有密退款需要使用浏览器打开 refund_url 字段所对应的地址,商家进行退款操作并且输入支付宝支付密码;
  • 批量退款成功后,调用批量退款查询接口不会返回退款链接,refund_url字段为空;
  • 批量退款请求中同时有不同的支付宝渠道时,必须是同一套参数(公私钥),否则打开链接跳转后会报错。
属性描述
id string批量退款对象 id,由 Ping++ 生成。
app string批量退款对应的 app 对象 ID,查看如何获取App ID
object string值为 "batch_refund"。
batch_no string批量退款批次号,3-24位,允许字母和英文。
created timestamp批量退款创建时间,用 Unix 时间戳表示。
description string批量退款详情,最多 255 个 Unicode 字符。针对 cmb_wallet & cmb_pc_qr 渠道最多支持 99 字节;针对 jdpay_wap 渠道最多支持 128 字节。
metadata hash参考元数据
charges array需要退款的 charge 对象数组。
refunds list退款详情列表,详见 refund 退款
refund_url string退款 URL,仅在渠道为支付宝时有值,你需要获取该地址,在浏览器中打开并且输入支付宝支付密码才能完成退款。
status string批量退款状态,目前支持 5 种状态。created:退款对象已创建,所有订单在队列待处理;pending: 处理中;succeeded: 成功; failed: 失败; partially_succeeded: 部分成功。
time_succeeded integer退款成功的 Unix 时间戳。
livemode boolean是否是生产模式。

退款状态 status 说明

  • created: 退款对象已创建,订单在队列待处理,有任何一笔在 created 状态,批量退款的状态也是 created
  • pending: 具体单笔退款信息已经创建,已经向渠道请求,等待银行处理;若多笔退款,有任何一笔在 pending 状态,批量退款的状态也是 pending
  • succeeded: 所有退款都已成功退款,此状态会发送批量退款成功的 webhook 通知
  • failed: 所有退款都退款失败
  • partially_succeeded: 所有退款都已经处理完成,但包含部分成功、部分失败的状态,此状态会发送退款成功的 webhook 通知

对象示例

{
	"id": "1511801051441290118",
	"app": "app_r1uDe9rDashboard",
	"object": "batch_refund",
	"batch_no": "Br20180100944122120465",
	"created": 1515134483,
	"description": "Testing for batch refund",
	"charges": [{
		"charge": "ch_fHyjLKaj5OSOKCSWj01unzzL",
		"refund": "re_qXPmnTD4ezHSWjLyfP5KWorT",
		"status": "succeeded",
		"failure_msg": null,
		"amount": 1,
		"description": "Description ch_fHyjLKaj5OSOKCSWj01unzzL"
	}, {
		"charge": "ch_HmnDKKDmrb185mbjDOCqbjct",
		"refund": "re_DGm9S4jPWHKGTyzTaHPCG090",
		"status": "failed",
		"failure_msg": null,
		"amount": 10,
		"description": "Description ch_HmnDKKDmrb185mbjDOCqbjct"
	}],
	"refunds": {
		"object": "list",
		"url": null,
		"has_more": false,
		"data": [{
			"id": "re_qXPmnTD4ezHSWjLyfP5KWorT",
			"object": "refund",
			"order_no": "qXPmnTD4ezHSWjLyfP5KWHuT",
			"amount": 1,
			"created": 1515134486,
			"succeed": true,
			"status": "succeeded",
			"time_succeed": 1515134486,
			"description": "Description ch_fHyjLKaj5OSOKCSWj01unzzL",
			"failure_code": null,
			"failure_msg": null,
			"metadata": {},
			"charge": "ch_fHyjLKaj5OSOKCSWj01unzzL",
			"charge_order_no": "46093aa0c1d5f2fe",
			"transaction_no": "2018010421001004920246701437",
			"extra": {}
		}, {
			"id": "re_DGm9S4jPWHKGTyzTaHPCG090",
			"object": "refund",
			"order_no": "DGm9S4jPWHKGTyzTaHPCG090",
			"amount": 10,
			"created": 1515134489,
			"succeed": false,
			"status": "failed",
			"time_succeed": null,
			"description": "Description ch_HmnDKKDmrb185mbjDOCqbjct",
			"failure_code": null,
			"failure_msg": null,
			"metadata": {},
			"charge": "ch_HmnDKKDmrb185mbjDOCqbjct",
			"charge_order_no": "T160824050908ag",
			"transaction_no": null,
			"extra": {}
		}]
	},
	"refund_url": null,
	"status": "partially_succeeded",
	"time_succeeded": 1515134513,
	"livemode": true,
	"metadata": {
		"userStr": "KTs/YDg3ZFUFONZUC10SuA=="
	}
}