/v1/payments/refundApply

2024-11-29 02:51

POST /v1/payments/refundApply

The refundApply API is used to initiate a refund of a successful payment, refund a transaction and return money to the payer. The transaction can be refunded partially or fully. This API returns SUCCESS when deducting money from the merchant is successful.

Note:

1) The merchant/partner submits a refund request to wallets directly

2) Wallets determines whether the refund is successful based on its own payment status and respond to merchants/partners.

3) Multiple refund requests are supported for one successful payment, but the total refund amount can not be greater than the payment amount.

Message structure

A message consists of a header and body. The following sections are focused on the body structure. For the header structure, see：

Request

Property	Data type	Required	Description	Example
refundRequestId	String	Yes	The unqiue ID of a refund generated by merchants. Max. length: 64 characters. This field is used for idempotence control. For the refund requests which are initiated with the same `refundRequestId` and reach a final status (S or F), the wallet must return the unique result.	"2019112719074101000700000088881xxxx"
paymentId	String	Yes	The unqiue ID of the corresponding original payment. Max. length: 64 characters.	"201911271907410100070000009999xxxx"
refundAmount	Amount	Yes	Refund amount.	{ "currency": "CLP", "value": "10000" }
refundReason	String	No	Refund reason. Max. length: 256 characters.	"have returned goods to the shop"

Response

Property

Data type

Required

Description

Example

result

Result

Yes

The request result, which contains information such as status and error codes.

{

"resultCode": "SUCCESS",

"resultStatus": "S",

"resultMessage": "success"

}

refundId

String

Unique refund order number. It is generated by Wallet, which uniquely identifies the refund.

It is mandatory when the result.resultStatus is S.

Max. length: 64 characters.

"2019112719074101000700000019000xxxx"

Result Process Logic

In the response, the result.resultStatus field indicates the result of processing a request as follows.

resultStatus	Decription
S	The corresponding `result.resultCode` is "SUCCESS" and the `result.resultMessage` is "Success". It means that the refund is successful, the merchant/partner can process as success.
U	The corresponding `result.resultCode` is "UNKNOWN_EXCEPTION" and `result.resultMessage` is "An API calling is failed, which is caused by unknown reasons.". For details, see the Common error codes section. It means that when handling the refund request, an unknown exception occurs. The merchant/partner can call the Refund Inquiry (`inquiryRefund`) API to query or retry this Refund (`refund`) API. What needs to note is as follow: U status (inquiry/retry still gets U) can not set to fail or success on merchant/partner system. U status (inquiry/retry still gets U) should not refund/charge to user by offline (Maybe will make fund loss). If other response (almost never occur), the merchant/partner should process like U.
F	That means this transaction is failed. The corresponding `result.resultCode` and `result.resultMessage` vary based on different situations. It means that the refund is failed. The failure reasons can be the followings, but not limited to: The refund date time exceeds the allowable refund window (`result.resultCode` = REFUND_WINDOW_EXCEED). The refund amount is greater than the payment amount. For details, see the following Error codes section.

Error codes

Error codes are usually classified into the following categories:

Common error codes: are common for all Mini Program OpenAPIs.
API-specific error codes: are listed in the following table.

resultStatus	resultCode	resultMessage
S	SUCCESS	Success
F	MSG_PARSE_ERROR	Message parsed error.
F	FUNCTION_NOT_MATCH	Function parameter does not match API.
F	INVALID_CLIENT	Invalid client.
F	INVALID_SIGNATURE	Signature is invalid.
F	INVALID_CLIENT_STATUS	Invalid client status.
F	ORDER_STATUS_INVALID	Order status is invalid.
F	ORDER_NOT_EXIST	Order does not exist.
F	PARTNER_NOT_EXIST	Partner status abnormal.
F	REFUND_AMOUNT_EXCEED	The total refund amount has exceed the payment amount.
F	REFUND_WINDOW_EXCEED	Exceed Refund window.
F	REPEAT_REQ_INCONSISTENT	Repeated submit, and requests are inconsistent.
F	AGREEMENT_REFUND_NOT_ALLOWED	Refund not allowed by contract
F	PARTIAL_REFUND_NOT_ALLOWED	Partial refund not allowed, Coupon payment may be included

Sample

For example, a wallet user applies for refund of 100 USD of a successful payment at the merchant/partner. So the merchant/partner will call this refund API to the wallet to refund money to users.

User can start a refund request from the Mini Program or the merchant cashier.
The merchant server calls this refund interface to refund.
E-wallet returns the refund result to the merchant server.
The merchant should return the refund result to the Mini Program or the merchant cashier.

Request

copy
{
  "paymentId": "20221124111212800100166473700277756",
  "refundRequestId": "rrIX-vONE-HiNM-QLMJ-emWN-sFlC-JX",
  "refundAmount": {
    "currency": "CLP",
    "value": "123450"
  },
  "refundReason": "User refund the goods."
}

refundRequestId is the unique ID of this refund request, generated by merchant/partner, merchant/partner should make sure it is unique, because wallet will use refundRequestId to do idempotent process.
paymentId is the payment ID generated by Wallet, which is the unique payment identifier associated with this refund.
refundAmount describes 100 USD should refund to user, refund amount should less than origin payment amount. The amount to pay out for this refund.refundAmount.currency and paymentAmount.currency in payment request are the same. And if there are multiple refunds for a particular payment, the total successful refunded amount cannot exceed the payment amount in the payment transaction.

Note:

paymentId and paymentRequestId can not both empty, wallet has to find out the origin payment order based on paymentId or paymentRequestId.

Response

copy
{
  "result": {
    "resultCode": "SUCCESS",
    "resultStatus": "S",
    "resultMessage": "Success"
  },
  "refundId": "20221124111212800100166473700277756"
}

result.resultStatus==S shows that the Wallet refund is successful.
refundId is generated by Wallet, uniquely identifies the refund.
refundTime describes the success date time of this refund.