手机网站支付接口

2020-11-09 09:09

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

#网关URL

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

#请求参数

参数	类型 (长度是字节)	描述	是否可空	示例
基本参数
service	String	接口名称	不可空	create_forex_trade_wap
partner	String(16)	境外商户在支付宝的用户ID. 2088开头的16位数字	不可空	2088001159940003
_input_charset	String	请求数据的编码集，支持UTF-8。	不可空	UTF-8
sign_type	String	签名算法 DSA, RSA, and MD5.	不可空	RSA
sign	String	签名值	不可空	e5815a4556db338ed237f7d3fd222184
notify_url	URL(200)	针对该交易支付成功之后的通知接收URL。	可空
return_url	URL(200)	交易付款成功之后，返回到商家网站的URL。	可空
业务参数
subject	String(255)	商品的标题/交易标题/订单标题/订单关键字或简要介绍等。该参数最长为128个汉字。特殊字符不支持。备注：本字段的值会在客户支付时被展示给客户。	不可空	婴儿衣服
body	String(400)	对一笔交易的具体描述信息。如果是多种商品，请将商品描述字符串累加传给body。特殊字符不支持。	可空	大码婴儿服
out_trade_no	String(64)	境外商户交易号（确保在境外商户系统中唯一）	不可空	Test123
currency	String(10)	结算币种	不可空	USD
total_fee	Number(8,2)	商品的外币金额，范围是0.01～1000000.00.	可空	100.30
rmb_fee	Number(8,2)	范围为0.01～1000000.00 如果商户网站使用人民币进行标价就是用这个参数来替换total_fee参数，rmb_fee和total_fee不能同时使用	可空	100.30
timeout_rule	String(10)	此为买家登陆到完成支付的有效时间。默认12小时，如果需要其它值，请联系技术支持团队进行设置。	可空	5m 10m 15m 30m 1h 2h 3h 5h 10h 12h 1d.
order_create	long(10)	交易创建付款时间。此参数必须要和timeout_rule参数一起使用，控制交易有效期。时间以毫秒计，此参数的值由Java方法System.currentTimeMillis()获得，从epoch(1970年1月1日00:00:00 GMT)开始计算。这里请使用北京时间以便于和支付宝系统时间匹配。	可空	1586497520310
supplier	String(16)	显示供货商名字	可空
refer_url	String(200)	商户网站主页网址。如果商户没有网站，本字段可填商户应用程序下载地址。注：商户必填。	不可空	www.secondarymerchantDOMAIN.com
product_code	String(32)	支付宝产品代号。您使用的支付宝产品代号为 NEW_WAP_OVERSEAS_SELLER	不可空	NEW_WAP_OVERSEAS_SELLER
split_fund_info	String(1 600)	分账信息，json 格式，具体请参见“分账明细说明”	可空
app_pay	String(1)	这个参数用来标记该笔支付是否唤起支付宝钱包来进行支付。如果支付宝钱包没有安装，则使用wap方式支付。	可空	app_pay=Y
secondary_merchant_id	String(64)	由支付机构给二级商户分配的唯一ID。注：机构必填。	可空	A80001
secondary_merchant_name	String(128)	由支付机构给二级商户分配的唯一名称。注：机构必填。	可空	Muku
secondary_merchant_industry	String(4)	支付宝分配的二级商户的行业代码，如公共饮食行业、餐馆：5812 百货公司：5311 住房-旅馆：7011 出租车：4121 注：机构必填。	可空	7011
trade_information	String(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_type	String	业务类型。该字段仅支持以下5类入参： 1: 酒店 2: 航空 3: 留学 4: 贸易 5: 其他, 包含所有不属于前四类的其他业务类型。例如，流量充值，机场接机服务等。若业务类型超过一种，则传入多个且用竖线(\|)分隔。	不可空	1\|2\|3\|4\|5 or 1
hotel_name	String	酒店名称，仅支持数字，字母，空格，及,.<>()[]/\-等特殊字符。若存在多个酒店名称，则传入多个且用竖线(\|)分隔。备注：仅在business_type字段值为1时，本字段为必填。	不可空	zlidu, sluhg-987, 889utng
check_in_time	Date	入住酒店时间，格式为yyyy-MM-dd。时区: GMT +8. 备注：仅在business_type字段值为1时，本字段为必填。	不可空	2018-10-20
check_out_time	Date	离开酒店时间。格式: yyyy-MM-dd。时区: GMT +8。备注：仅在business_type字段值为1时，本字段为必填。	不可空	2018-10-22
flight_number	String	飞机乘客对应的飞机航班号，如存在转机场景，则传入多个且用竖线(\|)分隔。备注：仅在business_type字段值为2时，本字段为必填。	不可空	NWS 996\|TWF 8854
departure_time	Date	起飞时间格式: yyyy-MM-dd HH:mm Timezone: GMT +8. 如存在转机场景，则传入多个且用竖线(\|)分隔。备注：仅在business_type字段值为2时，本字段为必填	不可空	2018-10-22 20:49
admission_notice_url	String	学生的留学录取通知书图片链接。备注：仅在business_type字段值为3时，本字段为必填。	不可空	https://www.iconfont.cn/search/index?test
goods_info	String	商品信息，包含商品的SKU名和相应的数量，格式为 SKU_名^数量。若存在超过一件商品，用竖线(\|)分隔。备注：仅在business_type字段值为4时，本字段为必填。	不可空	pencil^2\|eraser^5\|iPhone XS 256G^1
total_quantity	Number	一个订单中的商品总量。备注：仅在business_type字段值为4时，本字段为必填。	不可空	8
other_business_type	String	如果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_type	String	签名方式 DSA, RSA, MD5.	RSA
sign	String	签名	e5815a4556db338ed237f7d3fd222184
业务参数
trade_status	String(32)	交易状态	TRADE_FINISHED
trade_no	String(64)	支付宝交易号。最短16位，最长64位	2015070800001000100080029361
out_trade_no	String(64)	境外商户交易号（确保在境外商户系统中唯一）	2525759240575424
currency	String(3)	结算币种.	USD
total_fee	Number(8,2)	商品的外币金额，范围是0.01～1000000.00.	11.00
rmb_fee	Number(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_type	String	签名方式 DSA, RSA, MD5.	RSA
sign	String	签名	e5815a4556db338ed237f7d3fd222184
业务参数
notify_type	String	通知类型, value： trade_status_sync.	trade_status_sync
notify_id	String(34)	支付宝通知流水号，境外商户可以用这个流水号询问支付宝该条通知的合法性	92c60707dc43a5b2d648b7b4d3c2e1592g
notify_time	Timestamp	通知时间（支付宝时间），格式：yyyy-MM-dd HH:mm:ss	2015-06-30 09:56:02
trade_status	String(32)	交易状态: TRADE_FINISHED TRADE_CLOSED	TRADE_FINISHED
trade_no	String(64)	支付宝交易号。最短16位，最长64位	2015070800001000100080029361
out_trade_no	String(64)	境外商户交易号（确保在境外商户系统中唯一）	2525759240575424
currency	String(3)	结算币种.	USD
total_fee	Number(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_TIMEOUT	Session 超时
ILLEGAL_TARGET_SERVICE	错误的target_service
ILLEGAL_ACCESS_SWITCH_SYSTEM	partner不允许访问该类型的系统
EXTERFACE_IS_CLOSED	接口已关闭