Create a Connected Account

Register and onboard a new connected merchant to WorldFirst for your users, merchants, subsidiaries, business partners or clients. Submit the required merchant's business information, contact details, and legal entity data for KYC/KYB verification. Note: This endpoint is available to approved partners only. Contact us at techsupport**__**@**__**worldfirst.com — our team is ready to assist you.
Request Parameters
When legal entity type = COMPANY
referenceAccountIdstring
required
A unique merchant identifier on the partner side. Use as an idempotency key — duplicate submissions with the same value return the original result. Maximum length: 64 characters.
registrationRegionstring
required
Registration country/region. ISO 3166-1 alpha-2 two-letter code (e.g., US, GB, HK, CN).
registrationLegalNamestring
required
Registered legal entity name of the company. Maximum length: 128 characters.
contactContact
required
Contact information for the registration application.
Show child parametersShow child parameters
legalEntityInfoLegalEntityInfo
required
Legal entity information for KYB review.
Show child parametersShow child parameters
agreementsAgreements
required
Record of the user's agreement to WorldFirst terms and conditions.
Show child parametersShow child parameters
Response Parameters
resultResult
API call result. See Result.
statusstring
Account registration status. See AccountStatus.
idstring
WorldFirst-assigned unique merchant identifier. The ID is generated after the account is created and will be returned via Webhook. This may take some time.
referenceAccountIdstring
Integrator-side merchant identifier.
createdAtdatetime
Account creation timestamp. ISO 8601 extended format. See Data Types.
Error Codes
resultCoderesultStatusresultMessageTroubleshooting
SUCCESSSsuccessN/A
REPEAT_REGISTRATIONFRegistration for the merchant is repeatedA merchant with the same `referenceAccountId` already exists. Use Query to check the existing account.
REGISTRATION_UNDER_REVIEWFA previously submitted registration is currently under reviewWait for the review to complete. No new registration or modification is allowed.
REGISTRATION_CLOSEDFRegistration has been closedThe registration was closed. Contact WorldFirst support.
INVALID_PHONE_FORMATFPhone number format invalidCheck `contactPhone` format.
INVALID_EMAIL_FORMATFEmail format invalidCheck `contactEmail` format.
UN_SUPPORT_BUSINESSFUnsupported businessThe region or entity type is not supported.
INVOKE_IMEMBERPROD_FAILFAn internal service invocation failed.Retry the request. If the issue persists, contact WorldFirst support.
PARAM_ILLEGALFController information is required when there is no UBO.Recheck the request. Provide required info to retry again.
PARAM_ILLEGALFBusiness ContactEntities is empty, controller or UBO information is required.Recheck the request. Provide required info to retry again.
Definition
POST /api/open/v1/accounts/create
Request
{
"referenceAccountId": "partner-merchant-001",
"contact": {
  "contactEmail": "support@merchant-example.com"
},
"registrationRegion": "CN",
"registrationLegalName": "Example Trading Co., Ltd.",
"agreements": {
  "agreedToTermsAndConditions": true,
  "agreedToDataUsage": true
},
"legalEntityInfo": {
  "legalEntityType": "COMPANY",
  "company": {
    "legalName": "Example Trading Co., Ltd.",
    "registrationType": "ENTERPRISE_REGISTRATION_CN",
    "registrationNo": "91360100MA3XXXXX",
    "registrationDate": "2020-01-01T00:00:00+08:00",
    "registrationAddress": {
      "region": "CN",
      "state": "Jiangxi",
      "city": "Nanchang",
      "address1": "No. 85 Jiefang West Road, Qingyunpu District"
    },
    "englishRegistrationAddress": {
      "region": "CN",
      "state": "Jiangxi Province",
      "city": "Nanchang City",
      "address1": "No. 85, Jiefang West Road, Qingyunpu District"
    },
    "enterpriseType": "UNIPO",
    "certificates": [
      {
        "certificateType": "ENTERPRISE_REGISTRATION",
        "certificateNo": "91360100MA3XXXXX",
        "files": [
          "file-key-biz-license-001"
        ],
        "holderName": "Example Trading Co., Ltd.",
        "effectivePeriodType": "LONG_TERM",
        "effectiveDate": "2020-01-01T00:00:00+08:00"
      }
    ],
    "attachments": [
      {
        "attachmentKey": "file-key-biz-license-001",
        "attachmentName": "business_license.pdf",
        "attachmentType": "BUSINESS_LICENSE"
      }
    ]
  },
  "businessProfile": {
    "businessName": "Example Trading Co., Ltd.",
    "englishBusinessName": "Example Trading Co., Ltd.",
    "industryType": "N046",
    "brand": "ExTrade",
    "operatingRegions": [
      "US",
      "GB",
      "DE"
    ],
    "goodsOrServices": [
      "Electronics",
      "Accessories"
    ],
    "websites": [
      "https://www.example-trading.com"
    ],
    "businessAddress": {
      "region": "CN",
      "city": "Nanchang",
      "address1": "No. 85 Jiefang West Road, Qingyunpu District"
    }
  },
  "relatedParties": [
    {
      "relationship": "LEGAL_REPRESENTATIVE",
      "legalEntityType": "INDIVIDUAL",
      "individual": {
        "legalName": "San Zhang",
        "userName": {
          "fullName": "Zhang San",
          "firstName": "San",
          "lastName": "Zhang"
        },
        "userEnglishName": {
          "fullName": "San Zhang",
          "firstName": "San",
          "lastName": "Zhang"
        },
        "gender": "MALE",
        "nationality": "CN",
        "birthDate": "1990-01-01T00:00:00+08:00",
        "residentAddress": {
          "region": "CN",
          "city": "Beijing",
          "address1": "No.XX, XX Road, Haidian District",
          "zipCode": "100080"
        },
        "certificates": [
          {
            "certificateType": "ID_CARD",
            "certificateNo": "1101011990******",
            "files": [
              "file-key-id-front-001",
              "file-key-id-back-001"
            ],
            "holderName": "San Zhang",
            "effectivePeriodType": "TIME_RANGE",
            "effectiveDate": "2015-01-01T00:00:00+08:00",
            "expireDate": "2035-01-01T00:00:00+08:00"
          }
        ],
        "attachments": [
          {
            "attachmentKey": "file-key-id-front-001",
            "attachmentName": "id_card_front.jpg",
            "attachmentType": "ID_CARD_FRONT_SIDE"
          },
          {
            "attachmentKey": "file-key-id-back-001",
            "attachmentName": "id_card_back.jpg",
            "attachmentType": "ID_CARD_BACK_SIDE"
          }
        ]
      }
    },
    {
      "relationship": "BENEFICIAL_OWNER",
      "legalEntityType": "INDIVIDUAL",
      "shareHoldingRatio": "0.80",
      "individual": {
        "legalName": "San Zhang",
        "userName": {
          "fullName": "Zhang San"
        },
        "userEnglishName": {
          "fullName": "San Zhang"
        },
        "nationality": "CN",
        "birthDate": "1990-01-01T00:00:00+08:00",
        "residentAddress": {
          "region": "CN",
          "city": "Beijing"
        },
        "certificates": [
          {
            "certificateType": "ID_CARD",
            "certificateNo": "1101011********",
            "files": [
              "file-key-id-front-001",
              "file-key-id-back-001"
            ],
            "holderName": "San Zhang",
            "effectivePeriodType": "TIME_RANGE",
            "effectiveDate": "2015-01-01T00:00:00+08:00",
            "expireDate": "2035-01-01T00:00:00+08:00"
          }
        ],
        "attachments": []
      }
    },
    {
      "relationship": "DIRECTOR",
      "legalEntityType": "INDIVIDUAL",
      "individual": {
        "legalName": "Si Li",
        "userName": {
          "fullName": "Li Si",
          "firstName": "Si",
          "lastName": "Li"
        },
        "userEnglishName": {
          "fullName": "Si Li",
          "firstName": "Si",
          "lastName": "Li"
        },
        "nationality": "CN",
        "birthDate": "1985-06-15T00:00:00+08:00",
        "residentAddress": {
          "region": "CN",
          "city": "Shanghai"
        },
        "certificates": [
          {
            "certificateType": "ID_CARD",
            "certificateNo": "3101011985****",
            "files": [
              "file-key-id-front-002",
              "file-key-id-back-002"
            ],
            "holderName": "Si Li",
            "effectivePeriodType": "TIME_RANGE",
            "effectiveDate": "2018-03-01T00:00:00+08:00",
            "expireDate": "2038-03-01T00:00:00+08:00"
          }
        ],
        "attachments": []
      }
    }
  ]
}
}
Response
{
"result": {
  "resultCode": "SUCCESS",
  "resultStatus": "S",
  "resultMessage": "success"
},
"status": "PROCESSING",
"id": "2188123456789012",
"referenceAccountId": "partner-merchant-001",
"createdAt": "2026-06-25T10:00:00+08:00"
}