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

      线下二级商户报备接口（条码支付）

      调用此接口可将线下支付的二级商户信息报备到支付宝系统中。您也可以通过此接口更新已报备的二级商户信息。


      #网关URL


      #请求参数

      参数描述
      基本参数

      service

      String 不可空

      接口名称

      示例:alipay.overseas.secmerchant.offline.maintain

      partner

      String(16) 不可空

      支付宝分配的用于标识支付宝帐户的合作伙伴ID。合作伙伴ID是2088开头的16位数字。

      示例:2088*********662

      _input_charset

      String 不可空

      请求数据的编码集。支持UTF-8，GBK和GB2312。

      示例:UTF-8

      sign_type

      String 不可空

      签名类型。支持RSA，RSA2和MD5。请使用大写形式。

      示例:MD5

      sign

      String 不可空

      签名值

      示例:2118ac8fad6bc1d9e88a6cd017c18d37

      timestamp

      String 不可空

      商户服务器发出请求的北京时间，格式为yyyy-MM-dd HH:mm:ss。默认情况下，请求会在30分钟后过期。

      示例:2012-12-21 17:11:16

      业务参数（针对收单机构及系统集成商）

      secondary_merchant_name

      String(128) 不可空

      二级商户的法定注册名称，将显示在钱包和对账文件中，用于标识二级商户。

      注意：如果二级商户类型为个人，请在此字段中填写个体负责人的法定全名。

      示例:Alipay (China) Network Technology Co., Ltd

      secondary_merchant_id

      String(64) 不可空

      合作伙伴分配的用于标识二级商户的唯一ID。ID可以包含字母、数字和下划线。

      示例:63472327348

      store_id

      String(64) 不可空

      合作伙伴分配的用于标识二级商户商店的唯一ID。对于出租车和豪华轿车（MCC 4121），请填写车牌号。

      示例:23372327348

      store_name

      String(256) 不可空

      商店名称。对于出租车和豪华轿车（MCC 4121），请填写车牌号。

      示例:Apple store

      store_country

      String(2) 不可空

      商店注册国家或地区，请使用ISO 3166中定义的两个字母的国家或地区代码。

      示例:HK

      store_address

      String(330) 不可空

      报备的商店地址。请使用邮政地址格式。

      示例:No.276, Road YinCheng, Shanghai

      store_industry

      String(4) 不可空

      商店的4位MCC代码。关于MCC代码，详情参见MCC list。

      示例:4121

      internal_store_photo

      String(256)

      商店内部照片的URL

      示例:http://testmerchant.com/

      external_storefront_photo

      String(256)

      商店外部照片的URL

      示例:URL

      extend_params

      String(1024)

      关于出租车司机的信息，格式为JSON，固定的键为operation_id, contact_way和contact_person。如果您是首次报备一位司机并在store_industry参数填写4121，则必须提供此参数，否则将返回错误码CATEGORY_NOT_SUPPORT_DRIVER。详情参见extend_params.

      注意：

      • 每个operation_id的值必须是唯一的。
      • 一旦报备了某位司机，此字段信息不支持更新。
      • 此参数最多可输入10位司机的信息。

      示例:[{"operation_id": "1000332", "contact_way": "138xxxx1232", "contact_person": "driverName1"}, {"operation_id": "1082943492", "contact_way": "158xxxx2232", "contact_person": "driverName2"}]

      业务参数（仅针对收单机构）

      secondary_merchant_type

      String 不可空

      二级商户类型，可填入的值如下：

      • INDIVIDUAL: 个人独资或个体户
      • ENTERPRISE: 有限公司、私人公司、合伙企业、有限责任合伙企业（LLP）、有限责任公司（LLC）、S类公司（S Corp）、C类公司（C Corp）、信托或非营利组织（NPO）

      示例:INDIVIDUAL

      registration_no

      String(128)

      商业注册文件上指定的商业登记号

      注意：当二级商户类型是INDIVIDUAL且没有登记号时，不需要填写此字段。

      示例:012345678

      register_country

      String(2) 不可空

      商店注册国家或地区，请使用ISO 3166中定义的两个字母的国家或地区代码。

      示例:HK

      register_address

      String(256)

      商业注册文件上指定的商业登记地址。使用邮政地址格式。

      示例:No.277, Road YinCheng, Shanghai, China

      shareholder_name

      String(64)

      二级商户主要股东的法定名称。仅当二级商户类型为ENTERPRISE时需填写此字段。

      示例:Jack Li (股东为个人), Alipay.com Co.,Ltd (股东为企业)

      shareholder_id

      String(128)

      二级商户主要股东的身份证号、护照号码或商业登记号码。仅当二级商户类型为ENTERPRISE时需填写此字段。

      示例:G53453888 (股东为个人), 012345678 (股东为企业)

      representative_name

      String(64)

      个体负责人的法定全名。仅当二级商户类型为INDIVIDUAL时指定此字段。如果二级商户类型为ENTERPRISE，则此字段非必填。

      示例:Tom Li

      representative_id

      String(128)

      个体负责人的身份证或护照号码。仅当二级商户类型为INDIVIDUAL时指定此字段。如果二级商户类型为ENTERPRISE，则此字段非必填。

      示例:123456789

      settlement_no

      String(64)

      二级商户的结算银行账号，仅支持字母和数字。

      示例:2600100000

      contact_no

      String(64)

      二级商户联系电话，仅支持数字及特殊字符+-()

      示例:186xxxx0000

      contact_email

      String(128)

      二级商户联系邮箱

      示例:tomli@gmail.com

      cs_no

      String(64)

      二级商户客服电话，仅支持数字及特殊字符+-()

      示例:952xx

      cs_email

      String(128)

      二级商户客服邮箱

      示例:customerservice@xxxcompany.com


      #extend_params

      当store_industry的值为4121时，必须填写extend_params字段的值。

      extend_params字段用于填写JSON格式的出租司机信息，JSON的键为operation_id, contact_way和 contact_person。此字段最多可输入10位司机的信息。


      参数描述

      operation_id

      String(64) 不可空

      出租车司机ID。仅支持数字和字母。

      注意：每个operation_id的值必须是唯一的。当您第一次注册司机信息必须填写此字段，此后此字段不支持添加或更新。

      示例:1082943492

      contact_way

      String(256)

      出租车司机的电话号码

      注意：仅支持+、-、数字和空格。

      示例:158xxxx2232

      contact_person

      String(64) 不可空

      出租车司机姓名

      示例:driverName2


      注意：

      如果字符串类型的参数没有长度限制，系统将不检查其长度。


      #同步返回参数

      参数描述
      基本参数

      is_success

      String 不可空

      用于展示请求是否成功，值为T表示成功，值为F表示失败。

      注意：成功的请求并不意味着业务被接受并成功完成处理。

      示例:T

      sign_type

      String

      签名类型。支持RSA、RSA2和MD5。请使用大写形式。

      示例:MD5

      sign

      String

      签名值

      示例:3afc92ac4708425ab74ecb2c4e58ef56

      error

      String

      请求失败时返回的错误代码，用于描述请求失败的原因。有关详细信息，参见本文档中的错误码。

      示例:PARAM_ILLEGAL

      result_code

      String

      请求的处理结果。仅当is_success字段的值为T时，返回此字段。

      示例:SUCCESS


      注意：

      由于支付宝服务器端的升级，同步响应可能返回更多参数，对于此API文档中未包含的参数，请忽略。


      #错误码

      #业务错误码

      错误代码

      含义

      MCC_CAN_NOT_MODIFY

      传入的MCC与原始MCC不匹配。

      解决方案：请确保传入的MCC值与原始MCC值保持一致。

      MCC_TYPE_ILLEGAL

      MCC无效。

      解决方案：修改MCC类型，然后重试。

      PARAM_ILLEGAL

      参数不合法：参数太长、参数格式错误、或未传递必需的参数。

      解决方案：根据API文档检查并修正参数。

      SYSTEM_ERROR

      支付宝系统错误。

      解决方案：稍后再试。

      LBS_GEOGRAPHIC_INFORMATION_INVALID

      地址与国家/地区不匹配，或者该地址无法定位。

      解决方案：确保地址有效，使用谷歌地图中可以找到的地址。

      CATEGORY_NOT_SUPPORT_DRIVER

      如果store_industry字段为4121，且当您第一次发送请求时未传入extend_params字段，则当您更新店铺信息并传入司机信息时将返回此错误。

      解决方案：当store_industry字段为4121时，必须传入extend_params字段。

      DUPLICATE_REQUEST

      提交重复请求。上一个注册报备请求仍在处理中。

      解决方案：等待上一个报备请求处理完成。

      MERCHANT_TYPE_ILLEGAL

      错误的二级商户类型。secondary_merchant_type字段的值只能是ENTERPRISE或INDIVIDUAL。

      解决方案：为secondary_merchant_type字段输入正确的值。

      BUSINESS_NAME_UPDATE_FORBIDDEN

      无法更新secondary_merchant_name字段的值，因为企业名称不支持更新。

      REGISTRATION_NO_UPDATE_FORBIDDEN

      无法更新registration_no字段的值，因为该字段不支持更新。

      REGISTER_COUNTRY_UPDATE_FORBIDDEN

      无法更新register_country字段的值，因为该字段不支持更新。

      MERCHANT_TYPE_UPDATE_FORBIDDEN

      无法更新secondary_merchant_type字段，因为该字段不支持更新。

      REPRESENTATIVE_NAME_UPDATE_FORBIDDEN

      无法更新representative_name字段，因为该字段不支持更新。

      REPRESENTATIVE_ID_UPDATE_FORBIDDEN

      无法更新representative_id字段，因为该字段不支持更新。


      #网关错误码

      错误码描述
      ILLEGAL_SIGN签名不合法
      ILLEGAL_DYN_MD5_KEY

      动态密钥信息不正确

      ILLEGAL_ENCRYPT

      加密不正确

      ILLEGAL_ARGUMENT

      参数不正确

      ILLEGAL_SERVICE

      服务参数不正确

      ILLEGAL_USER

      用户ID不正确

      ILLEGAL_PARTNER

      合作伙伴ID不正确

      ILLEGAL_EXTERFACE

      接口配置不正确

      ILLEGAL_PARTNER_EXTERFACE

      合作伙伴的接口信息不正确

      ILLEGAL_SECURITY_PROFILE

      找不到匹配的私钥配置

      ILLEGAL_AGENT机构ID不正确
      ILLEGAL_SIGN_TYPE

      签名类型不正确

      ILLEGAL_CHARSET

      字符集是非法的

      HAS_NO_PRIVILEGE

      无权访问

      INVALID_CHARACTER_SET

      字符集无效


      #系统错误码

      错误码描述
      SYSTEM_ERROR

      支付宝系统错误

      SESSION_TIMEOUT

      会话超时

      ILLEGAL_TARGET_SERVICE

      错误的目标服务

      ILLEGAL_ACCESS_SWITCH_SYSTEM

      商户不允许访问此类系统

      EXTERFACE_IS_CLOSED

      接口已关闭


      #示例

      #请求示例

      报备商铺的请求示例：

      https://intlmapi.alipay.com/gateway.do?service=alipay.overseas.secmerchant.offline.maintain&partner=208xxxxxxxxx8155&_input_charset=UTF-8&sign_type=MD5&timestamp=2019-09-04%2000%3A00%3A12&secondary_merchant_name=Mika's%20coffee%20shop&secondary_merchant_id=1314520&store_id=1993&store_name=Mika's%20coffee%20shop&store_country=US&store_address=3%20Old%20Concord%20Rd%2C%20Burlington%2C%20MA%2001803%E7%BE%8E%E5%9B%BD&store_industry=5499&internal_store_photo=https%3A%2F%2Fwww.mikascoffee%2Fimg_321323.jpg&external_storefront_photo=https%3A%2F%2Fwww.mikascoffee%2Fimg_321322.jpg&secondary_merchant_type=INDIVIDUAL&registration_no=1314520&register_country=US&register_address=3%20Old%20Concord%20Rd%2C%20Burlington%2C%20MA%2001803%E7%BE%8E%E5%9B%BD&shareholder_name=mika&shareholder_id=342xxxxxxxxx0000&contact_no=%2B8618688888888&sign=af2d1f166779562fae5dfb056daf7196


      报备司机的请求示例：

      https://intlmapi.alipay.com/gateway.do?service=alipay.overseas.secmerchant.offline.maintain&partner=208xxxxxxxxx8155&_input_charset=UTF-8&sign_type=MD5&timestamp=2019-09-04 00%3A00%3A12&secondary_merchant_name=Mika's coffee shop&secondary_merchant_id=1314520&store_id=3344&store_name=Mika's drive&store_country=US&store_address=3 Old Concord Rd%2C Burlington%2C MA 01803&store_industry=4121&extend_params=[{"operation_id"%3A"1000332"%2C"contact_way"%3A"138xxxxx1232"%2C"contact_person"%3A"Driver Li"}%2C{"operation_id"%3A"1000333"%2C"contact_way"%3A"13888881232"%2C"contact_person"%3A"Tom"}]&secondary_merchant_type=INDIVIDUAL&registration_no=1314520&register_country=US&register_address=3 Old Concord Rd%2C Burlington%2C MA 01803&shareholder_name=mika&shareholder_id=3428000000000000&contact_no=%2B8618688888888&sign=7daf7f81bbfb77037bb3d6a5b177725f


      #返回示例

      请求成功的返回示例:

      copy
      <?xml version="1.0" encoding="utf-8"?>
