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

手机网站支付接口

境外收单买家在境外商户网站拍下用外币标价的商品后，选择支付宝方式付款，境外商户系统调用支付宝境外收单支付接入接口，页面跳转到支付宝收银台，支付宝会自动向境外收单买家显示人民币标识的商品报价。

网关URL

环境HTTPS请求URL
生产环境https://intlmapi.alipay.com/gateway.do
测试环境https://mapi.alipaydev.com/gateway.do

请求参数

参数类型 (长度是字节)描述是否可空示例
基本参数
serviceString接口名称

不可空

create_forex_trade_wap
partnerString(16)境外商户在支付宝的用户ID. 2088开头的16位数字

不可空

2088001159940003
_input_charsetString请求数据的编码集，支持UTF-8。

不可空

UTF-8
sign_typeString签名算法 
DSA, RSA, and MD5.

不可空

RSA
signString签名值

不可空

e5815a4556db338ed237f7d3fd222184
notify_urlURL(200)针对该交易支付成功之后的通知接收URL。

可空

return_urlURL(200)交易付款成功之后，返回到商家网站的URL。

可空

业务参数
subject    String(255)商品的标题/交易标题/订单标题/订单关键字或简要介绍等。该参数最长为128个汉字。特殊字符不支持。备注：本字段的值会在客户支付时被展示给客户。

不可空

婴儿衣服
bodyString(400)对一笔交易的具体描述信息。如果是多种商品，请将商品描述字符串累加传给body。特殊字符不支持。

可空

大码婴儿服
out_trade_noString(64)境外商户交易号（确保在境外商户系统中唯一）

不可空

Test123
currencyString(10)结算币种

不可空

USD
total_feeNumber(8,2)商品的外币金额，范围是0.01～1000000.00.

可空

100.30
rmb_feeNumber(8,2)范围为0.01～1000000.00
如果商户网站使用人民币进行标价就是用这个参数来替换total_fee参数，rmb_fee和total_fee不能同时使用

可空

100.30
timeout_ruleString(10)

此为买家登陆到完成支付的有效时间。

注：本字段在这个接口下传值必须与order_create参数结合使用才可对订单超时时间起到控制作用，本字段取值可在1m-15d之间。如果需要其它值，请联系技术支持团队进行设置。

可空

5m 10m 15m 30m 1h 2h 3h 5h 10h 12h 1d 3d 7d 15d.

order_create

long(10)交易创建付款时间。此参数必须要和timeout_rule参数一起使用，控制交易有效期。时间以毫秒计，此参数的值由Java方法System.currentTimeMillis()获得，从epoch(1970年1月1日00:00:00 GMT)开始计算。这里请使用北京时间以便于和支付宝系统时间匹配。

可空

1586497520310

supplier   String(16)显示供货商名字

可空

 
refer_urlString(200)

商户网站主页网址。如果商户没有网站，本字段可填商户应用程序下载地址。

注：商户必填。

不可空

www.secondarymerchantDOMAIN.com
product_codeString(32)支付宝产品代号。您使用的支付宝产品代号为
NEW_WAP_OVERSEAS_SELLER

不可空

NEW_WAP_OVERSEAS_SELLER
split_fund_infoString(1 600)分账信息，json 格式，具体请参见“分账明细说明”

可空

 
app_payString(1)这个参数用来标记该笔支付是否唤起支付宝钱包来进行支付。如果支付宝钱包没有安装，则使用wap方式支付。

可空

app_pay=Y
secondary_merchant_idString(64)由支付机构给二级商户分配的唯一ID。
注：机构必填。

可空

A80001
secondary_merchant_nameString(128)由支付机构给二级商户分配的唯一名称。
注：机构必填。

可空

Muku
secondary_merchant_industryString(4)支付宝分配的二级商户的行业代码，如
公共饮食行业、餐馆：5812
百货公司：5311
住房-旅馆：7011
出租车：4121
注：机构必填。

可空

7011
trade_informationString(6000)交易信息, 详情参见trade_information

不可空

{"business_type":"1","hotel_name":"zlidu, sluhg-987, 889utng","check_in_time":"2018-10-20","check_out_time":"2018-10-22"}

trade_information

