网站支付接口
境外收单买家在境外商户网站拍下用外币标价的商品后，选择支付宝方式付款，境外商户系统调用支付宝境外收单支付接入接口，页面跳转到支付宝收银台，支付宝会自动向境外收单买家显示人民币标识的商品报价。
网关URL
| 环境 | HTTPS请求URL |
| 生产环境 | https://intlmapi.alipay.com/gateway.do |
| 测试环境 | https://mapi.alipaydev.com/gateway.do |
请求参数
| 参数 | 类型 (长度是字节) | 描述 | 可选 | 示例 |
| 基本参数 | ||||
| service | String | 接口名称 | 不可空 | create_forex_trade |
| 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) | 商品的简要介绍，特殊字符不支持。备注：本字段的值会在客户支付时被展示给客户。 | 不可空 | 婴儿衣服 |
| body | String(400) | 商品的详细描述，不支持特殊字符。 | 可空 | 婴儿衣服大码 |
| 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小时，最大15天。此为买家登陆到完成支付的有效时间。如果需要使用其他值，请与支付宝技术支持联系。 | 可空 | 5m 10m 15m 30m 1h 2h 3h 5h 10h 12h 1d. |
| order_gmt_create | Date | yyyy-MM-dd HH:mm:ss 这里请使用北京时间以便于和支付宝系统时间匹配，此参数必须要和order_valid_time参数一起使用，控制从跳转到买家登陆的有效时间 | 可空 | |
| order_valid_time | String(5) | 最大值为2592000，单位为秒，此参数必须要和order_gmt_create参数一起使用，控制从跳转到买家登陆的有效时间 | 可空 | 3600 |
| supplier | String(16) | 显示供货商名字 | 可空 | |
| secondary_merchant_id | String(64) | 由支付机构给二级商户分配的唯一ID。 注：机构必填。 | 可空 | A80001 |
| secondary_merchant_name | String(64) | 由支付机构给二级商户分配的唯一名称。 注：机构必填。 | 可空 | Muku |
| secondary_merchant_industry | String(4) | 支付宝分配的二级商户的行业代码，如 公共饮食行业、餐馆：5812 百货公司：5311 住房-旅馆：7011 出租车：4121 注：机构必填。 | 可空 | 7011 |
| refer_url | String(200) | 二级商户的网址。 注：机构必填。 | 不可空 | http://testmerchant.com |
| product_code | String(32) | 网站支付: NEW_OVERSEAS_SELLER | 不可空 | NEW_OVERSEAS_SELLER |
| split_fund_info | String(1 600) | 分账信息，json 格式，具体请参见“分账明细说明” | 可空 | |
| 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的值，应保留小数点后2位数字，例如，100.30 美元。但日本和韩国的货币，应没有小数，就像1000韩元和1000日元。如果传了其他格式的数据系统会返回错误，例如，美元101.999。 - 如果
both order_gmt_create+order_valid_time和timeout_rule都传了，系统会用order_gmt_create+order_valid_time来控制订单过期时间 - 参数
return_url里面不能带有回传参数。如果商家在return_url里面传了参数，支付宝系统会把它去除。
同步返回
| 参数名 | 类型（长度字节） | 描述 | 示例 |
| 基本参数 | |||
| sign_type | String | 签名方式 DSA, RSA, MD5. | RSA |
| sign | String | 签名 | e5815a4556db338ed237f7d3fd222184 |
| 业务参数 | |||
| trade_status | String(32) | 交易状态，固定值为：TRADE_FINISHED。 | 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 |
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 - 随着业务的增长，支付宝可能会添加新的参数（现有参数不会改变）。 进行通知验证时，商家必须使用从支付宝返回的所有参数。
异步通知
除了通过网页重定向的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 |
通知触发条件
Trigger condition name | Description | Note |
TRADE_FINISHED | 交易成功 | true (触发通知) |
WAIT_BUYER_PAY | 交易创建 | false (不触发通知) |
TRADE_CLOSED | 交易关闭 | true (触发通知) |
异步通知示例
https://www.namesilo.com/alipay_ipn.php?notify_id=92c60707dc43a5b2d648b7b4d3c2e1592g¬ify_type=trade_status_sync&sign=***&trade_no=2015063000001000080055080394&total_fee=7.99&out_trade_no=9677726c8757aea6d4df81091811b047¤cy=USD¬ify_time=2015-06-30 09:56:02&trade_status=TRADE_FINISHED&sign_type=MD5
http://www.namesilo.com/alipay_ipn.php?notify_id=0578bc470961e3b43fb676db616711fd2k¬ify_type=trade_status_sync&sign=***&trade_no=2015061700001000100000583330&total_fee=11.00&out_trade_no=2082389608326064¤cy=USD¬ify_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次通知（通知的间隔频率一般是：2m,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¬ify_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 | 接口已关闭 |