alipay.intl.merchant.common.indirectMerchant.maintain (for online payments)

2021-02-26 07:48

You can use this interface to register and store secondary merchants information for online payments into Alipay system by setting the operationType field to ADD. You can also use this interface to modify the registered information of secondary merchants by setting the operationType field to MODIFY.

Request

Service address

Environment	URL
Production	https://open-sea.alipay.com/api/alipay/intl/merchant/common/indirectMerchant/maintain.htm

Request head

Parameter Description

version

String(8) Required

The API version

Example:2.0.4

function

String(128) Required

The API name

Example:alipay.intl.merchant.common.indirectMerchant.maintain

clientId

String(32) Required

The unique ID assigned by Alipay to identify a client that makes API calls

Example:385xxxxxxxxx0001

reqTime

Date time Required

Date time with timezone, see RFC 3339 Section 5.6 for details.

Example:2001-07-04T12:08:56+05:30

reqMsgId

String(64) Required

The unique ID assigned by the client to identify a request message. Note: The reqMsgId identifies a unique system request, but it is not used to identify a unique business request.

Example:123xxxxxxxxxxxxxxx3fda

reserve

String(256)

Key/Value formatted parameter for future use. This parameter is required when you are an ISV. If you are an ISV, you need to provide the isvAccesstoken value.

Example:{"isvAccesstoken":123123123sdfsddsf}

Request body

Parameter Description

merchantId

String(64) Required

A unique partner ID to identify a contracted Alipay Account.

Example:211xxxxxxxxxxxxxx2999

operationType

String Required

Specify the purpose of using this interface. The value can be one of the following items.ADD: add a new record.MODIFY: modify an existing record.

Example:ADD

sellerInfo

SellerInfo Required

Seller information， see SellerInfo for details.

Example:{ "sellerId": "58000001", "sellerName": "Alipay (China) Network Technology Co., Ltd", "sellerType":"ENTERPRISE", "registrationNo": "83720154037071","registrationCountry": "CN","registrationAddress": "Shanghai","representativeName": "Zhangsan","representativeId": "69833444422","settlementNo": "1551263547569833","contactNo": "086+13001720000","contactEmail": "Zhangsan@alipay.com"}

notifyUrl

String(1024)

The merchant notify url

Example:www.alipay.com/notify.htm

extendInfo

String(2048)

Reserved for extended information

Example:{}

Sub-parameters

sellerInfo

Parameter Description

sellerId

String(32) Required

The unique ID assigned by the partner to identify a secondary merchant. The ID can contain letters, numbers, and underscores.

Example:63472327348

sellerName

String(128) Required

Registration legal name of the secondary merchant, which is shown in the wallet and reconciliation file to identify a secondary merchant. Note: If the secondary merchant type is INDIVIDUAL, specify the full legal name of the business owner to this field.

Example:Alipay (China) Network Technology Co., Ltd

sellerMcc

String(10) Required

Business category code of the secondary merchant. See MCC list.

Example:1402

paymentScene

String Required

Specify the payment scene. The value isONLINE when the payment is an online payment.

Example:ONLINE

sellerType

String Required

Secondary merchant type, the value can be INDIVIDUAL for the sole proprietorship or ENTERPRISE for the limited company, private company, partnership, limited liability partnership (LLP), limited liability company (LLC), S corporation (S Corp), C corporation (C Corp), trust, or nonprofit organization (NPO)

Example:INDIVIDUAL

siteInfos

String Required

This field is in JSON format and can contain up to 5 website URLs or app download URLs. See siteInfos for details.URLs in this field cannot be updated incrementally. To add or remove URLs, re-pass the value again.This field is only for online merchants.

Example:[{"siteType":"WEB","siteUrl":"https://alipay.com","siteName":"websit"},{"siteType":"APP","siteUrl":"https://alipay.com","siteName":"websit"}]

registrationNo

String(128)

Business registration number specified on the business registration document.Note: This field is not required when the secondary merchant type is INDIVIDUAL and no registration number exists.

