Skip to main content
POST
/
api
/
v2.1
/
fincard
/
virtual
/
card
/
holder
/
v2
/
create
Create Cardholder V2
curl --request POST \
  --url https://sandbox.finhub.cloud/api/v2.1/fincard/virtual/card/holder/v2/create \
  --header 'Content-Type: application/json' \
  --header 'X-Forwarded-From: <x-forwarded-from>' \
  --data '
{
  "cardholderType": "<string>",
  "merchantOrderNo": "<string>",
  "cardTypeId": 123,
  "areaCode": "<string>",
  "mobile": "<string>",
  "email": "<string>",
  "firstName": "<string>",
  "lastName": "<string>",
  "birthday": "<string>",
  "country": "<string>",
  "town": "<string>",
  "address": "<string>",
  "postCode": "<string>",
  "nationality": "<string>",
  "gender": "<string>",
  "occupation": "<string>",
  "annualSalary": "<string>",
  "accountPurpose": "<string>",
  "expectedMonthlyVolume": "<string>",
  "idType": "<string>",
  "idNumber": "<string>",
  "issueDate": "<string>",
  "idNoExpiryDate": "<string>",
  "idFrontId": "<string>",
  "idBackId": "<string>",
  "personalInfo": {
    "firstName": "John",
    "lastName": "Doe",
    "middleName": "William",
    "dateOfBirth": "1990-01-15T00:00:00.000Z",
    "gender": "MALE",
    "nationality": "US",
    "email": "john.doe@example.com",
    "phoneNumber": "+1234567890",
    "mobileNumber": "+1234567890"
  },
  "residentialAddress": {
    "addressLine1": "123 Main St",
    "addressLine2": "Apt 4B",
    "city": "New York",
    "state": "NY",
    "postalCode": "10001",
    "country": "US",
    "addressType": "RESIDENTIAL",
    "isPrimary": true
  },
  "employmentInfo": {
    "employerName": "Tech Corp",
    "occupationCode": "001",
    "occupationTitle": "Software Engineer",
    "industry": "TECHNOLOGY",
    "employmentStatus": "FULL_TIME",
    "employmentStartDate": "2020-01-01T00:00:00.000Z",
    "monthlyIncome": 5000,
    "annualIncome": 60000,
    "incomeCurrency": "USD",
    "employerAddress": {
      "addressLine1": "123 Main St",
      "addressLine2": "Apt 4B",
      "city": "New York",
      "state": "NY",
      "postalCode": "10001",
      "country": "US",
      "addressType": "RESIDENTIAL",
      "isPrimary": true
    }
  },
  "kycDocuments": [
    {
      "documentType": "PASSPORT",
      "documentNumber": "AB123456789",
      "documentExpiryDate": "2030-01-15T00:00:00.000Z",
      "documentIssueDate": "2020-01-15T00:00:00.000Z",
      "documentIssuingCountry": "US",
      "documentFrontImageUrl": "https://example.com/doc-front.jpg",
      "documentBackImageUrl": "https://example.com/doc-back.jpg",
      "selfieImageUrl": "https://example.com/selfie.jpg",
      "verificationStatus": "PENDING"
    }
  ]
}
'
{
  "success": true,
  "code": 200,
  "msg": "Success",
  "data": {
    "cardholderId": "ch-12345678",
    "accountId": "wsb-12345678",
    "cardholderReference": "REF123456",
    "personalInfo": {
      "firstName": "John",
      "lastName": "Doe",
      "middleName": "William",
      "dateOfBirth": "1990-01-15T00:00:00.000Z",
      "gender": "MALE",
      "nationality": "US",
      "email": "john.doe@example.com",
      "phoneNumber": "+1234567890",
      "mobileNumber": "+1234567890"
    },
    "residentialAddress": {
      "addressLine1": "123 Main St",
      "addressLine2": "Apt 4B",
      "city": "New York",
      "state": "NY",
      "postalCode": "10001",
      "country": "US",
      "addressType": "RESIDENTIAL",
      "isPrimary": true
    },
    "mailingAddress": {
      "addressLine1": "123 Main St",
      "addressLine2": "Apt 4B",
      "city": "New York",
      "state": "NY",
      "postalCode": "10001",
      "country": "US",
      "addressType": "RESIDENTIAL",
      "isPrimary": true
    },
    "employmentInfo": {
      "employerName": "Tech Corp",
      "occupationCode": "001",
      "occupationTitle": "Software Engineer",
      "industry": "TECHNOLOGY",
      "employmentStatus": "FULL_TIME",
      "employmentStartDate": "2020-01-01T00:00:00.000Z",
      "monthlyIncome": 5000,
      "annualIncome": 60000,
      "incomeCurrency": "USD",
      "employerAddress": {
        "addressLine1": "123 Main St",
        "addressLine2": "Apt 4B",
        "city": "New York",
        "state": "NY",
        "postalCode": "10001",
        "country": "US",
        "addressType": "RESIDENTIAL",
        "isPrimary": true
      }
    },
    "kycDocuments": [
      {
        "documentType": "PASSPORT",
        "documentNumber": "AB123456789",
        "documentExpiryDate": "2030-01-15T00:00:00.000Z",
        "documentIssueDate": "2020-01-15T00:00:00.000Z",
        "documentIssuingCountry": "US",
        "documentFrontImageUrl": "https://example.com/doc-front.jpg",
        "documentBackImageUrl": "https://example.com/doc-back.jpg",
        "selfieImageUrl": "https://example.com/selfie.jpg",
        "verificationStatus": "PENDING"
      }
    ],
    "cardholderType": "B2B",
    "riskLevel": "LOW",
    "kycLevel": "STANDARD",
    "sourceOfFunds": "SALARY",
    "purposeOfAccount": "PERSONAL_USE",
    "politicallyExposedPerson": false,
    "sanctionsScreeningRequired": true,
    "cardholderStatus": "ACTIVE",
    "kycStatus": "VERIFIED",
    "verificationTime": 1640995200000,
    "createTime": 1640995200000,
    "updateTime": 1640995200000,
    "numberOfCards": 2,
    "activeCards": 2
  }
}