参数类型 (长度是字节)描述是否可空示例
business_typeString业务类型。该字段仅支持以下5类入参：
1: 酒店
2: 航空
3: 留学
4: 贸易
5: 其他, 包含所有不属于前四类的其他业务类型。例如，流量充值，机场接机服务等。
若业务类型超过一种，则传入多个且用竖线(|)分隔。		不可空1|2|3|4|5
or
1
hotel_nameString酒店名称，仅支持数字，字母，空格，及,.<>()[]/\-等特殊字符。若存在多个酒店名称，则传入多个且用竖线(|)分隔。备注：仅在business_type字段值为1时，本字段为必填。不可空zlidu, sluhg-987, 889utng
check_in_timeDate入住酒店时间，格式为yyyy-MM-dd。 时区: GMT +8. 备注：仅在business_type字段值为1时，本字段为必填。不可空2018-10-20
check_out_timeDate离开酒店时间。格式: yyyy-MM-dd。时区: GMT +8。备注：仅在business_type字段值为1时，本字段为必填。不可空2018-10-22
flight_numberString飞机乘客对应的飞机航班号，如存在转机场景，则传入多个且用竖线(|)分隔。备注：仅在business_type字段值为2时，本字段为必填。不可空NWS 996|TWF 8854
departure_timeDate起飞时间
格式: yyyy-MM-dd HH:mm
Timezone: GMT +8. 如存在转机场景，则传入多个且用竖线(|)分隔。备注：仅在business_type字段值为2时，本字段为必填		不可空2018-10-22 20:49
admission_notice_urlString学生的留学录取通知书图片链接。备注：仅在business_type字段值为3时，本字段为必填。不可空https://www.iconfont.cn/search/index?test
goods_infoString商品信息，包含商品的SKU名和相应的数量，格式为 SKU_名^数量。若存在超过一件商品，用竖线(|)分隔。备注：仅在business_type字段值为4时，本字段为必填。不可空pencil^2|eraser^5|iPhone XS 256G^1
total_quantityNumber一个订单中的商品总量。备注：仅在business_type字段值为4时，本字段为必填。不可空8
other_business_typeString如果business_type字段值为5（其他），请务必在此字段写明具体从事的行业类型。不可空机场接机服务

Note:

  • 如果商家希望其产品标价为人民币，商家可以使用参数“rmb_fee”人民币付款金额。此时，参数“total_fee”应被忽略。付款金额将显示成人民币给用户。
    • 商家不应改变参数“currency”的值，这是支付宝支付商户的结算货币.
    • 参数“total_fee” 和“rmb_fee”只能使用一个
  • 外币金额和人民币金额的值（如total_fee和rmb_fee的值）必须精确到小数点后两位。如100 USD。 其它格式将导致报错，如100.999 USD. 但当外币金额单位是JPY时，金额必须是整数，如100 JPY。
  • 参数“return_url”里面不能带有回传参数。如果商家在“return_url”里面传了参数，支付宝系统会把它去除。

同步返回

参数名类型（长度字节）描述示例
基本参数
sign_typeString签名方式 
DSA, RSA, MD5.		RSA
signString签名e5815a4556db338ed237f7d3fd222184
业务参数
trade_statusString(32)交易状态TRADE_FINISHED
trade_noString(64)支付宝交易号。最短16位，最长64位2015070800001000100080029361
out_trade_noString(64)境外商户交易号（确保在境外商户系统中唯一）2525759240575424
currencyString(3)结算币种.USD
total_feeNumber(8,2)商品的外币金额，范围是0.01～1000000.00.11.00
rmb_feeNumber(8,2)如果请求时传入了rmb_fee，同步返回中也会有这个参数。11.00

 Note:

  • 买家在支付成功后会看到一个支付宝提示交易成功的页面，该页面会停留几秒，然后会自动跳转回商户指定的同步通知页面（参数return_url）。
  • 该页面中获得参数的方式，需要使用GET方式获取，如request.QueryString("out_trade_no")、$_GET['out_trade_no']。
  • 该方式仅仅在买家付款完成以后进行自动跳转，因此只会进行一次。
  • 该方式不是支付宝主动去调用商户页面，而是支付宝的程序利用页面自动跳转的函数，使用户的当前页面自动跳转。
  • 该方式可在本机而不是只能在服务器上进行调试。
  • 返回URL只有一分钟的有效期，超过一分钟该链接地址会失效，验证则会失败。
  • 设置页面跳转同步通知页面（return_url）的路径时，不要在页面文件的后面再加上自定义参数。例如：
    错误的写法：http://www.alipay.com/alipay/return_url.php?xx=11
    正确的写法：http://www.alipay.com/alipay/return_url.php
  • 由于支付宝会对页面跳转同步通知页面（return_url）的域名进行合法有效性校验，因此设置页面跳转同步通知页面（return_url）的路径时，不要设置成本机域名，也不能带有特殊字符（如“!”），如：
  • 错误的写法：
    http://localhost/alipay/return_url.php
    http://localhost:80/alipay/return_url.php
    http://商户自定义地址/alipay/return!url.do
  • 正确的写法：
    能够正常访问的域名地址：http://商户自定义地址/alipay/return_url.php
    能够正常访问的IP地址：http://121.1.1.255/alipay/return_url.php
  • 随着业务的增长，支付宝可能会添加新的参数（现有参数不会改变）。 进行通知验证时，商家必须使用从支付宝返回的所有参数。

