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

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

ParameterDescription
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