Alipay, China's leading third-party online payment solution

- [About This Guide](./1) - [Introduction](./2) - [The Payment Workflow and User Interaction](./3) - [The Payment Workflow](./3) - [The User Interaction](./4) - [Quick Integration](./5) - [Integration Overview](./5) - [Pre-create Flow](./6) - [Cancel Flow](./8) - [Refund Flow](./7) - [Reconciliation Files](./10) - [SFTP Connection](./10) - [Transaction File Format](./11) - [Settlement File Format](./12) - [API List](./13) - [The Pre-create Interface](./13) - [The Request Parameters](./13) - [The Return Parameters](./14) - [Asynchronous Notification](./28) - [The Error Code](./15) - [The Cancel Interface](./16) - [The Request Parameters](./16) - [The Return Parameters](./17) - [The Error Code](./18) - [The Refund Interface](./19) - [The Request Parameters](./19) - [The Return Parameters](./20) - [The Error Code](./21) - [The Query Interface](./22) - [The Request Parameters](./22) - [The Return Parameters](./23) - [The Error Code](./24) - [Secondary Merchant Info Interface](./32) - [Request Parameters](./32#request) - [Return Parameters](./32#sync) - [Error Code](./32#error) - [Change History](./32#history) - [Secondary Merchant Registration Status](./33) - [Request Parameters](./33#request) - [Return Parameters](./33#sync) - [Error Code](./33#error) - [Change History](./33#history) - [Digital Signature](./29) - [Digital Algorithms](./29) - [RSA Key Generation with Open SSL](./30)

This interface provides the ability to refund a transaction both in whole and in partial. By design, the refund request cannot be reversed, use retry instead.

The gateway URL:

Environment	HTTPS request URL
Production environment	https://intlmapi.alipay.com/gateway.do
Test environment	https://mapi.alipaydev.com/gateway.do

If you want to use Alipay sandbox to test the integration, see the sandbox handbook for details.

If you use POST method, please specify the _input_charset in the request URL. For example, https://mapi.alipaydev.com/gateway.do?_input_charset=UTF-8

Request parameters

Parameter	Type(Byte)	Description	Nullable	Example
Basic parameter
service	String	Description	No	alipay.acquire.overseas.spot.refund
sign	String	Signature value. See “Digital Signature”.	No	c8il4epm90wyn768fijgqhy8tay37gqa
sign_type	String	The type could be DSA, RSA or MD5; Capital letters only.	No	MD5
partner	String	One Alipay account has only one Alipay ID. Composed of 16-digit number beginning with 2088	No	2088102012343978
_input_charset	String	Character set of parameter code. Default is GBK if not send.	Yes	UTF-8
notify_url	String	The url to which Alipay sends payment result in async mode. It is in POST method. Note: For information security, the url must be on https protocol. This URL cannot have extra parameters. For example, “https://xxx.com/foo.php?star=obama” is not allowed.	Yes	https://www.test.com/alipay/notify_url.php
Operation parameter
partner_trans_id	String(64)	The original partner transaction id given in the payment request	No	2010121000000002
alipay_trans_id	String(64)	The Alipay transaction ID.	Yes	201311221703338463
partner_refund_id	String(64)	The refund order id on partner system. partner_refund_id cannot be same as partner_transaction_id partner_refund_id together with partner identify a refund transaction	No	301012133000002
refund_amount	Number(9,2)	Less than or equal to the original transaction amount and the left transaction amount if ever refunded.	No	39.25
currency	String(10)	The refund currency. Use upper case. See Supported Currency List for details.	No	USD
refund_reason	String(128)	The reason of refund	Yes	Refund the good
is_sync	String(1)	The refund request is processed synchronously or asynchronously. Value: Y or N. 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.	Yes	Y

A request Example

https://intlmapi.alipay.com/gateway.do?partner_trans_id=9699196959845722&partner_refund_id=301012133000002&refund_amount=786.09&currency=USD&sign=30ff71107f6824dc3d28af7619870e26&sign_type=MD5&_input_charset=UTF-8&service=alipay.acquire.overseas.spot.refund&partner=2088102012343978

Parameter List

Parameters accepted by Alipay gateway:

Parameter	Type (Byte)	Description	Nullable	Example
is_success	String(1)	It indicates that a request is accepted by Alipay gateway. l T for accepted	No	T
sign_type	String	The type could be DSA, RSA or MD5; Capital letters only.	No	MD5
sign	String(32)	See “4 Digital Signature”.	No	59c7275cf3c82f038b7c0076f9888926
result_code	String(32)	To describe the response status of a request: SUCCESS, FAILED, UNKNOW.	No	SUCCESS
error	String(48)	To describe the reason of the result_code when it is failed/unknown, leave it blank when result_code is success.	Yes	TRANS_NOT_FOUND
partner_trans_id	String(64)	Equal to the partner_trans_id given in the request	No	201311221000000002
alipay_trans_id	String(64)	On the partner’s payment request, the alipay system creates a transaction id to handle it. The alipay_trans_id has one-one association with partner + partner_trans_id.	Yes	201311221703338463
partner_refund_id	String(64)	The refund order id on partner system. partner_refund_id together with partner identify a refund transaction	No	301012133000002
refund_amount	Number(9,2)	Less than or equal to the original transaction amount and the left transaction amount if ever refunded.	No	39.25
currency	String(10)	Refund currency	No	USD
exchange_rate	Number	The rate of conversion the currency given in the request to CNY. The conversion happens at the time when Alipay’s trade order is created.	Yes	6.0939
refund _amount_cny	Number(9,2)	Refund amount in CNY. It is the exact amount that the Alipay has refunded.	Yes	239.19

Parameters rejected by Alipay gateway:

Parameter	Type (length range)	Description	Nullable	Example
is_success	String(1)	It indicates that a request is rejected by Alipay gateway. l F for rejected	No	F
sign_type	String	The type could be DSA, RSA or MD5; Capital letters only.	No	MD5
sign	String(32)	See “4 Digital Signature”.	No	59c7275cf3c82f038b7c0076f9888926
error	String(48)	To describe the reason of the result_code when it is failed/unknown, leave it blank when result_code is success.	Yes	TRANS_NOT_FOUND

A response example

Normal input:

<?xmlversion="1.0"encoding="UTF-8"?> 
 <alipay> 
  <is_success>T</is_success> 
  <request> 
   <param name="_input_charset">UTF-8</param> 
   <param name="partner_trans_id">2010121000000002</param> 
   <param name="partner">2088102012343978</param> 
   <param name="service">alipay.acquire.overseas.pay</param> 
   <param name="partner_refund_id">301012133000002</param> 
   <param name="refund_amount">39.25</param> 
   <param name="currency">USD</param> 
   <param name="refund_reson">back</param> 
   <param name="sign">22904adafb1806178b410d2d5c9c02a3</param> 
   <param name="sign_type">MD5</param> 
  </request> 
  <response> 
   <alipay> 
    <partner_trans_id>2010121000000002</partner_trans_id> 
    <alipay_trans_id>201311221703338463</alipay_trans_id> 
    <partner_refund_id>301012133000002</partner_refund_id> 
    <refund_amount>39.25</refund_amount> 
    <currency>USD</currency> 
    <exchange_rate>6.0939</exchange_rate> 
    <refund_amount_CNY>239.19</refund _amount_CNY> 
    <result_code>SUCCESS</result_code> 
   </alipay> 
  </response> 
  <sign>6fb8a322f15cfd0fcfe65301b10f6994</sign> 
  <sign_type>MD5</sign_type> 
 </alipay>

Error output:

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

Error List

Error Code	Description
SYSTEM_ERROR	Alipay system is currently not available, please try again later.
ILLEGAL_SIGN	Illegal signature. Please read chapter Digital Signature
INVALID_PARAMETER	Parameter value error. Please check the standard of each request parameter according to the API specification
ILLEGAL_ARGUMENT	Parameter name error. Please check each request parameter according to the API specification, contact Alipay technical support if this error persists
ILLEGAL_PARTNER	Incorrect partner ID. Please make sure the value of partner parameter matches the partner value provided by Alipay, contact Alipay technical support if this error persists
ILLEGAL_EXTERFACE	Interface configure error. Please make sure service parameters has the same value with the one in API specification, contact Alipay technical support if this error persists
ILLEGAL_PARTNER_EXTERFACE	Partner ID do not have access privilege. contact Alipay technical support
ILLEGAL_SIGN_TYPE	Illegal sign type. Please make sure the value of sign_type is amongst MD5,DSA and RSA, contact Alipay technical support if this error persists
HAS_NO_PRIVILEGE	Has no privilege. Please contact Alipay technical support
REASON_TRADE_BEEN_FREEZEN	Corresponding trade has been frozen due to security issues. Please contact Alipay technical support
TRADE_NOT_EXIST	Cannot find corresponding trade according to input “partner_trans_id”. 1) Make sure the partner_trans_id is correct 2)if the issue persists, please contact Alipay Technical Support
TRADE_STATUS_ERROR	Corresponding trade status is not allowed for current operate. 1) Make sure the trade status is correct 2)if the issue persists, please contact Alipay technical support
REFUND_AMT_RESTRICTION	The input “refund_amount” is more than original trade amount, or total refund amount is more than original trade amount, cannot be processed by Alipay. Merchant need to check if the return amount is correct
REQUEST_AMOUNT_EXCEED	The same with “REFUND_AMT_RESTRICTION”. Merchant need to check if the return amount is correct
RETURN_AMOUNT_EXCEED	The same with “REFUND_AMT_RESTRICTION”. Merchant need to check if the return amount is correct
REFUND_CHARGE_ERROR	The refund failed because the payment is in progress. Please try again later.

