添加子商户以及个人信息

端点目标 URL

沙盒环境请求地址：POST https://preapi.futurepay-develop.com/api/v1/Onboarding/linkMerchantApi/addSubMerchant

生产环境请求地址：POST https://api.futurepay.global/api/v1/v1/Onboarding/linkMerchantApi/addSubMerchant

字段说明

调用的特定输入参数

字段名称	必填	类型	描述
merchantName	M	string(1,255)	子商户昵称
merchantEmail	M	string(1,64)	子商户邮箱
personalInformation.longTermEffectiveness	M	boolean	证件长期有效
personalInformation.nationality	M	string(2)	国籍(通过获取字典数据接口获取dictKey=nationality)
personalInformation.identityType	M	integer	证件类型(1:身份证，2:护照)
personalInformation.identityNumber	M	string(1,50)	证件号码
personalInformation.firstName	M	string(1,50)	英文名
personalInformation.lastName	M	string(1,50)	英文姓
personalInformation.firstNameCn	M	string(1,50)	中文名
personalInformation.lastNameCn	M	string(1,50)	中文姓
personalInformation.dateOfBirth	M	string(10)	出生日期(yyyy-MM-dd)
personalInformation.expirationDateBegan	M	string(10)	证件有效期开始(yyyy-MM-dd)
personalInformation.expirationDateEnded	Q	string(10)	证件有效期结束(yyyy-MM-dd)(longTermEffectiveness = false时必填，其他情况为空)
personalInformation.residenceCountry	M	string	居住国家iso2位编码(通过获取国家接口获取)
personalInformation.residenceProvince	Q	string	居住省份id(居住国家下存在省份时必填)(通过获取省份接口获取)
personalInformation.residenceCity	Q	string	居住城市id(居住省份下存在城市时必填)(通过获取城市接口获取)
personalInformation.residenceAddress	M	string(1,200)	居住地址
personalInformation.residenceZip	M	string(1,20)	居住邮编
personalInformation.portraitFace	M	string	证件人像面(文件url通过文件上传获取)
personalInformation.nationalEmblemSurface	Q	string	证件国徽面(identityType=1时必填)(文件url通过文件上传获取)
personalInformation.proofOfAddress	M	[string]	地址证明文件(文件url通过文件上传获取)
dynamicDataList	M	list	个性化表单数据集合
dynamicDataList.configKey	M	string	个性化表单配置key
dynamicDataList.valueFramework	M	object	个性化表单数据
linkToLiveVerification.verificationLink	O	string	验证链接
linkToLiveVerification.validityTime	O	string	验证到期
linkToLiveVerification.status	O	string	验证状态

响应data参数

同查询子商户详情接口一致

集成

添加子商户调用输入

{
        "merchantName": "testName",
        "merchantEmail": "[email protected]",
        "personalInformation": {
            "nationality": "CN",
            "identityType": "1",
            "identityNumber": "110000194910010101",
            "firstName": "firstName",
            "lastName": "lastName",
            "firstNameCn": "名",
            "lastNameCn": "姓",
            "dateOfBirth": "1949-10-01",
            "expirationDateBegan": "1949-10-01",
            "expirationDateEnded": "2025-12-12",
            "residenceCountry": "CN",
            "residenceProvince": "2257",
            "residenceCity": "19332",
            "residenceAddress": "详细地址",
            "residenceZip": "110100",
            "portraitFace": "1989162017658933248",
            "nationalEmblemSurface": "1989162072558178304",
            "proofOfAddress": [
                "1989162072558178304"
            ],
            "longTermEffectiveness": false
        },
        "businessInformation": {
            "applyProducts": [
                "GLOBAL_RECEIVABLES"
            ],
            "tradingVolume": "11111.00",
            "transactionsNumber": "11",
            "averageCollectionAmount": "11.00",
            "averagePaymentAmount": "12.00",
            "businessWebsite": [
                "https://premerchant.futurepay-develop.com/"
            ],
            "industryCategory": "commerce_trade",
            "businessCountry": [
                "CN"
            ],
            "servicesType": "LOGISTICS_TRANSPORTATION_OTHER",
            "openingPurpose": "开户目的",
            "payingParty": [
                {
                    "name": "付款方甲",
                    "country": "CN",
                    "tradingVolume": "44",
                    "currency": "CNY"
                },
                {
                    "name": "付款方乙",
                    "country": "CN",
                    "tradingVolume": "33",
                    "currency": "CNY"
                },
                {
                    "name": "付款方丙",
                    "country": "CN",
                    "tradingVolume": "22",
                    "currency": "CNY"
                }
            ],
            "beneficiary": [
                {
                    "name": "受益人甲",
                    "country": "CN",
                    "tradingVolume": "44",
                    "currency": "CNY"
                },
                {
                    "name": "受益人乙",
                    "country": "CN",
                    "tradingVolume": "11",
                    "currency": "CNY"
                },
                {
                    "name": "受益人丙",
                    "country": "CN",
                    "tradingVolume": "22",
                    "currency": "CNY"
                }
            ]
        }
    }

