Create a Cardholder

Create a cardholder and submit their identity documents for KYC review. The cardholder enters PENDING on creation and becomes ACTIVE once the review passes. The response returns the complete Cardholder resource, so no follow-up query is required.
Request Parameters
requestIdstring
required
Idempotency key for this cardholder-creation request. Assign a unique UUID per request so that a retry never creates a duplicate cardholder. Max 64 characters.
typestring
required
Cardholder type. This value determines how the uploaded identification files are interpreted.

Valid Values:

EMPLOYEE — An employee of your business.
SHAREHOLDER — A shareholder or beneficial owner of your business.
personInfoPersonInfo
required
Personal details of the cardholder, used for KYC verification.
Show child parametersShow child parameters
nationalitystring
required
Cardholder's nationality, as a three-letter country code following the ISO 3166-1 alpha-3 standard (for example, CHN).
identificationIdentification
required
Identity documents submitted for KYC review.
Show child parametersShow child parameters
Response Parameters
resultResult
See Result.
idstring
Unique cardholder identifier. Use this ID to query, list, or delete the cardholder, and to issue cards to them. Max 64 characters.
typestring
Cardholder type, echoed from the request.

Valid Values:

EMPLOYEE — An employee of your business.
SHAREHOLDER — A shareholder or beneficial owner of your business.
statusstring
Current cardholder status. Always PENDING immediately after creation.

Valid Values:

PENDING — Under review, awaiting KYC verification.
ACTIVE — Review passed; cards can now be issued to this cardholder.
FAILED — Review failed or the cardholder was rejected.
personInfoPersonInfo
Personal details of the cardholder, echoed from the request.
Show child parametersShow child parameters
nationalitystring
Cardholder's nationality, as a three-letter ISO 3166-1 alpha-3 country code.
createdAtdatetime
Timestamp when the cardholder was created. ISO 8601 extended format.
Error Codes
resultCoderesultStatusresultMessageTroubleshooting
SUCCESSSSuccess.Cardholder created and submitted for review.
PARAM_ILLEGALFIllegal parameters exist.Verify `type`, `nationality` (ISO 3166-1 alpha-3) and `personInfo.dateOfBirth` (`yyyy-MM-dd`) against this reference.
DUPLICATE_CARDHOLDERFThe cardholder information is duplicated.A cardholder with the same identity already exists. Look it up with List Cardholders instead of creating a duplicate.
CONTRACT_CHECK_FAILFThe contract check has failed.Contact WorldFirst support to confirm the contract status, then retry.
AUTHORIZATION_NOT_EXISTFThe authorization relationship does not exist.Verify the `account-id` / `access-token` authorization before retrying.
USER_NOT_EXISTFThe user does not exist.Retry with correct user information.
RISK_REJECTFThe request was rejected by risk control.Do not retry. Contact WorldFirst support with the `requestId`.
Definition
POST /api/open/v1/issuing/cardholders/create
Request
{
"requestId": "req_20240115_001",
"type": "EMPLOYEE",
"personInfo": {
  "userName": {
    "firstName": "San",
    "lastName": "Zhang"
  },
  "dateOfBirth": "1990-06-15"
},
"nationality": "CHN",
"identification": {
  "fileList": [
    {
      "fileKey": "file_key_001",
      "fileName": "passport_front.jpg"
    },
    {
      "fileKey": "file_key_002",
      "fileName": "relationship_proof.jpg"
    }
  ]
}
}
Response
{
"result": {
  "resultCode": "SUCCESS",
  "resultMessage": "success",
  "resultStatus": "S"
},
"id": "ch_abc123xyz",
"type": "EMPLOYEE",
"status": "PENDING",
"personInfo": {
  "userName": {
    "firstName": "San",
    "lastName": "Zhang",
    "fullName": "San Zhang"
  },
  "dateOfBirth": "1990-06-15"
},
"nationality": "CHN",
"createdAt": "2024-01-15T08:00:00Z"
}