Request parameter is the request data provided to Alipay by merchant when conducting data interaction with Alipay so that further process can be conducted by Alipay based on these data.

The gateway URL:

Environment	HTTPS request URL
Production environment	https://intlmapi.alipay.com/gateway.do
Test environment	https://mapi.alipaydev.com/gateway.do

If you want to use Alipay sandbox to test the integration, see the sandbox handbook for details.

If you use POST method, please specify the _input_charset in the request URL. For example, https://mapi.alipaydev.com/gateway.do?_input_charset=UTF-8

Request parameters

Parameter	Type (Byte Length)	Parameter Description	Nullable	Example
Basic Parameters
service	String	Interface name	N	alipay.acquire.cancel
partner	String(1 6)	Unique Alipay user number corresponding to authorized Alipay account number. Composed of 16 numbers beginning with 2088.	N	2088101125328850
_input_ charset	String	Encoding format used in merchant’s website, such as utf-8, gbk, gb2312, etc	N	utf-8
sign_type	String	Four values, namely, DSA, RSA, RSA2 and MD5 can be chosen; and must be capitalized	N	MD5
sign	String	Please refer to “7 Signature Mechanism”.	N	363a752668ee2b3b8f1 24c623bd028ad
timestamp	String	Time stamp of the merchant server sending request, accurate to the millisecond.	N	1456507704121
terminal_timestamp	String	Time stamp of the terminal sending request, accurate to the millisecond.	Y	1456507704102
Business Parameters
out_tra de_no	String(6 4)	Unique order No. in Alipay’s merchant’s website	N	99003911198989
trade_ no	String(6 4)	The trade serial number of the trade in Alipay system. 16 bits at least and 64 bits at most. If out_trade_no and trade_no are transmitted at the same time, trade_no shall govern.	Y	2013112611001004680 073956707

Part of the parameter type is String. Length range is not specified, which indicates that the system will not check out the length of the parameter.

Example

https://intlmapi.alipay.com/gateway.do?sign=83cff02d58eeb51f9343f475aeb06654&_input_charset=utf-8&out_trade_no=2017082100005665&partner=2088021966388155&service=alipay.acquire.cancel&timestamp=20170821193901

Synchronous Return by XML

Alipay will return result data to merchant after it has completed the processing of request data so as to facilitate further processing conducted by merchant based on these data.

The result returned can be divided into two types, one is the result of normal business acceptance and process, the other is system-level abnormity or transmitted data error. For the normal business acceptance and process, merchant is required to analyze response code to judge whether business is processed successfully.

List

Parameter	Type (length)	Description	Nullable	Example
Basic parameters
is_success	String	Request succeeds or not. Successful request does not mean the business is accepted and processed successfully. T: success F: failure	N	T
sign_type	String	Four values, namely, DSA, RSA, RSA2 and MD5 can be chosen and must be capitalized	Y	MD5
sign	String	Please refer to Signature Mechanism for details.	Y	fc209d86b57b2adb23 254a897ebaa7d9
error	String	This parameter does not exist if request succeeds; This parameter will be error code if request fails. Please refer to Error Code for details.	Y	ILLEGAL_SIGN
Business parameters
result_code	String(32)	Response code of cancel processing result. SUCCESS: successful refund FAIL: unsuccessful refund UNKNOWN: unknown result	N	SUCCESS
trade_no	String(64)	Trade number of the trade in Alipay system 16 bits at least and 64 bits at most	Y	201311201100100433 0000121536
out_trade_no	String(64)	Unique order ID in order system in corresponding merchant’s website other than Alipay trade number. Uniqueness of this parameter in merchant’s website shall be guaranteed. This is a parameter transmitted upon corresponding request, which shall be returned in its original shape.	Y	99003911198989
retry_flag	String(1)	Y: The cancel failed due to retriable error N: The cancel failed due to non-retriable error	Y	Y
action	String(10)	The action of cancel. close: only closed the transaction, but no refund. refund: had a refund.	Y	close
detail_error_code	String(48)	Give cause description to the response code returned. Please refer to Error Code for details. If the response code of result_code is SUCCESS, this parameter shall not be returned.	Y	TRADE_STATUS_ERROR
detail_error_des	String(64)	Give literal statement as to the detailed error code. If the response code of result_code is SUCCESS, this parameter shall not be returned.	Y	Trade status is illegal.

With the evolution of Alipay server, the parameters returned synchronously may return more child nodes, procedure user is required to ignore the child nodes beyond the document description.

Example

Business is accepted and processed normally, and cancel is conducted successfully:

<?xml version="1.0" encoding="utf-8"?> 
 <alipay> 
     <is_success>T</is_success> 
     <request> 
       <param name="sign">66b3a14ec95846f01d42564e6953c81b</param> 
       <param name="_input_charset">UTF-8</param> 
       <param name="sign_type">MD5</param> 
       <param name="service">alipay.acquire.cancel</param> 
       <param name="partner">2088101126765726</param> 
       <param name="out_trade_no">99003911198989</param> 
       <param name="timestamp">1456507705033</param> 
     </request> 
     <response> 
       <alipay> 
         <result_code>SUCCESS</result_code> 
         <out_trade_no>3406822113320232</out_trade_no> 
         <trade_no>2013111511001004390000105126</trade_no> 
         <action>refund</action> 
       </alipay> 
     </response> 
     <sign>3afc92ac4708425ab74ecb2c4e58ef56</sign> 
     <sign_type>MD5</sign_type> 
 </alipay>

Request succeeds, business processing fails:

<?xml version="1.0" encoding="utf-8"?> 
 <alipay> 
   <is_success>T</is_success> 
   <request> 
     <param name="sign">66b3a14ec95846f01d42564e6953c81b</param> 
     <param name="_input_charset">UTF-8</param> 
     <param name="sign_type">MD5</param> 
     <param name="service">alipay.acquire.cancel</param> 
     <param name="partner">2088101126765726</param> 
     <param name="out_trade_no">99003911198989</param> 
     <param name="timestamp">1456507705033</param> 
   </request> 
   <response> 
     <alipay> 
      <result_code>FAIL</result_code> 
      <detail_error_code>TRADE_STATUS_ERROR</detail_error_code> 
      <detail_error_des>illegal trade status</detail_error_des> 
     </alipay> 
    </response> 
    <sign>fc209d86b57b2adb23254a897ebaa7d9</sign> 
    <sign_type>RSA</sign_type> 
 </alipay>

