请求参数说明

请求参数是商户在与支付宝进行数据交互时，提供给支付宝的请求数据，以便支付宝根据这些数据进一步处理。

参数	参数名称	类型（字节长度）	参数说明	是否可为空	样例
基本参数
service	接口名称	String	接口名称。	不可空	alipay.acquire.customs
partner	合作者身份ID	String(16)	签约的支付宝账号对应的支付宝唯一用户号。 以2088开头的16位纯数字组成。	不可空	2088101142878662
_input_charset	参数编码字符集	String	商户网站使用的编码格式，如utf-8、gbk、gb2312等。	不可空	utf-8
sign_type	签名方式	String	DSA、RSA、MD5三个值可选，必须大写。	不可空	MD5
sign	签名	String	请参见“9  签名机制”。	不可空	2118ac8fad6bc1d9e88a6cd017c18d37
业务参数
out_request_no	报关流水号	String(32)	商户生成的用于唯一标识一次报关操作的业务编号。 建议生成规则：yyyymmmdd型8位日期拼接4位序列号。 该参数长度为6~32位。	不可空	9193457120563834
trade_no	支付宝交易号	String(64)	该交易在支付宝系统中的交易流水号，最长64位。	不可空	2015051446800462000100020003
merchant_customs_code	商户海关备案编号	String(20)	商户在海关备案的编号。	不可空	hanguo
amount	报关金额	String(20)	报关金额，单位为人民币“元”，精确到小数点后2位。 注意： 交易累计的报关金额不得大于交易总金额。	不可空	2
customs_place	海关编号	String(20)	海关编号，参见“10.4  海关编号”，大小写均支持。	不可空	HANGZHOU
merchant_customs_name	商户海关备案名称	String(256)	商户海关备案名称。	不可空	jwyhanguo_card
is_split	是否拆单	String(1)	商户控制本单是否拆单报关。 仅当该参数传值为T或者t时，才会触发拆单（报关海关必须支持拆单）。	可空	T
sub_out_biz_no	子订单号	String(32)	商户子订单号。拆单时由商户传入，且拆单时必须传入，否则会报INVALID_PARAMETER错误码。	可空	2015080811223212345453
buyer_name	订购人姓名	String(10)	订购人姓名。即订购人留在商户处的姓名信息。	可空	王一
buyer_id_no	订购人身份证号	String(18)	订购人身份证号。即订购人留在商户处的身份证信息。	可空	230227198707201827

样例：

https://mapi.alipay.com/gateway.do?trade_no=2015051446800462000100020003&merchant_customs_code=hanguo&sign_type=MD5&merchant_customs_name=jwyhanguo_card&sign=2118ac8fad6bc1d9e88a6cd017c18d37&amount=2&_input_charset=UTF-8&customs_place=HANGZHOU&service=alipay.acquire.customs&out_request_no=9193457120563834&partner=2088101142878662

 

说明：
本样例仅供参考，支付宝网关为https://mapi.alipay.com/gateway.do。

同步返回参数说明

支付宝对商户提供的请求数据进行处理后，返回给商户结果数据，以便商户根据这些数据进一步处理。

返回结果分两种场景，一种为业务正常受理的结果，一种为系统级异常或者接入数据错误。对于业务正常受理，商户需要解析响应码以判断业务是否处理成功。

参数	参数名称	类型（长度范围）	参数说明		是否可为空	样例
基本参数
is_success	请求是否成功	String		请求是否成功。请求成功不代表业务处理成功。 l  T代表成功 l  F代表失败	不可空	T
sign_type	签名方式	String		DSA、RSA、MD5三个值可选，必须大写。	可空	MD5
sign	签名	String		请参见“9  签名机制”。	可空	3afc92ac4708425ab74ecb2c4e58ef56
error	错误代码	String		l  请求成功时，不存在本参数； l  请求失败时，本参数为错误代码，参见“10.2  接入错误码”和“10.3  系统错误码”。	可空	ILLEGAL_SIGN
业务参数
result_code	响应码	String(32)	处理结果响应码。 l  SUCCESS：成功 l  FAIL：失败		不可空	SUCCESS
trade_no	支付单据号	String(64)	支付宝推送到海关的支付单据号。		可空	2013111511001004390000105126
alipay_declare_no	支付宝报关流水号	String(64)	支付宝报关流水号。		可空	2013112611001004680073956707
detail_error_code	详细错误码	String(48)	对返回响应码进行原因说明，请参见“10.1  业务错误码”。 当result_code响应码为SUCCESS时，不返回该参数。		可空	SAME_CUSTOMS_DECLARE_ONCE
detail_error_des	详细错误描述	String(64)	对详细错误码进行文字说明，请参见“10.1  业务错误码”中的“含义”。 当result_code响应码为SUCCESS时，不返回该参数。		可空	同一笔交易同一个海关只能报关一次
identity_check	订购人身份信息和支付人身份信息的验证结果	String(1)	l  T表示商户传入的订购人姓名和身份证号和支付人的姓名和身份证号一致。 l  F代表商户传入的订购人姓名和身份证号和支付人的姓名和身份证号不一致。 对于同一笔报关单支付宝只会校验一次，如果多次重推不会返回此参数。		可空	T
ver_dept	核验机构	String(1)	核验机构标志 1-银联2-网联3-其他			2
pay_code	支付企业的海关注册登记编号	String(18)	支付企业的海关注册登记编号			31222699S7
pay_transaction_id	交易唯一编号	String(32)	交易唯一编号（可在央行认可的机构验证）			20190408234700101010101010101
total_amount	交易总金额(单位:分)	String(17)	实际交易金额			30000
currency	币种	String(13)	实际交易币制（海关编码）			142