示例

请求示例

https://mapi.alipaydev.com/gateway.do?subject=Beautylish+Order+%23TESTING+-+CHANGE+ME&sign_type=RSA&out_trade_no=8315919735609649&currency=USD&total_fee=100&partner=2088101122136241&notify_url=http%3A%2F%2Fwww.alipay.com&sendFormat=normal&return_url=http%3A%2F%2Fwww.alipay.com&sign=Rbn7JXjgG%2BWt%2FHK8ej1oov8OTDrI7rxH%2FQmfNJ%2FyASGuayUVvD3NkoP0mLo5rmRNF8qNrzH0lQ68U0EFcU4Z6pCVavHI%2BML3lNUagkFQ3YcS6f9pY1WoyEUt02%2FC2VyzxiEDTM%2FS6o6YiDZaUUdS2EPTHPBgvJLvghcafyMKTIo%3D&_input_charset=UTF-8&secondary_merchant_id=834945&secondary_merchant_industry=3435&secondary_merchant_name=holiday&service=create_forex_trade_wap&trade_information={"business_type":"1","hotel_name":"zlidu, sluhg-987, 889utng","check_in_time":"2018-10-20","check_out_time":"2018-10-22"}

返回示例

http://api.receive.com/receive_notify.htm?sign=6c1fd40533ccb5126aa78778ab10417a&trade_no=2015070800001000100080029361&total_fee=11.00&sign_type=MD5&out_trade_no=2525759240575424&trade_status=TRADE_FINISHED&currency=USD

异步通知

除了通过网页重定向的API响应，API响应也可以以异步POST方法发送给合作伙伴，如果商家在请求中设置了参数“notify_url”并且目标URL会处理异步通知。这种支付解决方案必须处理异步通知。 

支付宝会在25小时内自动重复多次发送异步通知直到商家服务器回复“success”消息在响应中。 

在处理同步返回和异步通知的时候，需要考虑下面几个方面：

  • 异步通知可能比同步返回先到达
  • 重复的异步通知消息

异步通知返回参数

参数名类型（长度字节）描述示例
基本参数
sign_typeString签名方式 
DSA, RSA, MD5.		RSA
signString签名e5815a4556db338ed237f7d3fd222184
业务参数
notify_typeString通知类型, value： trade_status_sync.trade_status_sync
notify_idString(34)支付宝通知流水号，境外商户可以用这个流水号询问支付宝该条通知的合法性92c60707dc43a5b2d648b7b4d3c2e1592g
notify_timeTimestamp通知时间（支付宝时间），格式：yyyy-MM-dd HH:mm:ss2015-06-30 09:56:02
trade_statusString(32)交易状态: 
TRADE_FINISHED
TRADE_CLOSED		TRADE_FINISHED
trade_noString(64)支付宝交易号。最短16位，最长64位2015070800001000100080029361
out_trade_noString(64)境外商户交易号（确保在境外商户系统中唯一）2525759240575424
currencyString(3)结算币种.USD
total_feeNumber(8,2)商品的外币金额，范围是0.01～1000000.00.11.00

异步通知示例

https://www.namesilo.com/alipay_ipn.php?notify_id=92c60707dc43a5b2d648b7b4d3c2e1592g&notify_type=trade_status_sync&sign=xxx&trade_no=2015063000001000080055080394&total_fee=7.99&out_trade_no=9677726c8757aea6d4df81091811b047&currency=USD&notify_time=2015-06-30 09:56:02&trade_status=TRADE_FINISHED&sign_type=MD5