添加子商户调用输出

{
    "code": "0",
    "msg": "success",
    "serverTime": "1763347647783",
    "data": {
        "subMerchantId": "1990250402871947264",
        "requestID": "89b4a43b-f358-451a-967f-3bcbf9f88cfe",
        "merchantName": "testName",
        "merchantEmail": "[email protected]",
				"status": "Filling",
      	"personalInformation": {
						"status":"Submitted",
            "nationality": "CN",
            "identityType": "1",
            "identityNumber": "110000194910010101",
            "firstName": "firstName",
            "lastName": "lastName",
            "firstNameCn": "名",
            "lastNameCn": "姓",
            "dateOfBirth": "1949-10-01",
            "expirationDateBegan": "1949-10-01",
            "expirationDateEnded": "2025-12-12",
            "residenceCountry": "CN",
            "residenceProvince": "2257",
            "residenceCity": "19332",
            "residenceAddress": "详细地址",
            "residenceZip": "110100",
            "portraitFace": "https://futurebank-oss-dev.oss-ap-southeast-1.aliyuncs.com/baseInfo/1866780349053448192/kycAPI/0216b0cb6bf4458aa9d3317c664a4650.jpg?Expires=1763351247&OSSAccessKeyId=LTAI5t8WygUaJCd46Wk7fcKt&Signature=Sdo5BWOgnznxM2%2FR%2FQjgn6NuknI%3D",
            "nationalEmblemSurface": "https://futurebank-oss-dev.oss-ap-southeast-1.aliyuncs.com/baseInfo/1866780349053448192/kycAPI/c4fc11755d3c434f9b8e2c885511706d.jpg?Expires=1763351247&OSSAccessKeyId=LTAI5t8WygUaJCd46Wk7fcKt&Signature=vLurtX%2BB3Z2nPNo7c%2FjAIjRPBBg%3D",
            "proofOfAddress": [
                "https://futurebank-oss-dev.oss-ap-southeast-1.aliyuncs.com/baseInfo/1866780349053448192/kycAPI/c4fc11755d3c434f9b8e2c885511706d.jpg?Expires=1763351247&OSSAccessKeyId=LTAI5t8WygUaJCd46Wk7fcKt&Signature=vLurtX%2BB3Z2nPNo7c%2FjAIjRPBBg%3D"
            ],
            "longTermEffectiveness": false
        },
        "dynamicDataList": [
            {
                "configKey": "KYC_MERCHANT_BASIC",
                "status": "Submitted",
                "valueFramework": {
                    "transactionsNumber": "100",
                    "businessWebsiteList": [],
                    "funding": [
                        "salary_income",
                        "e_commerce_Platform",
                        "Advertising_Platform",
                        "Acquirer_Tool",
                        "Developer_Platform"
                    ],
                    "averageCollectionAmount": "1000",
                    "Materials": [
                        "baseInfo/1929803377366183936/kycAPI/abe944b2e61f4f958cd0560d478406f0.png"
                    ],
                    "applyProductList": [
                        "GLOBAL_RECEIVABLES"
                    ],
                    "businessCountryList": [
                        "CN"
                    ],
                    "EmploymentStatus": "Student",
                    "openingPurpose": "1111开户",
                    "tradingVolume": "1000",
                    "averagePaymentAmount": "1000"
                }
            },
            {
                "configKey": "KYC_MERCHANT_PAYER",
                "status": "Submitted",
                "valueFramework": {
                    "list": [
                        {
                            "country": "US",
                            "name": "名称11",
                            "tradingVolume": {
                                "amount": "101",
                                "currency": "USD"
                            }
                        },
                        {
                            "country": "US",
                            "name": "名称22",
                            "tradingVolume": {
                                "amount": "101",
                                "currency": "USD"
                            }
                        },
                        {
                            "country": "US",
                            "name": "名称32",
                            "tradingVolume": {
                                "amount": "101",
                                "currency": "USD"
                            }
                        }
                    ]
                }
            },
            {
                "configKey": "KYC_MERCHANT_BENEFICIARY",
                "status": "Submitted",
                "valueFramework": {
                    "list": [
                        {
                            "country": "US",
                            "name": "名称11",
                            "tradingVolume": {
                                "amount": "101",
                                "currency": "USD"
                            }
                        },
                        {
                            "country": "US",
                            "name": "名称22",
                            "tradingVolume": {
                                "amount": "101",
                                "currency": "USD"
                            }
                        },
                        {
                            "country": "US",
                            "name": "名称32",
                            "tradingVolume": {
                                "amount": "101",
                                "currency": "USD"
                            }
                        }
                    ]
                }
            }
        ],
        "linkToLiveVerification": null
    },
    "success": true
}

