Alipay, China's leading third-party online payment solutionAlipay, China's leading third-party online payment solution

alipay.dut.customer.agreement.page.sign

Auto-debit sign interface -- alipay.dut.customer.agreement.page.sign.

Request

Service address

Environment

HTTPS request URL

Production environment

https://intlmapi.alipay.com/gateway.do

Test environment

https://mapi.alipaydev.com/gateway.do

Request parameters

ParameterType (length)DescriptionRequiredExample
Basic parameter
serviceStringService NameYalipay.dut.customer.agreement.page.sign
partnerString(16)Partner ID that is composed of 16 digits beginning with 2088.Y2088001159940003
_input_charsetStringThe charset with which the request data is encoded. UTF-8 is supported.

N

UTF-8
sign_typeStringSign type. DSA, RSA, and MD5 are supported. Use uppercase.YRSA
signStringSign valueYe5815a4556db338ed237f7d3fd222184
return_urlString(200)

After the payment is completed, the result is sent to this URL through URL redirect.

N

http://api.test.alipay.net/atinterface/receive_return.htm
notify_urlString(200)

The URL for receiving asynchronous notifications after the payment is completed.

N

http://api.test.alipay.net/atinterface/receive_notify.htm
Business parameter
product_codeString(64)The code that identifies a payment solution signed between Alipay and the user.YGENERAL_WITHHOLDING_P
access_infoStringAccess channel info. Please refer the detailed information.Y{"channel":"PC"}
sceneString(64)The code for specific scenario, identifying a business case which agreed between Alipay and the merchant. If leave blank, the default value is DEFAULT|DEFAULT.YINDUSTRY|MEDICAL
sign_validity_periodString(8)Valid period of the agreement. Integer with time unit. Currently, only d: days and m: months are supported.
If leave blank, no expeiration date

N

2m
external_sign_noString(32)The agreement number in the merchant’s system. It should be unique.Ye8qdwl9caset5zugii2r7q0k8ikopxor32
agreement_detailStringAgreement detail. In json formation, please refer the detailed introduction.

N

{"payToolSummaryDetails":[{"payToolSummary":"COUPON_DC_COUPON_DEFAULT","extInfo":null},{"payToolSummary":"BANKCARD_CC_EXPRESS_DEFAULT","extInfo":null},{"payToolSummary":"BANKCARD_CC_CARTOON_DEFAULT","extInfo":null}]}
prod_propertiesStringAgreement product properties, in json formation. Please refer the detailed introduction

N

{"AuthBizInfo":{"platform":"TMALLHK_BAIL"}}
external_user_idStringUser id in the merchant’s system. Used to be shown at the signing page

N

abbbc
zm_auth_infoStringSesame credit authorization info. In JSON formation, please refer the detailed introduction

N

{"buckleAppId":"1000011","buckleMerchantId":"268820000021172633575"}
third_party_typeString(32)Type of the third party who signs the agreement with Alipay and Alipay user. Default value is PARTNERYPARTNER
sales_product_codeString(64)The code that identifies a payment solution signed between Alipay and the user.YFor overseas auto-debit it is mandatory to use FOREX_GENERAL_WITHHOLDING .
Optional to China Autodebit GENERAL_WITHHOLDING

access_info

ParameterType (length)Description

Required

Example
channelStringThe user access channel: ALIPAYAPP: Alipay Wallet PC: PC browser WAP: WAP mobile browserY

PC

agreement_detail

ParameterType (length)Description

Required

Example
payToolSummaryDetailsList of payment tools, in JSONService name

N

[{"payToolSummary":"COUPON_DC_COUPON_DEFAULT","extInfo":null},{"payToolSummary":"BANKCARD_CC_EXPRESS_DEFAULT","extInfo":null},{"payToolSummary":"BANKCARD_CC_CARTOON_DEFAULT","extInfo":null}]
payToolSummaryPayment tool, in JSONName of payment tools. Supports tools that are listed separately.

N

BANKCARD_CC_EXPRESS_DEFAULT
extInfoextended info, in JSONUsed for Partner’s specific business information.

N

{"key1":"value1","key2":"value2"}

prod_properties

ParameterType (length)Description

Required

Example
AuthBizInfoStringAuthorization business info

N

{"platform":"TMALLHK_BAIL"}

zm_auth_info

ParameterType (length)Description

Required

Example
buckleAppIdStringMerchant AppId in Sesame Credit System

Y

1000011
buckleMerchantIdStringMerchant Id in Sesame Credit SystemY268820000021172633575

Response

Synchronous response

ParameterType (length)Description

Required

Example
Basic parameter
is_successStringIt the request is success at gateway level. It doesn’t mean the business is success.
T: success
F: failure

Y

T
sign_typeStringSign type. DSA and RSA are supported. Use uppercase.

Y

RSA
signStringSign value

Y

59c7275cf3c82f038b7c0076f9888926
_input_charsetString

The charset with which the request data is encoded. UTF-8 is supported.

N

utf-8
Business parameter
agreement_noStringAgreement number generated by Alipay.

Y

20141020000353099885
product_codeStringThe code that identifies a payment solution signed between Alipay and the user.