http://www.namesilo.com/alipay_ipn.php?notify_id=0578bc470961e3b43fb676db616711fd2k&notify_type=trade_status_sync&sign=xxx&trade_no=2015061700001000100000583330&total_fee=11.00&out_trade_no=2082389608326064&currency=USD&notify_time=2015-06-17+02%3A37%3A02&trade_status=TRADE_CLOSED&sign_type=RSA

 Note:

  • 必须保证服务器异步通知页面（notify_url）上无任何字符，如空格、HTML标签、开发系统自带抛出的异常提示信息等.
  • 支付宝是用POST方式发送通知信息，因此该页面中获取参数的方式，如：
    request.Form("out_trade_no")、$_POST['out_trade_no']；
  • 支付宝主动发起通知，该方式才会被启用；
  • 只有在支付宝的交易管理中存在该笔交易，且发生了交易状态的改变，支付宝才会通过该方式发起服务器通知（即时到账中交易状态为“等待买家付款”的状态默认是不会发送通知的）；
  • 服务器间的交互，不像页面跳转同步通知可以在页面上显示出来，这种交互方式是不可见的；
  • 第一次交易状态改变（即时到账中此时交易状态是交易完成）时，不仅页面跳转同步通知页面会启用，而且服务器异步通知页面也会收到支付宝发来的处理结果通知；
  • 程序执行完后必须打印输出“success”（不包含引号）。如果商户反馈给支付宝的字符不是success这7个字符，支付宝服务器会不断重发通知，直到超过24小时22分钟。
    一般情况下，25小时以内完成8次通知（通知的间隔频率一般是：4m,10m,10m,1h,2h,6h,15h）；
  • 程序执行完成后，该页面不能执行页面跳转。如果执行页面跳转，支付宝会收不到success字符，会被支付宝服务器判定为该页面程序运行出现异常，而重发处理结果通知；
  • cookies、session等在此页面会失效，即无法获取这些数据；
  • 该方式的调试与运行必须在服务器上，即互联网上能访问；
  • 该方式的作用主要防止订单丢失，即页面跳转同步通知没有处理订单更新，它则去处理；
  • 当商户收到服务器异步通知并打印出success时，服务器异步通知参数notify_id才会失效。也就是说在支付宝发送同一条异步通知时（包含商户并未成功打印出success导致支付宝重发数次通知），服务器异步通知参数notify_id是不变的。
  • 商户与支付宝约定后，异步通知可能会返回更多的参数信息。随着业务的发展，异步通知也可能有新的参数信息返回，商户在收到异步通知后，需要对支付宝所有的返回参数(除了sign_type和sign)都参与验签，而不是只对上表中的参数参与验签。

异步通知校验

为了系统的健康，支付宝建议校验异步通知。商家只能校验过去1分钟之内的异步通知消息，并且在商家服务器返回‘success’消息之前。 

示例:

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

错误码

基本上API接口的调用的检查是在支付宝的2个级别进行的。 

第一个级别是在支付宝网关。在这里会进行一些基础的校验，如签名，商家ID是否有效或者是否有权限使用某个接口等。如果校验失败，就会返回相应的错误码，归类在下面的网关错误中。 

一旦网关校验通过了，接口请求就会被转发到内部系统进行进一步的处理。 这里会进行业务逻辑的校验。如果校验失败，就会返回相应的错误码，归类在业务错误代码中。

业务错误码

错误代码含义
FOREX_MERCHANT_NOT_SUPPORT_THIS_CURRENCY不支持该币种
ILLEGAL_SECURITY_PROFILE不支持该加密方式
REPEAT_OUT_TRADE_NO外部交易号重复
ILLEGAL_CURRENCY币种参数不正确
ILLEGAL_TIMEOUT_RULE超时参数不正确
SYSTEM_EXCEPTION支付宝系统错误
ILLEGAL_ARGUMENT参数不正确

网关错误

如果请求参数里面有错误，支付宝网关会报错。整个流程还是在支付宝这端而不会返回到商户端。

错误代码含义
ILLEGAL_SIGN签名错误
ILLEGAL_SERVICE接口参数不正确
ILLEGAL_PARTNER商户PID不对
ILLEGAL_SIGN_TYPE签名方法错误
ILLEGAL_PARTNER_EXTERFACE商家无权使用该接口
ILLEGAL_DYN_MD5_KEY动态密钥信息错误
ILLEGAL_ENCRYPT加密不正确
ILLEGAL_USER用户ID不正确
ILLEGAL_EXTERFACE接口配置错误
ILLEGAL_AGENT代理商不正确
HAS_NO_PRIVILEGE无权访问
INVALID_CHARACTER_SET字符集不正确

系统错误

当出现系统错误提示时，请联系支付宝技术支持协助处理

错误代码含义
SYSTEM_ERROR支付宝系统错误
SESSION_TIMEOUTSession 超时
ILLEGAL_TARGET_SERVICE错误的target_service
ILLEGAL_ACCESS_SWITCH_SYSTEMpartner不允许访问该类型的系统
EXTERFACE_IS_CLOSED接口已关闭