修改子商户个人信息

端点目标 URL

沙盒环境请求地址：POST https://preapi.futurepay-develop.com/api/v1/Onboarding/linkMerchantApi/editSubMerchant

生产环境请求地址：POST https://api.futurepay.global/api/v1/v1/Onboarding/linkMerchantApi/editSubMerchant

字段说明

调用的特定输入参数

同添加子商户以及个人信息接口一致

响应data参数

同查询子商户详情接口一致

集成

修改子商户调用输入

{
    "subMerchantId": "1990250402871947264",
    "merchantName": "testName",
    "merchantEmail": "[email protected]",
    "personalInformation": {
        "nationality": "CN",
        "identityType": "1",
        "identityNumber": "110000194910010101",
        "firstName": "firstName",
        "lastName": "lastName",
        "firstNameCn": "名",
        "lastNameCn": "姓",
        "dateOfBirth": "1949-10-01",
        "expirationDateBegan": "1949-10-01",
        "expirationDateEnded": "2025-12-12",
        "residenceCountry": "CN",
        "residenceProvince": "2257",
        "residenceCity": "19332",
        "residenceAddress": "详细地址",
        "residenceZip": "110100",
        "portraitFace": "1989162017658933248",
        "nationalEmblemSurface": "1989162072558178304",
        "proofOfAddress": [
            "1989162072558178304"
        ],
        "longTermEffectiveness": false
    }
}

修改子商户调用输出

