forex_refund

2021-02-26 07:00

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

Parameter Description

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 are encoded. UTF-8 is supported

Example:UTF-8

sign_type

String Required

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

Example:RSA

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

String(64) Required

The unique refund ID for the refund request

Example:205485121225

out_trade_no

String(64) Required

The transaction ID of the original payment

Example:990xxxxxxx8989

return_amount

Number(9,2)

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. The return_amount and return_rmb_amount fields cannot be empty at the same time, therefore, one of them must be specified.

Example:100.30

return_rmb_amount

Number(9,2)

The refund amount in CNY. The value is in the range of 0.01 - 1000000.00, with at most 2 digits after the decimal point. Either the return_amount or return_rmb_amount field can be specified.

Example:10.20

currency

String(10) Required

The currency for the refund. The value of this field is not CNY, even when the return_rmb_amount parameter is not null. Use upper case. For more information about supported currencies, see Supported Currencies.

Example:USD

gmt_return

String(14) 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

String(100)

Reason for the refund

Example:Out of supply

product_code

String(32) Required

Product code of the Alipay product that you use, which is NEW_OVERSEAS_SELLER for website payment refund, and NEW_WAP_OVERSEAS_SELLER for WAP or APP payment refund.

Example:NEW_OVERSEAS_SELLER

is_sync

String(1)

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

split_fund_info

String(1600)

Split fund information, which is in the JSON format. For more details, see Refund Split Detail Info.

Example:[{"transOut":"2088101137935255","amount":"0.10","currency":"USD","desc":"test1"},{"transOut":"2088101126707869","amount":"0.10","currency":"USD","desc":"test2"}]

Note:

The decimal place accuracy of amounts, such as the values of return_amount, depends on the value of currency. If the value of currency isJPY, then the amount must be an integer. For example, 100 JPY. For other currencies, the amount is of two decimal place accuracy. For example, 100.00 USD. Amounts in other formats will cause error, for example, 100.999 USD. The values of parameters such as return_rmb_amount are also of two decimal places because the currency is CNY. is_sync YNTF

Response

Synchronous response

Parameter Description

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 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:REPEATED_REFUNDMENT_REQUEST

Asynchronous response

Parameter Description

Basic parameter

notify_type

String

Notification type

Example:refund_status_sync

notify_time

Timestamp

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

Example:2009-08-12 11:08:32

notify_id

String

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

Example:70fec0c2730b27528665af4517c27b95

sign_type

String

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

Example:MD5

sign

String

Sign value

Example:656578b72f40e52326dba4a41d6da62b

Business parameter

out_trade_no

String(64)

The unique transaction ID that is assigned by the merchant for the refund

Example:990xxxxxxx8989

out_return_no

String(64)

Refund ID of the partner

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

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(8)

The currency for the refund

Example:CNY

return_amount

Number(9,2)

Refund amount

Example:100.00

Error codes

Business errors

Returned result	Description
REFUNDMENT_VALID_DATE_EXCEED	The refund cannot be performed after the specified refund time period.
SYSTEM_EXCEPTION	System exception
ILLEGAL_ARGUMENT	Illegal argument
REPEATED_REFUNDMENT_REQUEST	Duplicated refund request
RETURN_AMOUNT_EXCEED	Refund amount is over the payment amount.
CURRENCY_NOT_SAME	Different currency from the payment currency
PURCHASE_TRADE_NOT_EXIST	The payment transaction does not exist.
BUYER_NOT_EXIST	The buyer does not exist.
REFUND_CHARGE_ERROR	The refund failed because the payment is in progress. Please try again later.
MORE_THAN_ALLOW_REFUND_FOREX_FEE	The refund amount is more than the refundable amount.

Access errors

Returned result	Description
ILLEGAL_SIGN	Illegal signature
ILLEGAL_SERVICE	Service parameter is incorrect.
ILLEGAL_PARTNER	Incorrect partner ID
ILLEGAL_SIGN_TYPE	Signature is of wrong type.
ILLEGAL_PARTNER_EXTERFACE	Service is not activated for this account.
ILLEGAL_DYN_MD5_KEY	Dynamic key information is incorrect.
ILLEGAL_ENCRYPT	Encryption is incorrect.
ILLEGAL_USER	User ID is incorrect.
ILLEGAL_EXTERFACE	Interface configuration is incorrect.
ILLEGAL_AGENT	Agency ID is incorrect.
HAS_NO_PRIVILEGE	No right to visit
INVALID_CHARACTER_SET	The character set is invalid.

System errors

Returned result	Description
SYSTEM_ERROR	Alipay system error
SESSION_TIMEOUT	Session timeout
ILLEGAL_TARGET_SERVICE	Wrong target service
ILLEGAL_ACCESS_SWITCH_SYSTEM	Merchant is not allowed to visit system of this type.
EXTERFACE_IS_CLOSED	The interface has been closed.

Samples

Request

Request sample with the return_amount field specified

https://intlmapi.alipay.com/gateway.do?service=forex_refund&partner=2088021017666931&_input_charset=UTF-8&sign_type=MD5&notify_url=https%3A%2F%2Fwww.mikascoffee.com%2Fnotify&currency=USD&product_code=NEW_OVERSEAS_SELLER&out_return_no=out_return_no_20190904_142347&out_trade_no=out_trade_no_20190830_204330&return_amount=0.01&gmt_return=20190904142347&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=8080dd500a1ecb05a393e168d57090d2

Request sample with the return_rmb_amount field specified

https://intlmapi.alipay.com/gateway.do?service=forex_refund&partner=2088021017666931&_input_charset=UTF-8&sign_type=MD5&notify_url=https%3A%2F%2Fwww.mikascoffee.com%2Fnotify&currency=USD&product_code=NEW_OVERSEAS_SELLER&out_return_no=out_return_no_20190904_142347&out_trade_no=out_trade_no_20190830_204330&return_rmb_amount=0.07&gmt_return=20190904142347&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=4c13c00a832ebbd2a08379dd3d8e2ec6

Response

Synchronous response sample

Success response

copy

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

Error response

copy

<?xml version="1.0" encoding="utf-8"?>
<alipay>
    <is_success>F</is_success>
    <error>ILLEGAL_SIGN</error>
</alipay>

Asynchronous response sample

copy

https://www.mikascoffee.com/notify
notify_type=refund_status_sync
return_amount=0.01
notify_time=2019-09-04 18:07:27
out_trade_no=out_trade_no_20190826_204553
refund_status=REFUND_SUCCESS
sign=$$$
out_return_no=out_return_no_20190904_142349
currency=USD
sign_type=MD5
notify_id=201xxxxxxxxxxxxxxxxxxxxxxxxxxxx9467