Example:012345678

registrationCountry

String(2) Required

Registration country of the secondary merchant, specified by a 2-letter code defined in ISO 3166. For more details about the 2-letter country code, see ISO 3166.

Example:HK

registrationAddress

String(800) Required

Business registration address specified on the business registration document. Use postal address format.

Example:No.278, Road YinCheng, Shanghai, China

shareholderName

String(128)

Legal name of the primary shareholder of the secondary merchant. Specify this field only when the secondary merchant type is ENTERPRISE.

Example:Jack Li (if the shareholder is an individual), Alipay.com Co.,Ltd (if the shareholder is an enterprise)

shareholder_id

String(128)

ID or passport number, or business registration number of the primary shareholder of the secondary merchant. Specify this field only when the secondary merchant type is ENTERPRISE.

Example:G53453888 (if the shareholder is an individual), 012345678 (if the shareholder is an enterprise)

representativeName

String(128)

Full legal name of the business owner. Specify this field only when the secondary merchant type is INDIVIDUAL. This field is optional if the secondary merchant type is ENTERPRISE.

Example:Tom Li

representativeId

String(128)

ID or passport number of the business owner. Specify this field only when the secondary merchant type is INDIVIDUAL. This field is optional if the secondary merchant type is ENTERPRISE.

Example:123456789

settlementNo

String(128)

Settlement bank account number of the secondary merchant, letters and numbers only

Example:2600100000

contactNo

String(40)

Contact phone number of the secondary merchant, numbers and special characters +-() only

Example:+86139xxxx7893

contactEmail

String(64)

Contact email address of the secondary merchant

Example:tomli@gmail.com

customerServiceNo

String(64)

Customer service phone number of the secondary merchant, numbers and special characters +-() only

Example:0213355xxx89

customerServiceEmail

String(64)

Customer service email address of the secondary merchant

Example:customerservice@xxxcompany.com

siteInfos

Parameter Description

siteType

String(20) Required

Site type. For website URL, the value for this parameter must be WEB. For app download URL, the value for this parameter must be APP. Use uppercase.

Example:WEB

siteUrl

String(256) Required

Site URL.

When site_type is WEB, pass the URL in this format: http/https + SLD + TLD, for example, https://www.alipay.com
When site_type is APP, pass the APP download URL starting with http/https, for example, https://itunes.apple.com/cn/app/id333206289

Example:https://www.alipay.com

siteName

String(128)

Site name

Example:xx Store

Response

Response head

Parameter Description

version

String(8) Required

The API version

Example:2.0.4

function

String(128) Required

The API name

Example:alipay.intl.acquiring.offline.pay

clientId

String(32) Required

The unique ID assigned by Alipay to identify a client that makes API calls

Example:385xxxxxxxxx0001

respTime

Date time Required

Date time with timezone, see RFC 3339 Section 5.6 for details.

Example:2001-07-04T12:08:56+05:30

reqMsgId

String(64) Required

The unique ID assigned by client to identify a request message

Example:123xxxxxxxxxxxxxxx3fda

reserve

String(256)

Key/Value formatted parameter for future use

Example:{key/value}

Response body

Parameter Description

resultInfo

ResultInfo Required

See resultInfo for details.

Example:{ "resultStatus": "S", "resultCodeId": "00000000", "resultCode":"SUCCESS", "resultMsg": "result message" }

resultInfo

Parameter Description

resultStatus

String(2) Required

The request status can be:S: successF: failureU: unknown

Example:S

resultCodeId

String(8) Required

An 8-digit code that is used to identify a result. When resultStatus is S, the value must be 00000000. When resultStatus is F or U, the value can be other result ID specified by the interface.

Example:00000000

resultCode

String(64) Required

The result code

Example:SUCCESS

resultMsg

String(256)

When resultCode is S, this value can be empty. When resultCodeis F or U, the error description is required.

Example:success

Result code

Basic result code