说明：
同步返回的参数随支付宝服务端的演化，可能会返回更多的节点，需要程序使用方对文档说明以外的节点予以忽略。

样例：

• 业务正常受理并报关成功返回样例

<?xml version="1.0" encoding="utf-8"?>
<alipay>
    <is_success>T</is_success>
    <request>
        <param name="trade_no">2015051446800462</param>
        <param name="merchant_customs_code">hanguo</param>
        <param name="sign_type">MD5</param>
        <param name="merchant_customs_name">jwyhanguo_card</param>
        <param name="sign">2118ac8fad6bc1d9e88a6cd017c18d37</param>
        <param name="amount">2</param>
        <param name="_input_charset">UTF-8</param>
        <param name="customs_place">HANGZHOU</param>
        <param name="service">alipay.acquire.customs</param>
        <param name="out_request_no">9193457120563834</param>
        <param name="partner">2088101142878662</param>
    </request>
    <response>
        <alipay>
            <result_code>SUCCESS</result_code>
            <trade_no>2013111511001004390000105126</trade_no>
            <alipay_declare_no>2013112611001004680073956707</alipay_declare_no>
        </alipay>
    </response>
    <sign>3afc92ac4708425ab74ecb2c4e58ef56</sign>
    <sign_type>MD5</sign_type>
</alipay>

• 请求成功，业务处理失败返回样例

<?xml version="1.0" encoding="utf-8"?>
<alipay>
    <is_success>T</is_success>
    <request>
        <param name="trade_no">2015051446800462</param>
        <param name="merchant_customs_code">hanguo</param>
        <param name="sign_type">MD5</param>
        <param name="merchant_customs_name">jwyhanguo_card</param>
        <param name="sign">2118ac8fad6bc1d9e88a6cd017c18d37</param>
        <param name="amount">2</param>
        <param name="_input_charset">UTF-8</param>
        <param name="customs_place">HANGZHOU</param>
        <param name="service">alipay.acquire.customs</param>
        <param name="out_request_no">9193457120563834</param>
        <param name="partner">2088101142878662</param>
    </request>
    <response>
        <alipay>
           <detail_error_code>SAME_CUSTOMS_DECLARE_ONCE</detail_error_code>
           <detail_error_des>同一笔交易同一个海关只能报关一次</detail_error_des>
           <result_code>FAIL</result_code>
        </alipay>
    </response>
    <sign>3afc92ac4708425ab74ecb2c4e58ef56</sign>
    <sign_type>MD5</sign_type>
</alipay>

• 请求失败或者接入数据错误时返回样例

<?xml version="1.0" encoding="utf-8"?>
<alipay>
    <is_success>F</is_success>
    <error>ILLEGAL_SIGN</error>
</alipay>

同步返回特性

1. 支付宝处理完商户的请求数据后，当前的支付宝网关页面（https://mapi.alipay.com）会自动刷新，并立刻输出处理结果；
2. 处理一次请求，当前界面只跳转回来一次，即只返回一次处理结果；
3. 该步骤可在本机电脑调试，无需到服务器上；
4. 处理结果显示的格式是XML格式；
5. 可对这个XML格式的处理结果进行XML远程解析，使之能在支付宝处理结果时获取到相关处理结果数据，并对这个结果界面进行商户的业务逻辑处理；
6. 本地电脑或商户服务器的配置上需支持XML远程解析，如：需要支持SSL；
7. 页面跳转后，浏览器地址栏中的链接仅在一分钟内有效，超过一分钟该链接地址会失效，导致该页面中商户编写的业务逻辑程序无法完成处理。

商户业务处理注意事项

当支付宝处理完成后，支付宝会以XML同步返回数据的形式，把数据反馈给商户网站。商户可以利用编程方法来模拟http请求远程解析XML获得处理的结果数据，增加商户的业务逻辑处理程序。此时，商户必须判断商户网站中是否已经对该次的结果数据做过同样处理。如果不判断，存在潜在的风险，商户自行承担因此而产生的所有损失。

重推功能说明

报关接口支持重推、修改功能。如果某笔交易已请求报送海关，但电子口岸丢单；或如果某笔交易已请求报送海关，但商户备案号、备案名称、海关编码填错，都可以使用重推修改功能，重新向海关推送。重推时，需要保持报关流水号out_request_no和原始请求一致，否则认为是一条新请求。重推修改只能对商户备案号、备案名称、海关编码和金额做修改。重推金额不重复计入报关总金额。

重推的前提条件

