forex_refund

Call this interface to refund a transaction.

To initiate multiple refund transactions by using a same partner ID (partner), send the refund requests with an interval of at least 3 seconds.

Request

Service address

Environment

HTTPS request URL

Production environment

https://intlmapi.alipay.com/gateway.do

Test environment

https://mapi.alipaydev.com/gateway.do

Request parameters

ParameterDescription
Basic parameter

service

String Required

Interface name 

Example:forex_refund

partner

String(16) Required

The partner ID that is assigned by Alipay to identify an Alipay account. The partner ID is composed of 16 digits and begins with 2088. 

Example:2088*********662

_input_charset

String Required

The charset with which the request data is encoded. UTF-8 is supported.

Example:UTF-8

sign_type

String Required

Sign type. RSA, RSA2 and MD5 are supported. Use uppercase. 

Example:RSA2

sign

String Required

Sign value 

Example:e5815a4556db338ed237f7d3fd222184

notify_url

URL(200)

The URL for receiving asynchronous notifications after the payment is completed.

Example:http://www.test.com/alipay/notify_url.php

Business parameter

out_return_no

Required

The unique refund ID for the refund request 

Example:205485121225

out_trade_no

Required

The payment ID for the original payment transaction 

Example:990xxxxxxx8989

return_amount
Required

The amount to refund in the settlement currency. The value is in the range of 0.01 – 1000000.00, with at most 2 digits after the decimal point.

Example:100.30

currency

Required

The currency for the refund. Only HKD is supported. 

Example:HKD

gmt_return

Required

Refund transaction time, with a format of yyyy-MM-dd HH:mm:ss. Use GMT+8.

Example:2013-11-27 15:45:57

reason

Required

Reason for the refund 

Example:product defect

is_sync

Required

Indicates that the refund request is processed synchronously or asynchronously with a value of Y or N.The default value is N, which means an asynchronous response from Alipay is returned to the merchant if the merchant has set the value of the notify_url field when sending the refund request. If the value is set as Y, it means only a synchronous response is returned to the merchant. 

Example:N

Note:

