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

2020-10-27 08:53

You can use this interface to register and store secondary merchants information for offline 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"}

storeInfo

storeInfo Required

Store information, see storeInfo for details. This field is only for offline merchants.

Example:{"storeId": "569833","storeName": "ShopName","storeIndustry": "8501","internalStorePhoto": "www.alipay.com/internalStorePhoto.jpg","externalStorefrontPhoto": "www.alipay.com/externalStorePhoto.jpg","customerServiceNo": "086+13701720000","customerServiceEmail": "

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

paymentScene

String Required

Specify the payment scene. The value isOFFLINE when the payment is an offline payment.

Example:OFFLINE

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

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 Required

String(800)

Business registration address specified on the business registration document. Use postal address format. Specify this field only when the secondary merchant type is ENTERPRISE. This field is optional if the secondary merchant type is INDIVIDUAL.

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)

shareholderId

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

#storeInfo

Parameter Description

storeId

String(32) Required

The unique ID assigned by the partner to identify a store of a secondary merchant. For taxicabs and limousines (MCC 4121), use the license plate number.

Example:23372327348

storeName

String(128) Required

Store name. For taxicabs and limousines (MCC 4121), use the license plate number.

Example:StoreName

storeMcc

String(10) Required

A 4-digit MCC code of the store. See MCC list for details.

Example:4121

storeCountry

String(10) Required

Store registration country. A 2-letter code defined in ISO 3166.

Example:HK

storeAddress

String(1024) Required

Registered store address. Use postal address format.

Example:No.256, Road YinCheng, Shanghai

internalStorePhoto

String(256)

URL of the store interior photo.

Example: http://testmerchant.com

externalStorefrontPhoto

String(256)

URL of the store exterior photo.

Example: http://testmerchant.com

#

#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

resultCodeId	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_m2",
        "sellerName": "Alipay (China) Network Technology Co., Ltd",
        "paymentScene": "OFFLINE",
        "sellerType": "ENTERPRISE",
        "registrationNo": "83720154037071",
        "registrationCountry": "HK",
        "registrationAddress": "Zhonghuan",
        "shareholderName": "Zhangsan",
        "shareholderId": "69833444422",
        "settlementNo": "1551263547569833",
        "contactNo": "086+13001720000",
        "contactEmail": "Zhangsan@alipay.com",
        "customerServiceNo": "086+13701720000",
        "customerServiceEmail": "test@alipay.com"
      },
      "storeInfo": {
        "storeId": "yoka_global_s2",
        "storeName": "yoka global store",
        "storeMcc": "4111",
        "storeCountry": "CN",
        "storeAddress": "Huzhou, Zhejiang",
        "internalStorePhoto": "http://www.alipay.com/internalStorePhoto.jpg",
        "externalStorefrontPhoto": "http://www.alipay.com/externalStorePhoto.jpg"
      }
    }
  },
  "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:33:02-07:00",
      "version": "2.0.4"
    }
  },
  "signature": "K76pYNOFZO86kojFYWOO1LJbhbcWC3iGk09di6a/XAj6L6KoXgY0kHHqlRWJ1Ilql9ooQHpl2TedR0dDUQYMMKUAiGbNPFpMqBQMDWcfGPnf3Gj5UiLMQFbqnMiRdY3r2nXliWCSdJtmN7NAxw2xysSjXRXVFydGSemcapjtQrj4ULMt+7Gi/VEAy1NPkkkloPAOwpDiEEfea91nHL/UJZ46jL2AnC4CqD662WQisDi03QK9rcaXP0JcIK3pgnpEDuInkKxtlXAYA5tqi/vAXyh3cShYAEFaziquaF2Xy3EDzB8M7krpuPxhC9gusb17zwhmZsvoCqIulGzeNrWiiQ=="
}