1
- [About This Guide](./1) - [Introduction](./2) - [The Payment Workflow and User Interaction](./4) - [The Payment Workflow](./4) - [Merchant Direct](./4) - [Merchant Scans with System Integrator](./5) - [Merchant Scans with Acquirer](./6) - [Merchant Scans with Integrator and Acquirer](./7) - [The User Interaction](./3) - [Quick Integration](./36) - [Integration Overview](./36) - [Pay Flow](./15) - [Cancel Flow](./16) - [Refund Flow](./37) - [Query Flow](./18) - [Testing & Pre-launching](./19) - [Sandbox](./19) - [Service Mocking](./40) - [Integration Cases](./42) - [iDiagnose](./45) - [Demo Code Download](./38#DemoDownload) - [Reconciliation Files](./29) - [Obtaining Reconciliation Files](./44) - [Transaction File Format](./30) - [Settlement File Format](./31) - [API List](./9) - [The Payment Interface](./9) - [The Request Parameter](./9) - [The Return Parameter](./20) - [The Error Code](./21) - [Offline to online scenarios](./28) - [The Cancel Interface](./32) - [The Request Parameter](./33) - [The Return Parameter](./35) - [The Error Code](./34) - [The Refund Interface](./11) - [The Request Parameter](./11) - [The Return Parameter](./24) - [The Error Code](./25) - [The Query Interface](./12) - [The Request Parameter](./12) - [The Return Parameter](./26) - [The Error Code](./27) - [The Secondary Merchant Info Interface](./43) - [The Request Parameter](./43#request) - [The Return Parameter](./43#sync) - [The Error Code](./43#error) - [Digital Signature](./13) - [Digital Algorithms](./13) - [RSA Key Generation with Open SSL](./14)
Barcode Payment

About This Guide

Audience

This document targets at the technical person who are intending to integrate with the Barcode Payment solution.

Conventions

Interface

In this context, the interface is the channel that the Alipay system provides the relevant service by invoking the corresponding APIs with the required parameter values. Throughout this guide, we may use interface and serive interchangeably.

Customer Support

For technical questions, please contact Global Merchant Technical Support.
For non-technical questions, like how to sign up with Alipay, please contact Global Merchant Business 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.

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

 

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

REVERSAL

REFUND

CANCEL

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

Operator_name

String

Operator name (store name field)

12

Order_scene

String

Order scenarios:

Scan QR code mode : shopQrCode

Barcode mode: It is blank

13

Trans_currency

String(8)

List currency

14

Trans_amount

Number(9,2)

Amount in list currency/refund amount in list currency

15

Trans_forex_rate

String

Exchange rate of list currency against settlement currency

An example of file content:

Partner:208800000000|Payment_time: 2013-12-02|Total_count:4

Partner_transaction_id|Transaction_id|Transaction_amount|Charge_amount|Currency|Payment_time|Transaction_type|Remark|Secondary_merchant_industry|Secondary_merchant_name|Operator_name|Order_scene|Trans_currency|Trans_amount|Trans_forex_rate 0001|201312020445|100|3|HKD|2013-12-02 10:45:42|PAYMENT||5812|xxx|xxx|shopQrCode|TWD|100|0.031 0002|201312020446|100|3|HKD|2013-12-02 10:45:13|REVERSAL||5812|xxx|xxx|shopQrCode|TWD|100|0.031 0003|201312020448|100|3|HKD|2013-12-02 10:45:09|REFUND|Refund|5812|xxx|xxx|shopQrCode|TWD|100|0.031

 

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:

  • "transaction_id" when canceling a transaction;
  • "partner_trans_id" when type is normal transaction;
  • "partner_refund_id" when type is refundament transaction;
  • "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

    Rmb_amount

    Number(9,2)

    The amount of fund in CNY currency

    5

    fee

    Number(9,2)

    The amount of commission fee in foreign currency

    6

    Settlement

    Number(9,2)

    Settlement amount in foreign currency

    7

    Rmb_settlement

    Number(9,2)

    Settlement amount in CNY currency

    8

    Currency

    String(10)

    Abbreviated currency code, such as USD

    9

    Rate

    Number(8,6)

    Currency rate

    10

    Payment_time

    String(19)

    YYYY-MM-DD HH:MM:SS

    Empty if the status being “failed” or “waiting”, e.g. 2016-02-10 01:01:01

    11

    Settlement_time

    String(19)

    YYYY-MM-DD HH:MM:SS
    Empty if unliquidated

    12

    Type

    String(1)

    Normal transaction:P
    Refunding transaction:R

    13

    Status

    String(1)

    Normal transaction:
    L: Liquidated
    Refundament transaction :
    L: Liquidated

    14

    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

    15

    Secondary_merchant_industry

    String(4)

    Industry classification identifier( MCC )

    16

    Secondary_merchant_name

    String

    Secondary merchant name (or a taxi company name)

    17

    Operator_name

    String

    Operator name (store name field)

    18

    Order_scene

    String

    Order scenarios:

    Scan QR code mode : shopQrCode

    19

    Trans_currency

    String(10)

    List currency

    20

    Trans_amount

    Number(9,2)

    Transaction amount in list currency/refund amount in list currency

    21

    Trans_forex_rate

    String

    Exchange rate of list currency against settlement currency

    An example of file content:

    Partner_transaction_id|Transaction_id|Amount|Rmb_amount|Fee|Settlement|Rmb_settlement|Currency|Rate|Payment_time|Settlement_time|Type|Status|Remarks|Secondary_merchant_industry|Secondary_merchant_name|Operator_name|Order_scene|Trans_currency|Trans_amount|Trans_forex_rate

    EASA-20170801233604653-5GP0GVWNY|2017080221001004060213245489|369.30|2001.38|2.22|367.08|1989.37|AUD|5.41940000|2017-08-02 07:36:46|2017-08-03 15:46:00|P|L||5311|xxx|xxx|shopQrCode|AUD|369.30|1

     

    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 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 (Range of Length)

    Parameter 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 means success

    Ÿ   F means 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(3

    2)

    Response code of cancel processing result.

    Ÿ   SUCCESS: successful refund

    Ÿ   FAIL: unsuccessful refund

    Ÿ   UNKNOWN: unknown result

    N

    SUCCESS

     

    trade_no

    String(6

    4)

    Trade number of the trade in Alipay system

    16 bits at least and 64 bits at most

    Y

    201311201100100433

    0000121536

    out_trade_no

    String(6

    4)

    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_cod

    e

    String(4

    8)

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

     

    detail_er ror_des

    String(6

    4)

     

    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.

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

    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.

    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. 

    For a transaction that has been successfully paid, the customer can request the merchant for refunding as long as the refunding period is still valid, and the merchant can make use of the refunding interface to achieve the goal.

    For the integration of the refunding service, we would like to highlight:

    1. The refund service name is: alipay.acquire.overseas.spot.refund;
    2. The refunding service is only applicable to a transaction that has been successfully paid;
    3. The refunding of a transaction can be full or partial, i.e. the refunding amount can respectively be the same as or less than the original transaction amount that has been paid;
    4. Regarding whether Alipay will return the charged fee of the original transaction, it depends on your contract with Alipay.
    5. Comparing with the cancel interface (alipay.acquire.cancel), this service does not impose the 24-hours constraint, i.e. the merchant server can invoke this service at any time that between the moment when the transaction was paid and the time before the refunding period expires;
    6. If a refunding request encounters a failure, please retry for a reasonable number of times. 

    Watch the video below to have a quick overview of Alipay sandbox portal, and the preparations that are required before you access the portal.

    Creating an Alipay merchant account


    Before you can test in the Alipay sandbox environment, you must create an Alipay merchant account on the Alipay for Business website first. If you already have an Alipay merchant account, skip to Alipay sandbox portal.

    Complete the following steps to create an Alipay merchant account:

    1. Go to the Alipay for Business website: https://global.alipay.com
    2. In the top-right corner of the homepage, click Sign Up.
    3. Enter your email, enter the code displayed, and then click Continue.
    4. Follow the instructions to complete the account creation.

    Alipay sandbox portal


    The Alipay sandbox portal contains the information and tools you need to test in the Alipay sandbox environment, which include the test accounts information and the Alipay sandbox app.

    Sign in to the Alipay sandbox portal


    1) Go to: https://isandbox.alipaydev.com/user/intlAccountDetails.htm
    2) Sign in with your Alipay merchant account.
    For how to create an Alipay merchant account, see Create an Alipay merchant account.

    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.

    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

    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 ?