Merchant Onboarding Interface（Merchant→Geoswift）

Function Description

If you need to open a collection account for a sub-merchant, you must first onboard the sub-merchant. This interface can be used to onboard and modify sub-merchant information.

Interface URL

Request endpoint：https://api.geoswift.com/va/declaration/createOrUpdate

Name Type&Length Description Required
merchantId varchar(9) The unique identifier of the merchant in the Geoswift system M
requestId varchar(50) Merchant-defined order number, must be unique within the merchant's account transactions. When the operation type is MODIFY, this value must match the original order number used during account creation. M
notifyUrl varchar(100) The URL where Geoswift will send notifications via POST once the onboarding status reaches a final state. M
type Json Operation type;
CREATE for creation,
MODIFY for updates (when the sub-merchant’s onboarding status is RETURN, use this parameter to modify based on the audit remarks; the merchant request ID must be the same as during creation).		 M
company Json Company information;
See the table "company information.”		 M
business Json Business information;
See the table "business information."		 M
beneficialList Json Beneficiary information;
Information on individuals holding 25% or more equity or shares. See the table "Beneficiary information."		 M
legalList Json Information on directors or legal representatives.
See the table "legal information."		 M
authorizedList Json Information on authorized signatories.
See the table "Authorized signatory information."		 M
certificate Json See the table "qualification documents." M
agreeCooperationAgreement Fixed value Agree Cooperation Agreement;
Defaults to "Y" to agree with the declaration upon creating a sub-merchant.		 O
hmac varchar(512) The parameter signature generated by the merchant. For methods to obtain HMAC, please refer to the "Geoswift Encryption and Decryption Process Specification." M

Request Parameters（company，Company Information）

Name Type&Length Description Required
country Enum State or Country of Company Establishment;
Three-letter ISO country code;
Cannot be changed;
Required if type is CREATE.
Not needed if type is MODIFY.
See the country code table.		 C
signedName varchar(80) Registered Company Name;
Company name in English format;
Cannot be changed.
Required if type is CREATE.
Not needed if type is MODIFY.
Allowed characters: A-Z, a-z, 0-9, "()", ".", ",", "-", and space.		 C
usedName varchar(80) Former company names. Allowed characters:
A-Z, a-z, 0-9, "()", ".", ",", "-", and space.		 O
shortName varchar(80) Short name of the company. Allowed characters:
A-Z, a-z, 0-9, "()", ".", ",", "-", and space.		 O
brandName varchar(80) Brand name. Allowed characters:
A-Z, a-z, 0-9, "()", ".", ",", "-", and space.		 O
registerAddress varchar(200) Registered address of the company. Allowed characters:
A-Z, a-z, 0-9, "()", ".", ",", "-", and space.		 M
businessAddress varchar(180) Business address of the company. Allowed characters:
A-Z, a-z, 0-9, "()", ".", ",", "-", and space.		 M
addressType 枚举值 Type of company address:
0 for registered address,
1 for business address.		 M
phone varchar(20) Company contact phone number. M
br varchar(8) Business registration number (digits and letters).
Required if the country is HKG.		 C
brStartDate varchar(8) Business Registration Start Date;
Format: YYYYMMDD. Required if the country is HKG.		 C
brEndDate varchar(8) Business Registration End Date
Format: YYYYMMDD. Required if the country is HKG.		 C
ci varchar(7) Company registration number (digits and letters).
Required if the country is HKG.		 C
licenseNumber varchar(18) Business license number (digits and letters).
Required if the country is CHN.		 C
licenseNumberStartDate varchar(8) Business license Start Date
Format: YYYYMMDD. Required if the country is CHN.		 C
licenseNumberEndDate varchar(8) Business License End Date
Format: YYYYMMDD. Required if the country is CHN.		 C
registerNumber varchar(15) Company Registration Certificate Number(digits and letters).
Required if the country is not CHN or HKG.		 C
establishDate varchar(8) Date of Establishment
Format: YYYYMMDD. Date of company establishment.		 M
legalPersonName varchar(100) Name of the legal representative in English format.
For example, if the name is 李凯 in Chinese, it should be Li Kai here.		 M
companyType Enum Company type:
1 for Private Limited Company,
2 for Public Company,
3 for Subsidiary of a Public Company,
4 for State-Owned Enterprise,
5 for Sole Proprietorship,
6 for Partnership (Unlimited Liability),
7 for Corporation (US only),
8 for Other.		 M
companyTypeDesc varchar(100) Description of company type, required when companyType is 8. C
webSite varchar(100) Company website URL. M
email varchar(50) The official company contact email address. M

Request Parameters（business, Business Information）