{
    "code": "0",
    "msg": "success",
    "serverTime": "1763350047088",
    "data": {
        "subMerchantId": "1990250402871947264",
        "requestID": "511dfc3f-8d18-4fc3-9aa9-ad2494a675a0",
        "merchantName": "testName",
        "merchantEmail": "[email protected]",
				"status": "Filling",
        "personalInformation": {
            "nationality": "CN",
            "identityType": "1",
            "identityNumber": "110000194910010101",
            "firstName": "firstName",
            "lastName": "lastName",
            "firstNameCn": "名",
            "lastNameCn": "姓",
            "dateOfBirth": "1949-10-01",
            "expirationDateBegan": "1949-10-01",
            "expirationDateEnded": "2025-12-12",
            "residenceCountry": "CN",
            "residenceProvince": "2257",
            "residenceCity": "19332",
            "residenceAddress": "详细地址",
            "residenceZip": "110100",
            "portraitFace": "https://futurebank-oss-dev.oss-ap-southeast-1.aliyuncs.com/baseInfo/1866780349053448192/kycAPI/0216b0cb6bf4458aa9d3317c664a4650.jpg?Expires=1763353647&OSSAccessKeyId=LTAI5t8WygUaJCd46Wk7fcKt&Signature=NSXfN8g9YgGWJ1DuEeCL2X1zb00%3D",
            "nationalEmblemSurface": "https://futurebank-oss-dev.oss-ap-southeast-1.aliyuncs.com/baseInfo/1866780349053448192/kycAPI/c4fc11755d3c434f9b8e2c885511706d.jpg?Expires=1763353647&OSSAccessKeyId=LTAI5t8WygUaJCd46Wk7fcKt&Signature=SQSTzgJ%2B0MuHtP3aJLjF92BzyfA%3D",
            "proofOfAddress": [
                "https://futurebank-oss-dev.oss-ap-southeast-1.aliyuncs.com/baseInfo/1866780349053448192/kycAPI/c4fc11755d3c434f9b8e2c885511706d.jpg?Expires=1763353647&OSSAccessKeyId=LTAI5t8WygUaJCd46Wk7fcKt&Signature=SQSTzgJ%2B0MuHtP3aJLjF92BzyfA%3D"
            ],
            "longTermEffectiveness": null
        },
        "dynamicDataList": [
            {
                "configKey": "KYC_MERCHANT_BASIC",
                "status": "Submitted",
                "valueFramework": {
                    "transactionsNumber": "100",
                    "businessWebsiteList": [],
                    "funding": [
                        "salary_income",
                        "e_commerce_Platform",
                        "Advertising_Platform",
                        "Acquirer_Tool",
                        "Developer_Platform"
                    ],
                    "averageCollectionAmount": "1000",
                    "Materials": [
                        "baseInfo/1929803377366183936/kycAPI/abe944b2e61f4f958cd0560d478406f0.png"
                    ],
                    "applyProductList": [
                        "GLOBAL_RECEIVABLES"
                    ],
                    "businessCountryList": [
                        "CN"
                    ],
                    "EmploymentStatus": "Student",
                    "openingPurpose": "1111开户",
                    "tradingVolume": "1000",
                    "averagePaymentAmount": "1000"
                }
            },
            {
                "configKey": "KYC_MERCHANT_PAYER",
                "status": "Submitted",
                "valueFramework": {
                    "list": [
                        {
                            "country": "US",
                            "name": "名称11",
                            "tradingVolume": {
                                "amount": "101",
                                "currency": "USD"
                            }
                        },
                        {
                            "country": "US",
                            "name": "名称22",
                            "tradingVolume": {
                                "amount": "101",
                                "currency": "USD"
                            }
                        },
                        {
                            "country": "US",
                            "name": "名称32",
                            "tradingVolume": {
                                "amount": "101",
                                "currency": "USD"
                            }
                        }
                    ]
                }
            },
            {
                "configKey": "KYC_MERCHANT_BENEFICIARY",
                "status": "Submitted",
                "valueFramework": {
                    "list": [
                        {
                            "country": "US",
                            "name": "名称11",
                            "tradingVolume": {
                                "amount": "101",
                                "currency": "USD"
                            }
                        },
                        {
                            "country": "US",
                            "name": "名称22",
                            "tradingVolume": {
                                "amount": "101",
                                "currency": "USD"
                            }
                        },
                        {
                            "country": "US",
                            "name": "名称32",
                            "tradingVolume": {
                                "amount": "101",
                                "currency": "USD"
                            }
                        }
                    ]
                }
            }
        ],
        "linkToLiveVerification": {
            "verificationLink": null,
            "validityTime": null,
            "status": null
        }
    },
    "success": true
}

查询子商户信息

端点目标 URL

沙盒环境请求地址：POST https://preapi.futurepay-develop.com/api/v1/Onboarding/linkMerchantApi/editSubMerchant

生产环境请求地址：POST https://api.futurepay.global/api/v1/v1/Onboarding/linkMerchantApi/editSubMerchant

字段说明