Request fails or the data accessed are incorrect

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

Error List

Error Code	Description	Action
SYSTEM_ERROR	Alipay system is currently not available.	Retry this request with the exact parameters. Refer Case 2 at here for detailed instruction.
ILLEGAL_SIGN	Illegal signature.	Please read chapter Digital Signature
INVALID_PARAMETER	Parameter error.	Please check the standard of each request parameter according to the API specification
ILLEGAL_ARGUMENT	Parameter error.	Please check each request parameter according to the API specification, contact Alipay technical support if this error persists
ILLEGAL_PARTNER	Incorrect partner ID.	Please make sure the value of partner parameter matches the partner value provided by Alipay, contact Alipay technical support if this error persists
ILLEGAL_EXTERFACE	Interface configure error.	Please make sure that the service parameters has the same value with the one in API specification, contact Alipay technical support if this error persists
ILLEGAL_PARTNER_EXTERFACE	Partner ID do not have access privilege.	Make sure your agreement with Alipay has been finalized. Contact Alipay technical support if needed.
ILLEGAL_SIGN_TYPE	Illegal sign type.	Please make sure the value of sign_type is among MD5,DSA and RSA, contact Alipay technical support if this error persists
HAS_NO_PRIVILEGE	Has no privilege.	Please contact Alipay technical support
REASON_TRADE_BEEN_FREEZEN	Corresponding trade has been frozen due to security issues.	Please contact Alipay technical support
TRADE_NOT_EXIST	Cannot find corresponding trade according to input “partner_trans_id”.	1) Make sure the partner_trans_id is correct 2)if the issue persists, please contact Alipay Technical Support
TRADE_STATUS_ERROR	Corresponding trade status is not allowed for current operate.	1) Make sure the trade status is correct 2)if the issue persists, please contact Alipay technical support
BUYER_ERROR	The buyer does not exist.	Please contact Alipay technical support.
BUYER_ENABLE_STATUS_FORBID	Buyer account status prohibits the refund.	Please contact Alipay technical support.
SELLER_ERROR	The seller does not exist.	Please contact Alipay technical support.
MERCHANT_BALANCE_NOT_ENOUGH	Merchant balance is not enough for refund.	Try again later after new transactions occurred.
TRADE_CANCEL_TIME_OUT	The cancellation request is beyond the opening hours.	Please use the refund interface instead.
SELLER_BALANCE_NOT_ENOUGH	Insufficient balance of seller.	Try again later after new transactions occurred.
REASON_TRADE_REFUND_FEE_ERR	Invalid refund amount.	Please contact Alipay technical support for help.
TRADE_HAS_FINISHED	Transaction completed.	Please use the refund interface instead.
REFUND_CHARGE_ERROR	The refund failed because the payment is in progress.	Please try again later.

Handling result of alipay.acquire.cancel

Case 1. When the invocation failed with network issue or request timeouted, so got no response from Alipay

Check your network connectivity to Alipay gateway. Retry(Every 3 seconds, up to 5 times.) this request with the exact parameters until you get a response from Alipay.
If still not work, request Alipay tech support for help.

Case 2. Received response from Alipay, but (1) is_success=F and error=SYSTEM_ERROR, or (2) is_success=T and result_code=FAIL and detail_error_code=SYSTEM_ERROR, or (3) is_success=T and result_code=UNKNOWN.

Retry(Every 3 seconds, up to 5 times.) this request with the exact parameters until you get a response from Alipay.
If still not work, request Alipay tech support for help.

Case 3. Received response from Alipay, and is_success=T and result_code=SUCCESS. Mark merchant cancel order as processed successfully

Case 4. Received response from Alipay, and (1) is_success=F and error=!SYSTEM_ERROR, or (2) is_success=T and result_code=FAIL and detail_error_code!=SYSTEM_ERROR. Mark merchant cancel order as failed. Refer specific error code for instrunction

Pseudo code:

try{
  if(isCase3){ //CASE 3
    doSuccessProcess();
  }
  else if(isCase4){ //CASE 4
    doFailureProcess();
  }
  else{ //CASE 2
   
    retrySuccess = retryWithSameParameters(); //Retry every 3 seconds, up to 5 times.

    if(retrySuccess){
      doSuccessProcess();
    }
    else{
      //request Alipay tech support.
    }
  }

}catch (Exception ex){ // CASE 1

    retrySuccess = retryWithSameParameters(); //Retry every 3 seconds, up to 5 times.

    if(retrySuccess){
      doSuccessProcess();
    }
    else{
      //request Alipay tech support.
    }
  }
}

This interface provides the ability to query a transaction with partner_trans_id or alipay_trans_id.

The gateway URL:

Environment	HTTPS request URL
Production environment	https://intlmapi.alipay.com/gateway.do
Test environment	https://mapi.alipaydev.com/gateway.do

If you want to use Alipay sandbox to test the integration, see the sandbox handbook for details.

If you use POST method, please specify the _input_charset in the request URL. For example, https://mapi.alipaydev.com/gateway.do?_input_charset=UTF-8

Request parameters

Parameter	Type (Byte)	Description	Nullable	Example
Basic parameter
service	String	Interface name.	No	alipay.acquire.overseas.query
sign	String	Signature value. See “Digital Signature”.	No	c8il4epm90wyn768fijgqhy8tay37gqa
sign_type	String	The type could be DSA, RSA or MD5; Capital letters only.	No	MD5
partner	String	One Alipay account has only one Alipay ID. Composed of 16-digit number beginning with 2088	No	2088102012343978
_input_charset	String	Character set of parameter code. Default is GBK if not send.	Yes	UTF-8
Operation parameter
partner_trans_id	String(64)	The original partner transaction id given in the payment request	No	2010121000000002
alipay_trans_id	String(64)	On the partner’s payment request, the alipay system creates a transaction id to handle it. The alipay_trans_id has one-one association with partner + partner_trans_id.	YES	201311221703338463

A request example

https://intlmapi.alipay.com/gateway.do?partner_trans_id=9699196959845722&sign_type=MD5&_input_charset=UTF-8&service=alipay.acquire.overseas.query&partner=2088102012343978

Parameter List

Parameter	Type (Byte)	Description	Nullable	Example
is_success	String(1)	It indicates that a request is accepted by Alipay gateway. l T for accepted	No	T
sign_type	String	The type could be DSA, RSA or MD5; Capital letters only.	No	MD5
sign	String(32)	See “4 Digital Signature”.	No	59c7275cf3c82f038b7c0076f9888926
result_code	String(32)	To describe the response status of a request: SUCCESS, FAIL	No	SUCCESS
error	String(48)	To describe the reason of the result_code when it is failed/unknown, leave it blank when result_code is success.	Yes	TRANS_NOT_FOUND
alipay_trans _status	String(32)	WAIT_BUYER_PAY, TRADE_SUCCESS, TRADE_CLOSED	Yes	TRADE_SUCCESS
alipay_buyer_login_id	String(20)	The buyer’s Alipay login Id, the id might be an email or mobile number. The id is partially masked for privacy.	YES	cao*@126.com or 186*22156
alipay_buyer_user_id	String(16)	This ID stands for each Alipay account number ,unique in Alipay system start with “2088”	No	2088102130896433
partner_trans_id	String(64)	Equal to the partner_trans_id given in the request	No	201311221000000002
alipay_trans_id	String(64)	On the partner’s payment request, the alipay system creates a transaction id to handle it. The alipay_trans_id has one-one association with partner + partner_trans_id.	YES	201311221703338463
alipay_pay_time	String(16)	The time of the transaction has been paid. Format：YYYYMMDDHHMMSS	YES	201311212323
currency	String(8)	The currency used for labeling the price of the transaction;	No	USD
trans_amount	Number(9,2)	the transaction amount in the currency given above; Range: 0.01-100000000.00. Two digits after decimal point.	No	39.25
exchange_rate	Number(8,6)	The rate of conversion the currency given in the request to CNY. The conversion happens at the time when Alipay’s trade order is created.	YES	6.0939
trans _amount_cny	Number(9,2)	Transaction amount in CNY. It is the exact amount that the buyer has paid	YES	239.19
m_discount_forex_amount	Number(9,2)	If coupons/vouchers are used in the transaction, the discount amount redeened in the settlement currency will be returned. Otherwise, no return.	Yes	2.19
forex_total_fee	Number(9,2)	Transaction amount in the settlement currency. Note: This parameter only applies to some Alipay businesses.	YES	42.19
trans_forex_rate	Number(8,6)	Exchange rate between the price currency and settlement currency. Note: This parameter only applies to some Alipay businesses.	YES	6.0939

