1
- [About This Guide](./1) - [Terminologies](./2) - [Product Introduction](./3) - [The Payment Workflow and User Interaction](./4) - [The Payment Workflow](./4) - [The User Interaction](./5) - [System Integration](./6) - [Integration Overview](./6) - [Standard solution](./41) - [System Interaction Flow](./41) - [Prerequisites: Prepare your account info](./11) - [1. Configure the authorization callback page URL](./39) - [2. Obtain the Alipay user ID](./35) - [3. Create Order using alipay.acquire.create](./7) - [4. Apply payment using jsapi:tradePay](./37) - [5. Receive Async payment result notifications](./36) - [6. Integrate the Cancel Interface](./34) - [7. Integrate the Refund Interface](./9) - [8. Integrate the Query Interface](./43) - [Simplified Solution](./40) - [System Interaction Flow](./40) - [1. Pre-create order using alipay.acquire.precreate](./38) - [2. Receive Async payment result notifications](./46) - [3. Integrate the Cancel Interface](./44) - [4. Integrate the Refund Interface](./45) - [5. Integrate the Query Interface](./47) - [Testing Credentials](./48) - [Demo Code Download](./60#DemoDownload) - [API List](./49) - [The Pre-create Interface](./49) - [The Request Parameters](./49) - [The Return Parameters](./50) - [Asynchronous Notification](./58) - [The Error Code](./51) - [The Create Interface](./52) - [The Request Parameters](./52) - [The Return Parameters](./53) - [Asynchronous Notification](./59) - [The Error Code](./54) - [The OAuth Interface](./55) - [The Request Parameters](./55) - [The Return Parameters](./56) - [The Cancel Interface](./19) - [The Request Parameters](./19) - [The Return Parameters](./20) - [The Error Code](./21) - [The Refund Interface](./22) - [The Request Parameters](./22) - [The Return Parameters](./23) - [The Error Code](./24) - [The Query Interface](./28) - [Request Parameters](./28) - [Return Parameters](./29) - [Error Code](./30) - [The Secondary Merchant Info Interface](./62) - [The Request Parameter](./62#request) - [The Return Parameter](./62#sync) - [The Error Code](./62#error) - [Digital Signature](./25) - [Digital Algorithms](./25) - [RSA Key Generation with Open SSL](./26) - [Reconciliation Files](./12) - [Obtaining Reconciliation Files](./61) - [Transaction File Format](./13) - [Settlement File Format](./14) - [Contact US](./42)
Third-party Merchant QR Code payment

About This Guide

This guide provides an overview of the Third-party Merchant QR Code payment and it’s overall workflow, and then introduces the detailed integration steps.

Target Audience

This guide is intended for developers and testers of Alipay partners who want to integrate Alipay Third-party Merchant QR Code payment solution.

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

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)

refund currency

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> 
   <sign>02f6b289c46b8d0c1ea62b4f78637c1a</sign> 
   <sign_type>MD5</sign_type> 
 </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

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

TRADE_HAS_CLOSE

The transaction is closed and refunds are not allowed anymore.

Check the status of this transaction and the refund time window setting.

MERCHANT_BALANCE_NOT_ENOUGH

Insufficient balance of the merchant to process this refund request. The previous transactions may have been settled to the merchant bank account.

Retry the refund after new transactions occur and the merchant's balance is sufficient.

INVALID_ROUNDED_AMOUNT