Name Type&Length Description Required
businessNature varchar(500) 详细描述提供产品和服务
例如: 卖衣服， 电商買卖平台，电脑编程， 旅游中介....		 M
productType 枚举值 支持的类型如下：
E-commerce：电商；
Tuition：学费；
Accommodation：住宿；
Travel：旅游；
Communication service：通讯服务；
Software service：软件服务；
Trade in goods：货物贸易
Other：其他
可多选，以英文逗号分隔
例如：E-commerce，Communication service		 M
tradeMode Enum Trade Mode:
P2P,
B2B,
B2C,
C2B.
Multiple selections allowed, separated by commas. Example: P2P,B2B.B		 M
businessModeDesc varchar(1000) Business Model Description;
Detailed description of the business model, including currencies used for incoming and outgoing transactions. Attach a cash flow diagram to explain the source and destination of funds.		 M
cashFlowPathList varchar(200) Cash Flow Diagram (Business Description Attachment)
Detailed description of the business model or attach a cash flow diagram explaining the source and destination of funds.
Up to 3 files, each not exceeding 10MB.
File formats: PNG, JPG, JPEG, PDF, ZIP.		 M
cashSourceCountry varchar(100) Source of Funds Country
Provide country codes.
For multiple countries, separate with commas. Example: GBR,SGP,HKG,CHN.		 M
cashSource varchar(100) Source of Funds:
Goods Payment;
Service Rendered;
Commission;
Others;
Multiple selections allowed, separated by commas. Example: Goods Payment, Others.		 M
cashSourceDesc varchar(500) Required if cashSource includes Others. M
enterCurrency varchar(100) Currency for Incoming Fund.
Currency codes. For multiple currencies, separate with commas. Example: USD,SGD,HKD,CNH.
Refer to the appendix: Currency Codes.		 M
enterForUse varchar(100) Purpose of Remittance:
Settlement;
Daily Operation;
Others;
Can be separated by commas. Example: Settlement, Daily Operation, Others.		 M
enterForUseDesc varchar(100) Description of Purpose of Remittance.
Required if enterForUse includes Others.		 M
outCurrency varchar(100) Currency for Outgoing Funds.
Currency codes. For multiple currencies, separate with commas. Example: USD,SGD,HKD,CNH. Refer to the appendix: Currency Codes.		 M
lastYearSaleAmount Numeric Sales Amount for the Past Year.
Amount (no decimal places).		 M
expectNumberPerMonth Numeric Estimated Monthly Transactions.
Number of transactions per month.		 M
expectAmountPerMonth Numeric Estimated Monthly Transaction Amount in USD.
Amount (no decimal places).		 M
companyAssets Numeric Company Assets
Amount (no decimal places). Total assets (total liability + total equity).		 M
branchCountry varchar(100) Country of Client Branches.
Three-letter ISO country codes. For multiple countries, separate with commas. Example: GBR,SGP,HKG,CHN. Refer to the country code table.		 M
beneficialCountry varchar(100) Beneficiary's Country.
Three-letter ISO country codes. For multiple countries, separate with commas. Example: GBR,SGP,HKG,CHN. Refer to the country code table.		 M
supplyCountry varchar(100) Country of Main Suppliers.
Three-letter ISO country codes. For multiple countries, separate with commas. Example: GBR,SGP,HKG,CHN. Refer to the country code table.		 M
buyCountry varchar(100) Country of Main Buyers.
Three-letter ISO country codes. For multiple countries, separate with commas. Example: GBR,SGP,HKG,CHN. Refer to the country code table.		 M

Request Parameters（beneficialList，Beneficiary Information）

Name Type&Length Description Required
name varchar(100) English name. M
idType Enum ID Type:
HK IDENTITY CARD 
PASSPORT NO
FOREIGN NATIONAL ID
IDENTITY CARD
OTHER		 M
idNo varchar(30) ID Number:
Length requirements vary by ID type:
HK IDENTITY CARD: 7 digits;
PASSPORT NO: 9 digits;
IDENTITY CARD: 18 digits;
FOREIGN NATIONAL ID/OTHER: <= 30 digits.		 M
address varchar(180) Residential address. M
stockPercent varchar(3) Equity Share %.
Percentage of equity held. Supports values up to 100 and up to 2 decimal places. For example, if the equity share is 30.87%, pass 30.87.		 M
addressProofList varchar(200) Proof of Residential Address.
Path for SFTP file upload. Documents can include rental contracts, utility bills within the last 3 months, company bank statements for the last 3 months, or tax documents within the last 12 months.
Up to 3 files, each not exceeding 10MB.
File formats: PNG, JPG, JPEG, PDF, ZIP.		 M
picList varchar(200) Identification Photos.
Path for SFTP file upload. Includes photos of the ID (front and back) and certified ID information by a lawyer. Up to 3 files, each not exceeding 10MB. File formats: PNG, JPG, JPEG, PDF, ZIP.		 M

Request Parameters（legalList，Legal Representative Information）