Parameters rejected by Alipay gateway:

Parameter	Type (Byte)	Description	Nullable	Example
is_success	String(1)	It indicates that a request is rejected by Alipay gateway. l F for rejected	No	F
sign_type	String	The type could be DSA, RSA or MD5; Capital letters only.	No	MD5
sign	String(32)	See “4 Digital Signature”.	No	59c7275cf3c82f038b7c0076f9888926
detail_error_code	String(48)	To describe the reason of the result_code when it is failed/unknown, leave it blank when result_code is success.	Yes	TRANS_NOT_FOUND
detail_error_des	String(48)	To describe the reason of the result_code when it is failed/unknown, leave it blank when result_code is success.	Yes

Please also note that details_error_code and details_error_description parameter value are subject to be newly introduced further; please consider when coding to handle forward compatibility for this further error code introduction.

A response example

Normal input:

<?xmlversion="1.0"encoding="UTF-8"?> 
 <alipay> 
  <is_success>T</is_success> 
  <request> 
   <param name="_input_charset">UTF-8</param> 
   <param name="partner_trans_id">2010121000000002</param> 
   <param name="partner">2088102012343978</param> 
   <param name="service">alipay.acquire.overseas.query</param> 
   <param name="sign">22904adafb1806178b410d2d5c9c02a3</param> 
   <param name="sign">c7d17d40111b8264975a6bfba77962cb</param> 
  </request> 
  <response> 
   <alipay> 
    <alipay_trans_id>2011091703338463</alipay_trans_id> 
    <partner_trans_id>201311221000000002</partner_trans_id> 
    <alipay_buyer_login_id>cao***@126.com</alipay_buyer_login_id> 
    <alipay_pay_time>20131120155823</alipay_pay_time> 
    <exchange_rate>6.0939</exchange_rate> 
    <trans_amount>39.25</trans_amount> 
    <trans_amount_CNY>239.19</trans_amount_CNY> 
    <result_code>SUCCESS</result_code> 
    <alipay_trans _status>TRADE_SUCCESS</alipay_trans _status> 
   </alipay> 
  </response> 
  <sign>6fb8a322f15cfd0fcfe65301b10f6994</sign> 
  <sign_type>MD5</sign_type> 
 </alipay>

Error output:

<?xml version="1.0" encoding="UTF-8"?> 
 <alipay> 
  <is_success>F</is_success> 
  <error>ILLEGAL_SIGN</error> 
  <sign>02f6b289c46b8d0c1ea62b4f78637c1a</sign> 
  <sign_type>MD5</sign_type> 
 </alipay>

Error List

Error Code	Description	Action
SYSTEM_ERROR	Alipay system failed to process the request due to temporary internal glitch.	Retry this request with the exact parameters. Refer Case 2 at here for detailed instruction.
ILLEGAL_SIGN	Illegal signature.	Please read chapter Digital Signature
INVALID_PARAMETER	Parameter value error.	Please check the standard of each request parameter according to the API speficaition
ILLEGAL_ARGUMENT	Parameter name error.	Please check each request parameter according to the API specification, contact Alipay technical support if this error persists
ILLEGAL_PARTNER	Incorrect partner ID.	Please make sure the value of partner parameter matches the partner value provided by Alipay, contact Alipay technical support if this error persists
ILLEGAL_EXTERFACE	Interface configure error.	Please make sure service parameters has the same value with the one in API specification, contact Alipay technical support if this error persists
ILLEGAL_PARTNER_EXTERFACE	Partner ID do not have access privilege.	contact Alipay technical support
ILLEGAL_SIGN_TYPE	Illegal sign type.	Please make sure the value of sign_type is amongst MD5,DSA and RSA, contact Alipay technical support if this error persists
HAS_NO_PRIVILEGE	Has no privilege.	Please contact Alipay technical support
REASON_TRADE_BEEN_FREEZEN	Corresponding trade is been frozen due to security issues.	Please contact Alipay technical support
TRADE_NOT_EXIST	Cannot find corresponding trade according to inputted “partner_trans_id”. 1) Make sure the partner_trans_id is correct 2)if the issue persists, please contact Alipay technical support	1) Make sure the partner_trans_id is correct 2)if the issue persists, please contact Alipay technical support

Handling result of alipay.acquire.query

Case 1. When the invocation failed with network issue or request timeouted, so got no response from Alipay

Check your network connectivity to Alipay gateway. Retry(Every 3 seconds, up to 10 times.) this request with the exact parameters until you get a response from Alipay.
If still not work, request Alipay tech support for help.

Case 2. Received response from Alipay, but (1) is_success=F and error=SYSTEM_ERROR, or (2) is_success=T and result_code=FAIL and detail_error_code=SYSTEM_ERROR

Retry(Every 3 seconds, up to 10 times.) this request with the exact parameters until you get a response from Alipay.
If still not work, request Alipay tech support for help.

Case 3. Received response from Alipay, and is_success=T and result_code=SUCCESS. Query succeeded.

Case 4. Received response from Alipay, and (1) is_success=F and error=!SYSTEM_ERROR, or (2) is_success=T and result_code=FAIL and detail_error_code!=SYSTEM_ERROR. Query failed. Refer specific error code for instrunction

Pseudo code:

try{
  if(isCase3){ //CASE 3
    doSuccessProcess();
  }
  else if(isCase4){ //CASE 4
    doFailureProcess();
  }
  else{ //CASE 2
   
    retrySuccess = retryWithSameParameters(); //Retry every 3 seconds, up to 10 times.

    if(retrySuccess){
      doSuccessProcess();
    }
    else{
      //request Alipay tech support.
    }
  }

}catch (Exception ex){ // CASE 1
   
    retrySuccess = retryWithSameParameters(); //Retry every 3 seconds, up to 10 times.

    if(retrySuccess){
      doSuccessProcess();
    }
    else{
      //request Alipay tech support.
    }
  }
}

Generate Pre-sign string

Parameters to sign

In the list of request and response parameters, all of them need to be signed except sign and sign_type. (sign_type also needs to be signed in some cases in the list of request parameters)

Generate Pre-sign string

Use the following code to package the data:


		//package the request parameters
		Map sParaTemp = new HashMap();
		sParaTemp.put("service", AlipayConfig.service);
                sParaTemp.put("partner", AlipayConfig.partner);
                sParaTemp.put("_input_charset", AlipayConfig.input_charset);
		sParaTemp.put("notify_url", AlipayConfig.notify_url);
		sParaTemp.put("return_url", AlipayConfig.return_url);
		sParaTemp.put("out_trade_no", out_trade_no);
		sParaTemp.put("subject", subject);
		sParaTemp.put("total_fee", total_fee);
		sParaTemp.put("body", body);
		sParaTemp.put("currency", currency);
		sParaTemp.put("product_code", product_code);
		split_fund_info = split_fund_info.replaceAll("\"", "'");
		sParaTemp.put("split_fund_info", split_fund_info);

		sParaTemp.put("secondary_merchant_id",secondary_merchant_id);
		sParaTemp.put("secondary_merchant_name",secondary_merchant_name);
		sParaTemp.put("secondary_merchant_industry",secondary_merchant_industry);

Rearrange parameters in the data set alphabetically
And connect rearranged parameters with &：

_input_charset=utf-8&app_pay=Y&body=test&currency=USD&notify_url=http://d4779318.ngrok.io/new_create_forex_trade_wap_JAVA-UTF-8-RSA/notify_url.jsp&out_trade_no=test20170901162***&partner=2088101122136***&product_code=NEW_WAP_OVERSEAS_SELLER&return_url=http://d4779318.ngrok.io/new_create_forex_trade_wap_JAVA-UTF-8-RSA/return_url.jsp&service=create_forex_trade_wap&subject=test123&total_fee=0.01