调用的特定输入参数

字段名称	必填	类型	描述
subMerchantId	M	string	子商户商户号

响应data参数

字段名称	类型	描述
requestID	string	请求唯一id
subMerchantId	string	子商户商户号
merchantName	string	子商户昵称
merchantEmail	string(email)	子商户邮箱
status	string	商户状态
personalInformation	object	个人信息
personalInformation.status	string	模块状态
personalInformation.longTermEffectiveness	boolean	证件长期有效
personalInformation.nationality	string	国籍
personalInformation.identityType	integer	证件类型
personalInformation.identityNumber	string	证件号码
personalInformation.firstName	string	英文名
personalInformation.lastName	string	英文姓
personalInformation.firstNameCn	string	中文名
personalInformation.lastNameCn	string	中文姓
personalInformation.dateOfBirth	string	出生日期(yyyy-MM-dd)
personalInformation.expirationDateBegan	string	证件有效期开始(yyyy-MM-dd)
personalInformation.expirationDateEnded	string	证件有效期结束(yyyy-MM-dd)
personalInformation.residenceCountry	string	居住国家
personalInformation.residenceProvince	string	居住省份
personalInformation.residenceCity	string	居住城市
personalInformation.residenceAddress	string	居住地址
personalInformation.residenceZip	string	居住邮编
personalInformation.portraitFace	string	证件人像面可查看链接
personalInformation.nationalEmblemSurface	string	证件国徽面可查看链接
personalInformation.proofOfAddress	[string]	地址证明文件可查看链接集合
dynamicDataList	list	个性化表单数据集合
dynamicDataList.configKey	string	个性化表单配置key
dynamicDataList.status	string	模块状态
dynamicDataList.valueFramework	object	个性化表单数据
linkToLiveVerification.verificationLink	string	验证链接
linkToLiveVerification.validityTime	string	验证到期
linkToLiveVerification.status	string	验证状态

集成

查询子商户信息调用输入

{
    "subMerchantId": "1988939494086324224"
}

查询子商户信息调用输出

