Alipay+ DocsAlipay+ Docs

refundAlipay+ → MPP

Alipay+ uses the refund API to initiate a refund of a successful payment.

Note: In the following sections, the Mobile Payment Partner (MPP) is also known as PSP. For example, pspId refers to the ID that identifies an MPP.

Structure

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

Note:

1. Set the data type of each parameter (except array) as String. This means that you must use double quotation marks (" ") to enclose the parameter value. Examples:

  • If the data type of a parameter is Integer and its value is 20, set it as "20".
  • If the data type of a parameter is Boolean and its value is true, set it as "true".  

2. For optional parameters that are not required in your case, you can take one of the following actions:

  • Exclude the parameters from the request body. 
  • Set the parameter values as null (without the double quotation marks). 

Do NOT leave the optional parameters empty by setting their values as ""; otherwise, an error might occur.   

Request parameters

acquirerId String  REQUIRED

The unique ID that is assigned by Alipay+ to identify an Acquiring Partner (ACQP). 

More information about this field:

  • Maximum length: 64 characters

pspId String  REQUIRED

The unique ID that is assigned by Alipay+ to identify an MPP. 

More information about this field:

  • Maximum length: 64 characters

paymentRequestId String  REQUIRED

The request ID of the payment to be refunded, assigned by Alipay+ to identify the original payment order. 

More information about this field:

  • Maximum length: 64 characters

paymentId String  REQUIRED

The unique ID that is assigned by the MPP to identify a payment order. 

More information about this field:

  • Maximum length: 64 characters

refundRequestId String  REQUIRED

The unique ID that is assigned by Alipay+ to identify a refund request.

More information about this field:

  • This field is an API idempotency field. For requests that are initiated with the same refundRequestId, the MPP must regard the requests as repeated and process the requests only once. The MPP is recommended to check the consistency of the following key request parameters: refundAmount, refundFromAmount, refundPromoInfo, and surchargeInfo. If any of their values is different from that in the previous request, the MPP needs to return the REPEAT_REQ_INCONSISTENT result code.
  • Maximum length: 64 characters

refundAmount Amount object REQUIRED

The refund amount that is paid by the MPP for this refund, in the payment currency, also known as transaction currency.

Important: The value of the refundAmount.currency parameter must be the same as the value of the paymentAmount.currency parameter of the original payment order.  

Show child parameters

refundFromAmount Amount object REQUIRED

The refund amount that the MPP settles to Alipay+ for this refund, in the MPP's currency.

Important: The value of the refundFromAmount.currency parameter must be the same as the value of the payToAmount.currency parameter of the original payment order. 

Show child parameters

refundQuote Quote object 

The exchange rate between the refund amount (refundAmount) and the refund from amount (refundFromAmount). 

This parameter is specified by Alipay+ if the value of the refundAmount.currency parameter is not the same as that of the refundFromAmount.currency parameter. 

Show child parameters

refundPromoInfo RefundPromoInfo object 

The promotion information related to the refund when a promotional discount is applied in the original payment.

This parameter is specified by Alipay+ if a promotional discount is applied to the original payment and Alipay+ forwards the promotion info to the MPP.  

Show child parameters

surchargeInfo SurchargeInfo object 

The surcharge information.

This parameter is specified by Alipay+ if a surcharge is applied in the original payment. 

Show child parameters

refundReason String  

The reasons for the refund.

This parameter is specified by Alipay+ if the ACQP provides the reason. 

More information about this field:

  • Maximum length: 256 characters

Response parameters

result Result object REQUIRED

The refund result. If this API is successfully called, the refund succeeds. For more information about how to return the refund result, see How to return the result

Show child parameters

refundId String  

The unique ID that is assigned by the MPP to identify a refund.

Return this parameter if the refund succeeds (the value of the result.resultCode parameter is SUCCESS). 

More information about this field:

  • Maximum length: 64 characters

refundTime Datetime  

The date and time when the refund reaches a final state of success.

Return this parameter if the refund succeeds (the value of the result.resultCode parameter is SUCCESS). 

More information about this field:

  • The value follows the ISO 8601 standard format. For example, "2019-11-27T12:01:01+08:00".
API Explorer

Request

Request Body

Response

Response Body

More information

How are the different amounts calculated

This section introduces how are refundAmount, refundFromAmount, and surchargeAmount calculated when Alipay+ calls the refund API request and provides calculation cases to illustrate the process.

Note: Alipay+ calculates the values of all amounts in the smallest currency unit. For example, if the currency is HKD and the amount is $1.00, the value of the amount is set to 100; or if the currency is JPY and the amount is ¥1, the value of the amount is set to 1.

refundAmount

Refund type

Full refund

Partial refund

Currency

The currency that is used by Alipay+ to create the payment order that is related to the refund.

Value

The same as the value of the paymentAmount.value parameter in the pay API request.

The same as the value of the refund amount that is requested by the ACQP from Alipay+.

Note: In case of partial refunds, Alipay+ ensures that the total refundAmount.value of all partial refunds does not exceed the value of the paymentAmount.value parameter in the original pay API request.

refundFromAmount

Refund type

Full refund

Partial refund

Currency

The currency that is used by the MPP.

Value

The same as the value of the payToAmount.value parameter in the pay API request

refundAmount * refundQuote - (refundAmount / payToAmount) * savingsAmount

Note: In case of partial refunds, Alipay+ ensures that the total refundFromAmount.value of all partial refunds does not exceed the value of the payToAmount.value parameter in the original pay API request.

surchargeAmount

Refund type

Full refund

Partial refund

Currency

The currency that is used by the MPP.

Value

The same as the value of the surchargeAmount.value parameter in the pay API request

refundAmount * surchargeQuote - (refundAmount / payToAmount) * savingsAmount