Do not use the halfwidth quotation mark (") in parameter values.

Response

Synchronous response

ParameterDescription

is_success

String Required

If the value of is_sync is Y, this parameter indicates whether the refund succeeds, with a value of T for success and F for failure.

If the value of is_sync is empty or N, this parameter indicates whether the request succeeds, with a value of T for success and F for failure. A successful request does not mean the business is accepted and processed successfully.

Example:T

error

String

Error message

Example:REPEATED_REFUNDMENT_REQUEST

Asynchronous response

ParameterDescription
Basic parameter

sign_type

String

Sign type. RSA, RSA2 and MD5 are supported. Use uppercase. 

Example:RSA

sign

String

Sign value 

Example:e5815a4556db338ed237f7d3fd222184

Business parameter

notify_type

String

Notification type, with a value of refund_status_sync 

Example:refund_status_sync

notify_id

String(34)

Notification ID, used by the partner system to verify the notification

Example:92c60707dc43a5b2d648b7b4d3c2e1592g

notify_time

Timestamp

The time in GMT+8 when the notification is sent. The time format is yyyy-MM-dd HH:mm:ss.

Example:2015-06-30 09:56:02

refund_status

String(32)

The refund status. The value can be REFUND_SUCCESS for a successful refund or REFUND_FAIL for a failed refund.

Example:REFUND_SUCCESS

out_trade_no

String(64)

The unique transaction ID that is assigned by the partner. This parameter is transmitted by the corresponding request and needs to be returned with the original value.

Example:990xxxxxxx8989

out_return_no

String(64)

Refund ID of the partner

error_code

String(64)

Error code that is returned when the request is failed, to describe the request failure reason. For more information, see the Error Code section in this document.

Example:RETURN_AMOUNT_EXCEED

currency

String(3)

The refund currency 

Example:HKD

return_amount

Number(9,2)

Refund amount

Example:100.00

Error codes

Business errors

Returned resultDescription
REFUNDMENT_VALID_DATE_EXCEEDCannot refund after the specified refund time.
SYSTEM_EXCEPTIONSystem exception
ILLEGAL_ARGUMENTIllegal argument
REPEATED_REFUNDMENT_REQUESTDuplicated refund request
RETURN_AMOUNT_EXCEEDRefund amount is over the payment amount
CURRENCY_NOT_SAMEDifferent currency from the payment currency
PURCHASE_TRADE_NOT_EXISTThe payment transaction does not exist
REFUND_CHARGE_ERRORThe refund is failed because the payment is in progress. Please try again later.

Access errors

Returned resultDescription
SYSTEM_EXCEPTIONAlipay system error
ILLEGAL_ARGUMENTIncorrect parameter
ILLEGAL_SIGNIllegal signature
ILLEGAL_SERVICEThe service parameter is incorrect
ILLEGAL_PARTNERIncorrect partner ID
ILLEGAL_SIGN_TYPESignature is of wrong type.
ILLEGAL_PARTNER_EXTERFACEService is not activated for this account
ILLEGAL_DYN_MD5_KEYDynamic key information is incorrect
ILLEGAL_ENCRYPTEncryption is incorrect.
ILLEGAL_USERUser ID is incorrect.
ILLEGAL_EXTERFACEInterface configuration is incorrect.
ILLEGAL_AGENTAgency ID is incorrect.
HAS_NO_PRIVILEGENo right to visit
INVALID_CHARACTER_SETThe character set is invalid.

System errors

Returned resultDescription
SYSTEM_ERRORAlipay system error
SESSION_TIMEOUTSession timeout
ILLEGAL_TARGET_SERVICEWrong target service
ILLEGAL_ACCESS_SWITCH_SYSTEMMerchant is not allowed to visit system of this type.
EXTERFACE_IS_CLOSEDThe interface has been closed.

Samples

Request

Asynchronous refund request:

https://intlmapi.alipay.com/gateway.do?service=forex_refund&partner=208xxxxxxxxx5500&_input_charset=UTF-8&sign_type=MD5&notify_url=https%3A%2F%2Fwww.mikascoffee.com%2Fnotify&currency=HKD&out_return_no=out_return_no_20190904_142347&out_trade_no=out_trade_no_20190910_140255&return_amount=0.01&gmt_return=20190910140255&reason=%E4%B9%B0%E5%AE%B6%E4%B8%BB%E5%8A%A8%E8%A6%81%E6%B1%82%E9%80%80%E6%AC%BE&sign=e1b27f1dedde149830e22da63091da7c

Synchronous refund request:

https://intlmapi.alipay.com/gateway.do?service=forex_refund&partner=208xxxxxxxxx5500&_input_charset=UTF-8&sign_type=MD5&notify_url=https%3A%2F%2Fwww.mikascoffee.com%2Fnotify&currency=HKD&out_return_no=out_return_no_20190904_142347&out_trade_no=out_trade_no_20190910_140255&return_amount=0.01&gmt_return=20190910140255&reason=%E4%B9%B0%E5%AE%B6%E4%B8%BB%E5%8A%A8%E8%A6%81%E6%B1%82%E9%80%80%E6%AC%BE&is_sync=Y&sign=83079e3e6540bf8efef87b1e76f4dbbf

Response

Synchronous response

copy
<?xml version="1.0" encoding="GBK"?>
<alipay>
    <is_success>T</is_success> 
</alipay>

Asynchronous response

copy
https://www.mikascoffee.com/notify
notify_type=refund_status_sync
return_amount=0.01
notify_time=2019-09-10 14:52:46
out_trade_no=out_trade_no_20190910_140255
refund_status=REFUND_SUCCESS
sign=$$
out_return_no=out_return_no_20190904_142347
currency=HKD
sign_type=MD5
notify_id=201xxxxxxxxxxxxxxxxxxxxxxxxxxx1673