Name Type&Length Description Required
name varchar(100) English name. M
idType Enum ID Type:
HK IDENTITY CARD
PASSPORT NO
FOREIGN NATIONAL ID
IDENTITY CARD
OTHER		 M
idNo varchar(30) ID Number. Length requirements vary by ID type: HK IDENTITY CARD: 7 digits; PASSPORT NO: 9 digits; IDENTITY CARD: 18 digits; FOREIGN NATIONAL ID / OTHER: <= 30 digits. M
address varchar(180) Residential address. M
addressProofList varchar(200) Proof of Residential Address;
Path for SFTP file upload. Documents can include rental contracts, utility bills within the last 3 months, company bank statements for the last 3 months, or tax documents within the last 12 months. Up to 3 files, each not exceeding 10MB. File formats: PNG, JPG, JPEG, PDF, ZIP.		 M
picList varchar(200) Identification Photos. Path for SFTP file upload. Includes photos of the ID (front and back) and certified ID information by a lawyer. Up to 3 files, each not exceeding 10MB. File formats: PNG, JPG, JPEG, PDF, ZIP. M

Request Parameters （authorizedList，Authorized Person Information）

Name Type&Length Description Required
name varchar(100) English name. M
idType Enum ID Type:
HK IDENTITY CARD
PASSPORT NO
FOREIGN NATIONAL ID
IDENTITY CARD
OTHER		 M
idNo varchar(30) ID Number.
Length requirements vary by ID type:
HK IDENTITY CARD: 7 digits;
PASSPORT NO: 9 digits;
IDENTITY CARD: 18 digits;
FOREIGN NATIONAL ID / OTHER: <= 30 digits.		 M
address varchar(180) Residential address. M
addressProofList varchar(200) Proof of Residential Address.
Path for SFTP file upload. Documents can include rental contracts, utility bills within the last 3 months, company bank statements for the last 3 months, or tax documents within the last 12 months. Up to 3 files, each not exceeding 10MB. File formats: PNG, JPG, JPEG, PDF, ZIP.		 M
picList varchar(200) Identification Photos.
Path for SFTP file upload. Includes photos of the ID (front and back) and certified ID information by a lawyer. Up to 3 files, each not exceeding 10MB. File formats: PNG, JPG, JPEG, PDF, ZIP.		 M

Request Parameters（certificate，Qualification Documents）

Name Type&Length Description Required
registrationCertificatePath varchar(200) Company Registration Certificate.
For non-Chinese enterprises, a copy of the company registration certificate must be uploaded. For Chinese enterprises, a copy of the business license or its duplicate must be uploaded. Only 1 file is allowed, with a maximum size of 10MB. File formats: PNG, JPG, JPEG, PDF, ZIP.		 M
businessRegistrationPath varchar(200) Business Registration Certificate
Required when it’s the Hong Kong enterprise. Only 1 file is allowed, with a maximum size of 10MB. File formats: PNG, JPG, JPEG, PDF, ZIP.		 C
annualDeclarationList varchar(200) Annual Declaration.
Required when it’s the Hong Kong enterprise. Up to 5 files are allowed, each with a maximum size of 10MB. File formats: PNG, JPG, JPEG, PDF, ZIP.		 C
addressProofList varchar(200) Office Location Proof.
Office photos (1 indoor and 1 outdoor showing the storefront), rental contract, utility bills within the last 3 months, company bank statements for the last 3 months, or tax documents within the last 12 months. Up to 5 files are allowed, each with a maximum size of 10MB. File formats: PNG, JPG, JPEG, PDF, ZIP.		 M
stockProofList varchar(200) Company Stock Ownership Documents.
Up to 5 files are allowed, each with a maximum size of 10MB. File formats: PNG, JPG, JPEG, PDF, ZIP.		 O
otherList varchar(200) Other Documents
Up to 5 files are allowed, each with a maximum size of 10MB. File formats: PNG, JPG, JPEG, PDF, ZIP.		 O

Sample