<alipay>
    <is_success>T</is_success>
    <request>
        <param name="service">alipay.overseas.secmerchant.offline.maintain</param>
        <param name="partner">208xxxxxxxxx8662</param>
        <param name="_input_charset">UTF-8</param>
        <param name="sign_type">MD5</param>
        <param name="sign">2118ac8fad6bc1d9e88a6cd017c18d37</param>
        <param name="timestamp">2018-08-03 00:28:32</param>
        <param name="secondary_merchant_name">Alipay (China) Network Technology Co., Ltd</param>
        <param name="secondary_merchant_id">201xxxxxxxxx0462</param>
        <param name="store_id">233xxxx7348</param>
        <param name="store_name">LV</param>
        <param name="store_country">HK</param>
        <param name="store_address">No.276, Road YinCheng, Shanghai</param>
        <param name="store_industry">4121</param>
        <param name="secondary_merchant_type">INDIVIDUAL</param>
        <param name="registration_no">012345678</param>
        <param name="register_country">HK</param>
        <param name="register_address">No.277, Road YinCheng, Shanghai, China</param>
        <param name=“representative_name”>Tom Li</param>
        <param name=“representative_id”>123456789</param>
        <param name="settlement_no">2600100000</param>
        <param name="contact_no">186xxxx0000 </param>
        <param name="contact_email">support@xcompany.com </param>
    </request>
<response>
    <alipay>
        <result_code>SUCCESS</result_code>
    </alipay>
</response>
<sign>744a87f0e3b40e6a8cd8f9705ce61511</sign>
<sign_type>MD5</sign_type>
</alipay>


      请求失败或访问数据错误的返回示例：

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