ResultID	ResultCode	ResultStatus	Remarks
00000000	SUCCESS	S	Success
00000019	PROCESS_FAIL	F	General business failure
00000901	UNKNOWN_EXCEPTION	U	API failed because of unknown reasons
00000004	PARAM_ILLEGAL	F	The parameter is incorrect.
00000007	INVALID_SIGNATURE	F	The signature is invalid.
00000008	KEY_NO_FOUND	F	The key is not found.
00000014	API_IS_INVALID	F	The API is invalid or nonactivated.
00000016	OAUTH_FAILED	F	The oAuth authentication failed.
00000021	ACCESS_DENIED	F	Access denied
00000024	REQUEST_TRAFFIC_EXCEED_LIMIT	F	The request traffic exceeds the limit.
12014152	CLIENT_FORBIDDEN_ACCESS_API	F	The Client is not authorized to use this API.
12014155	UNKNOWN_CLIENT	F	Unknown client
12014156	INVALID_CLIENT_STATUS	F	Invalid client status
00000030	SIGN_TYPE_INVALID	F	The sign type is invalid

Sample

Sample request

copy

{
  "request": {
    "head": {
      "version": "2.0.4",
      "function": "alipay.intl.merchant.common.indirectMerchant.maintain",
      "clientId": "385XPU2C2Y0GBK03",
      "reqTime": "2019-03-11T00:00:00+00:00",
      "reqMsgId": "332111111111",
      "reserve": "{}"
    },
    "body": {
      "merchantId": "$!{merchantId}",
      "operationType": "ADD",
      "sellerInfo": {
        "sellerId": "yoka_global_m1",
        "sellerName": "Alipay (China) Network Technology Co., Ltd",
        "sellerMcc": "4111",
        "paymentScene": "ONLINE",
        "sellerType": "ENTERPRISE",
        "siteInfos": [
          {
            "siteType": "WEB",
            "siteUrl": "https://yoka.com",
            "siteName": "websit"
          },
          {
            "siteType": "APP",
            "siteUrl": "https://app.yoka.com",
            "siteName": "websit"
          }
        ],
        "registrationNo": "83720154037071",
        "registrationCountry": "CN",
        "registrationAddress": "Lujiazui, Pudong, Shanghai",
        "shareholderName": "Zhangsan",
        "shareholderId": "69833444422",
        "settlementNo": "1551263547569833",
        "contactNo": "086+13001720000",
        "contactEmail": "Zhangsan@alipay.com",
        "customerServiceNo": "086+13701720000",
        "customerServiceEmail": "test@alipay.com"
      }
    }
  },
  "signature": "testing_signature"
}

Sample response

copy

{
  "response": {
    "body": {
      "resultInfo": {
        "resultCode": "SUCCESS",
        "resultCodeId": "00000000",
        "resultMsg": "Success",
        "resultStatus": "S"
      }
    },
    "head": {
      "clientId": "385XPU2C2Y0GBK03",
      "function": "alipay.intl.merchant.common.indirectMerchant.maintain",
      "reqMsgId": "332111111111",
      "respTime": "2019-03-29T22:27:02-07:00",
      "version": "2.0.4"
    }
  },
  "signature": "COSDtCc8cZlVG/ABueiaBnWQb77gg9cqSa18p5HEXGnb6bkQzZijzy5oT/Yz8g+8QegmLkNV476dMXVN99/ScHRRR6ylDlCgNWNDXTQKwBtTTYYLcLeuEqHQc5FdMgenqjv0eKcOMNHswovv+gQFjbAJa1xg1kLW9vmJbdotpXc7nTni8/AJi+Mpof37pCy6TYFXiyir4Gejj31r2WKQl0aPDJT6F6AutQI2rYAaaHryaAfxbEcJb8Y5W+THqxL0Jm2qQBr19rBFUVbfJPaMCRJEmIU72NoxVcDp8x033+8HVbUxOfgQyFlo83JhmXC9YLnNN3wG+AfA0mItrRBaCw=="
}