This is the pre-sign string.

Parameters without a value, can be excluded from sign;
Charset in sign must be consistent with the charset used previously
If _input_charset is passed, it also shall be signed.
According to HTTP protocol, special character like &,@ needs to do URL encoding, therefore the request receiver can get correct value. In this situation, pre-sign string shall be the original value instead of encoded one. For example: calling a particular API need to sign the parameter email, the pre-sign string shall be email=test@msn.com, rather than email=test%40msn.com.

Signature Generation

MD5 Signature

Private Key is necessary for MD5 signature. The MD5 private key is the 32-byte string which is composed of English letters and numbers. Partner can log on the Merchant Service Center (https://global.alipay.com) to check the private key.

Sign for request

After the partner receives the pre-sign string during requesting, the private key should be appended to the pre-sign string to generate the new string. Then this new string would be calculated with the MD5 signature algorithm by the MD5 signature function. Thus, the result 32-byte string is the signature result string. (the value is given to parameter “sign”)

Signature Verification for response

After receiving the pre-sign string during responding from Alipay system, the next step is the same as the procedure of Sign for request. When the 32-byte signature result string is generated, it should be verified whether the value is equal to the value of the parameter “sign”. If equal, the verification would be passed.

RSA, RSA2 Signature

Both private key and public key are necessary for RSA signature. Both private key and public key are generated with OPENSSL by partner. Partner and Alipay need to exchange their own public key. Therefore, partner uses Alipay public key and partner private key.

Sign for request

After the partner receives the pre-sign string during requesting, the partner private key and the pre-sign string are used in the RSA signature algorithm by the RSA signature function to get the result string. (the value is given to parameter “sign”)

Signature Verification for response

After receiving the pre-sign string during responding from Alipay system, the Alipay public key, the pre-sign string and the parameter “sign” are used in the RSA signature asymmetric algorithm by the RSA signature function to accomplish the signature verification.

This interface provides the ability to refund a transaction both in whole and in partial. By design, the refund request cannot be reversed, use retry instead.

The gateway URL:

Environment	HTTPS request URL
Production environment	https://intlmapi.alipay.com/gateway.do
Test environment	https://mapi.alipaydev.com/gateway.do

If you want to use Alipay sandbox to test the integration, see the sandbox handbook for details.

If you use POST method, please specify the _input_charset in the request URL. For example, https://mapi.alipaydev.com/gateway.do?_input_charset=UTF-8

Request parameters

Parameter	Type(Byte)	Description	Nullable	Example
Basic parameter
service	String	Description	No	alipay.acquire.overseas.spot.refund
sign	String	Signature value. See “Digital Signature”.	No	c8il4epm90wyn768fijgqhy8tay37gqa
sign_type	String	The type could be DSA, RSA or MD5; Capital letters only.	No	MD5
partner	String	One Alipay account has only one Alipay ID. Composed of 16-digit number beginning with 2088	No	2088102012343978
_input_charset	String	Character set of parameter code. Default is GBK if not send.	Yes	UTF-8
notify_url	String	The url to which Alipay sends payment result in async mode. It is in POST method. Note: For information security, the url must be on https protocol. This URL cannot have extra parameters. For example, “https://xxx.com/foo.php?star=obama” is not allowed.	Yes	https://www.test.com/alipay/notify_url.php
Operation parameter
partner_trans_id	String(64)	The original partner transaction id given in the payment request	No	2010121000000002
alipay_trans_id	String(64)	The Alipay transaction ID.	Yes	201311221703338463
partner_refund_id	String(64)	The refund order id on partner system. partner_refund_id cannot be same as partner_transaction_id partner_refund_id together with partner identify a refund transaction	No	301012133000002
refund_amount	Number(9,2)	Less than or equal to the original transaction amount and the left transaction amount if ever refunded.	No	39.25
currency	String(10)	The refund currency. Use upper case. See Supported Currency List for details.	No	USD
refund_reason	String(128)	The reason of refund	Yes	Refund the good
is_sync	String(1)	The refund request is processed synchronously or asynchronously. Value: Y or N. 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.	Yes	Y

A request Example

https://intlmapi.alipay.com/gateway.do?partner_trans_id=9699196959845722&partner_refund_id=301012133000002&refund_amount=786.09&currency=USD&sign=30ff71107f6824dc3d28af7619870e26&sign_type=MD5&_input_charset=UTF-8&service=alipay.acquire.overseas.spot.refund&partner=2088102012343978

OpenSSL installation

Linux（Ubuntu）
```
sudo apt-get install openssl
```

Windows
The developer can download Windows version of OpenSSL from the official site of https://www.openssl.org/source/.

RSA key pair generation

Linux

$ openssl
  OpenSSL> genrsa -out rsa_private_key.pem 1024 ##generating  private key
  OpenSSL> pkcs8 -topk8 -inform PEM -in rsa_private_key.pem  -outform PEM -nocrypt ##transform private key into PKCS8 format
  OpenSSL> rsa -in rsa_private_key.pem -pubout -out  rsa_public_key.pem ##Generate public key
  OpenSSL> exit

Windows operates in cmd window:

C:\Users\Hammer>cd C:\OpenSSL-Win32\bin ##enter OpenSSL directory
  C:\OpenSSL-Win32\bin>openssl.exe ##enter OpenSSL
  OpenSSL> genrsa -out rsa_private_key.pem 1024  ##generating private key
  OpenSSL> pkcs8 -topk8 -inform PEM -in rsa_private_key.pem  -outform PEM -nocrypt ##transform private key into PKCS8 format
  OpenSSL> rsa -in rsa_private_key.pem -pubout -out  rsa_public_key.pem ##Generate public key
  OpenSSL> exit

For Java developers, we need to remove the header, footer, <CR>, and space from the pkcs8 private key output in the console. For.NET and PHP developer, there is no need for the pkcs8 operation.

After the above steps, the user could see two files under the current folder (C:\OpenSSL-Win32\bin for Windows), rsaprivatekey.pem and rsapublickey.pem.
The former is the private key while the latter is the public key. The merchant should keep the private key and exchange the public key with Alipay for signature verification. The following are the examples on how to use the key pair.

Standard private key file（PHP,.NET）

Standard private key file in PKCS8 format(Java)

-----BEGIN PRIVATE  KEY-----MIICeAIBADANBgkqhkiG9w0BAQEFAASCAmIwggJeAgEAAoGBAN0yqPkLXlnhM+2H/57aHsYHaHXazr9pFQun907TMvmbR04wHChVsKVgGUF1hC0FN9hfeYT5v2SXg1WJSg2tSgk7F29SpsF0I36oSLCIszxdu7ClO7c22mxEVuCjmYpJdqb6XweAZzv4Is661jXP4PdrCTHRdVTU5zR9xUByiLSVAgMBAAECgYEAhznORRonHylm9oKaygEsqQGkYdBXbnsOS6busLi6xA+iovEUdbAVIrTCG9t854z2HAgaISoRUKyztJoOtJfI1wJaQU+XL+U3JIh4jmNx/k5UzJijfvfpT7Cv3ueMtqyAGBJrkLvXjiS7O5ylaCGuB0Qz711bWGkRrVoosPM3N6ECQQD8hVQUgnHEVHZYtvFqfcoq2g/onPbSqyjdrRu35a7PvgDAZx69Mr/XggGNTgT3jJn7+2XmiGkHM1fd1Ob/3uAdAkEA4D7aE3ZgXG/PQqlm3VbE/+4MvNl8xhjqOkByBOY2ZFfWKhlRziLEPSSAh16xEJ79WgY9iti+guLRAMravGrs2QJBAOmKWYeaWKNNxiIoF7/4VDgrcpkcSf3uRB44UjFSn8kLnWBUPo6WV+x1FQBdjqRviZ4NFGIP+KqrJnFHzNgJhVUCQFzCAukMDV4PLfeQJSmna8PFz2UKva8fvTutTryyEYu+PauaX5laDjyQbc4RIEMU0Q29CRX3BA8WDYg7YPGRdTkCQQCG+pjU2FB17ZLuKRlKEdtXNV6zQFTmFc1TKhlsDTtCkWs/xwkoCfZKstuV3Uc5J4BNJDkQOGm38pDRPcUDUh2/-----END PRIVATE  KEY-----

Public key file

-----BEGIN PUBLIC  KEY-----MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDQWiDVZ7XYxa4CQsZoB3n7bfxLDkeGKjyQPt2FUtm4TWX9OYrd523iw6UUqnQ+Evfw88JgRnhyXadp+vnPKP7unormYQAfsM/CxzrfMoVdtwSiGtIJB4pfyRXjA+KL8nIa2hdQy5nLfgPVGZN4WidfUY/QpkddCVXnZ4bAUaQjXQIDAQAB-----END PUBLIC  KEY-----

Upload the public key

Contact Global Merchant Technical Support to upload the public key. Please sign with the matching private key in the key pair.

This file consists of two parts: the header and record detail.

File header

The file header contains a list of the following fields (the field names are not showing in the file):

Occurring sequence in the header	Field	Type	Description
1	Partner	String(16)	2088123456543210
2	Payment_time	String(10)	The day that transaction happens, the format is YYYY-MM-DD HH:MM:SS
3	Total_count	Number(9)	The total number of the records in this file

Record Detail

No.	Field	Type(Byte)	Description
1	Partner_transaction_id	String(64)	A numbered transaction ID(unique in partner system)it is equal to “partner_trans_id” when transaction type is in (payment,reversal,reverse); it is equal to “partner_refund_id” when transaction type is refund
2	Transaction_id	String(64)	A numbered transaction ID （Unique inside the Alipay system）
3	Transaction_amount	Number(9,2)	Same to the definition given in the interface part; It is in the currency given below.
4	Charge_amount	Number(9,2)	Commission fee
5	Currency	String(8)	The currency given in the transaction request.
6	Payment_time	String(19)	The time of transaction; Format: YYYY-MM-DD HH:MM:SS
7	Transaction_type	String(8)	Transaction type： PAYMENT REVERSE REFUND
8	Remark	String(256)	Remark
9	Secondary_merchant_industry	String(4)	Industry classification identifier
10	Secondary_merchant_name	String	Secondary merchant name (or a taxi company name)
11	Secondary_merchant_id	String	Secondary merchant id
12	Operator_name	String	Operator name (store name field)
13	Order_scene	String	Order scenarios: Scan Merchant QR code mode: shopQrCode Barcode mode: paymentQrCode Scan Transaction QR code mode: transactionQrCode
14	Trans_currency	String(8)	List currency
15	Trans_amount	Number(9,2)	Amount in list currency/refund amount in list currency
16	Trans_forex_rate	String	Exchange rate of list currency against settlement currency
17	Issue	String	Indicates the payment type:ALIPAYCN for Alipay mainland user, ALIPAYHK for Alipay HK user.

An example of file content:

Partner:208800000000|Payment_time: 2017-04-27|Total_count:3

test001|2017042721001000000000000001|352.50|4.23|HKD|2017-04-27 07:20:14|PAYMENT||||331|||||1|ALIPAYCN

test002|2017042721001000000000000002|37.50|0.45|HKD|2017-04-27 08:30:21|PAYMENT||||302|||||1|ALIPAYCN

test003|2017042721001000000000000003|120.00|1.44|HKD|2017-04-28 11:08:26|REVERSAL||||349|||||1|ALIPAYHK

Record detail

No.	Field	Type	Description
1	Partner_transaction_ id	String(64)	A numbered transaction ID （Unique inside the partner system）,it is equal to “partner_trans_id” when type is normal transaction ; it is equal to “partner_refund_id” when type is refundament transaction; it is equal to “partner_trans_id” when the “partner_refund_id” is blank, such as 2010121000000002
2	Transaction_id	String(64)	A numbered transaction ID （Unique inside the Alipay system）such as 2015021021001001230099088888
3	Amount	Number(9,2)	The amount of fund in foreign currency.
4	Fee	Number(9,2)	The amount of commission fee in foreign currency
5	Settlement	Number(9,2)	Settlement amount in foreign currency
6	Currency	String(10)	Abbreviated currency code, such as USD
7	Payment_time	tring(19)	YYYY-MM-DD HH:MM:SS Empty if the status being “failed” or “waiting”, e.g. 2016-02-10 01:01:01
8	Settlement_time	String(19)	YYYY-MM-DD HH:MM:SS Empty if unliquidated
9	Type	String(1)	Normal transaction：P Refunding transaction：R
10	Status	String(1)	Normal transaction: P : Payment made L: Liquidated Refundament transaction : W:wait to be proceed P:refund success F: failed L:Liquidated
11	Remarks	String(256)	An optional field. If the transaction is refundament, reason field will be displayed in this column ,if the transaction is a payment ,subject field will be displayed in this column
12	Secondary_merchant_industry	String(4)	Industry classification identifier（ MCC ）
13	Secondary_merchant_name	String	Secondary merchant name (or a taxi company name)
14	Secondary_merchant_id	String	Secondary merchant id
15	Operator_name	String	Operator name (store name field)
16	Order_scene	String	Order scenarios: Scan Merchant QR code mode: shopQrCode Barcode mode: paymentQrCode Scan Transaction QR code mode: transactionQrCode
17	Trans_currency	String(10)	List currency
18	Trans_amount	Number(9,2)	Transaction amount in list currency/refund amount in list currency
19	Trans_forex_rate	String	Exchange rate of list currency against settlement currency
20	Issue	String	Indicates the payment type:ALIPAYCN for Alipay mainland user, ALIPAYHK for Alipay HK user.

An example of file content:

test001|2017042721001000000000000001|352.50|4.23|348.27|HKD|2017-04-27 07:20:14|2017-04-28 15:36:00|P|L||||331|||||1|ALIPAYCN

test002|2017042721001000000000000002|37.50|0.45|37.05|HKD|2017-04-27 08:30:21|2017-04-28 15:36:00|P|L||||302|||||1|ALIPAYCN

Call this interface to register offline secondary merchants information into Alipay system.

The gateway URL:

Environment	HTTPS request URL
Production environment	https://intlmapi.alipay.com/gateway.do
Test environment	https://mapi.alipaydev.com/gateway.do

If you want to use Alipay sandbox to test the integration, see the sandbox handbook for details.

If you are still using the previous sandbox gateway https://openapi.alipaydev.com, please use the https://mapi.alipaydev.com/gateway.do gateway instead. This gateway adjustment is caused by a system difference between the Alipay international sandbox test environment and the Alipay domestic sandbox test environment.
For a GET request or POST request, if the value of request parameters contains special characters or Chinese characters, you need to URL encode values of all the parameters in the request URL.
For a POST request, you need to include the _input_charset field in the gateway URL. For example，if the value of request parameters contains Chinese characters, the gateway URL is: https://intlmapi.alipay.com/gateway.do?_input_charset=utf-8

Request Parameters

Parameter	Type (bytes)	Description	Optional	Example
Basic Parameter
service	String	Service Name	N	alipay.overseas.secmerchant.offline.maintain
partner	String(16)	A unique partner ID to identify a contracted Alipay Account. A 16 digit number starts with 2088.	N	2088*********662
_input_charset	String	The charset with which the request data is encoded. For example, UTF-8, GBK, GB2312 etc.	N	gbk
sign_type	String	DSA, RSA, or MD5, use upper case	N	MD5
sign	String	The value of sign	N	2118ac8fad6bc1d9e88a6cd017c18d37
timestamp	String	The time when the merchant server sends request, in GMT + 8, format: yyyy-MM-dd HH:mm:ss. By default, the request expires in 30 minutes.	N	2012-12-21 17:11:16
Business Parameter
secondary_merchant_name	String(128)	Registration legal name of the secondary merchant, which is shown in the wallet and reconciliation file to identify a secondary merchant. Note: If the secondary merchant type is INDIVIDUAL, specify the full legal name of the business owner to this field.	N	Alipay.com Co.,Ltd
secondary_merchant_id	String(64)	The unique ID assigned by the partner to identify a secondary merchant. The ID can contain letters, numbers, and underscores.	N	63472327348
store_id	String(64)	Store ID. For taxicabs and limousines (MCC 4121), use the license plate number.	N	23372327348
store_name	String(256)	Store name. For taxicabs and limousines (MCC 4121), use the license plate number.	N	StoreName
store_country	String(2)	Store registration country. A 2-letter code defined in ISO 3166.	N	HK
store_address	String(330)	Registered store address. Use mailing address format.	N	Store address
store_industry	String(4)	A 4-digit MCC code of the store. See MCC list for details.	N	4121
internal_store_photo	String(256)	URL of the store interior photo.	Y	URL
external_storefront_photo	String(256)	URL of the store exterior photo.	Y	URL
extend_params	String(1024)	Taxi driver information in JSON format. JSON keys are fixed as operation_id, contact_way, and contact_person. Up to 10 drivers can be passed. Note: The value of each operation_id must be unique. This field cannot be updated incrementally. Pass this field the first time you register a driver; otherwise you cannot add it later when you update the driver information.	Y	[{"operation_id": "1000332", "contact_way": "138xxxx1232", "contact_person": "driverName1"}, {"operation_id": "1082943492", "contact_way": "158xxxx2232", "contact_person": "driverName2"}]
secondary_merchant_type	String	Secondary merchant type, the value can be INDIVIDUAL for the sole proprietorship or ENTERPRISE for the limited company, private company, partnership, limited liability partnership (LLP), limited liability company (LLC), S corporation (S Corp), C corporation (C Corp), trust, or nonprofit organization (NPO)	N	INDIVIDUAL
registration_no	String(128)	Business registration number specified on the business registration document. Note: This field is not required when the secondary merchant type is INDIVIDUAL and no registration number exists.	N	012345678
register_country	String(2)	Registration country of the secondary merchant, specified by a 2-letter code defined in ISO 3166. For more details about the 2-letter country code, see ISO 3166.	N	HK
register_address	String(256)	Business registration address specified on the business registration document. Use mailing address format.	N	No.277, Road YinCheng, Shanghai, China
shareholder_name	String(128)	Legal name of the primary shareholder of the secondary merchant. Specify this field only when the secondary merchant type is ENTERPRISE.	Y	Jack Li (if the shareholder is an individual), Alipay.com Co.,Ltd (if the shareholder is an enterprise)
shareholder_id	String(128)	ID or passport number, or business registration number of the primary shareholder of the secondary merchant. Specify this field only when the secondary merchant type is ENTERPRISE.	Y	G53453888 (if the shareholder is an individual), 012345678 (if the shareholder is an enterprise)
representative_name	String(128)	Full legal name of the business owner. Specify this field only when the secondary merchant type is INDIVIDUAL. This field is optional if the secondary merchant type is ENTERPRISE.	N	Tom Li
representative_id	String(128)	ID or passport number of the business owner. Specify this field only when the secondary merchant type is INDIVIDUAL. This field is optional if the secondary merchant type is ENTERPRISE.	N	123456789
settlement_no	String(64)	Settlement bank account number of the secondary merchant, letters and numbers only	N	2600100000
contact_no	String(64)	Contact phone number of the secondary merchant, numbers and special characters +-() only	N	186xxxx0000
contact_email	String(128)	Contact email address of the secondary merchant	N	tomli@gmail.com
cs_no	String(64)	Customer service phone number of the secondary merchant, numbers and special characters +-() only	Y	952xx
cs_email	String(128)	Customer service email address of the secondary merchant	Y	customerservice@xxxcompany.com

extend_params

Parameter	Type (bytes)	Description	Optional	Example
operation_id	String(64)	Taxi driver ID. Use only numbers and letters.	N	1082943492
contact_way	String(256)	Phone number of the taxi driver. Use “+”, numbers, spaces, and “-“.	Y	158xxxx2232
contact_person	String(64)	Taxi driver name	N	driverName2

Some parameters of String type have no length limit and the system will not check their length.

Sync Response

The response is in XML format.

Parameter	Type (bytes)	Description	Optional	Example
Basic Parameter
is_success	String	Request succeeds or not. Successful request does not mean the business request is accepted and processed successfully. T means success F means failure	N	T
sign_type	String	The value can be one of DSA, RSA, or MD5. Uppercase must be used.	Y	MD5
sign	String	The value of sign	Y	3afc92ac4708425ab74ecb2c4e58ef56
error	String	If the request succeeds, this parameter does not exist. When a request fails, the value of this parameter is the error code. See Access Errors and System Errors for details.	Y	PARAM_ILLEGAL
result_code	String	Request result code. This field is returned only when the is_success field is T.	Y	SUCCESS

The synchronous response may have more parameters due to the upgrade on the Alipay server side. You can ignore parameters that are not included in this API document.

Samples

Request Examples

The sample is for reference only. Alipay gateway is https://mapi.alipay.com/gateway.do?_input_charset=UTF-8.

Examples

Request succeeds


<?xml version="1.0" encoding="utf-8"?>
<alipay>
    <is_success>T</is_success>
    <request>
        <param name="service">alipay.overseas.secmerchant.offline.maintain</param>
        <param name="partner">2088101142878662</param>
        <param name="_input_charset">UTF-8</param>
        <param name="sign_type">MD5</param>
        <param name="sign">2118ac8fad6bc1d9e88a6cd017c18d37</param>
        <param name="timestamp">2018-08-03 00:28:32</param>
        <param name="secondary_merchant_name">hanguo</param>
        <param name="secondary_merchant_id">2015051446800462</param>
        <param name="store_id">23372327348</param>
        <param name="store_name">LV</param>
        <param name="store_country">HK</param>
        <param name="store_address">store address</param>
        <param name="store_industry">4121</param>
        <param name="secondary_merchant_type">INDIVIDUAL</param>
        <param name="registration_no">012345678</param>
        <param name="register_country">HK</param>
        <param name="register_address">No.277, Road YinCheng, Shanghai, China</param>
        <param name=“representative_name”>Tom Li</param>
        <param name=“representative_id”>123456789</param>
        <param name="settlement_no">2600100000</param>
        <param name="contact_no">186xxxx0000 </param>
        <param name="contact_email">support@xcompany.com </param>
    </request>
<response>
    <alipay>
        <result_code>SUCCESS</result_code>
    </alipay>
</response>
<sign>744a87f0e3b40e6a8cd8f9705ce61511</sign>
<sign_type>MD5</sign_type>
</alipay>

Request fails or the access data are wrong:


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

Error Codes

Business Logic Errors

Returned result	Description	Solution
MCC_CAN_NOT_MODIFY	The MCC passed in cannot match the original MCC.	Please ensure that the passed MCC is the same as the original MCC.
MCC_TYPE_ILLEGAL	The MCC is invalid.	Modify the MCC type and then try again.
PARAM_ILLEGAL	The parameter is illegal. The parameter is too long, parameter format is wrong, or a required parameter is not passed.	Please check and rectify the parameter according to the API document.
SYSTEM_ERROR	Alipay system error	Please try again later.
LBS_GEOGRAPHIC_INFORMATION_INVALID	The address cannot match the country/region, or the address cannot be located.	Please ensure that the address is valid and use the address that can be located in Google map.
CATEGORY_NOT_SUPPORT_DRIVER	When store_industry is 4121 and extend_params is not passed when you request in the first time, then this error occurs when you update the store information and pass the driver information.	Please remove the driver information from the extend_param.
DUPLICATE_REQUEST	Duplicate request submitted. The previous registration request is still in process.	Please wait until the previous registration request completes.
MERCHANT_TYPE_ILLEGAL	Illegal secondary merchant type. The value of the secondary_merchant_type field can only be ENTERPRISE or INDIVIDUAL.	Enter the correct value for the secondary_merchant_type field.

Access Errors

Returned result	Description
ILLEGAL_SIGN	Illegal signature
ILLEGAL_DYN_MD5_KEY	Dynamic key information is incorrect
ILLEGAL_ENCRYPT	Encryption is incorrect
ILLEGAL_ARGUMENT	Incorrect parameter
ILLEGAL_SERVICE	Service parameter is incorrect
ILLEGAL_USER	User ID is incorrect
ILLEGAL_PARTNER	Incorrect Partner ID
ILLEGAL_EXTERFACE	Interface configuration is incorrect
ILLEGAL_PARTNER_EXTERFACE	Partner's interface information is incorrect
ILLEGAL_SECURITY_PROFILE	Matching private key configuration is not found
ILLEGAL_AGENT	Agency ID is incorrect
ILLEGAL_SIGN_TYPE	The signature type is incorrect
ILLEGAL_CHARSET	The character set is illegal
HAS_NO_PRIVILEGE	Has no right to visit
INVALID_CHARACTER_SET	The character set is invalid

System Errors

When system error occurs, please contact Global Merchant Technical Support .

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

Change history

Date	Modifications
2019.02.18	Added the following fields: secondary_merchant_type, registration_no, register_country, register_address, shareholder_name, shareholder_id, representative_name, representative_id, settlement_no, contact_no, contact_email, cs_no, cs_email Added the DUPLICATE_REQUEST error code. Updated the description of the secondary_merchant_name field.
2019.02.28	Added the result_code field in the Sync Response part. Updated the solution part of the LBS_GEOGRAPHIC_INFORMATION_INVALID error code.

Date

Modifications

2019.02.18

Added the following fields: secondary_merchant_type, registration_no, register_country, register_address, shareholder_name, shareholder_id, representative_name, representative_id, settlement_no, contact_no, contact_email, cs_no, cs_email
Added the DUPLICATE_REQUEST error code.
Updated the description of the secondary_merchant_name field.

2019.02.28

Added the result_code field in the Sync Response part.
Updated the solution part of the LBS_GEOGRAPHIC_INFORMATION_INVALID error code.

Call this interface to query the registration status of secondary merchants.

The gateway URL:

Environment	HTTPS request URL
Production environment	https://intlmapi.alipay.com/gateway.do
Test environment	https://mapi.alipaydev.com/gateway.do

If you want to use Alipay sandbox to test the integration, see the sandbox handbook for details.

If you are still using the previous sandbox gateway https://openapi.alipaydev.com, please use the https://mapi.alipaydev.com/gateway.do gateway instead. This gateway adjustment is caused by a system difference between the Alipay international sandbox test environment and the Alipay domestic sandbox test environment.
For a GET request or POST request, if the value of request parameters contains special characters or Chinese characters, you need to URL encode values of all the parameters in the request URL.
For a POST request, you need to include the _input_charset field in the gateway URL. For example，if the value of request parameters contains Chinese characters, the gateway URL is: https://intlmapi.alipay.com/gateway.do?_input_charset=utf-8

Request Parameters

Parameter	Type (length in bytes)	Description	Optional	Example
Basic Parameter
service	String	Service Name	N	alipay.overseas.secmerchant.maintain.queryStatus
partner	String(16)	A unique partner ID to identify a contracted Alipay Account. A 16 digit number starts with 2088.	N	2088101142878662
_input_charset	String	The charset on partner website, such as utf-8, gbk, gb2312 etc.	N	gbk
sign_type	String	DSA, RSA, or MD5, capital letter	N	MD5
sign	String	The value of sign	N	2118ac8fad6bc1d9e88a6cd017c18d37
timestamp	String	The time when the merchant server sends request, in GMT + 8, format: yyyy-MM-dd HH:mm:ss. By default, the request expires in 30 minutes.	N	2012-12-21 17:11:16
Business Parameter
secondary_merchant_id	String(64)	Secondary merchant ID, need to be unique for each PID	N	MERCHANT_ID_0003
store_id	String(64)	Store ID, need to be unique for each group of PID and MID This field is required when the value of payment_method is INSTORE_PAYMENT.	N	STORE_ID_0003
payment_method	String	Payment method of the secondary merchant, the value is INSTORE_PAYMENT for offline payments.	N	INSTORE_PAYMENT

Sync Response

The response is in XML format.

Parameter	Type (bytes)	Description	Optional	Example
sign	String	The value of sign	Y	2118ac8fad6bc1d9e88a6cd017c18d37
sign_type	String	DSA, RSA, or MD5, capital letter	Y	MD5
secondary_merchant_id	String	Secondary merchant ID, need to be unique for each PID	N	MERCHANT_ID_0003
store_id	String	Store ID, need to be unique for each group of PID and MID This field is required when the value of payment_method is INSTORE_PAYMENT.	N	STORE_ID_0003
status	String	Registration status of the secondary merchant, the value can be SUCCESS if the merchant is successfully registered, UNDER_REVIEW if the application for registration is in process, and FAILED if the merchant is not registered.	N	SUCCESS
reject_reason	String	The reason that the merchant is not registered successfully.	Y	High risk merchant, registration reject.

Business Logic Errors

Returned result	Description	Solution
PARAM_ILLEGAL	Required parameters are not entered or illegal parameters entered. The illegal parameter might be too long, or with incorrect format.	Enter the correct parameters and send the request again.
DATA_NOT_EXIST	No data exists for the queried secondary merchant because the merchant is not registered.	Register the secondary merchant to Alipay system before you query the registration status.
SYSTEM_ERROR	Alipay system error	Please try again later.

Response Examples

The request succeeds and the query result is returned:


<?xml version="1.0" encoding="utf-8"?>
<alipay>
    <is_success>T</is_success>
<request>
    <param name="store_id">STORE_ID_0003</param>
    <param name="partner">2088101131367863</param>
    <param name="service">alipay.overseas.secmerchant.maintain.queryStatus</param>
    <param name="sign">9c4643447830d870b56c8181643da9e4</param>
    <param name="sign_type">MD5</param>
    <param name="_input_charset ">gbk</param>
    <param name="timestamp ">2012-12-21 17:11:16</param>
    <param name="_input_charset ">gbk</param>
    <param name="payment_method">INSTORE_PAYMENT</param>
    <param name="secondary_merchant_id">MERCHANT_ID_0003</param>
</request>
<response>
    <alipay>
        <secondary_merchant_id>MERCHANT_ID_0003</secondary_merchant_id>
        <status>UNDER_REVIEW</status>
        <store_id>STORE_ID_0003</store_id>
    </alipay>
</response>
<sign>a109ce66ba5b825759927c00be3259fa</sign>
<sign_type>MD5</sign_type>
</alipay>

Failed to get the query result:


<?xml version="1.0" encoding="utf-8"?>
<alipay>
<is_success>F</is_success>
<error>DATA_NOT_EXIST</error>
<sign>6dff2d017f284ca0147fc8f6891b4cb2</sign>
<sign_type>MD5</sign_type>
</alipay>

Change history

Version 1 released on Feb, 18, 2019.

About This Guide

Audience

Conventions

QR Code

Interface

Customer Support

The gateway URL:

Request parameters

A request Example

Parameter List

A response example

Error List

The gateway URL:

Request parameters

Example

Synchronous Return by XML

List

Example

Error List

Handling result of alipay.acquire.cancel

Pseudo code:

The gateway URL:

Request parameters

A request example

Parameter List

A response example

Error List

Handling result of alipay.acquire.query

Pseudo code:

Generate Pre-sign string

Parameters to sign

Generate Pre-sign string

Signature Generation

MD5 Signature

RSA, RSA2 Signature

The gateway URL:

Request parameters

A request Example

OpenSSL installation

RSA key pair generation

Upload the public key

The gateway URL:

Request Parameters

extend_params

Sync Response

Samples

Request Examples

Examples

Request succeeds

Request fails or the access data are wrong:

Error Codes

Business Logic Errors

Access Errors

System Errors

Change history

The gateway URL:

Request Parameters

Sync Response

Business Logic Errors

Response Examples

The request succeeds and the query result is returned:

Failed to get the query result:

Change history