The refund with this amount may have violated the rule that the calculated amount of both CNY and foreign currency should be fully or not fully refunded at the same time.

  • Take a transaction with 0.07 CNY (0.01 USD) as an example. A refund with 0.06 CNY would not be accepted because this comes to a situation where there is 0.01 CNY (0 USD) left for this transaction.
  • Please contact Alipay technical support.

    REASON_TRADE_REFUND_FEE_ERR

    Invalid refund amount.

    Check the request refund amount.

    Handling result of alipay.acquire.overseas.spot.refund

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

    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.

    Case 3. Received response from Alipay, and is_success=T and result_code=SUCCESS. Mark merchant refund 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 refund 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 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.

    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

    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

    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.

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

    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.

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

    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.

    OpenSSL installation

    RSA key pair generation

    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.

    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.

    During the payment process of a transaction, it is possible to encounter issues such as system exception or network accessibility. In such a scenario, you need to reverse the transaction. To implement this reversing, we would like to highlight the notes of below:

    1. In this integration, please use the CANCEL to reverse a transaction, and the interface name is: alipay.acquire.cancel;
    2. For a transaction that has been successfully paid, the CANCEL is able to refund the transaction within the transaction day (GMT+8).;
    3. Comparing with the REFUND service, if a transaction can be refunded by this CANCEL interface, the transaction fee that hass been charged by Alipay will always be refunded as well;
    4. For a transaction has encountered technical issues during making the payment, the CANCEL is able to roll back all the actions have been performed in the Alipay system regarding the specific transaction;
    5. For the full list of parameters and error code of this CANCEL service, please refer the interface API document for details. 

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

    Request Parameters

    Parameter

    Type (Byte)

    Parameter Description

    Nullable

    Example

     

    service

    String

    Interface name

    N

    alipay.acquire.precreate

    partner

    String(1

    6)

    Unique Alipay user number corresponding to authorized Alipay account number.

    Composed of 16 numbers beginning with 2088.

    N

    2088101568358171

    _input_charset

    String

    Encoding format used in merchant’s website, such as  utf-8, gbk, gb2312, etc

    N

    utf-8

    sign_type

    String

    Three values, namely, DSA, RSA and MD5 can be chose; and must be capitalized

    N

    MD5

    sign

    String

    See Digital Algorithm for details.

    N

    85bf83f78d5cefb804bd

    805532fc688e

    notify_url

    String(190)

    Alipay server takes the initiative to notify merchant of webpage http path designated by website.

    Y

    http://api.test.alipay.net/atinterface/receive_notify.htm

    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

    out_trade_no

    String(64)

    Unique order ID in Alipay’s merchant website

    N

    99003911198989

    subject

    String(256)

    Goods title/trade tile/order subject/order key word etc.

    The length of this parameter is up to 128 Chinese characters.

    N

    Payment by QR-Code

    product_code

    String(32)

    Order placement used to distinguish the business type:

  • OVERSEAS_MBARCODE_PAY: face to face payment overseas
  • N

    OVERSEAS_MBARCODE_PAY

    total_fee

    number (9,2)

    Total fee of this order. The range of values is [0.01, 100000000], such value can have up to two digits after the decimal point.

    N

    10

    seller_id

    String(28)

    Unique Alipay user ID corresponding to Seller’s Alipay account

    16 numbers beginning with 2088.

    If both sell_id and seller-email are null, the default value of this parameter to be filled out shall be the value of merchant.

    Y

    2088101106499364

    seller_email

    String(100)

    Seller’s Alipay account, may be email or phone number

    If seller_id is not null, the value of seller_id shall be the seller’s ID and this parameter can be neglected.

    Y

    test@alitest.com

    body

    String(400)

    Specific description of the trade. In case of a variety of goods, please accumulate the character strings descrbing the goods, and transmit the same to body.

    Y

    iphone cellphone

    show_url

    String(400)

    Hyperlink for the show of goods on the webpage of checkout counter.

    Y

    http://www.taobao.com/product/113714.html

    currency

    String(8)

    Settlement currency.

    Currency and trans_currency cannot be different foreign currency.

    N

    CNY

    trans_currency

    String(8)

    Pricing currency for the transaction, if it is not CNY, the CNY amount user will be charged will be calculated based on trans_currency and exchange rate.

    N

    CNY

    price

    Number (9,2)

    Unit price of the goods in the order. If this parameter is transmitted at request, the condition of total_fee=price×quantity must be met.

    Y

    1

    quantity

    String(100)

    Quantity of the goods in the order. If this parameter is transmitted at request, the condition of total_fee=price×quantity must be met.

    Y

    10

    goods_detail

    String

    Description of the details of goods in the format of json

    The maximum allowable goods number is 50.

    Y

    [{"goodsId":"apple-01","goodsName":"ipad","goodsCategory":"7788230","price":"2000.00","qu antity":"1"}]

    extend_params

    String(512)

    This parameter contains extended parameters of the request, and transmits business information of the merchant. Format: JSON. For details, see here

    N

    {"store_id":"BJ_ZZ_001","store_name":"Muku in the Dreieichstrabe","secondary_merchant_id":"A80001","secondary_merchant_name":"Muku","secondary_merchant_industry":"7011"}

    it_b_pay

    String(200)

    Set the overtime of non-payment trade, the trade will be closed automatically once the time is up, 3m by default.

    Range of values: 1m to 15d.

    m-minute, h-hour, d-day, 1c-current day (Whenever the trade is created, it will be closed at 0:00).

    Demical point of the numerical value of this parameter is rejected, for example, 1.5h can be tansformed to 90m.

    To realize this function, Alipay is needed to be advised to set close time.

    Y

    1d

    passback_parameters

    String(256)

    If merchant transfer this parameter by the request string, Alipay will feedback this parameter by the asynchronous notify (parameter name: extra_common_param).

    Y

    test

    Description of the extend_params

    Parameter Name Type Description Nullable Sample
    secondary_merchant_id Secondary merchant ID String A unique ID assigned by the partner to identify a secondary merchant. The ID can contain letters, numbers, and underscores. N A80001
    secondary_merchant_name Secondary merchant name String A name is shown in the Alipay Wallet and the reconciliation file to identify a secondary merchant. N Muku
    secondary_merchant_industry MCC code of the merchant String For MCC code definitions, see MCC list N 7011
    store_name Store name String Store name. Can be null only when the store information is verified. N Muku in the Dreieichstrabe
    store_id Store ID String Store ID, must be passed. N BJ_ZZ_001
    terminal_id Terminal ID String Terminal ID Y T80001

    sys_service_provider_id

    The technical provider id

    String(32)

    The technical provider id. This parameter identifies the payment system provider.

     

    Y

     R00998889911

    Part of parameter type is String, range of length is not specified, which means the system will not check out the length of this parameter.

    Description of Goods Details

    Goods details parameters shall be in the format of JSON and include the following parameters:

    Parameter

    Parameter Name

    Type (Byte Length)

    Parameter Description

    Nullable

    Example

    goodsId

    Goods ID

     

    String

    Goods ID

     

    N

    apple-01

    goodsName

    Goods name

     

    String

    Goods Name

     

    N

    ipad

    goodsCategory

    Goods category

     

    String

    Goods Category

     

    Y

    34543238

    showUrl

    Website for the show of goods

     

    String

    Hyperlink for the show of goods on the webpage of checkout counter.

     

    Y

    http://www.taobao.com

    quantity

    Goods quatity

    String

    Goods quatity

     

    N

    1

    body

    Goods description

    String

    Goods description

    Y

    Cellphone at a sale

    price

    Unit price of goods

    String

     

    Unit price of goods

     

    N

    2000

    The format structure:

    [ 
     {Goods_ID: goods ID 1, 
      goodsname: goods name 1,
      goods_category: goods category 1, 
      Website for the show of goods: website 1 for the show of goods, 
      goods quantity: goods quantity 1, 
      goods description: goods description 1, 
      unit price of goods: unit price 1 of goods
      }, 
     {Goods ID: goods ID 2, 
      goods name: goods name 2, 
      goods category: goods category 2, 
      Website for the show of goods: website 2 for the show of goods, 
      goods quantity: goods quantity 2, 
      goods description: goods description 2, 
      unit price of goods: unit price 2 of goods
      }, 
     … 
     ]
     
    Example:
    Business demand:
     goods ID: apple-01, 
     goods name: ipad,
     goods category: 
     7788230, quantity: 1,
     price: RMB 2,000 Yuan; 
    
     Parameter assignment: 
     goods_detail=[
      {"goodsId":"apple-01",
       "goodsName":"ipad",
       "goodsCategory" :"7788230",
       "price":"2000.00",
       "quantity":"1"}
       ] 
     

    Example

    https://intlmapi.alipay.com/gateway.do?_input_charset=UTF-8&body=iphone cellphone¤cy=USD&extend_params={"secondary_merchant_name":"Lotte","secondary_merchant_id":"123","secondary_merchant_industry":"5812","store_id":"A101","store_name":"McDonald in 966 3rd Ave, New York"}¬ify_url=http://api.test.alipay.net/atinterface/receive_notify.htm&out_trade_no=4363476566647440&partner=2088021966388155&passback_parameters=test&price=0.01&product_code=OVERSEAS_MBARCODE_PAY&quantity=1&seller_email= testoverseas1980@alipay.com&seller_id=2088021966388155&sendFormat=normal&service=alipay.acquire.precreate&show_url=http://www.taobao.com/product/113714.html&subject=Payment by QR-Code&total_fee=0.01&trans_currency=USD&sign=2127020ad640f41eec725c639f1de294

    The gateway of Alipay is https://intlmapi.alipay.com/gateway.do.

    Synchronous Return by XML

    Alipay processes the request data provided by merchant and then returns result data to merchant to enable merchant to conduct further processing 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.

    Parameter List

    Parameter

    Type (Byte)

    Parameter Description

    Nullable

    Example

    Basic Parameter

    is_success

    String

    Request succeeds or not. Successful request does not mean the business is accepted and processed successfully.

    Ÿ   T means success

    Ÿ   F means failure

    N

    T

    sign_type

    String

    Three values, namely, DSA, RSA and MD5 can be chose; and must be capitalized

    Y

    MD5

    sign

    String

    See Digital signature for details.

    Y

    ea489fc31da63253ba b52ed77fb45eb7

    error

    String

    This parameter does not exist if request succeeds;

    This parameter is error coade if request fails; please refer to “10.3 System Error Code”

    Y

    ILLEGAL_SIGN

    Result Code

    result_code

    String(32)

    Response code of the processing result of order placement and payment; please refer to “10.1 Business Response Code”

     N

    SUCCESS

    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

    voucher_type

    String(10)

    Voucher type, currently qrcode is the only supported value

    Y

    qrcode

    qr_code

    String(128)

    Value of the QR code

    Y

    https://qr.alipay.com/pmxqwqka1ts5grar29

    big_pic_url

    String

    QR code big picture URL

    Y

    http://mobilecodec. alipay.com/show.htm?code=baxga4hjmcal5rl8fa&picSize=L

    pic_url

    String

    QR code normal size URL

    Y

    http://mobilecodec. alipay.com/show.htm?code=baxga4hjmcal5rl8fa&picSize=M

    small_pic_url

    String

    QR code big size URL

    Y

    http://mobilecodec. alipay.com /show.htm?code=baxga4hjmcal5rl8fa&picSize=S

    detail_er ror_code

    String(48)

    Describes the returned response code. If the response code of result_code is ORDER_SUCCESS_PAY_S UCCESS, this parameter shall not be returned.

    Y

    REASON_ILLEGAL_STATUS

    detail_er ror_des

    String(64)

    Give literal statement as to the detailed error code. If the response code of result_code is ORDER_SUCCESS_PAY_S UCCESS, this parameter shall not be returned.

    Y

    Trade does not match with buyer

    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 acquiring is created successfully:

    <?xml version="1.0" encoding="UTF-8"?> 
    <alipay> 
        <is_success>T</is_success> 
        <request> 
            <param name="body">bodyyy</param> 
            <param name="operator_id">1232</param> 
            <param name="subject">dddd</param> 
            <param name="sign_type">RSA</param> 
            <param name="store_id">123</param> 
            <param name="out_trade_no">3177578879372734</param> 
            <param name="sendFormat">normal</param> 
            <param name="currency">GBP</param> 
            <param name="timestamp">1456507704121</param> 
            <param name="sign">T/9olfnp/rGwmSV0dCkJVvcMuJM2pbstsSFVH54FdN9AbWRbGKNzXwbELbLSJgNZWQej8QqHJauQztG/nC9McWSbeaNsmOrrLnZ+T5XQjCJHilBbupFBsLgF1vzSHe02bICumIjw8r81ysyTHXFmqROaG9hqs0TvFkDpA7O4Ft4=</param> 
            <param name="_input_charset">UTF-8</param> 
            <param name="trans_currency">GBP</param> 
            <param name="total_fee">8.8</param> 
            <param name="product_code">OVERSEAS_MBARCODE_PAY</param> 
            <param name="service">alipay.acquire.precreate</param> 
            <param name="partner">2088101181776059</param> 
            <param name="seller_id">2088101181776059</param> 
            <param name="alipay_ca_request">2</param> 
            <param name="extend_params">{"store_id":"BJ_ZZ_001","store_name":"Muku in the Dreieichstrabe","secondary_merchant_id":"A80001","secondary_merchant_name":"Muku","secondary_merchant_industry":"7011"}</param> 
        </request> 
        <response> 
            <alipay> 
                <big_pic_url>http://mobilecodec.daily.alipaydev.com/show.htm?code=bax009917nmpivmndisb00e6&picSize=L</big_pic_url> 
                <out_trade_no>3177578879372734</out_trade_no> 
                <pic_url>http://mobilecodec.daily.alipaydev.com/show.htm?code=bax009917nmpivmndisb00e6&picSize=M</pic_url> 
                <qr_code>https://qr.alipay.com/bax009917nmpivmndisb00e6</qr_code> 
                <result_code>SUCCESS</result_code> 
                <small_pic_url>http://mobilecodec.daily.alipaydev.com/show.htm?code=bax009917nmpivmndisb00e6&picSize=S</small_pic_url> 
                <voucher_type>qrcode</voucher_type> 
            </alipay> 
        </response> 
        <sign>ZDWE75ZB0YptqcxKC09g2dSuHEDnWbZ3j+tdpfAt1Il2FmJgJ7Mz9MX/QY0UxZXLP+bYjjC27OJgbhHljVUfrSYN/Ls4vvV/yg6I2/wetK/4Etdt/RJ2og7yRXhE+XzKaG7Q9rYhwnMq3lxukWZA2gep5T69P8yQS8Lz5KZrgjU=</sign> 
        <sign_type>RSA</sign_type> 
    </alipay>
    		

    Request succeeds, business processing fails:

    <?xml version="1.0" encoding="utf-8"?> 
     <alipay> 
      <is_success>T</is_success> 
      <request> 
       <param name="body">face-to-face-payment</param> 
       <param name="subject">iphone</param> 
       <param name="sign_type">MD5</param> 
       <param name="out_trade_no">99003911198989</param> 
       <param name="total_fee">10</param> 
       <param name="partner">2088101106499364</param> 
       <param name="quantity">10</param> 
       <param name="sign">a1cb41a4019351965d4418c9cb933f0f</param> 
       <param name="_input_charset">UTF-8</param> 
       <param name="price">1</param> 
       <param name="it_b_pay">1d</param> 
       <param name="product_code">OVERSEAS_MBARCODE_PAY</param> 
       <param name="service">alipay.acquire.precreate</param> 
       <param name="seller_id">2088101106499364</param> 
      </request> 
      <response> 
      <alipay>
       <result_code>FAIL</result_code> 
       <detail_error_code>INVALID_PARAMETER</detail_error_code> 
       <detail_error_des>request paramter invalid</detail_error_des> 
       </alipay> 
      </response> 
      <sign>ea489fc31da63253bab52ed77fb45eb7</sign> 
      <sign_type>MD5</sign_type> 
     </alipay> 
     

    Output when Request fails or the data accessed is wrong:

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

    Asynchronous Notification  

    Alipay will notify merchant’s website of the result data it processed through initiative notification from server after it completes the processing of request data of merchant. These result data are asynchronous notify parameters from server.

    Parameter List

    Example

    http://address_defined_by_merchant/alipay/notify_url.php?notify_id=ac05099524730693a8b330c5ecf72da978&seller_email=zhuzhanghu%40alitest.com&notify_type=trade_status_sync&buyer_em ail=13882390011&sign=601510b7970e52cc63db0f44997cf70e&trade_no=2013 112711001004940000394507&buyer_id=2088102105236945&quantity=10&tota l_fee=10.00&price=1.00&gmt_create=2013-11-27+15%3A45%3A57&out_trade_ no=5431395578198135&seller_id=2088101106499364&notify_time=2013-11-2 7+15%3A45%3A58&subject=%E5%A3%B0%E6%B3%A2%E6%94%AF%E4% BB%98-%E5%88%86%E8%B4%A6-sky&trade_status=WAIT_BUYER_PAY&sign_type=MD5

    This example is only for reference, and the actual gateway is the domain name of merchant.

    Business Response Code

    Response Code

    Description

    SUCCESS

    The ordering succeed.

    FAIL

    The ordering fails.

    Business Error Code

    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.

    CONTEXT_INCONSISTENT

    You were retrying a request identified by the same out_trade_no, but not all other request parameters were same.

    Retry this request with the exact parameters. Or use a fresh out_trade_no.

    TRADE_HAS_SUCCESS

    The payment of trade has been made successfully.

    Mark this transaction as paid in your merchant system.

    TRADE_HAS_CLOSE

    The trade has expired.

    Start a new transaction.

    TRADE_HAS_FINISHED

    The trade has been finished.

    Start a new transaction.

    REASON_ILLEGAL_STATUS

    The trade status is illegal.

    Start a new transaction.

    EXIST_FORBIDDEN_WORD

    Banned words are included in order information.

    Delete concerning words.

    ACCESS_FORBIDDEN

    Has no right to use the product.

    Make sure your agreement with Alipay still valid.

    SELLER_NOT_EXIST

    The seller does not exist.

    Check the seller parameter value.

    SELLER_BEEN_BLOCKED

    The seller's account has been Frozen.

    Contact Alipay tech support for help.

    INVALID_PARAMETER

    Parameter error.

    Please check the standard of each request parameter according to the API specification

    CURRENCY_NOT_SUPPORT

    This currency is not supported.

    Check the value of parameter currency.

    RESTRICTED_MERCHANT_INDUSTRY

    The transaction value cannot be greater than 5000 US dollars.

    Check your value of secondary_merchant_industry and contact Alipay technical support if needed.

    PRODUCT_AMOUNT_LIMIT_ERROR

    The transaction amount exceeded the limit.

    User change other payment method like cash or credit card

    EXCHANGE_AMOUNT_OR_CURRENCY_ERROR

    The exchange amount or currency is incorrect.

    Please contact Alipay technical support for help.

    ILLEGAL_MERCHANT_INDUSTRY

    Illegal MCC format.

    Make sure the value of secondary_merchant_industry be defined at MCC list

    FORBIDDEN_MERCHANT_INDUSTRY

    This transaction type is not allowed.

    Check your value of secondary_merchant_industry and contact Alipay technical support if needed.

    INVALID_RECEIVE_ACCOUNT

    The seller is not in the payee list.

    Please contact Alipay technical support for help.

    Access Error Code

    Error Code

    Description

    Action

    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.

    ILLEGAL_EXTERFACE_FOR_CA_VERIFY

    The interface is not allowed to use Certificate Verification Service.

    Please contact Alipay technical support for help.

    ILLEGAL_CERT_IS_OVERDUE

    Certificate verification failed due to the expired certificate.

    Check the status of your certificate.

    ILLEGAL_CA_SIGN

    Certificate verification failed.

    Check the status of your certificate.

    Trade Status

    Enumeration Name

    Description

    WAIT_BUYER_PAY

    The trade has been established and is waiting for the buyer to make payment.

    TRADE_CLOSED

    Trade closed whose payment has not been completed within specified time;

    Trades closed whose payment has been fully returned when the trade completes.

    TRADE_SUCCESS

    The trade succeeds and is operable, such as multi-level royalty distribution, refund, etc.

    TRADE_FINISHED

    The trade succeeds and finishes and is not operable.

    Handling result of alipay.acquire.precreate

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

    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

    Case 3. Received response from Alipay, and is_success=T and result_code=SUCCESS. Continue the business process by rendering the QR code

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

    Alipay will notify merchant’s website of the result data it processed through initiative notification from server after it completes the processing of request data of merchant. These result data are asynchronous notify parameters from server.

    3.1 Notification parameters

    Parameter Name Type Description Nullable Sample
    Basic parameters:
    notify_time Notification time Date The time when the notification is sent. The time format is yyyy-MM-dd HHss。 N 2013-11-27 15:45:58
    notify_type Notification type String Notification type N trade_status_sync
    notify_id Notification ID String Notification ID N ac05099524730693a8b330c5ecf72da978
    sign_type Sign type String The value can be one of DSA, RSA, or MD5. Uppercase must be used N MD5
    sign Signature String Refer to “8 Signature Mechanism”. N 601510b7970e52cc63db0f44997cf70e
    notify_action_type Notification action type String Notification action type: creat:createDirectPayTradeByBuyerAction Pay:payByAccountAction Refund:refundFPAction Reverse:reverseAction Close trade:closeTradeAction Finish:finishFPAction Y payByAccountAction
    Business parameters:
    out_trade_no The unique order number on the merchant's webpage String The merchant order number instead of the Alipay trade number. The number must be unique in merchant’s system and will be returned as is. Y 5431395578198135
    subject Title of the goods String Title of the goods/ Title of the trade/ Title of the order/Key words of the order and so on. The subject is in the first row of the Alipay transaction details and is very important for reconciliation. The subject will be returned as is. Y test subject
    trade_no Alipay trade number String The serial number of the trade in Alipay system. The range of the length value: 16-64 Y 2013112711001004940000394507
    trade_status Trade status String Current status of the trade. Y WAIT_BUYER_PAY
    gmt_create Trade creating time Date The time when the trade transaction is created. Format: yyyy-MM-dd HHss。 Y 2013-11-27 15:45:57
    gmt_payment Trade payment time Date The time when the payment is done. Format: yyyy-MM-dd HHss Y 2013-11-27 15:45:57
    seller_email Seller’s Alipay ID String Seller’s Alipay ID, can be email or phone number Y zhuzhanghu@alitest.com
    buyer_email Buyer’s Alipay ID String Buyer’s Alipay ID, can be email or phone number Y 13882390011
    seller_id Seller’s Alipay ID String Seller's unique Alipay user ID consists of 16 numbers that begin with 2088. Y 2088101106499364
    buyer_id Buyer’s Alipay ID String Buyer's unique Alipay user ID consists of 16 numbers that begin with 2088. Y 2088102105236945
    price Unit price of the goods Number Corresponding to the price in the request parameter and will be returned as is. Y 1.00
    quantity Quantity of the goods Number Corresponding to the quantity in the request parameter and will be returned as is. Y 10
    total_fee Money amount of the trade transaction. Number Money amount of the trade transaction. Corresponding to the request parameter and will be returned as is. Y 10.00
    body Description of the goods String The detail description of the trade transaction, including notes, description, details and so on. Corresponding to the request parameter and will be returned as is. Y Hello
    refund_fee Refund amount Number The refund amount. The unit is Yuan. Y 1.00
    out_biz_no Merchant’s business serial number String Merchant’s business Id. In most cases is the serial number of the refund request in the refund notification. Y HZRF001
    paytools_pay_amount Payment amount String Payment amount information of all successful payments in various channels. Y [{"MCARD":"7.94"},{"TMPOINT":"1.69"},{"BANKCARD":"5.55"}]
    extra_common_param Business passback parameter String The passback_parameters is returned as is. Y I'm a passback parameter
    m_discount_forex_amount the discount amount redeemed Number If coupons/vouchers are used in the transaction, the discount amount redeemed in the settlement currency will be returned. Otherwise, no return. Y 2.19

    3.1.1 The paytools_pay_amount parameters

    Parameter Name Type Description Nullable Sample
    ALIPAYACCOUNT Alipay account String The money amount paid by the balance of Alipay account. The unit is Yuan. Y 1.23
    MCARD Merchant's prepaid card String The money amount paid by the merchant's prepaid card. The unit is Yuan. Y 7.94
    MDISCOUNT Merhant's discount coupon String The money amount paid by the merchant's discount coupon. The unit is Yuan. Y 1.23
    TMPOINT Tmall points String The money amount paid by the Tmall points. The unit is Yuan. Y 1.69
    COUPON Coupon String The money amount paid by coupons. The unit is Yuan. Y 1.23
    POINT Taobao points String The money amount paid by points. The unit is Yuan. Y 1.23
    DISCOUNT Discount String The money amount paid by the discount. The unit is Yuan. Y 1.23
    BANKCARD Bank card String The money amount paid by the money fund. The unit is Yuan. Y 5.55
    MONEYFUND Money fund String The money amount paid by the money fund. The unit is Yuan. Y 1.23
    BAITIAO Baitiao String The money amount paid by BAITIAO. The unit is Yuan. Y 1.23
    PCARD Alipay card String The money amount paid by the Alipay card. The unit is Yuan. Y 2.13
    PCREDIT Credit payment(Consumption credit) String The money amount paid by the consumption credit card The unit is Yuan. Y 1.23
    MCOUPON Merchants issued coupon String The money amount paid by the merchants issued coupons. The unit is Yuan. Y 2.21

    Data structure:

    [
    {"<pay_tool_type_1>":"<amount_1>"}
    ,
    {"<pay_tool_type_2>":"<amount_2>"}
    ,
    …
    ]

    Sample:

    paytools_pay_amount=[{"MCARD":"7.94"},{"TMPOINT":"1.69"},{"BANKCARD":"5.55"}]

    3.2 Sample of asynchronous notification

    http://some_domain/alipay/notify_url.php?notify_id=ac05099524730693a8b330c5ecf72da978&seller_email=zhuzhanghu%40alitest.com&notify_type=trade_status_sync&buyer_email=13882390011&sign=601510b7970e52cc63db0f44997cf70e&trade_no=2013112711001004940000394507&buyer_id=2088102105236945&quantity=10&total_fee=10.00&price=1.00&gmt_create=2013-11-27+15%3A45%3A57&out_trade_no=5431395578198135&seller_id=2088101106499364&notify_time=2013-11-27+15%3A45%3A58&subject=%E5%A3%B0%E6%B3%A2%E6%94%AF%E4%BB%98-%E5%88%86%E8%B4%A6-sky&trade_status=WAIT_BUYER_PAY&sign_type=MD5

    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.

    Handling result of alipay.acquire.cancel

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

    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.

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

    Alipay provide reconciliation files to merchant using cross-border in-store payment services. Merchants can fetch the reconciliation files to view details of their balance. Reconciliation files consist of settlement files and transaction files. The settlement file of a T day is only generated if there is any settlement on that day. If you download settlement files from SFTP sites or Alipay global site, a summary file of the settlement is also available.

    Settlement time

    Transaction file generation time

    Settlement file generation time

    Note:

    The file naming rule is:

    1. $PID_transaction_$YYYYMMDD.txt;
    2. $PID_settlement_$YYYYMMDD.txt

     

    You can obtain the reconciliation files from Alipay global site or SFTP sites. However, the files obtained by using these channels vary in their names and contents, which is further explained in the following sections.

    Alipay global site (global.alipay.com)

    Login to Global portal (Alipay global site), go to My AlipayMy Transaction to view and download your transaction files and settlement files. You can also download the files at the Download Files tab.

    Watch the video to learn the procedure:

    Files can only be downloaded after the file is generated.

    SFTP

    To obtain your reconciliation files through SFTP, complete the following steps:

    1. Apply for an SFTP account
    2. After integration with Alipay, submit your PID and the IP address with which you visit SFTP site to Alipay Overseas Support. The IP address must not be an intranet IP. After receiving your request, Alipay will send you the login credentials in 5 working days.

    3. Connect to SFTP sites
    4. Download and install Winscp. Use the following settings to log in and obtain files:

      • Port: 22
      • Host Name: sftp.alipay.com (China) / isftp.alipay.com (U.S.)
      • Username and password

    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.

    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

    See Digital Signature.

    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)

    Name of the secondary merchant

    N

    secMerchantName

    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 address of the secondary merchant.

    N

    StoreAddress

    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": "13892921232", "contact_person": "driverName1"}, {"operation_id": "1082943492", "contact_way": "15839232232", "contact_person": "driverName2"}]

    Extend parameters

    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

    15839232232

    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

    See Signature Algorithms.

    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

    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

    String to be signed

    extend_params=[{"operationId": "xxx", "contactWay": "xxxx", "contactPerson": "xxxx"}, {"operationId": "xxx", "contactWay": "xxxx", "contactPerson": "xxxx"}];&external_storefront_photo=https://www.baidu.com/img/bd_logo1.png&internal_store_photo=https://www.baidu.com/img/bd_logo1.png&partner=2088101147261746&secondary_merchant_id=4318163847915537&secondary_merchant_name=yihan上线商户haha01&sendFormat=normal&service=alipay.overseas.secmerchant.offline.maintain&store_address=xxxxx&store_country=HK&store_id=1263712631132&store_industry=4082

    Generated URL

    http://www.sit.alipay.net/cooperate/gateway.do?store_industry=4082&sign_type=MD5&store_id=1263712631132&store_country=HK&sendFormat=normal&sign=ffd00d45aed71fb28aa8bb8d0838cb5e&secondary_merchant_name=yihan%C9%CF%CF%DF%C9%CC%BB%A7haha01&external_storefront_photo=https%3A%2F%2Fwww.baidu.com%2Fimg%2Fbd_logo1.png&secondary_merchant_id=4318163847915537&service=alipay.overseas.secmerchant.offline.maintain&internal_store_photo=https%3A%2F%2Fwww.baidu.com%2Fimg%2Fbd_logo1.png&partner=2088101147261746&store_address=xxxxx&extend_params=%5B%7B%22operationId%22%3A+%22xxx%22%2C++%22contactWay%22%3A+%22xxxx%22%2C+%22contactPerson%22%3A+%22xxxx%22%7D%2C+%7B%22operationId%22%3A+%22xxx%22%2C++%22contactWay%22%3A+%22xxxx%22%2C+%22contactPerson%22%3A+%22xxxx%22%7D%5D%3B

    The sample is for reference only. Alipay gateway is https://mapi.alipay.com/gateway.do?.

    Response Examples

    Request succeeds and the registration is successful:

    
    <?xml version="1.0" encoding="utf-8"?>
    <alipay>
        <is_success>T</is_success>
        <request>
            <param name="secondary_merchant_id">2015051446800462</param>
            <param name="secondary_merchant_name">hanguo</param>
            <param name="sign_type">MD5</param>
            <param name="secondary_merchant_industry">4378</param>
            <param name="sign">2118ac8fad6bc1d9e88a6cd017c18d37</param>
            <param name="register_country">CA</param>
            <param name="_input_charset">UTF-8</param>
            <param name="register_address">HANGZHOU</param>
            <param name="service">alipay.overseas.secmerchant.offline.maintain</param>
            <param name="site_infos">[{"site_type":"WEB","site_url":"https://alipay.com","site_name":"websit"}]</param>
            <param name="partner">2088101142878662</param>
            <param name="timestamp">2018-08-03 00:28:32</param>
        </request>
    <response>
        <alipay>
            <result_code>SUCCESS</result_code>
        </alipay>
    </response>
        <sign>3afc92ac4708425ab74ecb2c4e58ef56</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.

    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.

    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

    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.

    客服小机器人

    NEED HELP ?