Skip to main content
POST
/
api
/
v2.1
/
fincard
/
virtual
/
card
/
holder
/
create
Create Cardholder (Deprecated)
curl --request POST \
  --url https://sandbox.finhub.cloud/api/v2.1/fincard/virtual/card/holder/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>",
  "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
  }
}

Documentation Index

Fetch the complete documentation index at: https://docs.finhub.cloud/llms.txt

Use this file to discover all available pages before exploring further.

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 request

Create cardholder request (V1)

​
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]

​
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