43
- [Introduction](./2) - [Payment Flow and User Experience](./3) - [Interaction Process](./5) - [Client-side Integration](./42) - [iOS](./6) - [SDK Overview](./6) - [SDK Integration Process](./12) - [Android](./7) - [SDK Overview](./7) - [SDK Integration Process](./13) - [Server-side Integration](./41) - Prerequisites - [Implementing APIs](./41) - [Implementing Error Handling](./40) - [Testing in Sandbox](./46) - [Prerequisites](./47) - [Testing in Sandbox](./48) - [API List](./8) - [mobile.securitypay.pay](./8) - [Request Parameters Description](./8) - [Synchronous Response Parameters](./9#SynchronousResponseParameters) - [Server Asynchronous Notification Parameters](./10#ServerAsynchronousNotificationParameters) - [Codes Returned to Client End](./9#ClientReturnCodes) - [Error Codes](./14) - [Forex_refund](./21) - [Request Parameters](./21#Request) - [Sync Response](./21#Response) - [Async Notification](./51) - [Samples](./21#Samples) - [Error Codes](./22) - [Single_trade_query](./23) - [Request Parameters](./23#QueryRequest) - [Sync Response](./23#QueryResponse) - [Samples](./23#QuerySamples) - [Error Codes](./24#Errors) - [Forex_compare_file](./25) - [Request Parameters](./25#Forex_compare_file_Request) - [Sync Response](./25#Forex_compare_file_Response) - [Samples](./25#Forex_compare_file_Samples) - [Error Codes](./26) - [Forex_liquidation_file](./27) - [Request Parameters](./27#Forex_liquidation_file_Request) - [Sync Response](./27#Forex_liquidation_file_Response) - [Samples](./27#Forex_liquidation_file_Samples) - [Error Codes](./28) - [Forex_rate_file](./29) - [Request Parameters](./29#Forex_rate_file_Request) - [Sync Response](./29#Forex_rate_file_Response) - [Samples](./29#Forex_rate_file_Samples) - [Error Codes](./30) - [Notify_verify](./31) - [Request Parameters](./31#Notify_verify_Request) - [Sync Response](./31#Notify_verify_Response) - [Samples](./31#Notify_verify_Samples) - [Error Codes](./32) - [alipay.overseas.secmerchant.online.maintain](./50) - [Request Parameters](./50#request) - [Sync Response](./50#sync) - [Samples](./50#samples) - [Reconciliation Files](./37) - [About Reconciliation Files](./37) - [Obtaining Reconciliation Files](./38) - [API](./38#API) - [Alipay global site](./38#Global) - [SFTP](./38#SFTP) - [Reconciliation File Content](./39) - [Transaction file](./39#TransactionFile) - [Settlement file](./39#SettlementFile) - [Digital Signature](./43) - [Preparing Keys](./43) - [Generating Pre-sign String](./15) - [Signing the Request](./45) - [Verifying the Signature](./44) - [Resource Download](./20)
New Cross-border APP Payment

Preparing Keys

To generate a digital signature, normally a key is required to sign the data. You must prepare the MD5 private key or the RSA/DSA private and public key pair to generate and verify a digital signature.

MD5 sign type

MD5 private key is required for generating and verifying MD5 signatures. The MD5 secret key is the 32-byte string which is composed of English letters and numbers. You can log in to the Global Portal to view the private key:

  1. Log in with your user ID.
  2. Click My Technical Service and enter your payment password. If you don't know your payment password, please contact Global Merchant Business Support
  3. Check your MD5 Key. For example, the following graphic is an example of an MD5 Key:

RSA/DSA sign type

An RSA/DSA key pair contains the private key and the public key. The private key is required for generating the signature, while the public key is used for verifying the signature. The following steps assume that you are using RSA sign type, similar steps applied for generating and uploading DSA key pair.

Generating the private/public key pair

Many tools can be used to generate the RSA key pair. The following example illustrates the steps to generate the RSA key pair by using OpenSSL.

  1. Install OpenSSL
    • For linux system, use the following command:
      sudo apt-get install openssl
    • For windows system, download and then install OpenSSL from OpenSSL site.
  2. Generate RSA key pair.
    For linux system, use the following command:
    $ openssl
    OpenSSL> genrsa -out rsa_private_key.pem 1024 ##generating  private key
    OpenSSL> pkcs8 -topk8 -inform PEM -in rsa_private_key.pem  -outform PEM -nocrypt ##transform private key into PKCS8 format
    OpenSSL> rsa -in rsa_private_key.pem -pubout -out  rsa_public_key.pem ##Generate public key
    OpenSSL> exit          
    

    For windows system, use the following command:
    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 

After that, you can see two files under current folder, rsaprivatekey.pem and rsapublickey.pem. The former is the private key and the latter is the public key.

Notes:
  • For Java developers, remove the header, footer, carriage return, and space from the pkcs8 private key output in the console.
  • After creating a private key with openssl, if you use JAVA, you need to transform the private key into PKCS8 format; if you use .NET or PHP, no need to transform the private key into PKCS8 format.

The following are the examples of the key pair:

  • 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-----
  • Standard private key file in PKCS8 format(Java)
    -----BEGIN PRIVATE  KEY-----MIICeAIBADANBgkqhkiG9w0BAQEFAASCAmIwggJeAgEAAoGBAN0yqPkLXlnhM+2H/57aHsYHaHXazr9pFQun907TMvmbR04wHChVsKVgGUF1hC0FN9hfeYT5v2SXg1WJSg2tSgk7F29SpsF0I36oSLCIszxdu7ClO7c22mxEVuCjmYpJdqb6XweAZzv4Is661jXP4PdrCTHRdVTU5zR9xUByiLSVAgMBAAECgYEAhznORRonHylm9oKaygEsqQGkYdBXbnsOS6busLi6xA+iovEUdbAVIrTCG9t854z2HAgaISoRUKyztJoOtJfI1wJaQU+XL+U3JIh4jmNx/k5UzJijfvfpT7Cv3ueMtqyAGBJrkLvXjiS7O5ylaCGuB0Qz711bWGkRrVoosPM3N6ECQQD8hVQUgnHEVHZYtvFqfcoq2g/onPbSqyjdrRu35a7PvgDAZx69Mr/XggGNTgT3jJn7+2XmiGkHM1fd1Ob/3uAdAkEA4D7aE3ZgXG/PQqlm3VbE/+4MvNl8xhjqOkByBOY2ZFfWKhlRziLEPSSAh16xEJ79WgY9iti+guLRAMravGrs2QJBAOmKWYeaWKNNxiIoF7/4VDgrcpkcSf3uRB44UjFSn8kLnWBUPo6WV+x1FQBdjqRviZ4NFGIP+KqrJnFHzNgJhVUCQFzCAukMDV4PLfeQJSmna8PFz2UKva8fvTutTryyEYu+PauaX5laDjyQbc4RIEMU0Q29CRX3BA8WDYg7YPGRdTkCQQCG+pjU2FB17ZLuKRlKEdtXNV6zQFTmFc1TKhlsDTtCkWs/xwkoCfZKstuV3Uc5J4BNJDkQOGm38pDRPcUDUh2/-----END PRIVATE  KEY-----
  • Public key file
    -----BEGIN PUBLIC  KEY-----MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDQWiDVZ7XYxa4CQsZoB3n7bfxLDkeGKjyQPt2FUtm4TWX9OYrd523iw6UUqnQ+Evfw88JgRnhyXadp+vnPKP7unormYQAfsM/CxzrfMoVdtwSiGtIJB4pfyRXjA+KL8nIa2hdQy5nLfgPVGZN4WidfUY/QpkddCVXnZ4bAUaQjXQIDAQAB-----END PUBLIC  KEY-----

Exchanging the public key
You need to exchange your public key with Alipay. Contact Global Merchant Technical Support and provide your PID and public key information. Alipay will then make configurations accordingly, and provide you Alipay public key.

With the growing number of Chinese consumers purchasing merchandise on the oversea merchants’ site direct, the merchant could integrate with Alipay Standard Payment solution to offer the users the familiar user experience that they comfortable with, along the convenience provided for both the merchants and the consumers on the payment, FX exchange and settlement.

Once integrated, the merchant’s site will present an Alipay payment button when the consumer completes the payment and checks out.

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.

Merchants can check PID, Key, do refund, check/download transaction and settlement info on global.alipay.com:

Abbreviation

Currency

Decimal Number

AUD

Australian Dollar

2

CAD

Canadian Dollar

2

CHF

Confederation Helvetica Franc

2

DKK

Danish Krone

2

EUR

Euro

2

GBP

British Sterling

2

HKD

Hong Kong Dollar

2

JPY

Japanese Yen

0

KRW

Korean Won

0

NOK

Norwegian Krone

2

NZD

New Zealand Dollar

2

SEK

Swedish Krona

2

SGD

Singapore Dollar

2

THB

Thai Baht

2

USD

U.S. Dollar

2

Parameter

Type(length in bytes)

Description

Optional

Example

transIn

String

Alipay userID that Alipay account for deposit. Alipay userID that composed of 16 digits beginning with 2088.

N

2088101126708402

amount

String

Split Amount. The format must be correct to the currency!

N

0.10

currency

String

Split currency. If parameter (total_fee) was used, the split currency must be foreign currency and the same with settlement currency!
If parameter (rmb_fee) was used, the split currency must be ‘CNY’!

The parameter (total_fee and rmb_fee ) are mutual exclusive.

N

USD

desc

String

Split discretion

Y

 

For example

Format Structure :
split_fund_info=[{"transIn":"2088101126708402","amount":"0.10","currency":"USD","desc":"  Split _test1"},{"transIn":"2088101126707869","amount":"0.10","currency":"USD","desc":"Split_test2"}]
  • You can own at most 10 domestic split accounts.
  • You must own a domestic split account that has contracted successfully with Alipay. The domestic split account need to be linked with the global primary account. To check whether the link is successfully built, contact Global Merchant Business Support.

The single refund interface allows the partners to refund a transaction.

Request Parameters

Parameter Type (length in bytes) Description Optional Example
Basic Parameter
service String Service Name N forex_refund
partner String(16) Partner ID.
Composed of 16 digits beginning with 2088.
N 2088001159940003
_input_charset String The charset with which the request data is encoded;
UTF-8 is supported
N UTF-8
sign_type String Signature method. The following are supported. Must be uppercase.
DSA, RSA, and MD5.
N RSA
sign String Signature value. N e5815a4556db338ed237f7d3fd222184
Business Parameter
out_return_no String(64) The unique refund ID for refund request. N 205485121225
out_trade_no String(64) The payment ID for the original payment txn. N 205485121223
return_amount Number(8,2) The amount to refund in settlement currency. The value is between 0.01 – 1000000(max 2 digits after the decimal). Must use one of the two parameters: return_amount and return_rmb_amount Y 100.30
return_rmb_amount Number(15) Use this field to refund in CNY. The value is between 0.01 – 1000000(max 2 digits after the decimal). Must use one of the two parameters: return_amount and return_rmb_amount Y 10.20
currency String(10) Currency code. Even when return_rmb_amount is not null, currency is still foreign currency, not CNY N USD
gmt_return String(14) Refund Transaction time. YYYYMMDDHHMMSS, Beijing Time N  
reason String(100) Reason for the refund. Y out of supply
product_code String(32) NEW_OVERSEAS_SELLER N NEW_OVERSEAS_SELLER  
is_sync String(1) The refund request is processed synchronously or asynchronously. Value: Y or N. Default value is N, which is processed asynchronously. Y N
split_fund_info String(1 600) Split info, JSON format, more detail see Refund Split Detail Info Y [{"transOut":"2088101137935255","amount":"0.10","currency":"USD","desc":"test1"},{"transOut":"2088101126707869","amount":"0.10","currency":"USD","desc":"test2"}]  
  • The total of the refund amounts could not exceed the original payment amount.
  • The refund must be requested within a certain time period after the payment (specified in the contract, and the default is 3 month).

Sync Response

The response is in XML format


Parameter
Type (length in bytes) Description Optional Example
is_success String Status of the API call, ‘T’ or ‘F’ N T
error String Error message Y REPEATED_REFUNDMENT_REQUEST

Samples

Request Example

https://intlmapi.alipay.com/gateway.do?reason=refund+test&return_amount=0.1&sign_type=MD5& out_trade_no=iamdjc456¤cy=HKD&sign=8e9004797d3c7112b907bd184d775662&_input_charset=UTF-8&out_return_no=test005&service=forex_refund&partner=2088701998606387

Sync Response Examples

Success response
<?xml version="1.0" encoding="GBK"?>
<alipay>
    <is_success>T</is_success>    
</alipay>
Error response:
<?xml version="1.0" encoding="utf-8"?>
<alipay>
    <is_success>F</is_success>
    <error>ILLEGAL_SIGN</error>
</alipay>

For the system API calls, in general, the validations are being done at two levels on Alipay side.

The first level is at the API gateway level, where it does certain sanity checks such as verifying the signature, verifying if the partner ID is valid or whether the partner has permission to call this particular API, etc. If the validation fails, Alipay would return the appropriate error codes which are classified as the 'API Gateway Error Codes' as in the below.

Once it passes the validations at the API gateway level, the API request would be dispatched to the internal system for further processing, which it would be subjected to the validations of the business logic. The corresponding error codes returned are classified as the 'Business Error Codes".

Business Logic Errors

Returned result

Description

REFUNDMENT_VALID_DATE_EXCEED

Could not refund after the specified refund timeframe.

SYSTEM_EXCEPTION

System exception

ILLEGAL_ARGUMENT

Illegal argument

REPEATED_REFUNDMENT_REQUEST

Duplicated refund request

RETURN_AMOUNT_EXCEED

Refund amount is over the payment amount

CURRENCY_NOT_SAME

Different currency from the payment currency

PURCHASE_TRADE_NOT_EXIST

The payment transaction does not exist

Access Errors / Common errors with MAPI gateway

If the calling parameters have error in it, Alipay MAPI gateway will capture it and display the errors. However, the control flow will stay at the Alipay side and will NOT return to the merchant’s site.

Returned result

Description

SYSTEM_EXCEPTION

Alipay system error

ILLEGAL_ARGUMENT

Incorrect parameter

ILLEGAL_SIGN

Illegal signature

ILLEGAL_SERVICE

Service Parameter is incorrect

ILLEGAL_PARTNER

Incorrect Partner ID

ILLEGAL_SIGN_TYPE

Signature is of wrong type.

ILLEGAL_PARTNER_EXTERFACE

Service is not activated for this account

ILLEGAL_DYN_MD5_KEY

Dynamic key information is incorrect

ILLEGAL_ENCRYPT

Encryption is incorrect.

ILLEGAL_USER

User ID is incorrect.

ILLEGAL_EXTERFACE

Interface configuration is incorrect.

ILLEGAL_AGENT

Agency ID is incorrect.

HAS_NO_PRIVILEGE

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 to assist the error repair.

Returned result

Description

SYSTEM_ERROR

Alipay system error

SESSION_TIMEOUT

Session timeout

ILLEGAL_TARGET_SERVICE

Wrong  target service

ILLEGAL_ACCESS_SWITCH_SYSTEM

Merchant is not allowed to visit system of this type.

EXTERFACE_IS_CLOSED

The interface has been closed.

The partners can use this API to obtain the information on a particular transaction, such as the transaction’s ID, out_trade_no, item name, transaction status, etc.

Request Parameters

Parameter

Type(length)

Description

Optional

Example

Basic Parameters

service

String

API name

N

single_trade_query

partner

String(16)

A unique partner ID to identify a contracted Alipay Account.
A 16 digit number starts with 2088

N

2088101011913539

_input_charset

String

The charset on partner website like utf-8、gbk、gb2312 etc.

N

gbk

sign_type

String

Signature method. The value can be MD5, RSA, or RSA2. RSA2 is preferred. Uppercase must be used.

N

MD5

sign

String

Sign value

N

7d314d22efba4f336fb187697793b9d2

Business Parameters

trade_no

String(64)

The unique trade number in Alipay system.
Length from 16 to 64.

Y

2008102303210710

out_trade_no

String(64)

A unique number to identify a transaction in partner system

Y

6843192280647118

Note:
This API recieve https request only;

Sync Response

After Alipay finish processing request data, it will notify partner website by posting response data by the way of redirection. The response data of such procedure are these response parameters.
Synchronous Response Parameters Description

Parameters

Type(length)

Description

Optional

Example

Basic Parameters

is_success

String

Indicate whether the API has been called successfully, it does not indicate the result of business

  • T for True
  • F for False

N

T

sign_type

String

DSA, RSA or MD5, capital letter

N

MD5

sign

String

Sign value

N

7d314d22efba4f336fb187697793b9d2

error

String

Error information when query fails.

Y

TRADE_NOT_EXIST

Business Parameters

buyer_email

String

Buyer Alipay Account

N

tstable01@alipay.com

buyer_id

String

A unique buyer ID to identify a contracted Alipay Account.

N

2088002007018955

trade_status

String

The status of this transaction can be:

  • TRADE_FINISHED
  •  WAIT_BUYER_PAY
  • TRADE_CLOSED
  • N

    TRADE_FINISHED

    is_total_fee_adjust

    String

    Is total fee adjusted

    • T for True
    • F for False

    N

    F

    out_trade_no

    String

    A unique number to identify a transaction in partner system

    Y

    6843192280647118

    trade_no

    String

    The unique trade number in Alipay system.Length from 16 to 64. To query by Alipay trade number is preferred w.r.t the accuracy of the result.

    N

    2008102303210710

    subject

    String

    Goods name/trade name/order name/order key words etc.

    N

    Apple

    flag_trade_locked

    String

    • 1 for trade is locked.
    • 0 for trade is not locked.

    N

    0

    body

    String

    Detail description about a transaction, if there are multiple items involved, accumulate together into body.

    N

    Gundam MKII,Miniature Bracelet

    gmt_create

    Date

    Time when transaction is created. Format: yyyy-MM-dd HH:mm:ss

    N

    2008-10-22 20:49:31

    seller_email

    String

    Partner Alipay Account

    N

    tianc001@alipay.com

    seller_id

    String

    A unique partner ID to identify a contracted Alipay Account. A 16 digit number starts with 2088

    N

    2088002007018966

    total_fee

    Number

    The total amount of the transaction for the escrow payment. Range: 0.01 to 1000000.00, accurate to 2 digits after the decimal point. Unit: RMB.

    N

    100

    price

    Number

    Unit:RMB Yuan. Value Range [0.01,100000000.00],accurate to two decimal places.

    Y

    10.00

    quantity

    Number

    Quantity of goods.

    Y

    1

    coupon_discount

    String

    Coupon discount.

    Y

    1

    use_coupon

    String(1)

    Whether coupon is used in transaction.

    • T for True
    • F for False

    Y

    T

    discount

    Number

    Discount

    Y

    0.00

    gmt_last_modified_time

    Date

    Time when the total fee is modified latest. Format: yyyy-MM-dd HH:mm:ss

    Y

    2008-01-08 20:39:30

    gmt_payment

    Date

    Time when transaction is paid by user. Format: yyyy-MM-dd HH:mm:ss

    Y

    2008-10-22 20:49:50

    to_buyer_fee

    String

    Accumulative refunded fee.

    Y

    1.00

    to_seller_fee

    String

    Accumulative fee paid to seller.

    Y

    20.00

    payment_type

    String

    Please refer to “Payment Type”

    Y

    1

    operator_role

    String

    • B:Buyer
    • S:Seller

    Y

    B

    Samples

    Request Sample

    https://mapi.alipay.com/gateway.do?service=single_trade_query&sign=d8ed9f015214e7cd59bfadb6c945a87b&trade_no=2010121502730740&partner=2088721091300630&out_trade_no=2009011803596246&sign_type=MD5

    Response Sample

    Success response
    <alipay>
    <is_success>T</is_success>
    <request>
    <param name="_input_charset">UTF-8</param>
    <param name="service">single_trade_query</param>
    <param name="partner">2088721091300630</param>
    <param name="out_trade_no">2009011803596246</param>
    <param name="sendFormat">normal</param>
    </request>
    <response>
    <trade>
    <body>hello</body>
    <buyer_email>intltest059@service.alipay.com</buyer_email>
    <buyer_id>2088122921745555</buyer_id>
    <discount>0.00</discount>
    <flag_trade_locked>0</flag_trade_locked>
    <gmt_create>2017-06-15 16:25:31</gmt_create>
    <gmt_last_modified_time>2017-06-15 16:25:58</gmt_last_modified_time>
    <gmt_payment>2017-06-15 16:25:58</gmt_payment>
    <is_total_fee_adjust>F</is_total_fee_adjust>
    <operator_role>B</operator_role>
    <out_trade_no>2009011803596246</out_trade_no>
    <payment_type>100</payment_type>
    <price>0.02</price>
    <quantity>1</quantity>
    <seller_email>test@126.com</seller_email>
    <seller_id>2088721091300630</seller_id>
    <subject>world</subject>
    <to_buyer_fee>0.00</to_buyer_fee>
    <to_seller_fee>0.02</to_seller_fee>
    <total_fee>0.02</total_fee>
    <trade_no>2017061521001003550204235677</trade_no>
    <trade_status>TRADE_FINISHED</trade_status>
    <use_coupon>F</use_coupon>
    </trade>
    </response>
    <sign>6283ce0cf5aaa812d9c1d29719d53e8d</sign>
    <sign_type>MD5</sign_type>
    </alipay>
    Error response
    <?xml version="1.0"  encoding="utf-8"?>
      <alipay>
      <is_success>F</is_success>
      <error>ILLEGAL_SIGN</error>
      </alipay>

    For the system API calls, in general, the validations are being done at two levels on Alipay side.

    The first level is at the API gateway level, where it does certain sanity checks such as verifying the signature, verifying if the partner ID is valid or whether the partner has permission to call this particular API, etc. If the validation fails, Alipay would return the appropriate error codes which are classified as the 'API Gateway Error Codes' as in the below.

    Once it passes the validations at the API gateway level, the API request would be dispatched to the internal system for further processing, which it would be subjected to the validations of the business logic. The corresponding error codes returned are classified as the 'Business Error Codes".

    Business Logic Errors

    Error Codes

    Descriptions

    TRADE_NOT_EXIST

    Trade not exist. out_trade_no or Alipay trade_no is incorrect

    ILLEGAL_SIGN

    Illegal signature.

    ILLEGAL_DYN_MD5_KEY

    Dynamic key information is incorrect.

    ILLEGAL_ENCRYPT

    Encryption is incorrect.

    ILLEGAL_ARGUMENT

    Parameter is incorrect.

    ILLEGAL_SERVICE

    Service parameter is incorrect.

    ILLEGAL_USER

    User ID is incorrect.

    ILLEGAL_PARTNER

    Partner ID is incorrect.

    ILLEGAL_EXTERFACE

    Interface configuration is incorrect.

    ILLEGAL_PARTNER_EXTERFACE

    Partner’s interface information is incorrect.

    ILLEGAL_SECURITY_PROFILE

    Matching private key configuration has not been found.

    ILLEGAL_AGENT

    Agency ID is incorrect.

    ILLEGAL_SIGN_TYPE

    The signature type is incorrect.

    ILLEGAL_CHARSET

    The character set is illegal.

    ILLEGAL_CLIENT_IP

    Client IP address is illegal

    HAS_NO_PRIVILEGE

    Has no right to visit.

    ILLEGAL_DIGEST_TYPE

    Digest type is illegal

    ILLEGAL_DIGEST

    Digest is illegal

    ILLEGAL_FILE_FORMAT

    File format is illegal

    ILLEGAL_ENCODING

    Encoding type is illegal

    EXTERFACE_IS_CLOSED

    API is closed

    ILLEGAL_REQUEST_REFERER

    Anti-phishing checks illegal request

    ILLEGAL_ANTI_PHISHING_KEY

    Anti-phishing checks illegal timeframe

    ANTI_PHISHING_KEY_TIMEOUT

    Anti-phishing checks timeframe timeout

    ILLEGAL_EXTER_INVOKE_IP

    IP Anti-phishing checks illegal IP

    System Errors

    When system error occurs, please contact Alipay Technical Support to assist the error repair..

    Returned result

    Description

    SYSTEM_ERROR

    Alipay system failed to process the request due to temporary internal glitch.

    SESSION_TIMEOUT

    Session timeout

    ILLEGAL_TARGET_SERVICE

    Wrong  target service

    ILLEGAL_ACCESS_SWITCH_SYSTEM

    Merchant is not allowed to visit system of this type.

    EXTERFACE_IS_CLOSED

    The interface has been closed.

    Payment Type

    Type

    Description

    01

    Coupon Fee Pre-payment

    02

    Coupon Fee Payment

    03

    Reminding Payment

    04

    Automatic Sending Goods

    1

    Merchandise

    2

    Service Purchase

    3

    Online Auction

    4

    Donation

    5

    Post Fee Compensation

    6

    Bonus

    7

    Funds Purchase

    8

    Air Ticket

    9

    Go Dutch

    10

    Group Purchase

    11

    Electronic Ticket

    12

    Lottery Ticket

    13

    Auction

    14

    Mobile Payment

    15

    Flowers & Gifts

    16

    Agent Electronic Ticket

    17

    Party Membership Dues

    18

    Foreign Exchange

    19

    Automatic Charge

    20

    Refund of Overseas Payment

    21

    Refund of Instant Payment

    22

    Business Deposit

    24

    Cash Gift

    25

    Rent

    26

    Motopay

    23

    Shopping Chart

    27

    Escrow Payment of Group Purchase

    Transaction Status

    Status

    Description

    WAIT_BUYER_PAY

    Transaction awaits user payment.

    WAIT_SELLER_SEND_GOODS

    Transaction awaits seller sending goods.

    WAIT_BUYER_CONFIRM_GOODS

    Transaction awaits buyer confirming goods.

    TRADE_FINISHED

    Transaction is finished successfully.

    TRADE_CLOSED

    Transaction is closed during processing (finished, not successfully)

    WAIT_SYS_CONFIRM_PAY

    Transaction awaits system conforming payment, please do not send goods.

    WAIT_SYS_PAY_SELLER

    Buyer confirm goods, transaction awaits system paying to seller.

    TRADE_REFUSE

    Transaction refused.

    TRADE_REFUSE_DEALING

    Transaction refusing.

    TRADE_CANCEL

    Transaction canceled.

    TRADE_PENDING

    Pending Transaction.

    TRADE_SUCCESS

    Transaction complete, and available for refund

    BUYER_PRE_AUTH

    Buyer has paid. (IVR Payment)

    COD_WAIT_SELLER_SEND_GOODS

    Transaction awaits seller sending goods. (COD)

    COD_WAIT_BUYER_PAY

    Transaction awaits user payment. (COD)

    COD_WAIT_SYS_PAY_SELLER

    Buyer confirm goods, transaction awaits system paying to seller. (COD)

    Additional Trade Status

    Status

    Description

    ZHIFUBAO_CONFIRM

    Custom Service confirms goods for buyer.

    ZHIFUBAO_CANCEL_FP

    Custom Service cancels instant payment for buyer.

    DAEMON_CONFIRM_CANCEL_PRE_AUTH

    Expiration Program cancels pre authorization.

    DAEMON_CONFIRM_CLOSE

    Expiration Program cancels transaction as buyer did not pay.

    From time to time, the merchant needs to reconcile the transactions. This interface enables the merchants to download the transaction list in a specific time span to reconcile the transactions.

    Request Parameters

    Parameter

    Type (length in bytes)

    Description

    Optional

    Example

    Basic Parameter

    service

    String

    Service Name

    N

    forex_compare_file

    partner

    String(16)

    Partner ID.
    Composed of 16 digits beginning with 2088.

    N

    2088001159940003

    sign_type

    String

    Signature method. The following are supported. Must be uppercase.
    DSA, RSA, and MD5.

    N

    RSA

    sign

    String

    Signature value.

    N

    e5815a4556db338ed237f7d3fd222184

    Business Parameter

    start_date

    String

    The start date of the reconciliation period, formatted as YYYYMMDD

    N

     

    end_date

    String

    The end date of the reconciliation period, formatted as   YYYYMMDD

    N

     

    • The starting and end dates should be within a 10-day interval.
    • There is a time delay such that the transactions in the current day will not be listed in the return of this API call.
    • Currently the interface only supports .TXT file to be downloaded. The file contains no headings for data fields. Each data field is separated by “|”, following the order given in the specification.

    Sync Response

    Response format

    The responses could be in different formats for different use cases

    File Format for the Transaction Report file in the Response

    Order

    Field name

    Type

    Description

    1

    Partner transaction ID

    String(64)

    The  Unique transaction ID passed by the merchants in the payment transaction

    2

    Amount

    Number(8,2)

    The amount of fund in foreign currency.

    3

    Currency

    String(10)

    Abbreviated currency names.

    4

    Payment Time

    String(14)

    YYYYMMDDHHMMSS
    Empty if the status being “failed” or “waiting”.

    5

    Settlement Time

    String(14)

    YYYYMMDDHHMMSS
    Empty if unliquidated

    6

    Transaction type

    String(1)

    Normal transaction: P
    Refund transaction: R

    7

    Service charge

    Number(8,2)

    The amount of service charge.

    8

    Status

    String(1)

    Normal transaction:
    P : Payment made         
    L: Liquidated
    Refund transaction :
    F: Failed   
    L: Liquidated

    9

    Remark

    String(50)

    An optional field. If the transaction is refund, the time of the refund request should be added into the remark field in YYYYMMDDHHMMSS format.

    10

    Split foreign currency amount

    Number(8,2)

    This trade's split foreigh currency amount or this refund's split refund foreigh currency amount.

    11

    Split RMB amount

    Number(8,2)

    This trade's split RMB amount or this refund's split refund RMB amount.


    Samples

    Request Sample

    https://mapi.alipay.com/gateway.do?sign_type=MD5&sign=bb4c92c7cb7fc8a5280fe5f9f7ac309c&_input_charset=UTF-8&end_date=20150524&service=forex_compare_file&partner=2088002007018916&start_date=20150520

    Response Sample

    Success response

    The response is HTTP response with an attached file, which is the reconciliation file with the transactions included.
    The sample is for illustration of the browser download.

    Error response from the biz logic:
    File download failed: Over 10 days to Date period

    Error response from the Gateway:

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

    A sample of transaction report file:

    23342347424|112.11|USD|20070616090001||P|2.24|P|Unliquidated
    23342343423|102.32|USD|20070615090001|2007622090001|P|2.04|L|Liquidated

    For the system API calls, in general, the validations are being done at two levels on Alipay side.

    The first level is at the API gateway level, where it does certain sanity checks such as verifying the signature, verifying if the partner ID is valid or whether the partner has permission to call this particular API, etc. If the validation fails, Alipay would return the appropriate error codes which are classified as the 'API Gateway Error Codes' as in the below.

    Once it passes the validations at the API gateway level, the API request would be dispatched to the internal system for further processing, which it would be subjected to the validations of the business logic. The corresponding error codes returned are classified as the 'Business Error Codes".

    Business Logic Errors

    Returned result

    Description

    Over limit balance amount record

    Exceed the maximum entries : 100000

    System exception

    System exception

    Merchant ID incorrect

    Incorrect partner ID

    Finish date not ahead of today

    The end date could not be the future time

    No balance amount data in the period

    Do not have any trade during the period

    Over 10 days to date period

    Over 10 day limit for the request time span

    Finish date ahead of begin date

    The end date needs to be later than the begin date

    Illegal date period

    Null in date field

    Date format incorrect YYYYMMDD

    Incorrect format of the date ,YYYYMMDD

    Internet connected exception ,please try later

    Network exception

    Access Errors / Common Errors with MAPI Gateway

    If the calling parameters have error in it, Alipay MAPI gateway will capture it and display the errors. However, the control flow will stay at the Alipay side and will NOT return to the merchant’s site.

    Returned result

    Description

    SYSTEM_EXCEPTION

    Alipay system error

    ILLEGAL_ARGUMENT

    Incorrect parameter

    ILLEGAL_SIGN

    Illegal signature

    ILLEGAL_SERVICE

    Service Parameter is incorrect

    ILLEGAL_PARTNER

    Incorrect Partner ID

    ILLEGAL_SIGN_TYPE

    Signature is of wrong type.

    ILLEGAL_PARTNER_EXTERFACE

    Service is not activated for this account

    ILLEGAL_DYN_MD5_KEY

    Dynamic key information is incorrect

    ILLEGAL_ENCRYPT

    Encryption is incorrect.

    ILLEGAL_USER

    User ID is incorrect.

    ILLEGAL_EXTERFACE

    Interface configuration is incorrect.

    ILLEGAL_AGENT

    Agency ID is incorrect.

    HAS_NO_PRIVILEGE

    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 to assist the error repair.

    Returned result

    Description

    SYSTEM_ERROR

    Alipay system error

    SESSION_TIMEOUT

    Session timeout

    ILLEGAL_TARGET_SERVICE

    Wrong  target service

    ILLEGAL_ACCESS_SWITCH_SYSTEM

    Merchant is not allowed to visit system of this type.

    EXTERFACE_IS_CLOSED

    The interface has been closed.

    This interface enables the merchant reconcile the settled transactions with the settlement of the funds in the previous settlement cycle.

    Request Parameters

    Parameter

    Type (length in bytes)

    Description

    Optional

    Example

    Basic Parameter

    service

    String

    Service Name

    N

    forex_liquidation_file

    partner

    String(16)

    Partner ID.
    Composed of 16 digits beginning with 2088.

    N

    2088001159940003

    sign_type

    String

    Signature method. The following are supported. Must be uppercase.
    DSA, RSA, and MD5.

    N

    RSA

    sign

    String

    Signature value.

    N

    e5815a4556db338ed237f7d3fd222184

    Business Parameter

    start_date

    String

    The start date of the reconciliation period, formatted as YYYYMMDD

    N

     

    end_date

    String

    The end date of the reconciliation period, formatted as?? YYYYMMDD

    N

     

    • The starting and end dates should be provided within a 10-day interval.
    • There is a time delay such that the transactions in the current day will not be listed in the return of this API call.
    • Currently the interface only supports .TXT file to be downloaded. The file contains no headings for data fields. Each data field is separated by “|”, following the order given in the specification.

    Sync Response

    Response format

    The responses could be in different formats for different use cases

    File Format for the Settlement file in the Response

    Order

    Field name

    Type

    Description

    1

    Partner transaction ID

    String(64)

    The? Unique transaction ID passed by the merchants in the payment transaction

    2

    Amount

    Number(8,2)

    The amount of fund in foreign currency.

    3

    Currency

    String(10)

    Abbreviated currency names.

    4

    Payment Time

    String(14)

    YYYYMMDDHHMMSS
    Empty if the status being “failed” or “waiting”.

    5

    Settlement Time

    String(14)

    YYYYMMDDHHMMSS
    Empty if unliquidated

    6

    Transaction type

    String(1)

    Normal transaction: P
    Refund transaction: R

    7

    Service charge

    Number(8,2)

    The amount of service charge.

    8

    Status

    String(1)

    Normal transaction:
    L: Liquidated
    Refund transaction:
    L: Liquidated

    9

    Remark

    String(50)

    An optional field. If the transaction is refund, the time of the refund request should be added into the remark field in YYYYMMDDHHMMSS format.

    10

    Split foreign currency amount

    Number(8,2)

    This trade's split foreigh currency amount or this refund's split refund foreigh currency amount.

    11

    Split RMB amount

    Number(8,2)

    This trade's split RMB amount or this refund's split refund RMB amount.

    Samples

    Request Sample

    https://mapi.alipay.com/gateway.do?sign_type=MD5&sendFormat=normal&sign=bb4c92c7cb7fc8a5280fe5f9f7ac309c&_input_charset=UTF-8&end_date=20150524&service=forex_liquidation_file&partner=2088002007018916&start_date=20150520

    Response Samples

    Success response

    The response is HTTP response with an attached file, which is the settlement file with the transactions included.
    The sample is for illustration of the browser download.

    Error response from the biz logic:

    File download failed: Over 10 days to Date period

    Error response from the Gateway:

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

    An example of settlement report file:

    23342343423|102.32|USD|20070615090001|2007622090001|P|2.04|L|Liquidated

    For the system API calls, in general, the validations are being done at two levels on Alipay side.

    The first level is at the API gateway level, where it does certain sanity checks such as verifying the signature, verifying if the partner ID is valid or whether the partner has permission to call this particular API, etc. If the validation fails, Alipay would return the appropriate error codes which are classified as the 'API Gateway Error Codes' as in the below.

    Once it passes the validations at the API gateway level, the API request would be dispatched to the internal system for further processing, which it would be subjected to the validations of the business logic. The corresponding error codes returned are classified as the 'Business Error Codes".

    Business Logic Errors

    Returned result

    Description

    Over limit balance amount record

    Exceed the maximum entries: 100000

    System exception

    System exception

    Merchant ID incorrect

    Incorrect partner ID

    Finish date not ahead of today

    The end date could not be the future time

    No balance amount data in the period

    Do not have any trade during the period

    Over 10 days to date period

    Over 10 day limit for the request time span

    Finish date ahead of begin date

    The end date needs to be later than the begin date

    Illegal date period

    Null in date field

    Date format incorrect YYYYMMDD

    Incorrect format of the date ,YYYYMMDD

    Internet connected exception ,please try later

    Network exception

    Access Errors / Common Errors with MAPI Gateway

    If the calling parameters have error in it, Alipay MAPI gateway will capture it and display the errors. However, the control flow will stay at the Alipay side and will NOT return to the merchant’s site.

    Returned result

    Description

    SYSTEM_EXCEPTION

    Alipay system error

    ILLEGAL_ARGUMENT

    Incorrect parameter

    ILLEGAL_SIGN

    Illegal signature

    ILLEGAL_SERVICE

    Service Parameter is incorrect

    ILLEGAL_PARTNER

    Incorrect Partner ID

    ILLEGAL_SIGN_TYPE

    Signature is of wrong type.

    ILLEGAL_PARTNER_EXTERFACE

    Service is not activated for this account

    ILLEGAL_DYN_MD5_KEY

    Dynamic key information is incorrect

    ILLEGAL_ENCRYPT

    Encryption is incorrect.

    ILLEGAL_USER

    User ID is incorrect.

    ILLEGAL_EXTERFACE

    Interface configuration is incorrect.

    ILLEGAL_AGENT

    Agency ID is incorrect.

    HAS_NO_PRIVILEGE

    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 to assist the error repair.

    Returned result

    Description

    SYSTEM_ERROR

    Alipay system error

    SESSION_TIMEOUT

    Session timeout

    ILLEGAL_TARGET_SERVICE

    Wrong  target service

    ILLEGAL_ACCESS_SWITCH_SYSTEM

    Merchant is not allowed to visit system of this type.

    EXTERFACE_IS_CLOSED

    The interface has been closed.

    To get the exchange rate from Alipay, the partners can call this API.

  • The exchange rate changes once between 9:00 and 11:00 GMT+8 everyday.
  • The maximum number of queries is 100 each day.
  • Request Parameters

    Parameter

    Type (length in bytes)

    Description

    Optional

    Example

    Basic Parameter

    service

    String

    Service Name

    N

    forex_rate_file

    partner

    String(16)

    Partner ID.
    Composed of 16 digits beginning with 2088.

    N

    2088001159940003

    sign_type

    String

    Signature method. The following are supported. Must be uppercase.
    DSA, RSA, and MD5.

    N

    RSA

    sign

    String

    Signature value.

    N

    e5815a4556db338ed237f7d3fd222184

    • Currently the interface only supports .txt file to be downloaded.
    • The file contains no headings for data fields, and each data field is separated by “|”
    • The data is just for current day’s exchange rate.

    Sync Response

    Response format

    The responses could be in different formats for different use cases

    File Format for the Transaction Report file in the Response

    Order

    Field name

    Type

    Description

    1

    Date

    String(8)

    Rate releasing date: YYYYMMDD

    2

    Time

    String(6)

    Rate releasing time: HHMMSS

    3

    Currency

    String(3)

    Abbreviated currency names.

    4

    Rate

    String(10)

     

    Samples

    Request Sample

    https://mapi.alipay.com/gateway.do?sign_type=MD5&sendFormat=normal&sign=590a9fbbed8a5b9a86b426795445f9f0&service=forex_rate_file&partner=2088101122136241

    An example of the rate file:

    20160504|100030|CHF|6.829600|
    20160504|100030|EUR|7.491500|
    20160504|100030|THB|0.185877|
    20160504|100030|DKK|1.007800|
    20160504|100030|SGD|4.815600|
    20160504|100030|GBP|9.476100|
    20160504|100030|HKD|0.838800|
    20160504|100030|NOK|0.803000|
    20160504|100030|CAD|5.124900|
    20160504|100030|KRW|0.005814|
    20160504|100030|NZD|4.496100|
    20160504|100030|JPY|0.060934|
    20160504|100030|AUD|4.877600|
    20160504|100030|SEK|0.809800|
    20160504|090530|USD|6.534600|

    Response Samples

    Success response

    The response is HTTP response with an attached file, which is the FX rate file with the FX included.
    The sample is for illustration of the browser download.

    Error response from the biz logic:
    File download failed: Over 10 days to Date period
    Error response from the Gateway:
    <?xml version="1.0" encoding="UTF-8"?>
    <alipay>
    <is_success>F</is_success>
    <error>ILLEGAL_SIGN</error>
    </alipay>

    For the system API calls, in general, the validations are being done at two levels on Alipay side.

    The first level is at the API gateway level, where it does certain sanity checks such as verifying the signature, verifying if the partner ID is valid or whether the partner has permission to call this particular API, etc. If the validation fails, Alipay would return the appropriate error codes which are classified as the 'API Gateway Error Codes' as in the below.

    Once it passes the validations at the API gateway level, the API request would be dispatched to the internal system for further processing, which it would be subjected to the validations of the business logic. The corresponding error codes returned are classified as the 'Business Error Codes".

    Business Logic Errors

    Returned result

    Description

    System exception

    Alipay system error

    Merchant ID incorrect

    Invalid partner ID

    File empty

    Null content of the file

    Access Errors / Common Errors with MAPI Gateway

    If the calling parameters have error in it, Alipay MAPI gateway will capture it and display the errors. However, the control flow will stay at the Alipay side and will NOT return to the merchant’s site.

    Returned result Description

    ILLEGAL_ARGUMENT

    Incorrect parameter

    ILLEGAL_SIGN

    Illegal signature

    ILLEGAL_SERVICE

    Service Parameter is incorrect

    ILLEGAL_PARTNER

    Incorrect Partner ID

    ILLEGAL_SIGN_TYPE

    Signature is of wrong type.

    ILLEGAL_PARTNER_EXTERFACE

    Service is not activated for this account

    ILLEGAL_DYN_MD5_KEY

    Dynamic key information is incorrect

    ILLEGAL_ENCRYPT

    Encryption is incorrect.

    ILLEGAL_USER

    User ID is incorrect.

    ILLEGAL_EXTERFACE

    Interface configuration is incorrect.

    ILLEGAL_AGENT

    Agency ID is incorrect.

    HAS_NO_PRIVILEGE

    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 to assist the error repair.

    Returned result Description

    SYSTEM_ERROR

    Alipay system error

    SESSION_TIMEOUT

    Session timeout

    ILLEGAL_TARGET_SERVICE

    Wrong  target service

    ILLEGAL_ACCESS_SWITCH_SYSTEM

    Merchant is not allowed to visit system of this type.

    EXTERFACE_IS_CLOSED

    The interface has been closed.

    Request Parameters

    Parameter

    Type (length in bytes)

    Description

    Optional

    Example

    Basic Parameter

    service

    String

    Service Name

    N

    notify_verify

    partner

    String(16)

    Partner ID.
    Composed of 16 digits beginning with 2088.

    N

    2088001159940003

    Business Parameter

    notify_id

    String(34)

    The ID of Alipay system’s notification.

    N

    • The proper event sequence to verify async notification is as the following
      • Receive the notification, do not reply ‘Success’ yet. Otherwise the reply will impact the system behavior. (Alipay will return false for all the inquiries whose notification has been replied with “success”).
      • Verify the notify id through calling this API.
        • If the input parameter is invalid, Alipay will return “Invalid”
        • If the notification is sent by Alipay and the inquiry occurs with the pre-defined time frame, Alipay will return “True”.
        • If the notification is not sent by Alipay, Alipay will return “False”.
        • If the inquiry occurs out of the pre-defined time frame, Alipay will return “False”.
        • If the merchant has replied any of the notification with the response of “true”, Alipay will return “False”.
      • Once verified, the merchant should reply “Success” to the asynchronous notification. If not, process with the proper business logic.

    Sync Response

    The response is a string with the status.

    Response Samples

    If the input parameter is invalid, return,

    
    Invalid
    

    If the notification is from Alipay, and inquires in the valid time frame, (1 min)

    
    True
    

    If the notification is not from Alipay, or passes 1 min time frame,

    
    False
    

    Samples

    Request Sample

    https://intlmapi.alipay.com/gateway.do?service=notify_verify&partner=2088101122136241&notify_id=4465b04e84cb6bacc2bd1b52232c0b8gjg&sign=ciSBXc7gjCfXW8KMBxFiFH2cbMZtFelfTOGKqY2NF7q98RnH3E%2BiF5Cj%2Fu%2Bl8py1D%2FOsE%2FAva1ls8A6Tw1MzhG6ideJSgh4FxWmAjEnlczdfLj%2FqzA6qGzxdKGEXaSDFmTGglOembXUqK8g8ajICD%2BBH7xoxBRY7vtfylEXtojs%3D&sign_type=RSA

    For the system API calls, in general, the validations are being done at two levels on Alipay side.

    The first level is at the API gateway level, where it does certain sanity checks such as verifying the signature, verifying if the partner ID is valid or whether the partner has permission to call this particular API, etc. If the validation fails, Alipay would return the appropriate error codes which are classified as the 'API Gateway Error Codes' as in the below.

    Once it passes the validations at the API gateway level, the API request would be dispatched to the internal system for further processing, which it would be subjected to the validations of the business logic. The corresponding error codes returned are classified as the 'Business Error Codes".

    Business Logic Errors

    Returned result Description

    SYSTEM_EXCEPTION

    Alipay system error

    ILLEGAL_ARGUMENT

    Incorrect parameter

    ILLEGAL_SIGN

    Illegal signature

    ILLEGAL_SERVICE

    Service Parameter is incorrect

    ILLEGAL_PARTNER

    Incorrect Partner ID

    ILLEGAL_SIGN_TYPE

    Signature is of wrong type.

    Access Errors / Common Errors with MAPI Gateway

    If the calling parameters have error in it, Alipay MAPI gateway will capture it and display the errors. However, the control flow will stay at the Alipay side and will NOT return to the merchant’s site.

    Returned result Description

    SYSTEM_EXCEPTION

    Alipay system error

    ILLEGAL_ARGUMENT

    Incorrect parameter

    ILLEGAL_SIGN

    Illegal signature

    ILLEGAL_SERVICE

    Service Parameter is incorrect

    ILLEGAL_PARTNER

    Incorrect Partner ID

    ILLEGAL_SIGN_TYPE

    Signature is of wrong type.

    ILLEGAL_PARTNER_EXTERFACE

    Service is not activated for this account

    ILLEGAL_DYN_MD5_KEY

    Dynamic key information is incorrect

    ILLEGAL_ENCRYPT

    Encryption is incorrect.

    ILLEGAL_USER

    User ID is incorrect.

    ILLEGAL_EXTERFACE

    Interface configuration is incorrect.

    ILLEGAL_AGENT

    Agency ID is incorrect.

    HAS_NO_PRIVILEGE

    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 to assist the error repair.

    Returned result Description

    SYSTEM_ERROR

    Alipay system error

    SESSION_TIMEOUT

    Session timeout

    ILLEGAL_TARGET_SERVICE

    Wrong  target service

    ILLEGAL_ACCESS_SWITCH_SYSTEM

    Merchant is not allowed to visit system of this type.

    EXTERFACE_IS_CLOSED

    The interface has been closed.

    Refund split detail parameter format is JSON, include follow parameters:

    Parameter

    Type (Byte length)

    Description

    Optional

    Example

    transOut

    String

    Alipay userID that Alipay account for transfer refund fee . Alipay userID that composed of 16 digits beginning with 2088.

    N

    2088101126708402

    amount

    String

    Split Amount. The format must be correct to the currency!

    N

    0.10

    currency

    String

    Split currency .The currency must be same with refund currency!
    If parameter (total_fee) was used, the split currency must be foreign currency and the same with settlement currency!
    If parameter (rmb_fee) was used, the split currency must be ‘CNY’!

    The parameter (total_fee and rmb_fee ) are mutual exclusive.

    N

    USD

    desc

    String

    Split discretion

    Y

    Refund split test1

    Example

    Format Structure :

    split_fund_info=[{"transOut":"2088101126708402",  "amount":"0.10", "currency":"USD",  "desc":"test1"},   {" transOut  ":"2088101126708402", "amount":"0.30",  "currency":"USD", "desc":"test2"}]

    Refund splitting does not need to follow exactly the payment splitting. Just ensure that the total refund amount is equal to the total payment amount. For example, ¥9 of the total payment of ¥10 was allocated to the primary account, ¥1 to the split account. When performing a refund, you can return ¥5 through the primary account, ¥5 through the split account.

    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.

    What is a mock service

    The mock service provides simulations of different payment results to get you familiarized with the possible payment scenarios beforehand. With the simulated scenarios provided in a sandbox environment, you can test failed payment processes with different types of responses and learn to handle exception scenarios. The mock service aims to optimize your exception and error handling abilities and therefore, improve your Alipay integration quality with lower integration cost and better user experience.

    Previously, many exception scenarios are difficult or even impossible to be simulated. With the mock service, you can run test cases for all the scenarios and see whether the response is as designed. Besides the default mock rules, you can also customize mock rules for exception scenarios based on your business requirements. By now, the mock service supports the process of payment, cancel, refund, and query.

    How to use a mock service

    Before using a mock service, you need to have an Alipay merchant account. See Creating an Alipay merchant account

    Watch the following video to have a quick overview of how to use a Mock service:

    1. Log in your sandbox and go to the mock service part. By now, the mock service supports the following 4 APIs:

    2. Configure mock rules by specifying mock API requests and corresponding responses.
    Two types of mock rules exist for each API: default rules and custom rules.

    3. Send an API request that matches the specified mock rules. You will receive a corresponding mock response and then process it. For example, you can send an alipay.acquire.overseas.spot.pay request with the following mock rule. See the below sample code and a corresponding mock response for details. The default mock rule:

    Samples

    Sample request:

    http://mapi.alipaydev.com/gateway.do?client_info=%7B%22client_ip%22%3A%2210.20.30.40%22%7D&identity_code_type=barcode&memo=nomemo&trans_amount=9901&sign_type=MD5&trans_name=xxxzgl&buyer_identity_code=288888888888888888&partner_trans_id=8567745904202380&password=SJV88po0XvIptqWGM4rxP5EQ&sendFormat=normal¤cy=USD&sign=6030aea30c96e01c6e5c709c9f66a7df&agreement_info=%7B%22agreement_no%22%3A%22123%22%7D&trans_currency=USD&biz_product=OVERSEAS_MBARCODE_PAY&service=alipay.acquire.overseas.spot.pay&format_type=xml&quantity=1&partner=2088621880270354

    Sample response:

    
    <?xml version="1.0" encoding="GBK"?>
    <alipay>
         <is_success>T</is_success>
         <request>
            <param name="client_info">{"client_ip":"10.20.30.40"}</param>
            <param name="quantity">1</param>
            <param name="biz_product">OVERSEAS_MBARCODE_PAY</param>
            <param name="identity_code_type">barcode</param>
            <param name="sign">6030aea30c96e01c6e5c709c9f66a7df</param>
            <param name="memo">nomemo</param>
            <param name="trans_name">xxxzgl</param>
            <param name="trans_amount">9901</param>
            <param name="sendFormat">normal</param>
            <param name="partner_trans_id">8567745904202380</param>
            <param name="password">SJV88po0XvIptqWGM4rxP5EQ</param>
            <param name="format_type">xml</param>
            <param name="trans_currency">USD</param>
            <param name="partner">2088621880270354</param>
            <param name="agreement_info">{"agreement_no":"123"}</param>
            <param name="service">alipay.acquire.overseas.spot.pay</param>
            <param name="currency">USD</param>
            <param name="sign_type">MD5</param>
            <param name="buyer_identity_code">288888888888888888</param>
         </request>
         <response>
         	<alipay>
         		<error>SYSTEM_ERROR</error>
         		<result_code>FAILED</result_code>
         	</alipay>
         </response>
         <sign>d0117413cdf375ab667329892ab7f890</sign>
         <sign_type>MD5</sign_type>
    </alipay>
    

    Alipay provide reconciliation files to merchant using cross-border online payment and 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:

    You can obtain the reconciliation files by using APIs, or 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.

    API

    To acquire reconciliation files, first integrate Alipay online payment APIs with your system, and call the following two APIs.

    forex_compare_file is for acquiring transaction files.

    forex_liquidation_file is for acquiring settlement files.

    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

    Security audit requirements:

    • SFTP accounts that are not used within 90 days will be closed.
    • Only files within last 30 days can be viewed on the SFTP server. Files older than 30 days will be deleted.

    Reconciliation files consist of transaction files and settlement files. Settlement files from SFTP and Alipay global site also contain a summary file. Files form API, SFTP and Alipay global site varies in naming convention and contents.

    Transaction file

    Transaction files contain transaction record of the selected time period.

    Depending on where you download the file, the file name might consist of different parts. See the following table for details.

    Partner ID

    Date

    File Type

    File Suffix

    Sample

    API

    A unique ID assigned by Alipay

    YYYYMMDD + a 6-digit random number

    /

    .txt

    2088021017666931_20180531143440.txt

    Website

    A unique ID assigned by Alipay

    YYYYMMDD, YYYYMM, or YYYYMMDD + a 6-digit random number

    /

    .csv, .txt, or .xls

    2088611221573217_20180621151516.xls

    SFTP

    A unique ID assigned by Alipay

    YYYYMMDD

    A fixed value: "transaction"

    .csv

    2088721631012256_20171228_transaction.csv

    A transaction file might contain the following fields:

    NO.

    Field Name

    Description

    1

    Partner_transaction_id

    A unique transaction ID specified by the partner. It is the same with out_trade_no in the payment request or out_return_no in refund request.

    2

    Amount

    Transaction amount in foreign currency

    3

    Rmb_amount

    Transaction amount in CNY

    4

    Currency

    Currency

    5

    Fee

    Service fee in foreign currency

    6

    Rate

    Foreign exchange rate

    7

    Payment_time

    Payment time

    8

    Settlement_time

    Settlement time

    9

    Type

    Transaction type

    10

    Status

    Status.
    For transactions, P is paid, L is liquidated.
    For refunds, W is pending, F is failed.

    11

    Original_partner_transaction_ID

    The original partner transaction ID. It is the same with the out_trade_no in the payment request.

    12

    Transaction_ID

    A unique transaction ID specified by Alipay

    13

    Distribute_amount

    The split foreign currency amount of a trade or refund

    14

    Distribute_rmb_amount

    The split CNY amount of a trade or refund

    15

    Remarks

    Remarks

    16

    Settlement

    Settlement amount in foreign currency

    17

    Rmb_settlement

    Settlement amount in CNY

    The contents of transaction files that you download from API, website and SFTP are different. See the following table for details:

    NO.

    Field Name

    SFTP

    API

    Global Site Online

    Global Site Download

    1

    Partner_transaction_id

    Yes

    Yes

    Yes

    Yes

    2

    Amount

    Yes

    Yes

    Yes

    Yes

    3

    Rmb_amount

    Yes

    /

    Yes

    Yes

    4

    Currency

    Yes

    Yes

    Yes

    Yes

    5

    Fee

    Yes

    Yes

    Yes

    Yes

    6

    Rate

    Yes

    /

    Yes

    Yes

    7

    Payment_time

    Yes

    Yes

    Yes

    Yes

    8

    Settlement_time

    Yes

    Yes

    Yes

    Yes

    9

    Type

    Yes

    Yes

    Yes

    Yes

    10

    Status

    Yes

    Yes

    Yes

    Yes

    11

    Original_partner_transaction_ID

    Yes

    /

    /

    /

    12

    Transaction_ID

    Yes

    /

    /

    /

    13

    Distribute_amount

    Yes

    Yes

    Yes

    Yes

    14

    Distribute_rmb_amount

    Yes

    Yes

    Yes

    Yes

    15

    Remarks

    Yes

    Yes

    Yes

    Yes

    16

    Settlement

    Yes

    /

    /

    Yes

    17

    Rmb_settlement

    Yes

    /

    /

    Yes

    Settlement file

    Settlement files contain the settlement record of the selected time period.

    Note:

    The settlement files you download from Alipay global site and SFTP are compressed into a .zip file. The .zip file contains the settlement summary file and the settlement file. The naming convention of the .zip file is <PID>_<date>.<file_suffix>, for example, 2088021******931_20180508.zip.

    Settlement summary file

    Only settlement files obtained through SFTP or from Alipay global site at Download Files contain a settlement summary file, namely settlebatch file. The name of a settlebatch file contains the following parts:

    Partner ID

    File Type

    Date

    File Suffix

    Sample

    A unique ID assigned by Alipay

    A fixed value: "settlebatch"

    YYYYMMDD or YYYYMM

    .csv

    2088021******931_settlebatch_20180531.csv

    A settlebatch file might contain the following fields:

    NO.

    Field Name

    Description

    1

    settle_batch_no

    An internal serial number of the file in Alipay system

    2

    settle_date

    Settlement time

    3

    Amount

    Transaction amount in foreign currency

    4

    Fee

    Service fee in foreign currency

    5

    Settlement

    Settlement amount in foreign currency

    6

    Currency

    Currency

    Settlement file

    Settlement files contain the settlement details of the selected time period.

    Depending on where you download the file from, the file name might consist of different parts. See the following table for details.

    Partner ID

    File Type

    Date

    System Assigned ID

    File Suffix

    Sample

    API

    A unique ID assigned by Alipay

    /

    YYYYMMDD + a 6-digit random number

    /

    .txt

    2088021017666931_20180531143440.txt

    Alipay global site

    A unique ID assigned by Alipay

    A fixed value: "settle"

    YYYYMMDD, YYYYMM, or YYYYMMDD + a 6-digit random number

    A unique ID assigned to each settlement file by Alipay

    .csv, .txt, or .xls

    2088721631012256_settle_20171106_50002017080100032007000005107441.csv

    SFTP

    A unique ID assigned by Alipay

    A fixed value: "settle"

    YYYYMMDD

    A unique ID assigned to each settlement file by Alipay

    .csv

    2088721631012256_settle_20171106_50002017080100032007000005107441.csv

    A settlement file might contain the following fields:

    NO.

    Field Name

    Description

    1

    Partner_transaction_id

    The unique transaction ID specified by the partner. It is equal to “out_trade_no” in the payment request or “out_return_no” in the refund request.

    2

    Transaction_ID

    A unique transaction ID assigned by Alipay

    3

    Amount

    Transaction amount in foreign currency

    4

    Rmb_amount

    Transaction amount in CNY

    5

    Currency

    Currency

    6

    Fee

    Service fee in foreign currency

    7

    Rate

    Foreign exchange rate

    8

    Payment_time

    Payment time

    9

    Settlement_time

    Settlement time

    10

    Type

    Transaction type

    11

    Status

    Transaction status

    12

    Distribute_amount

    The split foreign currency amount of a trade or refund

    13

    Distribute_rmb_amount

    The split CNY amount of a trade or refund

    14

    Remarks

    Remarks

    15

    Settlement

    Settlement amount in foreign currency

    16

    Rmb_settlement

    Settlement amount in CNY

    The contents of settlement files that you download from API, website and SFTP, and files you view online at the website are different. See the following table for details:

    NO.

    Field Name

    SFTP

    API

    Global Site Download

    1

    Partner_transaction_id

    Yes

    Yes

    Yes

    2

    Transaction_ID

    Yes

    /

    /

    3

    Amount

    Yes

    /

    Yes

    4

    Rmb_amount

    Yes

    /

    Yes

    5

    Fee

    Yes

    Yes

    Yes

    6

    Distribute_amount

    Yes

    Yes

    /

    7

    Distribute_rmb_amount

    Yes

    /

    /

    8

    Settlement

    Yes

    Yes

    Yes

    9

    Rmb_settlement

    Yes

    /

    Yes

    10

    Currency

    Yes

    Yes

    Yes

    11

    Rate

    Yes

    Yes

    Yes

    12

    Payment_time

    Yes

    Yes

    Yes

    13

    Settlement_time

    Yes

    Yes

    Yes

    14

    Type

    Yes

    Yes

    Yes

    15

    Status

    Yes

    Yes

    Yes

    16

    Remarks

    Yes

    Yes

    Yes

    The Alipay returned error codes can be divided to the following types:

    Idempotence

    Idempotence means that in response to the same requests sent multiple times, Alipay should send back only one unique result.

    Alipay checks the idempotence for payments and refunds. See details as below:

    Timeout or system error (SYSTEM_ERROR)

    Because HTTPS requests depend on network stabilities, timeout might occur on PAY, QUERY, CANCEL and REFUND interface requests. At the same time, Alipay might return SYSTEM_ERROR for internal system problems. In both cases, partners can retry or query to get aligned with the final transaction status in Alipay.

    1. For QUERY, CANCEL and REFUND interface:
    2. Retry with the same parameter till get a result. If the retry exceeds the max times allowed, alarms will be triggered to notify the technical support team of the partner to check. If the retry results are always SYSTEM_ERROR, contact Alipay Technical Support for help.

    3. For PAY interface:
    4. a) Retry with the same parameter till get a result. If the retry exceeds the max times allowed, alarms will be triggered to notify the technical team of the partner to check. If the retry results are always SYSTEM_ERROR, contact Alipay Technical Support for help.

      b) If timeout or SYSTEM_ERROR returned, call the QUERY interface to obtain the status, if QUERY timeout again, call CANCEL to close the transaction.

      The following table lists the differences of using method a and method b:

      Alipay status Retry PAY interface Retry QUERY interface
      SYSTEM_ERROR SYSTEM_ERROR TRADE_NOT_EXIST
      WAIT_BUERY_PAY UNKNOW WAIT_BUERY_PAY
      TRADE_SUCCESS TRADE_SUCCESS TRADE_SUCCESS
      TRADE_CLOSED TRADE_CLOSED TRADE_CLOSED
      Table 1 Differences of using method a and method b

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

    Request Parameters

    Parameter

    Type (length in bytes)

    Description

    Optional

    Example

    Basic Parameter

    service

    String

    Service Name

    N

    alipay.overseas.secmerchant.online.maintain

    partner

    String(16)

    A unique partner ID to identify a contracted Alipay Account.

    A 16 digit number starts with 2088.

    N

    2088101142878662

    _input_charset

    String

    The charset on partner website, such as utf-8, gbk, gb2312 etc.

    N

    gbk

    sign_type

    String

    DSA, RSA, or MD5, capital letter

    N

    MD5

    sign

    String

    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(64)

    A name is shown in the Alipay Wallet and the reconciliation file to identify a secondary merchant.

    N

    secMerchantName

    secondary_merchant_id

    String(64)

    A unique ID assigned by the partner to identify a secondary merchant. The ID can contain letters, numbers, and underscores.

    N

    63472327348

    secondary_merchant_industry

    String(4)

    Business category code of the secondary merchant. See MCC list.

    N

    MCC list.

    register_country

    String(2)

    A 2-letter code defined in ISO 3166. For more details about the 2-letter country code, see ISO 3166.

    N

    HK

    register_address

    String(256)

    Registered address of the secondary merchant

    Y

    HANGZHOU

    site_infos

    String

    This field is in JSON format and can contain up to 5 website URLs or app download URLs. See site_infos for details.

    URLs in this field cannot be updated incrementally. To add or remove URLs, re-pass the value again.

    N

    Secondary merchant website URL or app download URL. Format: [{"site_type":"WEB","site_url":"https://alipay.com","site_name":"websit"},

    {"site_type":"APP","site_url":"https://alipay.com","site_name":"websit"}]

    Sub-parameter

    site_infos

    Parameter

    Type (length in bytes)

    Description

    Optional

    Example

    site_type

    String

    Site type. Website URL must be WEB, and app download URL must be APP. Use uppercase.

    N

    WEB

    site_url

    String(256)

    Site URL.

  • When site_type is WEB, pass the URL in this format: http/https + SLD + TLD, for example, https://www.alipay.com.
  • When site_type is APP, pass the APP download URL starting with http/https, for example, https://itunes.apple.com/cn/app/id333206289.
  • N

    https://www.alipay.com

    site_name

    String(512)

    Site name

    Y

    xx Store

    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 (length in 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

    partner=2018283223743743&secendary_merchant_name=merchantname &secendary_merchant_id=23647324&sign=2118ac8fad6bc1d9e88a6cd017c18d37&secondary_merchant_industry=4039&_input_charset=GBK®ister_address=HANGZHOU&service=alipay.overseas.secmerchant.online.maintain×tamp=1438432738473843&site_infos=[{"site_type":"WEB","site_url":"https://alipay.com","site_name":"websit"}]

    Generated URL

    http://mapi.alipay.com/gateway.do?_input_charset=UTF-8&service=alipay.overseas.secmerchant.online.maintain&partner=20881332189403823×tamp=2018-10-09 16:04:16&secondary_merchant_name=test1&secondary_merchant_id=100510000031&secondary_merchant_industry=5935®ister_country=HK®ister_address=HANGZHOU&site_infos=[{"site_type":"WEB","site_url":"https://alipay.com","site_name":"websit"}]&sign=8457f906bf89a5e444a6e5c28f8da499&sign_type=MD5

    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_industry">5935</param>
        <param name="_input_charset">UTF-8</param>
        <param name="sign">8457f906bf89a5e444a6e5c28f8da499</param>
        <param name="site_infos">
            [{"site_type":"WEB","site_url":"https://alipay.com","site_name":"websit"}]
        </param>
        <param name="secondary_merchant_id">100510000031</param>
        <param name="register_address">HANGZHOU</param>
        <param name="partner">2088131089302823</param>
        <param name="service">alipay.overseas.secmerchant.online.maintain</param>
        <param name="secondary_merchant_name">test1</param>
        <param name="register_country">HK</param>
        <param name="sign_type">MD5</param>
        <param name="timestamp">2018-10-09 16:04:16</param>
    </request>
    <response>
        <alipay>
            <result_code>SUCCESS</result_code>
        </alipay>
    </response>
    </alipay>
    

    Request succeeds but the registration fails:

    
    <alipay>
    <is_success>F</is_success>
    <error>PARAM_ILLEGAL</error>
    <sign>ba101b7ffb43afde9ba63c0de335218e</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_PARTNER</error>
    </alipay>
    

    Error Codes

    Business Logic Errors

    Returned result

    Description

    MCC_CAN_NOT_MODIFY

    The MCC passed in cannot match the original MCC. Please ensure that the passed MCC is the original MCC.

    REGISTER_COUNTRY_FORBIDDEN

    For anti-money laundering reasons, the country or region in register_country cannot be registered.

    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

    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

    In addition to the API response through the page redirect, the API response might also be sent to the partner asynchronously with the POST method if the merchant set 'notify_url' field in the request with the targeted URL to handle the asynchronous notification. Handling async notification is required for this refund solution if the value of the is_sync field is N.

    Alipay would retry the sending asynchronous notification multiple times within a 25-hour window until the partner acknowledges the receipt of the notification by sending a string 'Success' in the response. The partner needs to respond to avoid the further re-send of the async notification.
    When handling the API response through the page redirect and the asynchronous notification, the following aspects should be considered:

    Response Parameters in Async Notifications

    Parameter

    Type (length in bytes)

    Description

    Example

    Basic Parameter

    notify_type

    String

    The notification type

    trade_status_sync

    notify_time

    Date

    The time that the notification was sent

    2009-08-12 11:08:32

    notify_id

    String

    The notification ID

    70fec0c2730b275286 65af4517c27b95

    sign_type

    String

    Signature method. The following are supported. Must be uppercase.
    DSA, RSA, and MD5.

    MD5

    sign

    String

    Signature value.

    656578b72f40e52 326dba4a41d6da62b

    Business Parameter

    out_trade_no

    String(64)

    The merchant transaction ID for the refund

    3824701800653976

    out_return_no

    String(64)

    Refund ID of the partner

    refund_status

    String(32)

    The refund status. The value can be:
    REFUND_SUCCESS: refund successfully
    REFUND_FAIL: refund failed

    REFUND_SUCCESS

    error_code

    String(64)

    Error code for a failed refund, this parameter is required only for the refund failed

    RETURN_AMOUNT_EXCEED

    currency

    String(8)

    The currency for the refund

    CNY

    return_amount

    Number(8,2)

    Refund amount

    100.00

    Asynchronous Notification Example

    http://www.merchant.com/alipay/notify_url.php?sign=327fed8c8d07be26e2790e 216266f5a8¬ify_time=2015-06-16 19:27:27&out_return_no=YNTK20150616 008&return_amount=10.00&sign_type=MD5&refund_status=REFUND_SUCCE SS¬ify_type=refund_status_sync¬ify_id=179ed48796486c67af63836465f 7733m6a&out_trade_no=2332688563037664¤cy=USD

    • Make sure the Notification Page (notify_url) is absolutely blank, without space, html tag, or any error message threw from the program system.
    • Parameters in this page can be acquired with GET method, like request.Form("out_trade_no"), $_POST['out_trade_no'].
    • This response will be used, if Alipay initiatively notifies.
    • Alipay will notify when there is a real transaction in Alipay system and the status of that transaction has changed.
    • Interaction between servers, unlike interaction between websites which is visible, is usually not displayable.
    • When the first time the transaction status is changed, the page is redirected to the partner website, and a notification with the transaction result from Alipay will be received.
    • After the program is executed, the page must print “success” (without quote). If not, Alipay server keeps re-sending the notification, until over 24 hour 22 minutes Generally, there are 8 notifications within 25 hours (Frequency: 2m,10m,15m,1h,2h,6h,15h)
    • After the program is executed, the page should not be redirected. Otherwise, Alipay cannot receive the “success” string, and determines that an error occurred to the program execution. So Alipay will resend the notification.
    • Cookies and session are invalid on this page, so that these data cannot be captured.
    • The configuration and testing of this system must be on a server, via internet
    • By using the asynchronous notification, the transaction lost can be prevented. When the synchronous notification fails to update the transaction status, the asynchronous notification makes the update.
    • Only when the partner receives the sever asynchronous response and prints “success”, the parameter notify_id becomes invalid. That is to say, when Alipay sends the asynchronous notification, or when no “success” is printed and Alipay keeps re-sending the notifications, the parameter notify_id doesn't change.
    • Along with the business growth, Alipay may add new parameters (existing parameters will not change). When doing notification verification, Merchants MUST use all parameters (except sign and sign_type) returned from Alipay.

    Notification Verification

    It is recommended to verify if the notification is from Alipay.

    You can only verify the notifications sent within the last 1 minute, and before sending the ‘Success’ acknowledgement back to Alipay.
    For example:

    https://intlmapi.alipay.com/gateway.do? service=notify_verify&partner=2088101122136241&notify_id=+4465b04e84cb6bacc2bd1b52232c0b8gjg&sign=ciSBXc7gjCfXW8KMBxFiFH2cbMZtFelfTOGKqY2NF7q98RnH3E%2BiF5Cj%2Fu%2Bl8py1D%2FOsE%2FAva1ls8A6Tw1MzhG6ideJSgh4FxWmAjEnlczdfLj%2FqzA6qGzxdKGEXaSDFmTGglOembXUqK8g8ajICD%2BBH7xoxBRY7vtfylEXtojs%3D&sign_type=RSA

    For more details, please refer to the API document of notify_verify.

    客服小机器人

    NEED HELP ?