Headers

User-Agent
string

User agent

X-Forwarded-For
string

Forwarded for

X-Forwarded-From
string
required

Client application identifier

Example:

"client-app"

X-Tenant-ID
string

Tenant ID

deviceId
string

Device ID

platform
string

Platform

Body

application/json

Create cardholder V2 request

Create cardholder request (V2)

cardholderType
string
required

Cardholder business model: B2B or B2C

merchantOrderNo
string
required

Client transaction reference. length[20...40]

cardTypeId
integer<int64>
required

Card type ID (from Support Bins)

areaCode
string
required

Mobile area code. length[2...5]

mobile
string
required

Mobile phone number. length[5...20]

email
string
required

Email. length[5...50]

firstName
string
required

First name. English only. length[2...32]

lastName
string
required

Last name. English only. length[2...32]

birthday
string
required

Date of birth (yyyy-MM-dd)

country
string
required

Country/Region Code (ISO 3166-1 alpha-2)

town
string
required

City code

address
string
required

Address. length[2...40]

postCode
string
required

Postal code. length[2...15]

nationality
string

Nationality Code (ISO 3166-1 alpha-2). Required for B2C

gender
string

Gender: M (male), F (female). B2C only

occupation
string

Occupation code. B2C only

annualSalary
string

Annual salary. B2C only

accountPurpose
string

Account purpose. B2C only

expectedMonthlyVolume
string

Expected monthly trading volume. B2C only

idType
string

ID type: PASSPORT, HK_HKID, DLN, GOVERNMENT_ISSUED_ID_CARD. B2C only

idNumber
string

ID number. B2C only

issueDate
string

ID issuance date (yyyy-MM-dd). B2C only

idNoExpiryDate
string

ID expiry date (yyyy-MM-dd). B2C only

idFrontId
string

ID front image file ID (from upload API). B2C only

idBackId
string

ID back image file ID (from upload API). B2C only

personalInfo
object

Personal information (BFF structured alternative)

residentialAddress
object

Residential address (BFF structured alternative)

employmentInfo
object

Employment information

kycDocuments
object[]

KYC documents

Response

Successful response

Create cardholder response

success
boolean

Success flag

Example:

true

code
integer<int32>

Response code

Example:

200

msg
string

Response message

Example:

"Success"

data
object

Created cardholder data