1. 商户已向支付宝请求推送过同一个报关流水号(out_request_no)所标识的报关单；
2. 距离上一次推送已超过至少5分钟（支付宝可能根据实际运行情况调整此时间值）；
3. 本次拟推送的信息与上次推送完全一致，或除以下字段之外的其他字段完全一致：
   a)商户海关备案编号(merchant_customs_code)
   b)商户海关备案名称(merchant_customs_name)
   c)海关编号(customs_place)
   d)报关金额(amount)
   e)子订单号(sub_out_biz_no)
4. 目标海关支持重推：
   南沙国检不支持重推覆盖，如需要修改已入库的支付单，需要线下联系南沙国检。如果支付单未入库，请联系支付宝技术支持手工重推；
5. 如果报关金额(amount)变更了，新计算出的总报关金额不可超过原交易总金额。

重推的响应结果

1. 不满足重推条件且无字段变更，返回幂等成功；
2. 不满足重推条件但有字段变更，返回CONTEXT_INCONSISTENT错误码或其他业务错误码；
3. 满足重推条件，成功重推，返回值与首次推送成功的结果一致。

统一版各属地报关方案

2017年起，针对海关总署推行的统一版报文，目前大部分属地仅报送ZONGSHU或者仅报送属地即可，商户可在海关编号表中查看对应海关的统一版报送方案。当商户向天津、河南报送统一版支付单时请特别注意，需要同时报送支付单到总署系统和属地的国检系统。

天津、河南的统一版推送方法：天津、河南的支付单需要同时报往地方平台和总署。

当支付单不使用拆单功能，即is_split参数不为T或不传入is_split参数时：

1. 先推送属地，再用新的报关流水号(out_request_no)推送ZONGSHU
2. 两次推送除以下字段外，其余业务字段请保持不变，以免国检匹配失败：
   a) 海关编号(customs_place)
   b) 商户海关备案编号(merchant_customs_code)
   c) 商户海关备案名称(merchant_customs_name)

当支付单使用拆单功能，即is_split=T时：

1. 先推送属地，5分钟后再用同一个报关流水号(out_request_no)重推ZONGSHU
2. 重推时，除以下字段外，其余业务字段请保持不变，以免国检匹配失败：
   a) 海关编号(customs_place)
   b) 商户海关备案编号(merchant_customs_code)
   c) 商户海关备案名称(merchant_customs_name)

海关编号

支付宝备案名称：支付宝(中国)网络技术有限公司

海关名称	统一版各属地报关方案	海关编码	支付宝备案号
总署	直连总署	zongshu	31222699S7
河南保税物流中心	推送zhengzhou	zhengzhou	31222699S7
宁波海关	推送ningbo	ningbo	31222699S7
新郑综合保税区（空港）	先推送henan，再推送zongshu	henan	P460400005
天津海关	先推送tianjin，再推送zongshu	tianjin	Q12150016000019
南沙国检	推送nanshagj	nanshagj	1500004292
上海海关	推送shanghai_cbt	shanghai_cbt	31222699S7
广州海关（机场）	推送广州机场国检，备案信息需要传企业在广电的备案信息	guangzhou_airport	C000010000416158
广州海关（南沙）	推送广州南沙国检，备案信息需要传企业在广电的备案信息	guangzhou_nansha	C000010000416158
广州海关（黄埔）	推送广州黄埔国检，备案信息需要传企业在广电的备案信息	guangzhou_huangpu	C000010000416158
广州海关（沙田）	推送广州沙田国检，备案信息需要传企业在广电的备案信息	guangzhou_shatian	C000010000416158
杭州海关	推送hangzhou_zongshu	hangzhou_zongshu	ZF14021901

业务错误码

详细错误代码（detail_error_code）	含义（detail_error_des）	场景描述	解决方案
TRADE_NOT_EXIST	交易不存在	传入的trade_no错误，查询不到交易号	请检查trade_no参数是否正确
TRADE_STATUS_ERROR	交易状态不合法，不允许报关	交易当前状态不允许报关，如交易尚未支付成功或交易已经全额退款	请确认交易状态
INVALID_PARAMETER	参数不合法	参数格式不合法，如超长或者非空的参数未传等	请根据接口文档检查参数格式
CONTEXT_INCONSISTENT	同一笔请求参数不一致	同一个请求号，多次请求，但参数不一致	请核实参数
SAME_CUSTOMS_DECLARE_ONCE	同一笔交易同一个海关只能报关一次	同一笔交易在同一个海关只能报关一次，不能多次报关	请确认该笔交易在当前海关是否已经报关
REQUEST_AMOUNT_EXCEED	金额超限	累计报关金额超过交易金额	请确认该笔交易累计的报关金额
PARTNER_ERROR	交易partner跟报关请求partner不一致	交易的partner跟报关请求的partner不一致	请确认当前报关请求的partner是否跟交易的partner一致
PAYER_ENABLE_STATUS_FORBID	报关交易支付人状态非法	报关时报关的交易中的支付人状态校验不通过	请确认交易中的支付人在支付宝中当前的账户状态

FAQ

关于此文档暂时还没有FAQ