手机网站支付接口

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


#网关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_feermb_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_typesign)都参与验签,而不是只对上表中的参数参与验签。

#异步通知校验

为了系统的健康,支付宝建议校验异步通知。商家只能校验过去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接口已关闭