{ "business": { "enterCurrency": "HKD", "businessNature": "公司业务性质TEST 123**卖衣服,电商買卖平台，电脑编程/旅游中介", "companyAssets": 1234567800, "cashFlowPathList": [ "test.pdf", "test.jpg", "test.zip" ], "expectNumberPerMonth": 12345678, "branchCountry": "HKG", "beneficialCountry": "HKG", "buyCountry": "HKG", "cashSourceCountry": "HKG", "lastYearSaleAmount": 1234567800, "cashSourceDesc": "cashSource abcdef", "cashSource": "Goods Payment,Service Rendered,Commission,Others", "enterForUseDesc": "汇款资金用途描述", "tradeMode": "P2P,B2B,B2C,C2B", "enterForUse": "Settlement,Daily Operation,Others", "expectAmountPerMonth": 1234567800, "outCurrency": "HKD", "productType": "Communication service", "supplyCountry": "HKG", "businessModeDesc": "业务模式描述TEST 123**_详细描述业务模式,汇入及汇出币种，附上资金流动图说明资金来源及去向" }, "legalList": [ { "addressProofList": [ "test.jpg", "test.pdf", "test.zip" ], "address": "董事-居住地址test 001*01", "idType": "HK IDENTITY CARD", "picList": [ "test.jpg", "test.pdf", "test.zip" ], "name": "Dongshi name", "idNo": "HKG***1234" } ], "personalDataProtection": "Y", "certificate": { "addressProofList": [ "test.pdf", "test.jpg", "test.zip" ], "annualDeclarationList": [ "test.pdf", "test.jpg", "test.zip" ], "registrationCertificatePath": "test.pdf", "businessRegistrationPath": "test.pdf", "otherList": [], "stockProofList": [] }, "type": "CREATE", "authorizedList": [ { "addressProofList": [ "test.jpg", "test.zip", "test.pdf" ], "address": "授权人-居住地址test 001*01", "idType": "FOREIGN NATIONAL ID", "picList": [ "test.jpg", "test.zip", "test.pdf" ], "name": "Shouquan renName", "idNo": "TES***890a" } ], "merchantId": "G70000414", "requestId": "1725270382149", "beneficialList": [ { "addressProofList": [ "test.jpg", "test.zip", "test.pdf" ], "address": "持股人-居住地址test 001*01", "idType": "IDENTITY CARD", "stockPercent": "66.66", "picList": [ "test.jpg", "test.zip", "test.pdf" ], "name": "Chigu ren name", "idNo": "132***287X" } ], "hmac": "fJkEOep1OD7D6iKameESlpNWs+h1PvRYYOJUhniLTOjWilQGN9w2eXSa2qdDSElJ6xy1ZgcLrmw0RjRzUXaH3mn2sfYs6oTR/sUAoj+f6GrkRO5kHmlRN/hJ/wlA5FE2VIgIANgZI/ZpyPuGRt74zJkz4Nwy20EVCuMDSrwT/Opk1Njz74OdAPbaCNmQQtMQvGRw3dNVl8ewPkMfmuPPU8RcPs2depJ8tsM/ZAXPoJBQi3Qlaf1a4y5SMK9Lzj3kRlY4DW/FLHR5eODlIdia1id5wMgRlj6ndZbViqnvtfwxZniC1cAb8z14Glso3HUH/cfw3phX9roj+lnkBboHKg==", "notifyUrl": "https://qa-sdk-v2.geoswift.com/va/declaration/notify", "company": { "brStartDate": "20101111", "country": "HKG", "brandName": "Maisons 品牌名称", "brEndDate": "20301212", "companyType": "4", "licenseNumberEndDate": "", "addressType": "1", "ci": "GSZCH12", "establishDate": "19190909", "legalPersonName": "Fa ****** name", "br": "SYZZH123", "companyTypeDesc": "", "webSite": "https://www.geoswift.com/", "registerAddress": "zc Route ***** Switzerland", "signedName": "VA test-0001", "licenseNumberStartDate": "", "phone": "152****4190", "licenseNumber": "", "registerNumber": "", "businessAddress": "jy*****Chavannes", "shortName": "VA test jiancheng-001", "usedName": "", "email": "1725******@163.com" }, "agreeCooperationAgreement": "Y" }

Response Parameter List

Name Description
merchantId Merchant ID; Same as the request parameter.
requestId Same as the request parameter.
subMerchantId Sub Merchant Id
status Request Status:
SUCCESS
ERROR
errorCode Error code returned when the order is canceled or failed.
errorMessage Error description returned when the order is canceled or failed.
hmac Parameter signature generated by Geoswift. For the verification process, refer to the "Geoswift Encryption and Decryption Process Specifications".

Sample

{ "businessStatus": "SUCCESS", "hmac": "itcl29/BJ5HSd3prcpcRAvOUfb7Cdhw==", "merchantId": "G70000414", "requestId": "1725270382149", "status": "SUCCESS", "subMerchantId": "G70000420" }

2.7.Asynchronous callback Notification(Webhook)

Any review action that occurs during the merchant onboarding request will be notified to the merchant through this webhook. The sub-merchant's onboarding information will only take effect once the sub-merchant's status has passed the review."

Name Description
merchantId Same as the request parameter.
requestId Same as the request parameter.
subMerchantId Sub-merchant ID
type Operation Type:
CREATE
MODIFY
reviewStatus Sub-Merchant Review Status:
INIT
SUCCESS
REFUSE
RETURN
reviewRemarks Sub-Merchant Review Remarks
hmac Parameter signature generated by the merchant. For how to obtain the hmac, refer to the "Geoswift Encryption and Decryption Process Specifications".