13
- [About This Guide](./1)
- [Introduction](./2)
- [The Payment Workflow and User Interaction](./3)
- [The Payment Workflow](./3)
- [The User Interaction](./4)
- [Quick Integration](./5)
- [Integration Overview](./5)
- [Pre-create Flow](./6)
- [Cancel Flow](./8)
- [Refund Flow](./7)
- [Reconciliation Files](./10)
- [SFTP Connection](./10)
- [Transaction File Format](./11)
- [Settlement File Format](./12)
- [API List](./13)
- [The Pre-create Interface](./13)
- [The Request Parameters](./13)
- [The Return Parameters](./14)
- [Asynchronous Notification](./28)
- [The Error Code](./15)
- [The Cancel Interface](./16)
- [The Request Parameters](./16)
- [The Return Parameters](./17)
- [The Error Code](./18)
- [The Refund Interface](./19)
- [The Request Parameters](./19)
- [The Return Parameters](./20)
- [The Error Code](./21)
- [The Query Interface](./22)
- [The Request Parameters](./22)
- [The Return Parameters](./23)
- [The Error Code](./24)
- [Secondary Merchant Info Interface](./32)
- [Request Parameters](./32#request)
- [Return Parameters](./32#sync)
- [Error Code](./32#error)
- [Change History](./32#history)
- [Secondary Merchant Registration Status](./33)
- [Request Parameters](./33#request)
- [Return Parameters](./33#sync)
- [Error Code](./33#error)
- [Change History](./33#history)
- [Digital Signature](./29)
- [Digital Algorithms](./29)
- [RSA Key Generation with Open SSL](./30)
HK Wallet - Transaction QR Code
The Request Parameters of the Pre-create Interface
Request parameter is the request data provided to Alipay by merchant when conducting data interaction with Alipay so that further process can be conducted by Alipay based on these data.
The gateway URL:
If you want to use Alipay sandbox to test the integration, see the sandbox handbook for details.
If you use GET method, please specify the input_charset in the request URL. For example, https://mapi.alipaydev.com/gateway.do?_input_charset=UTF-8
Request Parameters
|
Parameter
|
Type (Byte)
|
Parameter Description
|
Nullable
|
Example
|
|
|
service
|
String
|
Interface name
|
N
|
alipay.acquire.precreate
|
|
partner
|
String(1
6)
|
Unique Alipay user number corresponding to authorized Alipay account number.
Composed of 16 numbers beginning with 2088.
|
N
|
2088101568358171
|
|
_input_charset
|
String
|
Encoding format used in merchant’s website, such as utf-8, gbk, gb2312, etc
|
N
|
utf-8
|
|
sign_type
|
String
|
Three values, namely, DSA, RSA and MD5 can be chose; and must be capitalized
|
N
|
MD5
|
|
sign
|
String
|
See Digital Algorithm for details.
|
N
|
85bf83f78d5cefb804bd
805532fc688e
|
|
notify_url
|
String(190)
|
Alipay server takes the initiative to notify merchant of webpage http path designated by website.
|
Y
|
http://api.test.alipay.net/atinterface/receive_notify.htm
|
|
timestamp
|
String
|
Time stamp of the merchant server sending request, accurate to the millisecond.
|
N
|
1456507704121
|
|
terminal_timestamp
|
String
|
Time stamp of the terminal sending request, accurate to the millisecond.
|
Y
|
1456507704102
|
|
out_trade_no
|
String(64)
|
Unique order ID in Alipay’s merchant website
|
N
|
99003911198989
|
|
subject
|
String(256)
|
Goods title/trade tile/order subject/order key word etc.
The length of this parameter is up to 128 Chinese characters.
|
N
|
Payment by QR-Code
|
|
product_code
|
String(32)
|
Order placement used to distinguish the business type:
OVERSEAS_MBARCODE_PAY: face to face payment overseas
|
N
|
OVERSEAS_MBARCODE_PAY
|
|
total_fee
|
number (9,2)
|
Total fee of this order. The range of values is [0.01, 100000000], such value can have up to two digits after the decimal point.
|
N
|
10
|
|
seller_id
|
String(28)
|
Unique Alipay user ID corresponding to Seller’s Alipay account
16 numbers beginning with 2088.
If both sell_id and seller-email are null, the default value of this parameter to be filled out shall be the value of merchant.
|
Y
|
2088101106499364
|
|
seller_email
|
String(100)
|
Seller’s Alipay account, may be email or phone number
If seller_id is not null, the value of seller_id shall be the seller’s ID and this parameter can be neglected.
|
Y
|
test@alitest.com
|
|
body
|
String(400)
|
Specific description of the trade. In case of a variety of goods, please accumulate the character strings descrbing the goods, and transmit the same to body.
|
Y
|
iphone cellphone
|
|
show_url
|
String(400)
|
Hyperlink for the show of goods on the webpage of checkout counter.
|
Y
|
http://www.taobao.com/product/113714.html
|
|
currency
|
String(8)
|
The settlement currency.
Currency and trans_currency cannot be different foreign currency.
Use upper case. See Supported Currency List for details.
|
N
|
CNY
|
|
trans_currency
|
String(8)
|
Pricing currency for the transaction, if it is not CNY, the CNY amount user will be charged will be calculated based on trans_currency and exchange rate.
|
N
|
CNY
|
|
price
|
Number (9,2)
|
Unit price of the goods in the order. If this parameter is transmitted at request, the condition of total_fee=price×quantity must be met.
|
Y
|
1
|
|
quantity
|
String(100)
|
Quantity of the goods in the order. If this parameter is transmitted at request, the condition of total_fee=price×quantity must be met.
|
Y
|
10
|
|
goods_detail
|
String
|
Description of the details of goods in the format of json. See goods_detail for details.
The maximum allowable goods number is 50.
|
Y
|
[{"goodsId":"apple-01","goodsName":"ipad","goodsCategory":"7788230","price":"2000.00","qu antity":"1"}]
|
|
extend_params
|
String(128)
|
Be used for transmitting specific business information of the merchant; this parameter will only be valid if merchant and Alipay agree to transmit this parameter and reach an agreement on the implication of this parameter.
For example, store ID and other information under the circumstance that payment can be made through sound wave; such information shall be written in the format of json. See extend_params for details.
|
N
|
{"STORE_ID":"BJ_ZZ_001","STORE_NAME":"Muku in the Dreieichstrabe","SECONDARY_MERCHANT_ID":"A80001","SECONDARY_MERCHANT_NAME":"Muku","SECONDARY_MERCHANT_ INDUSTRY":"7011"}
|
|
it_b_pay
|
String(200)
|
Set the overtime of non-payment trade, the trade will be closed automatically once the time is up.
Range of values: 1m～15d.
m-minute, h-hour, d-day, 1c-current day (Whenever the trade is created, it will be closed at 0:00).
Demical point of the numerical value of this parameter is rejected, for example, 1.5h can be tansformed to 90m.
To realize this function, Alipay is needed to be advised to set close time.
|
Y
|
1d
|
|
passback_parameters
|
String(256)
|
If merchant transfer this parameter by the request string, Alipay will feedback this parameter by the asynchronous notify (parameter name: extra_common_param).
|
Y
|
test
|
Part of parameter type is String, range of length is not specified, which means the system will not check out the length of this parameter.
goods_detail
Goods details parameters shall be in the format of JSON and include the following parameters:
|
Parameter
|
Parameter Name
|
Type (Byte Length)
|
Parameter Description
|
Nullable
|
Example
|
|
goodsId
|
Goods ID
|
String
|
Goods ID
|
N
|
apple-01
|
|
goodsName
|
Goods name
|
String
|
Goods Name
|
N
|
ipad
|
|
goodsCategory
|
Goods category
|
String
|
Goods Category
|
Y
|
34543238
|
|
showUrl
|
Website for the show of goods
|
String
|
Hyperlink for the show of goods on the webpage of checkout counter.
|
Y
|
http://www.taobao.com
|
|
quantity
|
Goods quatity
|
String
|
Goods quatity
|
N
|
1
|
|
body
|
Goods description
|
String
|
Goods description
|
Y
|
Cellphone at a sale
|
|
price
|
Unit price of goods
|
String
|
Unit price of goods
|
N
|
2000
|
The format structure:
[
{Goods_ID: goods ID 1,
goodsname: goods name 1,
goods_category: goods category 1,
Website for the show of goods: website 1 for the show of goods,
goods quantity: goods quantity 1,
goods description: goods description 1,
unit price of goods: unit price 1 of goods
},
{Goods ID: goods ID 2,
goods name: goods name 2,
goods category: goods category 2,
Website for the show of goods: website 2 for the show of goods,
goods quantity: goods quantity 2,
goods description: goods description 2,
unit price of goods: unit price 2 of goods
},
…
]
Example:
Business demand:
goods ID: apple-01,
goods name: ipad,
goods category:
7788230, quantity: 1,
price: RMB 2,000 Yuan;
Parameter assignment:
goods_detail=[
{"goodsId":"apple-01",
"goodsName":"ipad",
"goodsCategory" :"7788230",
"price":"2000.00",
"quantity":"1"}
]
extend_params
Business extension parameters shall be in the format of json and include the following parameters:
|
Parameter
|
Parameter Name
|
Type (Byte Length)
|
Parameter Description
|
Nullable
|
Example
|
|
SECONDARY_MERCHANT_ID
|
Secondary merchant id
|
String(32)
|
Used to differentiate the secondary merchant of the merchant, which is assigned by the merchant itself, not interfered by Alipay
|
N
|
A80001
|
|
SECONDARY_MERCHANT_NAME
|
Secondary merchant name
|
String(32)
|
Secondary merchant name, assigned by the merchant,not interfered by Alipay
|
N
|
Muku
|
|
secondary_merchant_industry
|
Secondary merchant industry
|
String(4)
|
Industry classification identifier of sub-merchant which assigned by Alipay. Such like:
catering industry: 5812
department stores: 5311
lodging industry: 7011
taxi industry: 4121
|
N
|
7011
|
|
STORE_ID
|
Store ID
|
String(32)
|
The unique id of the merchant’s shop which assigned by the merchant.
|
Y
|
BJ_ZZ_001
|
|
STORE_NAME
|
Store name
|
String(32)
|
The name of the merchant’s shop which used to show in the customer’s Alipay wallet and the reconciliation file
|
Y
|
Muku in the Dreieichstrabe
|
|
TERMINA L_ID
|
Terminal ID
|
String(10)
|
Terminal ID for submitting request.
|
Y
|
T80001
|
|
sys_service_provider_id
|
The technical provider id
|
String(32)
|
The technical provider id. This parameter is used to identify the payment system provider.
|
Y
|
R00998889911
|
Note:Business extension parameters only support one piece of store information.
Example:
- Business demand: transmit agent ID, store ID, store type, brand ID
- Parameter assignment: extend_params={"STORE_ID":"BJ_ZZ_001","STORE_NAME":"Muku in the Dreieichstrabe","SECONDARY_MERCHANT_ID":"A80001","SECONDARY_MERCHANT_NAME":"Muku","SECONDARY_MERCHANT_ INDUSTRY":"7011"}
Example
https://intlmapi.alipay.com/gateway.do?_input_charset=UTF-8&body=iphone cellphone¤cy=USD&extend_params={"secondary_merchant_name":"Lotte","secondary_merchant_id":"123","secondary_merchant_industry":"5812","store_id":"A101","store_name":"McDonald in 966 3rd Ave, New York"}¬ify_url=http://api.test.alipay.net/atinterface/receive_notify.htm&out_trade_no=4363476566647440&partner=2088021966388155&passback_parameters=test&price=0.01&product_code=OVERSEAS_MBARCODE_PAY&quantity=1&seller_email= testoverseas1980@alipay.com&seller_id=2088021966388155&sendFormat=normal&service=alipay.acquire.precreate&show_url=http://www.taobao.com/product/113714.html&subject=Payment by QR-Code&total_fee=0.01&trans_currency=USD&sign=2127020ad640f41eec725c639f1de294
This interface provides the ability to refund a transaction both in whole and in partial.
By design, the refund request cannot be reversed, use retry instead.
The gateway URL:
If you want to use Alipay sandbox to test the integration, see the sandbox handbook for details.
If you use POST method, please specify the _input_charset in the request URL. For example, https://mapi.alipaydev.com/gateway.do?_input_charset=UTF-8
Request parameters
|
Parameter
|
Type(Byte)
|
Description
|
Nullable
|
Example
|
|
Basic parameter
|
|
service
|
String
|
Description
|
No
|
alipay.acquire.overseas.spot.refund
|
|
sign
|
String
|
Signature value. See “Digital Signature”.
|
No
|
c8il4epm90wyn768fijgqhy8tay37gqa
|
|
sign_type
|
String
|
The type could be DSA, RSA or MD5;
Capital letters only.
|
No
|
MD5
|
|
partner
|
String
|
One Alipay account has only one Alipay ID. Composed of 16-digit number beginning with 2088
|
No
|
2088102012343978
|
|
_input_charset
|
String
|
Character set of parameter code.
Default is GBK if not send.
|
Yes
|
UTF-8
|
|
notify_url
|
String
|
The url to which Alipay sends payment result in async mode. It is in POST method.
Note:
For information security, the url must be on https protocol.
This URL cannot have extra parameters. For example, “https://xxx.com/foo.php?star=obama” is not allowed.
|
Yes
|
https://www.test.com/alipay/notify_url.php
|
|
Operation parameter
|
|
partner_trans_id
|
String(64)
|
The original partner transaction id given in the payment request
|
No
|
2010121000000002
|
|
alipay_trans_id
|
String(64)
|
The Alipay transaction ID.
|
Yes
|
201311221703338463
|
|
partner_refund_id
|
String(64)
|
The refund order id on partner system.
partner_refund_id cannot be same as partner_transaction_id
partner_refund_id together with partner identify a refund transaction
|
No
|
301012133000002
|
|
refund_amount
|
Number(9,2)
|
Less than or equal to the original transaction amount and the left transaction amount if ever refunded.
|
No
|
39.25
|
|
currency
|
String(10)
|
The refund currency. Use upper case. See Supported Currency List for details.
|
No
|
USD
|
|
refund_reason
|
String(128)
|
The reason of refund
|
Yes
|
Refund the good
|
|
is_sync
|
String(1)
|
The refund request is processed synchronously or asynchronously.
Value: Y or N.
Default value is N, which means an asynchronous response from Alipay is returned to the merchant if the merchant has set the value of the notify_url field when sending the refund request. If the value is set as Y, it means only a synchronous response is returned to the merchant.
|
Yes
|
Y
|
A request Example
https://intlmapi.alipay.com/gateway.do?partner_trans_id=9699196959845722&partner_refund_id=301012133000002&refund_amount=786.09¤cy=USD&sign=30ff71107f6824dc3d28af7619870e26&sign_type=MD5&_input_charset=UTF-8&service=alipay.acquire.overseas.spot.refund&partner=2088102012343978
Parameter List
Parameters accepted by Alipay gateway:
|
Parameter
|
Type (Byte)
|
Description
|
Nullable
|
Example
|
|
is_success
|
String(1)
|
It indicates that a request is accepted by Alipay gateway.
l T for accepted
|
No
|
T
|
|
sign_type
|
String
|
The type could be DSA, RSA or MD5;
Capital letters only.
|
No
|
MD5
|
|
sign
|
String(32)
|
See “4 Digital Signature”.
|
No
|
59c7275cf3c82f038b7c0076f9888926
|
|
result_code
|
String(32)
|
To describe the response status of a request:
SUCCESS, FAILED, UNKNOW.
|
No
|
SUCCESS
|
|
error
|
String(48)
|
To describe the reason of the result_code when it is failed/unknown, leave it blank when result_code is success.
|
Yes
|
TRANS_NOT_FOUND
|
|
partner_trans_id
|
String(64)
|
Equal to the partner_trans_id given in the request
|
No
|
201311221000000002
|
|
alipay_trans_id
|
String(64)
|
On the partner’s payment request, the alipay system creates a transaction id to handle it.
The alipay_trans_id has one-one association with partner + partner_trans_id.
|
Yes
|
201311221703338463
|
|
partner_refund_id
|
String(64)
|
The refund order id on partner system.
partner_refund_id together with partner identify a refund transaction
|
No
|
301012133000002
|
|
refund_amount
|
Number(9,2)
|
Less than or equal to the original transaction amount and the left transaction amount if ever refunded.
|
No
|
39.25
|
|
currency
|
String(10)
|
Refund currency
|
No
|
USD
|
|
exchange_rate
|
Number
|
The rate of conversion the currency given in the request to CNY.
The conversion happens at the time when Alipay’s trade order is created.
|
Yes
|
6.0939
|
|
refund _amount_cny
|
Number(9,2)
|
Refund amount in CNY.
It is the exact amount that the Alipay has refunded.
|
Yes
|
239.19
|
Parameters rejected by Alipay gateway:
|
Parameter
|
Type (length range)
|
Description
|
Nullable
|
Example
|
|
is_success
|
String(1)
|
It indicates that a request is rejected by Alipay gateway.
l F for rejected
|
No
|
F
|
|
sign_type
|
String
|
The type could be DSA, RSA or MD5;
Capital letters only.
|
No
|
MD5
|
|
sign
|
String(32)
|
See “4 Digital Signature”.
|
No
|
59c7275cf3c82f038b7c0076f9888926
|
|
error
|
String(48)
|
To describe the reason of the result_code when it is failed/unknown, leave it blank when result_code is success.
|
Yes
|
TRANS_NOT_FOUND
|
A response example
Normal input:
<?xmlversion="1.0"encoding="UTF-8"?>
<alipay>
<is_success>T</is_success>
<request>
<param name="_input_charset">UTF-8</param>
<param name="partner_trans_id">2010121000000002</param>
<param name="partner">2088102012343978</param>
<param name="service">alipay.acquire.overseas.pay</param>
<param name="partner_refund_id">301012133000002</param>
<param name="refund_amount">39.25</param>
<param name="currency">USD</param>
<param name="refund_reson">back</param>
<param name="sign">22904adafb1806178b410d2d5c9c02a3</param>
<param name="sign_type">MD5</param>
</request>
<response>
<alipay>
<partner_trans_id>2010121000000002</partner_trans_id>
<alipay_trans_id>201311221703338463</alipay_trans_id>
<partner_refund_id>301012133000002</partner_refund_id>
<refund_amount>39.25</refund_amount>
<currency>USD</currency>
<exchange_rate>6.0939</exchange_rate>
<refund_amount_CNY>239.19</refund _amount_CNY>
<result_code>SUCCESS</result_code>
</alipay>
</response>
<sign>6fb8a322f15cfd0fcfe65301b10f6994</sign>
<sign_type>MD5</sign_type>
</alipay>
Error output:
<?xml version="1.0" encoding="UTF-8"?>
<alipay>
<is_success>F</is_success>
<error>ILLEGAL_SIGN</error>
</alipay>
Error List
|
Error Code
|
Description
|
|
SYSTEM_ERROR
|
Alipay system is currently not available, please try again later.
|
|
ILLEGAL_SIGN
|
Illegal signature.
Please read chapter Digital Signature
|
|
INVALID_PARAMETER
|
Parameter value error.
Please check the standard of each request parameter according to the API specification
|
|
ILLEGAL_ARGUMENT
|
Parameter name error.
Please check each request parameter according to the API specification, contact Alipay technical support if this error persists
|
|
ILLEGAL_PARTNER
|
Incorrect partner ID.
Please make sure the value of partner parameter matches the partner value provided by Alipay, contact Alipay technical support if this error persists
|
|
ILLEGAL_EXTERFACE
|
Interface configure error.
Please make sure service parameters has the same value with the one in API specification, contact Alipay technical support if this error persists
|
|
ILLEGAL_PARTNER_EXTERFACE
|
Partner ID do not have access privilege.
contact Alipay technical support
|
|
ILLEGAL_SIGN_TYPE
|
Illegal sign type.
Please make sure the value of sign_type is amongst MD5,DSA and RSA, contact Alipay technical support if this error persists
|
|
HAS_NO_PRIVILEGE
|
Has no privilege.
Please contact Alipay technical support
|
|
REASON_TRADE_BEEN_FREEZEN
|
Corresponding trade has been frozen due to security issues.
Please contact Alipay technical support
|
|
TRADE_NOT_EXIST
|
Cannot find corresponding trade according to input “partner_trans_id”.
1) Make sure the partner_trans_id is correct 2)if the issue persists, please contact Alipay Technical Support
|
|
TRADE_STATUS_ERROR
|
Corresponding trade status is not allowed for current operate.
1) Make sure the trade status is correct 2)if the issue persists, please contact Alipay technical support
|
|
REFUND_AMT_RESTRICTION
|
The input “refund_amount” is more than original trade amount, or total refund amount is more than original trade amount, cannot be processed by Alipay.
Merchant need to check if the return amount is correct
|
|
REQUEST_AMOUNT_EXCEED
|
The same with “REFUND_AMT_RESTRICTION”.
Merchant need to check if the return amount is correct
|
|
RETURN_AMOUNT_EXCEED
|
The same with “REFUND_AMT_RESTRICTION”.
Merchant need to check if the return amount is correct
|
|
REFUND_CHARGE_ERROR |
The refund failed because the payment is in progress. Please try again later. |
Request parameter is the request data provided to Alipay by merchant when conducting data interaction with Alipay so that further process can be conducted by Alipay based on these data.
The gateway URL:
If you want to use Alipay sandbox to test the integration, see the sandbox handbook for details.
If you use POST method, please specify the _input_charset in the request URL. For example, https://mapi.alipaydev.com/gateway.do?_input_charset=UTF-8
Request parameters
|
Parameter
|
Type (Byte Length)
|
Parameter Description
|
Nullable
|
Example
|
|
Basic Parameters
|
|
service
|
String
|
Interface name
|
N
|
alipay.acquire.cancel
|
|
partner
|
String(1
6)
|
Unique Alipay user number corresponding to authorized Alipay account number.
Composed of 16 numbers beginning with 2088.
|
N
|
2088101125328850
|
|
_input_
charset
|
String
|
Encoding format used in merchant’s website, such as utf-8, gbk, gb2312, etc
|
N
|
utf-8
|
|
sign_type
|
String
|
Four values, namely, DSA, RSA, RSA2 and MD5 can be chosen; and must be capitalized
|
N
|
MD5
|
|
sign
|
String
|
Please refer to “7 Signature Mechanism”.
|
N
|
363a752668ee2b3b8f1
24c623bd028ad
|
|
timestamp
|
String
|
Time stamp of the merchant server sending request, accurate to the millisecond.
|
N
|
1456507704121
|
|
terminal_timestamp
|
String
|
Time stamp of the terminal sending request, accurate to the millisecond.
|
Y
|
1456507704102
|
|
Business Parameters
|
|
out_tra de_no
|
String(6
4)
|
Unique order No. in Alipay’s merchant’s website
|
N
|
99003911198989
|
|
trade_
no
|
String(6
4)
|
The trade serial number of the trade in Alipay system.
16 bits at least and 64 bits at most.
If out_trade_no and trade_no are transmitted at the same time, trade_no shall govern.
|
Y
|
2013112611001004680
073956707
|
Part of the parameter type is String. Length range is not specified, which indicates that the system will not check out the length of the parameter.
Example
https://intlmapi.alipay.com/gateway.do?sign=83cff02d58eeb51f9343f475aeb06654&_input_charset=utf-8&out_trade_no=2017082100005665&partner=2088021966388155&service=alipay.acquire.cancel×tamp=20170821193901
Synchronous Return by XML
Alipay will return result data to merchant after it has completed the processing of request data so as to facilitate further processing conducted by merchant based on these data.
The result returned can be divided into two types, one is the result of normal business acceptance and process, the other is system-level abnormity or transmitted data error. For the normal business acceptance and process, merchant is required to analyze response code to judge whether business is processed successfully.
List
|
Parameter
|
Type (length)
|
Description
|
Nullable
|
Example
|
|
Basic parameters
|
|
is_success
|
String
|
Request succeeds or not. Successful request does not mean the business is accepted and processed successfully.
T: success
F: failure
|
N
|
T
|
|
sign_type
|
String
|
Four values, namely, DSA, RSA, RSA2 and MD5 can be chosen and must be capitalized
|
Y
|
MD5
|
|
sign
|
String
|
Please refer to Signature Mechanism for details.
|
Y
|
fc209d86b57b2adb23
254a897ebaa7d9
|
|
error
|
String
|
This parameter does not exist if request succeeds;
This parameter will be error code if request fails. Please refer to Error Code for details.
|
Y
|
ILLEGAL_SIGN
|
|
Business parameters
|
|
result_code
|
String(32)
|
Response code of cancel processing result.
SUCCESS: successful refund
FAIL: unsuccessful refund
UNKNOWN: unknown result
|
N
|
SUCCESS
|
|
trade_no
|
String(64)
|
Trade number of the trade in Alipay system
16 bits at least and 64 bits at most
|
Y
|
201311201100100433
0000121536
|
|
out_trade_no
|
String(64)
|
Unique order ID in order system in corresponding merchant’s website other than Alipay trade number.
Uniqueness of this parameter in merchant’s website shall be guaranteed. This is a parameter transmitted upon corresponding request, which shall be returned in its original shape.
|
Y
|
99003911198989
|
|
retry_flag
|
String(1)
|
Y: The cancel failed due to retriable error
N: The cancel failed due to non-retriable error
|
Y
|
Y
|
|
action
|
String(10)
|
The action of cancel.
close: only closed the transaction, but no refund.
refund: had a refund.
|
Y
|
close
|
|
detail_error_code
|
String(48)
|
Give cause description to the response code returned. Please refer to Error Code for details.
If the response code of result_code is SUCCESS, this parameter shall not be returned.
|
Y
|
TRADE_STATUS_ERROR
|
|
detail_error_des
|
String(64)
|
Give literal statement as to the detailed error code. If the response code of result_code is SUCCESS, this parameter shall not be returned.
|
Y
|
Trade status is illegal.
|
With the evolution of Alipay server, the parameters returned synchronously may return more child nodes, procedure user is required to ignore the child nodes beyond the document description.
Example
Business is accepted and processed normally, and cancel is conducted successfully:
<?xml version="1.0" encoding="utf-8"?>
<alipay>
<is_success>T</is_success>
<request>
<param name="sign">66b3a14ec95846f01d42564e6953c81b</param>
<param name="_input_charset">UTF-8</param>
<param name="sign_type">MD5</param>
<param name="service">alipay.acquire.cancel</param>
<param name="partner">2088101126765726</param>
<param name="out_trade_no">99003911198989</param>
<param name="timestamp">1456507705033</param>
</request>
<response>
<alipay>
<result_code>SUCCESS</result_code>
<out_trade_no>3406822113320232</out_trade_no>
<trade_no>2013111511001004390000105126</trade_no>
<action>refund</action>
</alipay>
</response>
<sign>3afc92ac4708425ab74ecb2c4e58ef56</sign>
<sign_type>MD5</sign_type>
</alipay>
Request succeeds, business processing fails:
<?xml version="1.0" encoding="utf-8"?>
<alipay>
<is_success>T</is_success>
<request>
<param name="sign">66b3a14ec95846f01d42564e6953c81b</param>
<param name="_input_charset">UTF-8</param>
<param name="sign_type">MD5</param>
<param name="service">alipay.acquire.cancel</param>
<param name="partner">2088101126765726</param>
<param name="out_trade_no">99003911198989</param>
<param name="timestamp">1456507705033</param>
</request>
<response>
<alipay>
<result_code>FAIL</result_code>
<detail_error_code>TRADE_STATUS_ERROR</detail_error_code>
<detail_error_des>illegal trade status</detail_error_des>
</alipay>
</response>
<sign>fc209d86b57b2adb23254a897ebaa7d9</sign>
<sign_type>RSA</sign_type>
</alipay>
Request fails or the data accessed are incorrect
<?xml version="1.0" encoding="utf-8"?>
<alipay>
<is_success>F</is_success>
<error>ILLEGAL_SIGN</error>
</alipay>
Error List
|
Error Code
|
Description
|
Action
|
|
SYSTEM_ERROR
|
Alipay system is currently not available.
|
Retry this request with the exact parameters.
Refer Case 2 at here for detailed instruction.
|
|
ILLEGAL_SIGN
|
Illegal signature.
|
Please read chapter Digital Signature
|
|
INVALID_PARAMETER
|
Parameter error.
|
Please check the standard of each request parameter according to the API specification
|
|
ILLEGAL_ARGUMENT
|
Parameter error.
|
Please check each request parameter according to the API specification, contact Alipay technical support if this error persists
|
|
ILLEGAL_PARTNER
|
Incorrect partner ID.
|
Please make sure the value of partner parameter matches the partner value provided by Alipay, contact Alipay technical support if this error persists
|
|
ILLEGAL_EXTERFACE
|
Interface configure error.
|
Please make sure that the service parameters has the same value with the one in API specification, contact Alipay technical support if this error persists
|
|
ILLEGAL_PARTNER_EXTERFACE
|
Partner ID do not have access privilege.
|
Make sure your agreement with Alipay has been finalized. Contact Alipay technical support if needed.
|
|
ILLEGAL_SIGN_TYPE
|
Illegal sign type.
|
Please make sure the value of sign_type is among MD5,DSA and RSA, contact Alipay technical support if this error persists
|
|
HAS_NO_PRIVILEGE
|
Has no privilege.
|
Please contact Alipay technical support
|
|
REASON_TRADE_BEEN_FREEZEN
|
Corresponding trade has been frozen due to security issues.
|
Please contact Alipay technical support
|
|
TRADE_NOT_EXIST
|
Cannot find corresponding trade according to input “partner_trans_id”.
|
1) Make sure the partner_trans_id is correct 2)if the issue persists, please contact Alipay Technical Support
|
|
TRADE_STATUS_ERROR
|
Corresponding trade status is not allowed for current operate.
|
1) Make sure the trade status is correct 2)if the issue persists, please contact Alipay technical support
|
|
BUYER_ERROR
|
The buyer does not exist.
|
Please contact Alipay technical support.
|
|
BUYER_ENABLE_STATUS_FORBID
|
Buyer account status prohibits the refund.
|
Please contact Alipay technical support.
|
|
SELLER_ERROR
|
The seller does not exist.
|
Please contact Alipay technical support.
|
|
MERCHANT_BALANCE_NOT_ENOUGH
|
Merchant balance is not enough for refund.
|
Try again later after new transactions occurred.
|
|
TRADE_CANCEL_TIME_OUT
|
The cancellation request is beyond the opening hours.
|
Please use the refund interface instead.
|
|
SELLER_BALANCE_NOT_ENOUGH
|
Insufficient balance of seller.
|
Try again later after new transactions occurred.
|
|
REASON_TRADE_REFUND_FEE_ERR
|
Invalid refund amount.
|
Please contact Alipay technical support for help.
|
|
TRADE_HAS_FINISHED
|
Transaction completed.
|
Please use the refund interface instead.
|
|
REFUND_CHARGE_ERROR |
The refund failed because the payment is in progress. |
Please try again later. |
Handling result of alipay.acquire.cancel
Case 1. When the invocation failed with network issue or request timeouted, so got no response from Alipay
- Check your network connectivity to Alipay gateway. Retry(Every 3 seconds, up to 5 times.) this request with the exact parameters until you get a response from Alipay.
- If still not work, request Alipay tech support for help.
Case 2. Received response from Alipay, but (1) is_success=F and error=SYSTEM_ERROR, or (2) is_success=T and result_code=FAIL and detail_error_code=SYSTEM_ERROR, or (3) is_success=T and result_code=UNKNOWN.
- Retry(Every 3 seconds, up to 5 times.) this request with the exact parameters until you get a response from Alipay.
- If still not work, request Alipay tech support for help.
Case 3. Received response from Alipay, and is_success=T and result_code=SUCCESS. Mark merchant cancel order as processed successfully
Case 4. Received response from Alipay, and (1) is_success=F and error=!SYSTEM_ERROR, or (2) is_success=T and result_code=FAIL and detail_error_code!=SYSTEM_ERROR. Mark merchant cancel order as failed. Refer specific error code for instrunction
Pseudo code:
try{
if(isCase3){ //CASE 3
doSuccessProcess();
}
else if(isCase4){ //CASE 4
doFailureProcess();
}
else{ //CASE 2
retrySuccess = retryWithSameParameters(); //Retry every 3 seconds, up to 5 times.
if(retrySuccess){
doSuccessProcess();
}
else{
//request Alipay tech support.
}
}
}catch (Exception ex){ // CASE 1
retrySuccess = retryWithSameParameters(); //Retry every 3 seconds, up to 5 times.
if(retrySuccess){
doSuccessProcess();
}
else{
//request Alipay tech support.
}
}
}
This interface provides the ability to query a transaction with partner_trans_id or alipay_trans_id.
The gateway URL:
If you want to use Alipay sandbox to test the integration, see the sandbox handbook for details.
If you use POST method, please specify the _input_charset in the request URL. For example, https://mapi.alipaydev.com/gateway.do?_input_charset=UTF-8
Request parameters
|
Parameter
|
Type (Byte)
|
Description
|
Nullable
|
Example
|
|
Basic parameter
|
|
service
|
String
|
Interface name.
|
No
|
alipay.acquire.overseas.query
|
|
sign
|
String
|
Signature value. See “Digital Signature”.
|
No
|
c8il4epm90wyn768fijgqhy8tay37gqa
|
|
sign_type
|
String
|
The type could be DSA, RSA or MD5;
Capital letters only.
|
No
|
MD5
|
|
partner
|
String
|
One Alipay account has only one Alipay ID. Composed of 16-digit number beginning with 2088
|
No
|
2088102012343978
|
|
_input_charset
|
String
|
Character set of parameter code.
Default is GBK if not send.
|
Yes
|
UTF-8
|
|
Operation parameter
|
|
partner_trans_id
|
String(64)
|
The original partner transaction id given in the payment request
|
No
|
2010121000000002
|
|
alipay_trans_id
|
String(64)
|
On the partner’s payment request, the alipay system creates a transaction id to handle it.
The alipay_trans_id has one-one association with partner + partner_trans_id.
|
YES
|
201311221703338463
|
A request example
https://intlmapi.alipay.com/gateway.do?partner_trans_id=9699196959845722&sign_type=MD5&_input_charset=UTF-8&service=alipay.acquire.overseas.query&partner=2088102012343978
Parameter List
|
Parameter
|
Type (Byte)
|
Description
|
Nullable
|
Example
|
|
is_success
|
String(1)
|
It indicates that a request is accepted by Alipay gateway.
l T for accepted
|
No
|
T
|
|
sign_type
|
String
|
The type could be DSA, RSA or MD5;
Capital letters only.
|
No
|
MD5
|
|
sign
|
String(32)
|
See “4 Digital Signature”.
|
No
|
59c7275cf3c82f038b7c0076f9888926
|
|
result_code
|
String(32)
|
To describe the response status of a request:
SUCCESS, FAIL
|
No
|
SUCCESS
|
|
error
|
String(48)
|
To describe the reason of the result_code when it is failed/unknown, leave it blank when result_code is success.
|
Yes
|
TRANS_NOT_FOUND
|
|
alipay_trans _status
|
String(32)
|
WAIT_BUYER_PAY,
TRADE_SUCCESS,
TRADE_CLOSED
|
Yes
|
TRADE_SUCCESS
|
|
alipay_buyer_login_id
|
String(20)
|
The buyer’s Alipay login Id, the id might be an email or mobile number.
The id is partially masked for privacy.
|
YES
|
cao***@126.com or 186***22156
|
|
alipay_buyer_user_id
|
String(16)
|
This ID stands for each Alipay account number ,unique in Alipay system start with “2088”
|
No
|
2088102130896433
|
|
partner_trans_id
|
String(64)
|
Equal to the partner_trans_id given in the request
|
No
|
201311221000000002
|
|
alipay_trans_id
|
String(64)
|
On the partner’s payment request, the alipay system creates a transaction id to handle it.
The alipay_trans_id has one-one association with partner + partner_trans_id.
|
YES
|
201311221703338463
|
|
alipay_pay_time
|
String(16)
|
The time of the transaction has been paid.
Format：YYYYMMDDHHMMSS
|
YES
|
201311212323
|
|
currency
|
String(8)
|
The currency used for labeling the price of the transaction; |
No
|
USD
|
|
trans_amount
|
Number(9,2)
|
the transaction amount in the currency given above;
Range: 0.01-100000000.00. Two digits after decimal point.
|
No
|
39.25
|
|
exchange_rate
|
Number(8,6)
|
The rate of conversion the currency given in the request to CNY.
The conversion happens at the time when Alipay’s trade order is created.
|
YES
|
6.0939
|
|
trans _amount_cny
|
Number(9,2)
|
Transaction amount in CNY.
It is the exact amount that the buyer has paid
|
YES
|
239.19
|
|
m_discount_forex_amount
|
Number(9,2)
|
If coupons/vouchers are used in the transaction, the discount amount redeened in the settlement currency will be returned. Otherwise, no return.
|
Yes
|
2.19
|
|
forex_total_fee
|
Number(9,2)
|
Transaction amount in the settlement currency.
Note: This parameter only applies to some Alipay businesses.
|
YES
|
42.19
|
|
trans_forex_rate
|
Number(8,6)
|
Exchange rate between the price currency and settlement currency.
Note: This parameter only applies to some Alipay businesses.
|
YES
|
6.0939
|
Parameters rejected by Alipay gateway:
|
Parameter
|
Type (Byte)
|
Description
|
Nullable
|
Example
|
|
is_success
|
String(1)
|
It indicates that a request is rejected by Alipay gateway.
l F for rejected
|
No
|
F
|
|
sign_type
|
String
|
The type could be DSA, RSA or MD5;
Capital letters only.
|
No
|
MD5
|
|
sign
|
String(32)
|
See “4 Digital Signature”.
|
No
|
59c7275cf3c82f038b7c0076f9888926
|
|
detail_error_code
|
String(48)
|
To describe the reason of the result_code when it is failed/unknown, leave it blank when result_code is success.
|
Yes
|
TRANS_NOT_FOUND
|
|
detail_error_des
|
String(48)
|
To describe the reason of the result_code when it is failed/unknown, leave it blank when result_code is success.
|
Yes
|
|
Please also note that details_error_code and details_error_description parameter value are subject to be newly introduced further; please consider when coding to handle forward compatibility for this further error code introduction.
A response example
Normal input:
<?xmlversion="1.0"encoding="UTF-8"?>
<alipay>
<is_success>T</is_success>
<request>
<param name="_input_charset">UTF-8</param>
<param name="partner_trans_id">2010121000000002</param>
<param name="partner">2088102012343978</param>
<param name="service">alipay.acquire.overseas.query</param>
<param name="sign">22904adafb1806178b410d2d5c9c02a3</param>
<param name="sign">c7d17d40111b8264975a6bfba77962cb</param>
</request>
<response>
<alipay>
<alipay_trans_id>2011091703338463</alipay_trans_id>
<partner_trans_id>201311221000000002</partner_trans_id>
<alipay_buyer_login_id>cao***@126.com</alipay_buyer_login_id>
<alipay_pay_time>20131120155823</alipay_pay_time>
<exchange_rate>6.0939</exchange_rate>
<trans_amount>39.25</trans_amount>
<trans_amount_CNY>239.19</trans_amount_CNY>
<result_code>SUCCESS</result_code>
<alipay_trans _status>TRADE_SUCCESS</alipay_trans _status>
</alipay>
</response>
<sign>6fb8a322f15cfd0fcfe65301b10f6994</sign>
<sign_type>MD5</sign_type>
</alipay>
Error output:
<?xml version="1.0" encoding="UTF-8"?>
<alipay>
<is_success>F</is_success>
<error>ILLEGAL_SIGN</error>
<sign>02f6b289c46b8d0c1ea62b4f78637c1a</sign>
<sign_type>MD5</sign_type>
</alipay>
Error List
|
Error Code
|
Description
|
Action
|
|
SYSTEM_ERROR
|
Alipay system failed to process the request due to temporary internal glitch.
|
Retry this request with the exact parameters.
Refer Case 2 at here for detailed instruction.
|
|
ILLEGAL_SIGN
|
Illegal signature.
|
Please read chapter Digital Signature
|
|
INVALID_PARAMETER
|
Parameter value error.
|
Please check the standard of each request parameter according to the API speficaition
|
|
ILLEGAL_ARGUMENT
|
Parameter name error.
|
Please check each request parameter according to the API specification, contact Alipay technical support if this error persists
|
|
ILLEGAL_PARTNER
|
Incorrect partner ID.
|
Please make sure the value of partner parameter matches the partner value provided by Alipay, contact Alipay technical support if this error persists
|
|
ILLEGAL_EXTERFACE
|
Interface configure error.
|
Please make sure service parameters has the same value with the one in API specification, contact Alipay technical support if this error persists
|
|
ILLEGAL_PARTNER_EXTERFACE
|
Partner ID do not have access privilege.
|
contact Alipay technical support
|
|
ILLEGAL_SIGN_TYPE
|
Illegal sign type.
|
Please make sure the value of sign_type is amongst MD5,DSA and RSA, contact Alipay technical support if this error persists
|
|
HAS_NO_PRIVILEGE
|
Has no privilege.
|
Please contact Alipay technical support
|
|
REASON_TRADE_BEEN_FREEZEN
|
Corresponding trade is been frozen due to security issues.
|
Please contact Alipay technical support
|
|
TRADE_NOT_EXIST
|
Cannot find corresponding trade according to inputted “partner_trans_id”.
1) Make sure the partner_trans_id is correct 2)if the issue persists, please contact Alipay technical support
|
1) Make sure the partner_trans_id is correct 2)if the issue persists, please contact Alipay technical support
|
Handling result of alipay.acquire.query
Case 1. When the invocation failed with network issue or request timeouted, so got no response from Alipay
- Check your network connectivity to Alipay gateway. Retry(Every 3 seconds, up to 10 times.) this request with the exact parameters until you get a response from Alipay.
- If still not work, request Alipay tech support for help.
Case 2. Received response from Alipay, but (1) is_success=F and error=SYSTEM_ERROR, or (2) is_success=T and result_code=FAIL and detail_error_code=SYSTEM_ERROR
- Retry(Every 3 seconds, up to 10 times.) this request with the exact parameters until you get a response from Alipay.
- If still not work, request Alipay tech support for help.
Case 3. Received response from Alipay, and is_success=T and result_code=SUCCESS. Query succeeded.
Case 4. Received response from Alipay, and (1) is_success=F and error=!SYSTEM_ERROR, or (2) is_success=T and result_code=FAIL and detail_error_code!=SYSTEM_ERROR. Query failed. Refer specific error code for instrunction
Pseudo code:
try{
if(isCase3){ //CASE 3
doSuccessProcess();
}
else if(isCase4){ //CASE 4
doFailureProcess();
}
else{ //CASE 2
retrySuccess = retryWithSameParameters(); //Retry every 3 seconds, up to 10 times.
if(retrySuccess){
doSuccessProcess();
}
else{
//request Alipay tech support.
}
}
}catch (Exception ex){ // CASE 1
retrySuccess = retryWithSameParameters(); //Retry every 3 seconds, up to 10 times.
if(retrySuccess){
doSuccessProcess();
}
else{
//request Alipay tech support.
}
}
}
Generate Pre-sign string
Parameters to sign
In the list of request and response parameters, all of them need to be signed except sign and sign_type. (sign_type also needs to be signed in some cases in the list of request parameters)
Generate Pre-sign string
Use the following code to package the data:
//package the request parameters
Map sParaTemp = new HashMap();
sParaTemp.put("service", AlipayConfig.service);
sParaTemp.put("partner", AlipayConfig.partner);
sParaTemp.put("_input_charset", AlipayConfig.input_charset);
sParaTemp.put("notify_url", AlipayConfig.notify_url);
sParaTemp.put("return_url", AlipayConfig.return_url);
sParaTemp.put("out_trade_no", out_trade_no);
sParaTemp.put("subject", subject);
sParaTemp.put("total_fee", total_fee);
sParaTemp.put("body", body);
sParaTemp.put("currency", currency);
sParaTemp.put("product_code", product_code);
split_fund_info = split_fund_info.replaceAll("\"", "'");
sParaTemp.put("split_fund_info", split_fund_info);
sParaTemp.put("secondary_merchant_id",secondary_merchant_id);
sParaTemp.put("secondary_merchant_name",secondary_merchant_name);
sParaTemp.put("secondary_merchant_industry",secondary_merchant_industry);
Rearrange parameters in the data set alphabetically
And connect rearranged parameters with &：
_input_charset=utf-8&app_pay=Y&body=test¤cy=USD¬ify_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”)
- Signature Verification for response
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”)
- Signature Verification for response
After receiving the pre-sign string during responding from Alipay system, the Alipay public key, the pre-sign string and the parameter “sign” are used in the RSA signature asymmetric algorithm by the RSA signature function to accomplish the signature verification.
This interface provides the ability to refund a transaction both in whole and in partial.
By design, the refund request cannot be reversed, use retry instead.
The gateway URL:
If you want to use Alipay sandbox to test the integration, see the sandbox handbook for details.
If you use POST method, please specify the _input_charset in the request URL. For example, https://mapi.alipaydev.com/gateway.do?_input_charset=UTF-8
Request parameters
|
Parameter
|
Type(Byte)
|
Description
|
Nullable
|
Example
|
|
Basic parameter
|
|
service
|
String
|
Description
|
No
|
alipay.acquire.overseas.spot.refund
|
|
sign
|
String
|
Signature value. See “Digital Signature”.
|
No
|
c8il4epm90wyn768fijgqhy8tay37gqa
|
|
sign_type
|
String
|
The type could be DSA, RSA or MD5;
Capital letters only.
|
No
|
MD5
|
|
partner
|
String
|
One Alipay account has only one Alipay ID. Composed of 16-digit number beginning with 2088
|
No
|
2088102012343978
|
|
_input_charset
|
String
|
Character set of parameter code.
Default is GBK if not send.
|
Yes
|
UTF-8
|
|
notify_url
|
String
|
The url to which Alipay sends payment result in async mode. It is in POST method.
Note:
For information security, the url must be on https protocol.
This URL cannot have extra parameters. For example, “https://xxx.com/foo.php?star=obama” is not allowed.
|
Yes
|
https://www.test.com/alipay/notify_url.php
|
|
Operation parameter
|
|
partner_trans_id
|
String(64)
|
The original partner transaction id given in the payment request
|
No
|
2010121000000002
|
|
alipay_trans_id
|
String(64)
|
The Alipay transaction ID.
|
Yes
|
201311221703338463
|
|
partner_refund_id
|
String(64)
|
The refund order id on partner system.
partner_refund_id cannot be same as partner_transaction_id
partner_refund_id together with partner identify a refund transaction
|
No
|
301012133000002
|
|
refund_amount
|
Number(9,2)
|
Less than or equal to the original transaction amount and the left transaction amount if ever refunded.
|
No
|
39.25
|
|
currency
|
String(10)
|
The refund currency. Use upper case. See Supported Currency List for details.
|
No
|
USD
|
|
refund_reason
|
String(128)
|
The reason of refund
|
Yes
|
Refund the good
|
|
is_sync
|
String(1)
|
The refund request is processed synchronously or asynchronously.
Value: Y or N.
Default value is N, which means an asynchronous response from Alipay is returned to the merchant if the merchant has set the value of the notify_url field when sending the refund request. If the value is set as Y, it means only a synchronous response is returned to the merchant.
|
Yes
|
Y
|
A request Example
https://intlmapi.alipay.com/gateway.do?partner_trans_id=9699196959845722&partner_refund_id=301012133000002&refund_amount=786.09¤cy=USD&sign=30ff71107f6824dc3d28af7619870e26&sign_type=MD5&_input_charset=UTF-8&service=alipay.acquire.overseas.spot.refund&partner=2088102012343978
OpenSSL installation
RSA key pair generation
For Java developers, we need to remove the header, footer, <CR>, and space from the pkcs8 private key output in the console. For.NET and PHP developer, there is no need for the pkcs8 operation.
After the above steps, the user could see two files under the current folder (C:\OpenSSL-Win32\bin for Windows), rsaprivatekey.pem and rsapublickey.pem.
The former is the private key while the latter is the public key. The merchant should keep the private key and exchange the public key with Alipay for signature verification. The following are the examples on how to use the key pair.
Upload the public key
Contact Global Merchant Technical Support to upload the public key. Please sign with the matching private key in the key pair.
Call this interface to register offline secondary merchants information into Alipay system.
The gateway URL:
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 (bytes)
|
Description
|
Optional
|
Example
|
|
Basic Parameter
|
|
service
|
String
|
Service Name
|
N
|
alipay.overseas.secmerchant.offline.maintain
|
|
partner
|
String(16)
|
A unique partner ID to identify a contracted Alipay Account.
A 16 digit number starts with 2088.
|
N
|
2088*********662
|
|
_input_charset
|
String
|
The charset with which the request data is encoded. For example, UTF-8, GBK, GB2312 etc.
|
N
|
gbk
|
|
sign_type
|
String
|
DSA, RSA, or MD5, use upper case
|
N
|
MD5
|
|
sign
|
String
|
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(128)
|
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)
|
The unique ID assigned by the partner to identify a secondary merchant. The ID can contain letters, numbers, and underscores.
|
N
|
63472327348
|
|
store_id
|
String(64)
|
Store ID. For taxicabs and limousines (MCC 4121), use the license plate number.
|
N
|
23372327348
|
|
store_name
|
String(256)
|
Store name. For taxicabs and limousines (MCC 4121), use the license plate number.
|
N
|
StoreName
|
|
store_country
|
String(2)
|
Store registration country. A 2-letter code defined in ISO 3166.
|
N
|
HK
|
|
store_address
|
String(330)
|
Registered store address. Use mailing address format.
|
N
|
Store address
|
|
store_industry
|
String(4)
|
A 4-digit MCC code of the store. See MCC list for details.
|
N
|
4121
|
|
internal_store_photo
|
String(256)
|
URL of the store interior photo.
|
Y
|
URL
|
|
external_storefront_photo
|
String(256)
|
URL of the store exterior photo.
|
Y
|
URL
|
|
extend_params
|
String(1024)
|
Taxi driver information in JSON format. JSON keys are fixed as operation_id, contact_way, and contact_person. Up to 10 drivers can be passed.
Note: The value of each operation_id must be unique. This field cannot be updated incrementally. Pass this field the first time you register a driver; otherwise you cannot add it later when you update the driver information.
|
Y
|
[{"operation_id": "1000332", "contact_way": "138xxxx1232", "contact_person": "driverName1"}, {"operation_id": "1082943492", "contact_way": "158xxxx2232", "contact_person": "driverName2"}]
|
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 |
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.277, Road YinCheng, Shanghai, China |
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 |
186xxxx0000 |
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 |
952xx |
cs_email |
String(128) |
Customer service email address of the secondary merchant |
Y |
customerservice@xxxcompany.com |
extend_params
|
Parameter
|
Type (bytes)
|
Description
|
Optional
|
Example
|
|
operation_id
|
String(64)
|
Taxi driver ID. Use only numbers and letters.
|
N
|
1082943492
|
|
contact_way
|
String(256)
|
Phone number of the taxi driver. Use “+”, numbers, spaces, and “-“.
|
Y
|
158xxxx2232
|
|
contact_person
|
String(64)
|
Taxi driver name
|
N
|
driverName2
|
Some parameters of String type have no length limit and the system will not check their length.
Sync Response
The response is in XML format.
|
Parameter
|
Type (bytes)
|
Description
|
Optional
|
Example
|
|
Basic Parameter
|
|
is_success
|
String
|
Request succeeds or not. Successful request does not mean the business request is accepted and processed successfully.
T means success
F means failure
|
N
|
T
|
|
sign_type
|
String
|
The value can be one of DSA, RSA, or MD5. Uppercase must be used.
|
Y
|
MD5
|
|
sign
|
String
|
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 Examples
Examples
Request succeeds
<?xml version="1.0" encoding="utf-8"?>
<alipay>
<is_success>T</is_success>
<request>
<param name="service">alipay.overseas.secmerchant.offline.maintain</param>
<param name="partner">2088101142878662</param>
<param name="_input_charset">UTF-8</param>
<param name="sign_type">MD5</param>
<param name="sign">2118ac8fad6bc1d9e88a6cd017c18d37</param>
<param name="timestamp">2018-08-03 00:28:32</param>
<param name="secondary_merchant_name">hanguo</param>
<param name="secondary_merchant_id">2015051446800462</param>
<param name="store_id">23372327348</param>
<param name="store_name">LV</param>
<param name="store_country">HK</param>
<param name="store_address">store address</param>
<param name="store_industry">4121</param>
<param name="secondary_merchant_type">INDIVIDUAL</param>
<param name="registration_no">012345678</param>
<param name="register_country">HK</param>
<param name="register_address">No.277, Road YinCheng, Shanghai, China</param>
<param name=“representative_name”>Tom Li</param>
<param name=“representative_id”>123456789</param>
<param name="settlement_no">2600100000</param>
<param name="contact_no">186xxxx0000 </param>
<param name="contact_email">support@xcompany.com </param>
</request>
<response>
<alipay>
<result_code>SUCCESS</result_code>
</alipay>
</response>
<sign>744a87f0e3b40e6a8cd8f9705ce61511</sign>
<sign_type>MD5</sign_type>
</alipay>
Request fails or the access data are wrong:
<?xml version="1.0" encoding="utf-8"?>
<alipay>
<is_success>F</is_success>
<error>ILLEGAL_SIGN</error>
</alipay>
Error Codes
Business Logic Errors
|
Returned result
|
Description
|
Solution
|
|
MCC_CAN_NOT_MODIFY
|
The MCC passed in cannot
match the original MCC.
|
Please ensure that the passed MCC is the same as the original MCC.
|
|
MCC_TYPE_ILLEGAL
|
The MCC is invalid.
|
Modify the MCC type and then try again.
|
PARAM_ILLEGAL
|
The parameter is illegal.
The parameter is too long, parameter format is wrong, or a required parameter
is not passed.
|
Please check and rectify the parameter according to the API document.
|
|
SYSTEM_ERROR
|
Alipay system error
|
Please try again later.
|
|
LBS_GEOGRAPHIC_INFORMATION_INVALID
|
The address cannot match the country/region, or the address cannot be located.
|
Please ensure that the address is valid and use the address that can be located in Google map.
|
|
CATEGORY_NOT_SUPPORT_DRIVER
|
When store_industry is 4121 and extend_params is not passed when you request in the first time, then this error occurs when you update the store information and pass the driver information.
|
Please remove the driver information from the extend_param.
|
|
DUPLICATE_REQUEST
|
Duplicate request submitted. The previous registration request is still in process.
|
Please wait until the previous registration request completes.
|
|
MERCHANT_TYPE_ILLEGAL
|
Illegal secondary merchant type. The value of the secondary_merchant_type field can only be ENTERPRISE or INDIVIDUAL.
|
Enter the correct value for the secondary_merchant_type field.
|
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, register_country, register_address, shareholder_name, shareholder_id, representative_name, representative_id, settlement_no, contact_no, contact_email, cs_no, cs_email
- Added the DUPLICATE_REQUEST error code.
- Updated the description of the secondary_merchant_name field.
|
|
2019.02.28
|
- Added the result_code field in the Sync Response part.
- Updated the solution part of the LBS_GEOGRAPHIC_INFORMATION_INVALID error code.
|
Call this interface to query the registration status of secondary merchants.
The gateway URL:
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
|
2012-12-21 17:11:16
|
|
Business Parameter
|
|
secondary_merchant_id
|
String(64)
|
Secondary merchant ID, need to be unique for each PID
|
N
|
MERCHANT_ID_0003
|
|
store_id
|
String(64)
|
Store ID, need to be unique for each group of PID and MID
This field is required when the value of payment_method is INSTORE_PAYMENT.
|
N
|
STORE_ID_0003
|
|
payment_method
|
String
|
Payment method of the secondary merchant, the value is INSTORE_PAYMENT for offline payments.
|
N
|
INSTORE_PAYMENT
|
Sync Response
The response is in XML format.
|
Parameter
|
Type (bytes)
|
Description
|
Optional
|
Example
|
|
sign
|
String
|
The value of sign
|
Y
|
2118ac8fad6bc1d9e88a6cd017c18d37
|
|
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
|
|
store_id
|
String
|
Store ID, need to be unique for each group of PID and MID
This field is required when the value of payment_method is INSTORE_PAYMENT.
|
N
|
STORE_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.
|
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="store_id">STORE_ID_0003</param>
<param name="partner">2088101131367863</param>
<param name="service">alipay.overseas.secmerchant.maintain.queryStatus</param>
<param name="sign">9c4643447830d870b56c8181643da9e4</param>
<param name="sign_type">MD5</param>
<param name="_input_charset ">gbk</param>
<param name="timestamp ">2012-12-21 17:11:16</param>
<param name="_input_charset ">gbk</param>
<param name="payment_method">INSTORE_PAYMENT</param>
<param name="secondary_merchant_id">MERCHANT_ID_0003</param>
</request>
<response>
<alipay>
<secondary_merchant_id>MERCHANT_ID_0003</secondary_merchant_id>
<status>UNDER_REVIEW</status>
<store_id>STORE_ID_0003</store_id>
</alipay>
</response>
<sign>a109ce66ba5b825759927c00be3259fa</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>6dff2d017f284ca0147fc8f6891b4cb2</sign>
<sign_type>MD5</sign_type>
</alipay>
Change history
Version 1 released on Feb, 18, 2019.
