4
- [About This Guide](./1) - [Introduction](./2) - [Payment Flow and User Experience](./3) - [Quick Integration](./4) - [Interaction Process](./5) - [Client Call](./6) - [iOS](./6) - [Android](./7) - [Request Parameters Description](./8) - [Change History](./35) - [Transaction Notification](./9) - [Synchronous Response Parameters](./9#SynchronousResponseParameters) - [Codes Returned to Client End](./9#ClientReturnCodes) - [Server Asynchronous Notification Parameters](./10#ServerAsynchronousNotificationParameters) - [Trade Status](./10#TradeStatus) - [Verify The Notificaiton Is Sent By Alipay](./10#NotificaitonVerification) - [Business Logic Management](./10#BusinessLogicManagement) - [Attentions](./10#Attentions) - [Detailed Explanation of Integration Process](./11) - [iOS](./12) - [Import Code](./12#ImportCode) - [Remarks for Running Demo Code](./12#RunDemo) - [Configuration](./12#Configuration) - [Example on Logic of Code](./12#CodeLogic) - [Android](./13) - [Import Development Resource](./13#AndroidImportResource) - [Modify Manifest](./13#ModifyManifest) - [Add Confusing Rules](./13#AddRules) - [Generate Order Data](./13#GenOrder) - [Call Payment API](./13#CallPay) - [Payment Result Handling](./13#PayResultHandling) - [Get the SDK Version](./13#GetSDKVersion) - [Error Codes](./14) - [Demo Code Download](./34#DemoDownload) - [API List](./21) - [Forex_refund](./21) - [Request Parameters](./21#Request) - [Sync Response](./21#Response) - [Samples](./21#Samples) - [Error Codes](./22#Errors) - [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) - [alipay.overseas.secmerchant.online.maintain](./36) - [Request Parameters](./36#request) - [Sync Response](./36#sync) - [Samples](./36#samples) - [Error Codes](./36#error) - [Change History](./36#history) - [alipay.overseas.secmerchant.maintain.queryStatus](./37) - [Request Parameters](./37#request) - [Sync Response](./37#sync) - [Samples](./37#samples) - [Error Codes](./37#error) - [Change History](./37#history) - [Notify_verify](./31) - [Request Parameters](./31#Notify_verify_Request) - [Sync Response](./31#Notify_verify_Response) - [Samples](./31#Notify_verify_Samples) - [Error Codes](./32) - [Digital Signature](./15) - [Signature Algorithms](./15) - [Generate Pre-sign String](./15#SignatureString) - [RSA Signature](./15#RSASignature) - [RSA Key Generation with OpenSSL](./16) - [OpenSSL Installation](./16#OpenSSLInstallation) - [RSA Key Pair Generation](./16#RSAKeyPairGeneration) - [FAQ](./17) - [Global Portal](./17) - [Supported Currency List](./18) - [Resource Download](./20)
Cross-border APP Payment

Quick Integration

Pre-integration Preparation Phase
1.   Merchants need to sign the contract with Alipay and get authenticated before the technical integration. Please contact Global Merchant Business Support for assistance.
2. Order Review
Merchants can log on to global.alipay.com to check/review their orders’ status and progress details under the “My Orders” tab – see figure 1:

Figure 1 - Order details

For example, the contract for an order is active when the status of the order is “Done”(see the “Status” column). Please contact Global Merchant Business Support for further clarification.

3.    Public / Private Key Management
     1.    Keys Generating Steps
     2.    Keys Uploading Process: Please send the RSA public keys to Global Merchant Technical Support to upload.

Integration Phase
Server is responsible for generating orders and signatures, as well as accepting asynchronous payment notifications.
Client is responsible for using the order information sent by the server to call Alipay payment API, as well as returning the result page in accordance with SDK’s synchronously generated payment result.

Server Integration
Private keys generating and authorisation process must be done on the server side.
1.    Preparation
    1.    Determine development language
    2.    Determine encoding format
    3.    Determine signature method (PID + key)
    4.    Determine server configuration
2.    Payment order parameters assembling and signing
3.    Notification Process (i.e. When to notify? How to verify signature after receiving notification?)

Client Integration
1.    iOS Integration
    1.    API Description
    2.    Demo Example (For demonstration purpose, the assembling and signing of the request parameters are done on the client side. However, in practice, both assembling and signing should be carried out on the server side)
2.    Android integration
    1.    API Description
    2.    Demo Example (For demonstration purpose, the assembling and signing of the request parameters are done on the client side. However, in practice, both assembling and signing should be carried out on the server side)
3.    Request Parameters Description
4.    Synchronous Response Parameters Description

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.

Except for "sign" and "sign_type", all other parameters used need to be signed.

Generating the pre-sign string for request

For the following parameter array:

string[]  parameters={"partner=\"208861122157****\"",
"seller_id=\"208861122157****\"",
"out_trade_no=\"0811172929-1013\"",
"subject=\"test\"",
"body=\"test\"",
"currency=\"HKD\"",
"total_fee=\"0.1\"",
"notify_url=\"http://0ee96cd2.ngrok.io/notify.htm\"",
"service=\"mobile.securitypay.pay\"",
"payment_type=\"1\"",
"_input_charset=\"utf-8\"",
"appenv=\"system=java^version=1.8\"",
"forex_biz=\"FP\""
  };
Combine all array values in the format of key= “value” and then link them up by the character “&” in an alphabetical order. For example:

_input_charset="utf-8"&appenv="system=java^version=1.8"&body="test"¤cy="HKD"&forex_biz="FP"¬ify_url="http://0ee96cd2.ngrok.io/notify.htm"&out_trade_no="0811172929-1013"&partner="208861122157****”&payment_type="1"&seller_id="208861122157****”&service="mobile.securitypay.pay"&sign="$$$"&sign_type="RSA"&subject="test"&total_fee="0.1"

Generating the pre-sign string for synchronous notification

The following sample illustrates the content of a synchronous notification:

resultStatus={9000};memo={};result={partner="2088101568358171"&seller_id="xxx@alipay.com"&out_trade_no="0819145412-6177"&subject="test"&body="testtest"&total_fee="0.01"&notify_url="http://notify.msp.hk/notify.htm"&service="mobile.securitypay.pay"&payment_type="1"&_input_charset="utf-8"&it_b_pay="30m"&show_url="m.alipay.com"&success="true"&sign_type="RSA"&sign="hkFZr+zE9499nuqDNLZEF7W75RFFPsly876QuRSeN8WMaUgcdR00IKy5ZyBJ4eldhoJ/2zghqrD4E2G2mNjs3aE+HCLiBXrPDNdLKCZgSOIqmv46TfPTEqopYfhs+o5fZzXxt34fwdrzN4mX6S13cr3UwmEV4L3Ffir/02RBVtU="}

Take out the part of result, remove "sign" and "sign_type" parameters:

partner="2088101568358171"&seller_id="xxx@alipay.com"&out_trade_no="0819145412-6177"&subject="test"&body="testtest"&total_fee="0.01"&notify_url="http://notify.msp.hk/notify.htm"&service="mobile.securitypay.pay"&payment_type="1"&_input_charset="utf-8"&it_b_pay="30m"&show_url="m.alipay.com"&success="true"

Generating the pre-sign string for asynchronous notification

The following sample illustrates the contents of an asynchronous notification:

http://0ee96cd2.ngrok.io/notify.htm? buyer_id=208812287878****¤cy=HKD&forex_rate=0.85420000¬ify_id=e5f5c6a77034fcd111e373e7e61dcbegdy¬ify_type=trade_status_sync¬ify_time=2017-08-11 17:31:39&out_trade_no=0811172929-1013&rmb_fee=0.09&seller_id=208861122157****&trade_no=2017081121001003050274536539&total_fee=0.10&trade_status=TRADE_FINISHED&sign_type=RSA&sign=$$$

Remove sign and sign_type, sort other parameters in alphabetical order, and then link up all array values by the character of “&”:

buyer_id=208812287878****¤cy=HKD&forex_rate=0.85420000¬ify_id=e5f5c6a77034fcd111e373e7e61dcbegdy¬ify_type=trade_status_sync¬ify_time=2017-08-11 17:31:39&out_trade_no=0811172929-1013&rmb_fee=0.09&seller_id=208861122157****&trade_no=2017081121001003050274536539&total_fee=0.10&trade_status=TRADE_FINISHED

  • Parameters without value don't need to be transmitted, nor to be included in the data to be signed;
  • At signing, the character set used to change the character into byte stream must be consistent with that specified in _input_charset;
  • If the parameter _input_charset is transmitted, it shall also be included in the data to be signed.

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

  1. Only valid cross-border transactions submitted to Alipay can be settled to your designated overseas bank account.
  2. All PRC domestic transactions must be settled to your designated Chinese Alipay bank account.
  3. Alipay can only accept 4 types of funds for settlement in your designated Chinese Alipay bank account: (i) insurance fee (relating to the delivery), (ii) relevant tax, (iii) any delivery fee for goods and services; and (iv) any other fees directly related to a transaction submitted to Alipay.

N

SampleInsuranceFee=10usd|RelevantTax=10usd|DeliveryFee=10usd|AnyOtherFees=10usd

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":"SampleInsuranceFee=10usd|RelevantTax=10usd|DeliveryFee=10usd|AnyOtherFees=10usd"}]
  • 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, for example, out of supply, etc. Y 100.30

is_sync

String(1)

Refund processing mode:

Y - Execute the refund immediately and return the final result.

N - The refund request first recorded then scheduled for later processing. In case of refund execution failures, the system will automatically retry.

Y(The default value is N)

Y

  • 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

REFUND_CHARGE_ERROR

The refund failed because the payment is in progress. Please try again later.

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.

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(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.If both trade_no and out_trade_no are provided, trade_no is preferred.
Note: This parameter is required when out_trade_no is not provided.

Y

2008102303210710

out_trade_no

String(64)

A unique number to identify a transaction in partner system. If both trade_no and out_trade_no are provided, trade_no is preferred.
Note: This parameter is required when trade_no is not provided.

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

tsxxxe01@alipay.com

buyer_id

String

A unique buyer ID to identify a contracted Alipay Account.

N

208xxxxxxxxx8955

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.alipaydev.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>inxxxxt059@service.alipay.com</buyer_email>
    <buyer_id>208xxxxxxxxx5555</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.


    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.

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

    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.

    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.

    Call this interface to register online secondary merchants information into Alipay system. For frequently asked questions about this interface, see About the alipay.overseas.secmerchant.online.maintain API.

    The gateway URL:

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

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

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

    Request Parameters

    Parameter

    Type (length in bytes)

    Description

    Optional

    Example

    Basic Parameter

    service

    String

    Service Name

    N

    alipay.overseas.secmerchant.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

    The value of sign.

    N

    2118ac8fad6bc1d9e88a6cd017c18d37

    timestamp

    String

    The time when the merchant server sends request, in GMT + 8, format: yyyy-MM-dd HH:mm:ss.

    By default, the request expires in 30 minutes.

    N

    2012-12-21 17:11:16

    Business Parameter

    secondary_merchant_name

    String(64)

    Registration legal name of the secondary merchant, which is shown in the wallet and reconciliation file to identify a secondary merchant.

    Note: If the secondary merchant type is INDIVIDUAL, specify the full legal name of the business owner to this field.

    N

    Alipay.com Co.,Ltd

    secondary_merchant_id

    String(64)

    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)

    Registration country of the secondary merchant, specified by a 2-letter code defined in ISO 3166. For more details about the 2-letter country code, see ISO 3166.

    N

    HK

    register_address

    String(256)

    Business registration address specified on the business registration document. Use mailing address format.

    N

    No.278, Road YinCheng, Shanghai, China

    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"}]

    secondary_merchant_type

    String

    Secondary merchant type, the value can be INDIVIDUAL for the sole proprietorship or ENTERPRISE for the limited company, private company, partnership, limited liability partnership (LLP), limited liability company (LLC), S corporation (S Corp), C corporation (C Corp), trust, or nonprofit organization (NPO)

    N

    INDIVIDUAL

    registration_no

    String(128)

    Business registration number specified on the business registration document.

    Note: This field is not required when the secondary merchant type is INDIVIDUAL and no registration number exists.

    N

    012345678

    shareholder_name

    String(128)

    Legal name of the primary shareholder of the secondary merchant. Specify this field only when the secondary merchant type is ENTERPRISE.

    Y

    Jack Li (if the shareholder is an individual), Alipay.com Co.,Ltd (if the shareholder is an enterprise)

    shareholder_id

    String(128)

    ID or passport number, or business registration number of the primary shareholder of the secondary merchant. Specify this field only when the secondary merchant type is ENTERPRISE.

    Y

    G53453888 (if the shareholder is an individual), 012345678 (if the shareholder is an enterprise)

    representative_name

    String(128)

    Full legal name of the business owner. Specify this field only when the secondary merchant type is INDIVIDUAL. This field is optional if the secondary merchant type is ENTERPRISE.

    N

    Tom Li

    representative_id

    String(128)

    ID or passport number of the business owner. Specify this field only when the secondary merchant type is INDIVIDUAL. This field is optional if the secondary merchant type is ENTERPRISE.

    N

    123456789

    settlement_no

    String(64)

    Settlement bank account number of the secondary merchant, letters and numbers only

    N

    2600100000

    contact_no

    String(64)

    Contact phone number of the secondary merchant, numbers and special characters +-() only

    N

    +86139xxxx7893

    contact_email

    String(128)

    Contact email address of the secondary merchant

    N

    tomli@gmail.com

    cs_no

    String(64)

    Customer service phone number of the secondary merchant, numbers and special characters +-() only

    Y

    0213355xxx89

    cs_email

    String(128)

    Customer service email address of the secondary merchant

    Y

    customerservice@xxxcompany.com

    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

    The value of sign

    Y

    3afc92ac4708425ab74ecb2c4e58ef56

    error

    String

  • If the request succeeds, this parameter does not exist.
  • When a request fails, the value of this parameter is the error code. See Access Errors and System Errors for details.
  • Y

    PARAM_ILLEGAL

    result_code

    String

    Request result code. This field is returned only when the is_success field is T.

    Y

    SUCCESS

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

    Samples

    Request succeeds and the registration succeeds.

    
    <?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">No.278, Road YinCheng, Shanghai, China</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>
        <param name="secondary_merchant_type">INDIVIDUAL</param>
        <param name="registration_no">012345678</param>
        <param name=“representative_name”>Tom Li</param>
        <param name=“representative_id”>123456789 Li</param>
        <param name="settlement_no">2600100000</param>
        <param name="contact_no">+86139xxxx7893 </param>
        <param name="contact_email">tomli@gmail.com </param>
    </request>
    <response>
        <alipay>
            <result_code>SUCCESS</result_code>
        </alipay>
    </response>
    <sign>744a87f0e3b40e6a8cd8f9705ce61511</sign>
    <sign_type>MD5</sign_type>
    </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

    DUPLICATE_REQUEST

    Duplicate request submitted. The previous registration request is still in process.

    MERCHANT_TYPE_ILLEGAL

    Illegal secondary merchant type. The value of the secondary_merchant_type field can only be ENTERPRISE or INDIVIDUAL.

    Access Errors

    Returned result

    Description

    ILLEGAL_SIGN

    Illegal signature

    ILLEGAL_DYN_MD5_KEY

    Dynamic key information is incorrect

    ILLEGAL_ENCRYPT

    Encryption is incorrect

    ILLEGAL_ARGUMENT

    Incorrect parameter

    ILLEGAL_SERVICE

    Service Parameter is incorrect

    ILLEGAL_USER

    User ID is incorrect

    ILLEGAL_PARTNER

    Incorrect Partner ID

    ILLEGAL_EXTERFACE

    Interface configuration is incorrect

    ILLEGAL_PARTNER_EXTERFACE

    Partner's interface information is incorrect

    ILLEGAL_SECURITY_PROFILE

    Matching private key configuration is not found

    ILLEGAL_AGENT

    Agency ID is incorrect

    ILLEGAL_SIGN_TYPE

    The signature type is incorrect

    ILLEGAL_CHARSET

    The character set is illegal

    HAS_NO_PRIVILEGE

    Has no right to visit

    INVALID_CHARACTER_SET

    The character set is invalid

    System Errors

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

    Returned result

    Description

    SYSTEM_ERROR

    Alipay system error

    SESSION_TIMEOUT

    Session timeout

    ILLEGAL_TARGET_SERVICE

    Wrong target service

    ILLEGAL_ACCESS_SWITCH_SYSTEM

    Merchant is not allowed to visit system of this type

    EXTERFACE_IS_CLOSED

    The interface is closed

    Change history

    Date

    Modifications

    2019.02.18

    • Added the following fields: secondary_merchant_type, registration_no, shareholder_name, shareholder_id, representative_name, representative_id, settlement_no, contact_no, contact_email, cs_no, cs_email
    • Updated the following fields: The site_name field is changed to optional. The register_address field is changed to required.
    • Updated the description of the secondary_merchant_name field.
    • Added the DUPLICATE_REQUEST error code.

    2019.02.28

    Added the result_code field in the Sync Response part.

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

    The gateway URL:

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

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

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

    Request Parameters

    Parameter

    Type (length in bytes)

    Description

    Optional

    Example

    Basic Parameter

    service

    String

    Service Name

    N

    alipay.overseas.secmerchant.maintain.queryStatus

    partner

    String(16)

    A unique partner ID to identify a contracted Alipay Account.

    A 16 digit number starts with 2088.

    N

    2088101142878662

    _input_charset

    String

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

    N

    gbk

    sign_type

    String

    DSA, RSA, or MD5, capital letter

    N

    MD5

    sign

    String

    The value of sign

    N

    2118ac8fad6bc1d9e88a6cd017c18d37

    timestamp

    String

    The time when the merchant server sends request, in GMT + 8, format: yyyy-MM-dd HH:mm:ss.

    By default, the request expires in 30 minutes.

    N

    2019-02-01 08:30:10

    Business Parameter

    secondary_merchant_id

    String(64)

    Secondary merchant ID, need to be unique for each PID

    N

    MERCHANT_ID_0003

    payment_method

    String

    Payment method of the secondary merchant, the value is ONLINE_PAYMENT for online payments.

    N

    ONLINE_PAYMENT

    Sync Response

    The response is in XML format.

    Parameter

    Type (bytes)

    Description

    Optional

    Example

    sign

    String

    The value of sign

    Y

    744a87f0e3b40e6a8cd8f9705ce61511

    sign_type

    String

    DSA, RSA, or MD5, capital letter

    Y

    MD5

    secondary_merchant_id

    String

    Secondary merchant ID, need to be unique for each PID

    N

    MERCHANT_ID_0003

    status

    String

    Registration status of the secondary merchant, the value can be SUCCESS if the merchant is successfully registered, UNDER_REVIEW if the application for registration is in process, and FAILED if the merchant is not registered.

    N

    SUCCESS

    reject_reason

    String

    The reason that the merchant is not registered successfully. This field is required when status is FAILED.

    Y

    High risk merchant, registration reject.

    Business Logic Errors

    Returned result

    Description

    Solution

    PARAM_ILLEGAL

    Required parameters are not entered or illegal parameters entered. The illegal parameter might be too long, or with incorrect format.

    Enter the correct parameters and send the request again.

    DATA_NOT_EXIST

    No data exists for the queried secondary merchant because the merchant is not registered.

    Register the secondary merchant to Alipay system before you query the registration status.

    SYSTEM_ERROR

    Alipay system error

    Please try again later.

    Response Examples

    The request succeeds and the query result is returned:

    
    <?xml version="1.0" encoding="utf-8"?>
    <alipay>
        <is_success>T</is_success>
    <request>
        <param name="service">alipay.overseas.secmerchant.maintain.queryStatus</param>
        <param name="partner">2088101131367863</param>
        <param name=“_input_charset”>gbk</param>
        <param name="sign_type">MD5</param>
        <param name="sign">2118ac8fad6bc1d9e88a6cd017c18d37</param>
        <param name="timestamp">2019-02-01 08:30:10</param>
        <param name="secondary_merchant_id">MERCHANT_ID_0003</param>
        <param name="payment_method">ONLINE_PAYMENT</param>  
    </request>
    <response>
        <alipay>
            <secondary_merchant_id>MERCHANT_ID_0003</secondary_merchant_id>
            <status>UNDER_REVIEW</status>
        </alipay>
    </response>
    <sign>744a87f0e3b40e6a8cd8f9705ce61511</sign>
    <sign_type>MD5</sign_type>
    </alipay>
    

    Failed to get the query result:

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

    Change history

    Version 1 released on Feb, 18, 2019.
    客服小机器人

    NEED HELP ?