Y

GENERAL_WITHHOLDING_P
sceneStringThe scene code of the payment agreement.

Y

INDUSTRY|MEDICAL
statusStringStatus of the agreement.
TEMP: Temporary recorded, never activated
NORMAL: Normal status
STOP: Stopped

Y

NORMAL
sign_timeStringThe actual signing time of the agreement, in Beijing time.
Format: yyyy-MM-dd HH:mm:ss

Y

2014-10-20 11:49:19
sign_modify_timeStringThe last modification time of the agreement, in Beijing time.
Format: yyyy-MM-dd HH:mm:ss

Y

2014-10-20 11:49:19
valid_timeStringThe actual valid time of the agreement, in Beijing time.
Format: yyyy-MM-dd HH:mm:ss		Y2014-10-20 11:49:19
invalid_timeStringThe expiration time of the agreement, in Beijing time.
Format: yyyy-MM-dd HH:mm:ss

Y

2014-12-20 11:49:19
alipay_user_idStringAlipay user id. 16 digits number start with 2088

Y

2088102145412262
external_sign_noStringThe agreement number in the merchant’s system. It should be unique.

Y

e8qdwl9caset5zugii2r7q0k8ikopxor32
zm_open_idStringUser’s Sesame Credit open id. Used by the merchant to check the Sesame credit score

N

268816057852461313538942792
alipay_logon_idString

User's Alipay email or mobile phone registration number

N

13654872598

Asynchronous response

ParameterType (length)Description

Required

Example
Basic parameter
notify_timeString

Notify time in China Standard Time (GMT + 8).

Format: YYYY-MM-DD HH24:MM:SS. 

Y

2014-09-16 16:36:59

notify_typeString

Type of the notification.

Y

dut_user_sign

notify_idString

Notify id for verification. It can be used by the partner system to verify the notification. 

Y

af23ec9978084df827d552369be76a5leg

sign_typeStringSign type. DSA and RSA are supported. Use uppercase.

Y

RSA
signStringSign value

Y

59c7275cf3c82f038b7c0076f9888926
Business parameter
agreement_noStringAgreement number generated by Alipay.

Y

20141020000353099885
product_codeStringThe code that identifies a payment solution signed between Alipay and the user.

Y

GENERAL_WITHHOLDI NG_P
sceneStringThe scene code of the payment agreement.

Y

INDUSTRY|MEDICAL
statusStringStatus of the agreement.
TEMP: Temporary recorded, never activated;
NORMAL: Normal status;
STOP: Stopped

Y

NORMAL
sign_timeStringThe actual signing time of the agreement, in Beijing time. Format: yyyy-MM-dd
HH:mm:ss

Y

2014-10-20 11:49:19
sign_modify_timeStringThe actual signing time of the agreement, in Beijing time.
Format: yyyy-MM-dd
HH:mm:ss

Y

2014-10-20 11:49:19
valid_timeStringThe actual valid time of the agreement, in Beijing time.
Format: yyyy-MM-dd
HH:mm:ss

Y

2014-10-20 11:49:19
invalid_timeStringThe expiration time of the agreement, in Beijing time.
Format: yyyy-MM-dd
HH:mm:ss

Y

2014-12-20 11:49:19
partner_idStringThe merchant’s Alipay partner_id. 16 digits number start with 2088

Y

2088001159912750
alipay_user_idStringAlipay user id. 16 digits number start with 2088

Y

2088102145412260
external_sign_noStringThe agreement number in the merchant’s system. It should be unique.

Y

e8qdwl9caset5zugii2r7q0k8ikopxor32
zm_open_idStringUser’s Sesame Credit open id. Used by the merchant to check the Sesame credit score.N268816057852461313538942792
alipay_logon_idString

User's Alipay email or mobile phone registration number

N

13654872598

Error codes

Access errors

Error codeDescription
SYSTEM_ERRORSystem error.
SESSION_TIMEOUTSession timeout.
ILLEGAL_TARGET_SERVICEThe signature fails the verification.
ILLEGAL_ACCESS_SWITCH_SYSTEMThe signature method is unsupported.
ILLEGAL_SWITCH_SYSTEMTarget service is illegal.
EXTERFACE_IS_CLOSEDThe interface name is invalid.

Business errors