{
    "code": "0",
    "msg": "success",
    "serverTime": "1765857261570",
    "data": {
        "subMerchantId": "1988939494086324224",
        "requestID": "5aef9014-0875-488a-85bb-448e1cd0b270",
        "merchantName": "merchantName111",
        "merchantEmail": "[email protected]",
        "status": "Filling",
        "personalInformation": {
            "nationality": "CN",
            "identityType": "1",
            "identityNumber": "identityNumber2222",
            "firstName": "firstName",
            "lastName": "lastName",
            "firstNameCn": "firstNameCn11",
            "lastNameCn": "lastNameCn22",
            "dateOfBirth": "2025-10-10",
            "expirationDateBegan": "2025-10-10",
            "expirationDateEnded": "2035-10-10",
            "residenceCountry": "CN",
            "residenceProvince": "2247",
            "residenceCity": "19598",
            "residenceAddress": "15125123",
            "residenceZip": "residenceZip",
            "portraitFace": "https://futurebank-oss-dev.oss-ap-southeast-1.aliyuncs.com/baseInfo/1929803377366183936/kycAPI/abe944b2e61f4f958cd0560d478406f0.png?Expires=1765860861&OSSAccessKeyId=LTAI5t8WygUaJCd46Wk7fcKt&Signature=wcgwpqW8tgnBhIeUEyjXxRWeXTc%3D",
            "nationalEmblemSurface": "https://futurebank-oss-dev.oss-ap-southeast-1.aliyuncs.com/baseInfo/1929803377366183936/kycAPI/909a2dcdd84549f7bca9ac34a28cd973.jpg?Expires=1765860861&OSSAccessKeyId=LTAI5t8WygUaJCd46Wk7fcKt&Signature=dxItudShjCio2JNVmpm%2F5j4vXu4%3D",
            "proofOfAddress": [
                "https://futurebank-oss-dev.oss-ap-southeast-1.aliyuncs.com/baseInfo/1929803377366183936/kycAPI/cc8f7f58f52244a1909fbd09e0f2c334.jpeg?Expires=1765860861&OSSAccessKeyId=LTAI5t8WygUaJCd46Wk7fcKt&Signature=eX71vGsmJ28SXkIVoDoyykzhFog%3D"
            ],
            "status": "Submitted",
            "longTermEffectiveness": null
        },
        "linkToLiveVerification": {
            "verificationLink": null,
            "validityTime": null,
            "status": null
        },
        "dynamicDataList": [
            {
                "configKey": "KYC_MERCHANT_BASIC",
                "status": "Submitted",
                "valueFramework": {
                    "transactionsNumber": "100",
                    "businessWebsiteList": [],
                    "funding": [
                        "salary_income",
                        "e_commerce_Platform",
                        "Advertising_Platform",
                        "Acquirer_Tool",
                        "Developer_Platform"
                    ],
                    "averageCollectionAmount": "1000",
                    "Materials": [
                        "baseInfo/1929803377366183936/kycAPI/abe944b2e61f4f958cd0560d478406f0.png"
                    ],
                    "applyProductList": [
                        "GLOBAL_RECEIVABLES"
                    ],
                    "businessCountryList": [
                        "CN"
                    ],
                    "EmploymentStatus": "Student",
                    "openingPurpose": "1111开户",
                    "tradingVolume": "1000",
                    "averagePaymentAmount": "1000"
                }
            },
            {
                "configKey": "KYC_MERCHANT_PAYER",
                "status": "Submitted",
                "valueFramework": {
                    "list": [
                        {
                            "country": "US",
                            "name": "名称11",
                            "tradingVolume": {
                                "amount": "101",
                                "currency": "USD"
                            }
                        },
                        {
                            "country": "US",
                            "name": "名称22",
                            "tradingVolume": {
                                "amount": "101",
                                "currency": "USD"
                            }
                        },
                        {
                            "country": "US",
                            "name": "名称32",
                            "tradingVolume": {
                                "amount": "101",
                                "currency": "USD"
                            }
                        }
                    ]
                }
            },
            {
                "configKey": "KYC_MERCHANT_BENEFICIARY",
                "status": "Submitted",
                "valueFramework": {
                    "list": [
                        {
                            "country": "US",
                            "name": "名称11",
                            "tradingVolume": {
                                "amount": "101",
                                "currency": "USD"
                            }
                        },
                        {
                            "country": "US",
                            "name": "名称22",
                            "tradingVolume": {
                                "amount": "101",
                                "currency": "USD"
                            }
                        },
                        {
                            "country": "US",
                            "name": "名称32",
                            "tradingVolume": {
                                "amount": "101",
                                "currency": "USD"
                            }
                        }
                    ]
                }
            }
        ]
    },
    "success": true
}

子商户提交审核

端点目标 URL

沙盒环境请求地址：POST https://preapi.futurepay-develop.com/api/v1/Onboarding/linkMerchantApi/submitReview

生产环境请求地址：POST https://api.futurepay.global/api/v1/v1/Onboarding/linkMerchantApi/submitReview

字段说明

调用的特定输入参数

字段名称	必填	类型	描述
subMerchantId	M	string	子商户商户号

集成

子商户提交审核调用输入

{
    "subMerchantId": "1990250402871947264"
}

子商户提交审核调用输出

{
    "code": "0",
    "msg": "succeeded",
    "serverTime": "1763351728504",
    "success": true
}

字典对照表

模块状态

模块状态为待审核、已通过时数据不可修改

value	name
UnSubmitted	未填写
Submitted	已填写
Pending	待审核
Returned	已退回
Verified	已通过

商户状态

value	name
Filling	填写中
Pending	待审核
Activated	已激活
Returned	退回
Closed	关闭

WEBHOOK

当子商户状态变更时，我们会发送如下通知到您的主商户回调地址

{
	"merchantId": "1866780349053448192",
	"notificationItems": [
		{
			"eventCode": "SUB_MERCHANT_STATUS_NOTIFY",
			"subMerchantId": 1990250402871947264,
			"status": "Activated",
			"eventDate": 1763359209167
		}
	]
}