Note: In case of partial refunds, Alipay+ ensures that the total surchargeAmount.value of all partial refunds does not exceed the value of the surchargeAmount.value parameter in the original pay API request.

Calculation cases

The following three cases are provided for your reference.

Case 1

The following case is illustrated based on Case 1 that is introduced in the section How are the different amounts calculated of the pay API specification.

In this case, a Hong Kong user purchases a 1000 JPY merchandise from a Japanese merchant and applies a 5 JPY coupon provided by Alipay+ to the order. Besides, Alipay+ collects a surcharge on behalf of the MPP. 

Then, the user returns the merchandise to the Japanese merchant and demands a full fund.

Known conditions

As introduced in Case 1 in the pay API specification, the following amounts related to payment are already known:

  • Initial order amount: 1000 JPY
  • Instant discount: 5 JPY
  • Payment quote between JPY and HKD (paymentQuote): 1 JPY = 8.5614 HKD
  • Surcharge quote between JPY and HKD (surchargeQuote): 1 JPY = 8.9614 HKD
  • Refund quote between JPY and HKD (refundQuote): 1 JPY = 8.5614 HKD

Calculation results

The following amounts related to refund can be calculated as follows:

  • refundAmount = paymentAmount = 995 JPY
  • refundFromAmount = payToAmount = 8518 HKD
  • surchargeAmount = 8916 HKD

Case 2

The following case is illustrated based on Case 2 that is introduced in the section How are the different amounts calculated of the pay API specification.

In this case, a Hong Kong user purchases a 10000 USD merchandise from an American merchant and applies a 500 HKD coupon provided by Alipay+ to the order. No surcharge is collected.

Then, the user returns the merchandise to the American merchant and demands a full fund.

Known conditions

As introduced in Case 2 in the pay API specification, the following amounts related to payment are already known:

  • Initial order amount: 10000 USD
  • Instant discount: 500 HKD
  • Payment quote between USD and HKD (paymentQuote): 1 USD = 9.3307 HKD
  • Refund quote between USD and HKD (refundQuote): 1 USD = 9.3307 HKD

Calculation results

The following amounts related to refund can be calculated as follows:

  • refundAmount = paymentAmount = 9946 USD
  • refundFromAmount = payToAmount = 92807 HKD

Case 3

The following case is illustrated based on Case 2 that is introduced in the section How are the different amounts calculated of the pay API specification.

In this case, a Hong Kong user purchases two merchandises total worth 10000 USD from an American merchant and applies a 500 HKD coupon provided by Alipay+ to the order. No surcharge is collected.

Then, the user returns one merchandise worth 5000 USD to the American merchant and demands a partial refund. 

Known conditions

As introduced in Case 2 in the pay API specification, the following amounts related to payment are already known:

  • Initial order amount: 10000 USD
  • Instant discount: 500 HKD
  • Payment quote between USD and HKD (paymentQuote): 1 USD = 9.3307 HKD
  • Refund quote between USD and HKD (refundQuote): 1 USD = 9.3307 HKD

Calculation results

The following amounts related to refund can be calculated as follows:

  • refundAmount = 5000 USD
  • refundFromAmount = 5000 USD * 9.3307 USD/HKD - 500 HKD * (5000 USD / 10000 USD) = 46403.5 HKD 

How to return the result

According to the request processing result, the MPP needs to return the corresponding result (specified by the result parameter):

  • If the refund succeeds, set the value of result.resultStatus to S and the value of result.resultCode to SUCCESS.
  • If the refund fails, set the value of result.resultStatus to F and the value of result.resultCode accordingly.
  • If the refund result is unknown, set the value of result.resultStatus to U and the value of result.resultCode accordingly.

For more information about how to define your result codes, see the Result codes section below. 

Sample

1.1 Alipay+ sends a refund request to the Mobile Payment Partner.

Sample Code

1.2 The MPP returns the refund result to Alipay+.

Sample Code

Sample with promotion

In the following sample, a Korean user purchased a 100 JPY item from a Japanese merchant and paid 90 JPY for the item after applying a 10 JPY off 100 JPY coupon provided by Alipay+. Then, the user requests a refund for this payment. The promotion information related to the refund is specified by the refundPromoInfo parameter. 

 2.1 Alipay+ forwards a refund request to the MPP.

Sample Code

 

2.2 The MPP returns the refund result to Alipay+.

Sample Code

Result/Error codes

CodeValueMessage
SUCCESSSSuccess
ACCESS_DENIEDFAccess is denied.
CURRENCY_NOT_SUPPORT FThe currency is not supported.
INVALID_CLIENTFThe client is invalid.
INVALID_ORDER_STATUSFThe order status is invalid for this operation.
INVALID_SIGNATUREFThe signature is invalid.
KEY_NOT_FOUNDFThe key is not found.
MEDIA_TYPE_NOT_ACCEPTABLEFThe server does not implement the media type that is acceptable to the client.
METHOD_NOT_SUPPORTEDFThe server does not implement the requested HTTPS method.
NO_INTERFACE_DEFFAPI is not defined.
ORDER_NOT_EXISTFThe order doesn't exist.
PARAM_ILLEGALFIllegal parameters. For example, non-numeric input, invalid date.
PROCESS_FAILFA general business failure occurred. Do not retry.
REFUND_AMOUNT_EXCEEDFThe total refund amount exceeds the payment amount.
REPEAT_REQ_INCONSISTENTFRepeated requests are inconsistent.
USER_AMOUNT_EXCEEDFThe user balance exceeds the balance limit.
REQUEST_TRAFFIC_EXCEED_LIMITUThe request traffic exceeds the limit.
UNKNOWN_EXCEPTIONUAn API call failed, which is caused by unknown reasons.