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

About This Guide

Audience

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

Conventions

QR Code

Quick Response Code (QR Code) consists of black squares arranged in a square grid on a white background, which can be read by an imaging device and processed. The required data are then extracted from patterns that are present in both horizontal and vertical components of the image, as depicted below.

In this Transaction QR Code payment solution, the merchant system will send a request to the Alipay system with the transaction data, and the Alipay will respond a QR Code to represent the transaction.

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 .

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> 

 OpenSSL installation

l   Linux(Ubuntu)

sudo apt-get install openssl

l   Windows

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

  RSA key pair generation

l   Linux

$ openssl

OpenSSL> genrsa -out rsa_private_key.pem 1024 ##generating private key

OpenSSL> pkcs8 -topk8 -inform PEM -in rsa_private_key.pem -outform PEM -nocrypt ##transform private key into PKCS8 format

OpenSSL> rsa -in rsa_private_key.pem -pubout -out rsa_public_key.pem ##Generate public key

OpenSSL> exit     

l   Windows operates in cmd window:

C:\Users\Hammer>cd C:\OpenSSL-Win32\bin ##enter OpenSSL directory

C:\OpenSSL-Win32\bin>openssl.exe ##enter OpenSSL

OpenSSL> genrsa -out rsa_private_key.pem 1024  ##generating private key

OpenSSL> pkcs8 -topk8 -inform PEM -in rsa_private_key.pem -outform PEM -nocrypt ##transform private key into PKCS8 format

OpenSSL> rsa -in rsa_private_key.pem -pubout -out rsa_public_key.pem ##Generate public key

OpenSSL> exit

Remarks:

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

 

After the steps above, the user could see two files under the current folder (C:\OpenSSL-Win32\bin for Windows), rsaprivatekey.pem和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.

l   Standard private key file(PHP,.NET)

-----BEGIN RSA PRIVATE KEY-----

MIICXQIBAAKBgQC+L0rfjLl3neHleNMOsYTW8r0QXZ5RVb2p/vvY3fJNNugvJ7lo4+fdBz+LN4mDxTz4MTOhi5e2yeAqx+v3nKpNmPzC5LmDjhHZURhwbqFtIpZD51mOfno2c3MDwlrsVi6mTypbNu4uaQzw/TOpwufSLWF7k6p2pLoVmmqJzQiD0QIDAQABAoGAakB1risquv9D4zX7hCv9MTFwGyKSfpJOYhkIjwKAik7wrNeeqFEbisqv35FpjGq3Q1oJpGkem4pxaLVEyZOHONefZ9MGVChT/MNH5b0FJYWl392RZy8KCdq376Vt4gKVlABvaV1DkapL+nLh7LMo/bENudARsxD55IGObMU19lkCQQDwHmzWPMHfc3kdY6AqiLrOss+MVIAhQqZOHhDe0aW2gZtwiWeYK1wB/fRxJ5esk1sScOWgzvCN/oGJLhU3kipHAkEAysNoSdG2oWADxlIt4W9kUiiiqNgimHGMHPwp4JMxupHMTm7D9XtGUIiDijZxunHv3kvktNfWj3Yji0661zHVJwJBAM8TDf077F4NsVc9AXVs8N0sq3xzqwQD/HPFzfq6hdR8tVY5yRMb4X7+SX4EDPORKKsgnYcur5lk8MUi7r072iUCQQC8xQvUne+fcdpRyrR4StJlQvucogwjTKMbYRBDygXkIlTJOIorgudFlrKP/HwJDoY4uQNl8gQJb/1LdrKwIe7FAkBl0TNtfodGrDXBHwBgtN/t3pyi+sz7OpJdUklKE7zMSBuLd1E3O4JMzvWP9wEE7JDb+brjgK4/cxxUHUTkk592

-----END RSA PRIVATE KEY-----

l   Standard private key file in PKCS8 format(Java)

-----BEGIN PRIVATE KEY-----

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

-----END PRIVATE KEY-----

l   Public key file

-----BEGIN PUBLIC KEY-----

MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDQWiDVZ7XYxa4CQsZoB3n7bfxLDkeGKjyQPt2FUtm4TWX9OYrd523iw6UUqnQ+Evfw88JgRnhyXadp+vnPKP7unormYQAfsM/CxzrfMoVdtwSiGtIJB4pfyRXjA+KL8nIa2hdQy5nLfgPVGZN4WidfUY/QpkddCVXnZ4bAUaQjXQIDAQAB

-----END PUBLIC KEY-----

 

 Upload the public key

Contact Alipay technical support at overseas_support@service.alibaba.com to upload the public key. Please sign with the matching private key in the key pair.

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

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.

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

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.

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

File header  

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

Occurring sequence in the header

Field

Type

Description

1

Partner

String(16)

2088123456543210

2

Payment_time

String(10)

The day that transaction happens, the format is YYYY-MM-DD HH:MM:SS

