退款申请

Endpoint: POST /aggregate-pay/api/gateway/refund
Tags: 收单

Description

仅适用于支持退款的支付方式，同时仅支持180天内的交易发起退款。退款到账时效取决于银行和机构的处理时效。

Parameters

Field	In	Type	Required	Constraints	Description
`Content-Type`	header	string	Yes
`sign`	header	string	Yes		签名信息请参考技术文档

Parameter Examples

Content-Type: "application/json"
sign: "FPFVT3o227JrFRbqu19boZCpVVTF9KznxyRawUmxpfXilHV/0yK46haPhAjNu1hPUMy7Vw/ILXhfzffNm4Fj0apWknlTY9OJxnSoQxS9BTFtc61tn5yV1q69x/kkBl82/qwg+XTJ4fOzy7Mar3VaC1E2PlDA6RkkKBUyNE6RYgsdB+Su7an4+4HVTNAnoe74WyvBgxTLMNg28igBTdqxaO3w/UBY6ObVp7vkqkQGdL1Y+HgmMYaAVwrM3+ALWGId0sJ+YqTY4WJ+0xCRGhaSnybiIjZsQEYyID68WNUfuavDLDsEhaMm/HfQvf5p0R1Ltovp3wwJnEbQcjY458iX5A=="

Request Body

Content-Type: application/json

Field	Type	Required	Constraints	Description
`version`	string	Yes	maxLength: 8	接口版本当前值为：1.5
`keyVersion`	string	Yes	maxLength: 8	密钥版本当前值为：1
`requestTime`	string	Yes	maxLength: 32	请求时间，符合rfc3339规范，格式：yyyy-MM-dd'T'HH:mm:ss.SSSXXX 时间需要在当前时间两分钟内
`appId`	string	Yes	maxLength: 64	商户应用Id，PayerMax分配给商户应用的唯一标识
`merchantNo`	string	No	maxLength: 32	商户号，商户与PayerMax业务签约时生成的唯一标识
`data`	object	No		请求数据体
`data.outRefundNo`	string	Yes	maxLength: 64	商户退款申请号，唯一标识一笔退款申请交易
`data.refundAmount`	number	Yes		退款金额，金额的单位为元。除以下国家外按照各国币种支持的小数点位（最大四位）上送。注意：巴林、科威特、伊拉克，约旦、突尼斯、利比亚、奥马尔地区，本币只支持两位小数；印尼、中国台湾、巴基斯坦、哥伦比亚地区，本币不支持带小数金额。
`data.refundCurrency`	string	Yes	maxLength: 3	退款币种（原交易币种）
`data.outTradeNo`	string	No	maxLength: 64	原商户订单号，可以传outTradeNo，也可以传tradeToken，不能outTradeNo和tradeToken同时不传
`data.tradeToken`	string	No	maxLength: 64	正向交易单的交易Token，可以传outTradeNo，也可以传tradeToken，不能outTradeNo和tradeToken同时不传
`data.comments`	string	No	maxLength: 512	退款说明（商户退款理由）
`data.refundNotifyUrl`	string (uri)	No	maxLength: 256	退款回调地址，可后台配置【配置地址】

Example

json

{
  "version": "1.5",
  "keyVersion": "1",
  "requestTime": "2022-01-17T09:20:54.047+00:00",
  "appId": "3b242b56a8b64274bcc37dac281120e3",
  "merchantNo": "020213827212251",
  "data": {
    "outRefundNo": "R1642411016202",
    "refundAmount": 10000,
    "refundCurrency": "IDR",
    "outTradeNo": "P1642410680681",
    "tradeToken": "T2025020713159038685354",
    "comments": "20220117070423TI408900055079",
    "refundNotifyUrl": "https://www.refundNotifyUrl.example.com"
  }
}

Responses

200

错误码

分类	结果码	结果描述
SYSTEM_ERROR	System is busy, please try again later.	系统错误；请联系PayerMax
REQ_TIME_OVER_TIME	requestTime effective in two minutes	请求时间与服务端偏差超过2分钟，请检查requestTime后重新发起
TOO_MANY_REQUEST	Exceed request limitation, please retry later	触发接口并发限流,请稍后重试
SIGN_VERIFY_FAILED	The signature verify failed.	签名错误；请核实签名
MERCHANT_INVALID	The merchant has been offline.	无效商户
MERCHANT_APP_INVALID	Signature key is not configured.	无效商户APP
PARAMS_INVALID	${field} length must be between ${min} and ${max},but your input value length is ${length}.Make sure all requests length is correct.	无效参数-入参字段长度不符合要求；请参考官网字段描述
PARAMS_INVALID	${field} must be ${type} , but your input is ${valueType}.Make sure all requests type is correct.	无效参数-入参字段类型不正确；请参考官网字段描述
PARAMS_INVALID	${field} is invalid,because ${field} is null.	无效参数-入参字段不能为空；请参考官网字段描述
RDR_REFUNDED_NOT_SUPPORT_RETRY	This transaction has been triggered by RDR. A refund has already been successfully processed by the issuing bank. Merchants are not allowed to initiate any additional refund requests for this transaction.	订单已经发起RDR,不能再发起退款。
AMOUNT_INVALID	The refund amount exceed the transaction amount.	退款失败-退款金额超额，不能退款
REFUND_FAILED	The payment method does not support partial refund.	退款失败-支付方式不支持部分退款
REFUND_FAILED	The payment method does not support refund.	退款失败-支付方式不支持退款
REFUND_FAILED	The refund amount is too small to refund.	退款失败-退款金额太小不足以支付手续费
REFUND_INSUFFICIENT_BALANCE	Insufficient Txn currency in the to be Settled Account.	余额不足无法退款
ORDER_NOT_EXIST	The orginal order does not exist.	原订单不存在

Field	Type	Required	Constraints	Description
`code`	string	Yes		返回码，’APPLY_SUCCESS’代表成功。只代表接口请求成功，不代表订单状态。
`msg`	string	Yes		返回描述，’Success.’。只代表接口请求成功，不代表订单状态。
`data`	object	Yes
`data.outRefundNo`	string	Yes	maxLength: 64	商户退款申请号
`data.tradeOrderNo`	string	Yes	maxLength: 64	交易订单号
`data.refundTradeNo`	string	Yes	maxLength: 64	PayerMax退款流水号
`data.status`	string	Yes	maxLength: 32	退款状态：REFUND_PENDING，REFUND_FAILED

Response Example

json

{
  "code": "APPLY_SUCCESS",
  "msg": "",
  "data": {
    "outRefundNo": "R1642411016202",
    "tradeOrderNo": "20220117091121TI366100056090",
    "refundTradeNo": "20220117091657TI790000055087",
    "status": "REFUND_PENDING"
  }
}

退款申请 ​

Description ​

Parameters ​

Parameter Examples ​

Request Body ​

Example ​

Responses ​

200 ​

错误码 ​

Response Example ​

退款申请

Description

Parameters

Parameter Examples

Request Body

Example

Responses

200

错误码

Response Example