/v2/payments/refund

2023-05-31 12:13

POST /v2/payments/refund

With this API call, a merchant can initiate a partial or full refund for a successful payment.

Note：
Both the merchant and user can initiate a refund.
The super app determines whether the refund is successful based on the status of the original payment.
Multiple refund requests are supported for one successful payment, but the total refund amount cannot be greater than the original payment amount.

Structure

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

Request header

Field	Data type	Required	Description	Example
Agent-Token	String	No	An agent token that is issued by the merchant to authorize its ISV for API calls. Specify this parameter if an ISV calls the API in behalf of a merchant.

Request parameters

Field	Data type	Required	Description	Example
refundRequestId	String	Yes	Indicates the unique ID assigned by the merchant to identify a refund request. Maximum length: 64 characters Characters not allowed: special characters such as @ # ? Note: This field is an API idempotency field. For the refund requests which are initiated with the same refundRequestId, the super app must return the same refund result. See the Idempotency for details about API idempotency.	"2019112719074101000700000088881xxxx"
paymentId	String	Yes	Indicates the unique ID assigned by the super app to identify the payment to be refunded. Maximum length: 64 characters Characters not allowed: special characters such as @ # ? Can be `Null`. Note: This field is required when the value of paymentRequestId is `Null`.	"201911271907410100070000009999xxxx"
refundAmount	Amount	Yes	Indicates the refund amount. The total refund amount cannot be greater than the total payment amount whether for a partial refund or a full refund.	{ "currency": "USD", "value": "10000" }
refundReason	String	No	Indicates the refund reason. Maximum length: 256 characters Characters not allowed: special characters such as @ # ? Can be `Null`.	"have returned goods to the shop"
extendInfo	String	No	Indicates the extended information about this API. Maximum length: 4096 characters Characters not allowed: special characters such as @ # ? Can be `Null`.	{ "memo": "memo" }

Response parameters

AMS对比参考：https://global.alipay.com/docs/ac/ams/refund_online

Field	Data type	Required	Description	Example
result	Result	Yes	Indicates the request result such as status and error codes.	{ "resultCode": "SUCCESS", "resultStatus": "S", "resultMessage": "success" }
refundId	String	Yes	Indicates the unique ID assigned by the super app to identify a refund. Maximum length: 64 characters Characters not allowed: special characters such as @ # ?	"2019112719074101000700000019000xxxx"
refundTime	Datetime	No	Indicates the actual date and time when a refund is successful. The value follows the ISO 8601 standard format. For example, "2019-11-27T12:01:01+08:30". Note: This field is returned when this API call is successful (the value of result.resultStatus is `S`).	"2019-11-27T12:01:01+08:30"
extendInfo	String	No	Indicates the extended information about this API. Maximum length: 4096 characters Characters not allowed: special characters such as @ # ? Can be `Null`.	{ "memo": "memo" }

Result process logic

In the response, the result.resultStatus field indicates the result of processing a request. The following table describes each result status:

Result status	Description
S	The refund is successful. No further action is needed. The corresponding result.resultCode is `SUCCESS` and the result.resultMessage is `Success`.
A	The refund is already accepted by the super app. The corresponding result.resultCode is `ACCEPT`. For details, see the following Error codes section.
U	The status of the refund is unknown. 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.
F	The refund is failed. The corresponding result.resultCode and result.resultMessage are various based on different situations. 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 mini program's Open APIs in V2.
API-specific error codes are listed in the following table.

Error code	Result status	Error message	Further action
ACCEPT	A	The request is accepted by the super app successfully.	Query the final refund result via the /v2/payments/inquiryRefund API.
REFUND_IN_PROCESS	U	The refund is under processing.	Query the refund result via the /v2/payments/inquiryRefund API or retry with the same refundRequestId.
REPEAT_REQ_INCONSISTENT	F	The refund request is duplicated with the previous one.	For a new request, change to another refundRequestId.
ORDER_NOT_EXIST	F	The order does not exist.	Use a valid paymentId or paymentRequestId.
ORDER_STATUS_INVALID	F	The order status is invalid.	Query the order status via the /v2/payments/inquiryRefund API.
REFUND_WINDOW_EXCEED	F	The refund date exceeds the period during which the refund is supported.	Contact technical support to troubleshoot the issue.
REFUND_AMOUNT_EXCEED	F	The total refund amount exceeds the payment amount.	Enter a lower refund amount and try again.
CURRENCY_NOT_SUPPORT	F	The refund currency is not supported.	Initiate the refund in the same currency as the payment.

Samples

The merchant and user share the same data flow of refund. Take user refund as an example. The corresponding data flow is illustrated as below:

The user initiates a refund request.
The mini program forwards the refund request to the merchant server.
The merchant server calls this API to request the PDS server to refund.
The PDS server calls this API to request the super app server to refund.
The super app processes the request and returns the refund result to the PDS server.
The PDS processes the request and returns the refund result to the merchant server.
The merchant returns the refund result to the mini program.
The mini program returns the refund result to the user.

Request

copy
{
  "customerBelongsTo":"TNG",
  "refundRequestId": "2019112719074101000700000088881xxxx",
  "paymentId": "201911271907410100070000009999xxxx",
  "refundAmount": {
    "currency": "USD",
    "value": "10000"
  },
  "order":{
    "referenceOrderId": "OrderID_0101010101xxxx",
    "orderDescription": "SHOES",
    "orderAmount": {
      "currency": "USD",
      "value": "10000"
    },
    "orderCreateTime": "2020-01-01T12:01:01+08:30",
    "merchant": {
      "referenceMerchantId": "M00000000001xxxx",
      "merchantMCC": "1405",
      "merchantName": "UGG Technology Limited",
      "merchantDisplayName": "UGG",
      "merchantAddress": {
        "region": "MY",
        "city": "KL"
      }
    },
    "env": {
      "osType": "IOS",
      "terminalType": "APP"
    }
  }
}

The user or merchant initiates the refund request (2019112719074101000700000088881xxxx) to refund 100 USD of the original payment (201911271907410100070000009999xxxx).

Response

copy
{
  "result": {
    "resultCode": "SUCCESS",
    "resultStatus": "S",
    "resultMessage": "success"
  },
  "refundId": "2019112719074101000700000019000xxxx",
  "refundTime": "2019-11-27T12:01:01+08:30"
}

result.resultStatus is S, which shows that the refund is successful at refundTime (2019-11-27T12:01:01+08:30).
refundId is 2019112719074101000700000019000xxxx.