3

Total_count

Number(9)

The total number of the records in this file

 

Record Detail

 No.

Field

Type(Byte)

Description

1

Partner_transaction_id

String(64)

A numbered transaction ID(unique in partner system)it is equal to “partner_trans_id” when transaction type is in (payment,reversal,reverse); it is equal to “partner_refund_id” when transaction type is refund

2

Transaction_id

String(64)

A numbered transaction ID (Unique inside the Alipay system)

3

Transaction_amount

Number(9,2)

Same to the definition given in the interface part;

It is in the currency given below.

4

Charge_amount

Number(9,2)

Commission fee

5

Currency

String(8)

The currency given in the transaction request.

6

Payment_time

String(19)

The time of transaction;

Format: YYYY-MM-DD HH:MM:SS

7

Transaction_type

String(8)

Transaction type:
PAYMENT

REVERSE

REFUND

8

Remark

String(256)

Remark

9

Secondary_merchant_industry

String(4)

Industry classification identifier

10

Secondary_merchant_name

String

Secondary merchant name (or a taxi company name)

11

Secondary_merchant_id

String

Secondary merchant id

12

Operator_name

String

Operator name (store name field)

13

Order_scene

String

Order scenarios:

Scan Merchant QR code mode: shopQrCode

Barcode mode: paymentQrCode

Scan Transaction QR code mode: transactionQrCode

14

Trans_currency

String(8)

List currency

15

Trans_amount

Number(9,2)

Amount in list currency/refund amount in list currency

16

Trans_forex_rate

String

Exchange rate of list currency against settlement currency

17

Issue

String

Indicates the payment type:ALIPAYCN for Alipay mainland user, ALIPAYHK for Alipay HK user.

An example of file content:

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

Partner_transaction_id|Transaction_id|Transaction_amount|Charge_amount|Currency|Payment_time|Transaction_type|Remark|Secondary_merchant_industry|Secondary_merchant_name|Secondary_merchant_id|Operator_name|Order_scene|Trans_currency|Trans_amount|Trans_forex_rate|Issue

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

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

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

 

Record detail

No.

Field

Type

Description

1

Partner_transaction_ id

String(64)

A numbered transaction ID (Unique inside the partner system),it is equal to “partner_trans_id” when type is normal transaction ; it is equal to “partner_refund_id” when type is refundament transaction; it is equal to “partner_trans_id” when  the  “partner_refund_id” is blank, such as 2010121000000002

2

Transaction_id

String(64)

A numbered transaction ID (Unique inside the Alipay system)such as 2015021021001001230099088888

3

Amount

Number(9,2)

The amount of fund in foreign currency.

4

Fee

Number(9,2)

The amount of commission fee in foreign currency

5

Settlement

Number(9,2)

Settlement amount in foreign currency

6

Currency

String(10)

Abbreviated currency code, such as USD

7

Payment_time

tring(19)

YYYY-MM-DD HH:MM:SS

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

8

Settlement_time

String(19)

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

9

Type

String(1)

Normal transaction:P
Refunding transaction:R

10

Status

String(1)

Normal transaction:
P : Payment made    L: Liquidated
Refundament transaction :
W:wait to be proceed P:refund success
F: failed    L:Liquidated

11

Remarks

String(256)

An optional field. If the transaction is refundament, reason field will be displayed in this column ,if the transaction is a payment ,subject field will be displayed in this column

12

Secondary_merchant_industry

String(4)

Industry classification identifier( MCC )

13

Secondary_merchant_name

String

Secondary merchant name (or a taxi company name)

14

Secondary_merchant_id

String

Secondary merchant id

15

Operator_name

String

Operator name (store name field)

16

Order_scene

String

Order scenarios:

Scan Merchant QR code mode: shopQrCode

Barcode mode: paymentQrCode

Scan Transaction QR code mode: transactionQrCode

17

Trans_currency

String(10)

List currency

18

Trans_amount

Number(9,2)

Transaction amount in list currency/refund amount in list currency

19

Trans_forex_rate

String

Exchange rate of list currency against settlement currency

20

Issue

String

Indicates the payment type:ALIPAYCN for Alipay mainland user, ALIPAYHK for Alipay HK user.

An example of file content:

Partner_transaction_id|Transaction_id|Amount|Fee|Settlement|Currency|Payment_time|Settlement_time|Type|Status|Remarks|Secondary_merchant_industry|Secondary_merchant_name|Secondary_merchant_id|Operator_name|Order_scene|Trans_currency|Trans_amount|Trans_forex_rate|Issue

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

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

 

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

The gateway URL:

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

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

If you are still using the previous sandbox gateway https://openapi.alipaydev.com, please use the https://mapi.alipaydev.com/gateway.do gateway instead. This gateway adjustment is caused by a system difference between the Alipay international sandbox test environment and the Alipay domestic sandbox test environment.

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

    客服小机器人

    NEED HELP ?