Error codeDescription
AGREEMENT_DETAIL_CONFILCT_ERRORThe agreement detail is different from agreement detail in system.
USER_REALNAME_STAUTS_ERRORUser’s realname validation status error.
MERCHANT_AGREEMENT_ERRORMerchant partner’s agreement error.
USER_MOBILE_NOT_MATCH_ERRORThe provided mobile number is inconsistent with the user’s mobile number.
BUSINESS_NOT_SUPPORTED_ERRORThe business case is not supported.
PAY_TOOL_INFO_ERRORPayment tool information error.
USER_NOT_EXSIT_ERRORUser does not exist.
ERROR_RISK_ACCOUNT_FROZENRisk error, the user account is frozen.
ERROR_RISK_ACCOUNT_NOT_BIND_MOBILERisk error, the user account is not bind to a mobile device.
ERROR_RISK_ACCOUNT_STEALRisk error, the user account is stolen.
ERROR_RISK_TWO_PASSWORD_SAMERisk error, the user’s Alipay logon password and payment password are same.
ERROR_RISK_BATCH_REGISTERRisk error, the user is created in a batch job.
ERROR_RISK_BATCH_CERTIFIEDRisk error, the user is certified in a batch job.
ERROR_RISK_BLANCE_PAY_CLOSERisk error, user’s balance payment is closed.
ERROR_RISK_CTU_REFUSERisk error, CTU (Alipay Online Risk Engine) rejects the request.
ILLEGAL_ARGUMENTIllegal argument.
ILLEGAL_SIGNIllegal sign.
ILLEGAL_DYN_MD5_KEYDynamic MD5 key is illegal.
ILLEGAL_ENCRYPTIllegal encrypt.
ILLEGAL_SERVICEWrong service.
ILLEGAL_USERWrong user id.
ILLEGAL_PARTNERWrong partner id.
ILLEGAL_EXTERFACEIllegal external interface config.
ILLEGAL_PARTNER_EXTERFACEIllegal partner external interface config.
ILLEGAL_SECURITY_PROFILEIllegal security profile.
ILLEGAL_SIGN_TYPEIllegal sign type.
ILLEGAL_CHARSETIllegal charset.
ILLEGAL_CLIENT_IPClient IP has no access permission.
HAS_NO_PRIVILEGEHas no privilege.
ILLEGAL_DIGEST_TYPEIllegal digest type.
ILLEGAL_ENCODINGIllegal encoding.
ILLEGAL_SYSTEMIllegal system.
ILLEGAL_REQUEST_REFERERIllegal request referrer. Used for phising attack prevention.

Samples

Request sample

Request example via PC

https://mapi.alipay.com/gateway.do?sign_type=MD5&sign_validity_period=2m&return_url=http%3A%2F%2Fapi.test.alipay.net%2Fatinterface%2Freceive_return.htm&sign=07645be837ab67820d1ef2e2a8c343d5&_input_charset=UTF-8&product_code=GENERAL_WITHHOLDING_P&external_sign_no=e8qdwl9caset5zugii2r7q0k8ikopxor32&service=alipay.dut.customer.agreement.page.sign&scene=INDUSTRY%7CMEDICAL&partner=2088001159940003&access_info=%7B%22channel%22%3A%22PC%22%7D&notify_url=http%3A%2F%2Fapi.test.alipay.net%2Fatinterface%2Freceive_notify.htm

Request example via APP

alipays://platformapi/startapp?appId=20000067&url=https%3A%2F%2Fopenapi.alipaydev.com%2Fgateway.do%3F_input_charset%3DUTF-8%26access_info%3D%7B%22channel%22%3A%22ALIPAYAPP%22%7D%26external_sign_no%3D123456789-1-52188048%26notify_url%3Dhttp%3A%2F%2Fsandbox.hq.agoda.com%2FPaymentNotification-qa%2FAlipayBNPL%2FSaveNotification%26partner%3D2088621880535422%26product_code%3DGENERAL_WITHHOLDING_P%26return_url%3Dhttp%3A%2F%2Fdevto.payment.webservices.agoda.local%2Fpaypal%2FSuccess.aspx%26sales_product_code%3DFOREX_GENERAL_WITHHOLDING%26scene%3DINDUSTRY%7CHOTEL%26service%3Dalipay.dut.customer.agreement.page.sign%26sign%3D2198439006194efadc0cc81501ffeccf%26sign_type%3DMD5

Note:

For how to generate a URL to evoke Allipay Wallet, see How to generate a URL to evoke Allipay Wallet

Response sample

Synchronous response sample

http://merchant.com/alipay/return_url.php?agreement_no=20141020000353099885&external_sign_no=e8qdwl9caset5zugii2r&scene=INDUSTRY|MEDICAL&status=NORMAL&sign_time=2014-10-20+11%3A49%3A19&sign_modify_time=2014-10-20+11%3A49%3A19&invalid_time=2014-12-20+11%3A49%3A19&is_success=T&product_code=GENERAL_WITHHOLDING_P&valid_time=2014-10-20+11%3A49%3A19&sign=5d26b4133e9d56f416c02bb903c161f1&sign_type=MD5&alipay_user_id=2088102145412262

Asynchronous response sample

http://merchant.com/alipay/notify_url.php?notify_time=2014-10-20+11%3A33%3A36&notify_type=dut_user_sign&notify_id=df35c47ed9df1fe4157a555e5c1f4a39&sign_type=MD5&sign=b1af584504b8e845ebe40b8e0e733729&agreement_no=20141020000353099885&product_code=GENERAL_WITHHOLDING_P&scene=INDUSTRY|MEDIA&status=NORMAL&alipay_user_id=2088002008073305&sign_time=2014-10-20+11%3A49%3A19&sign_modify_time=2014-10-20+11%3A49%3A19&valid_time=2014-10-20+11%3A49%3A19&invalid_time=2014-12-20+11%3A49%3A19&partner_id=2088001159912755