> ## 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.

# Create Cardholder V2

> Create cardholder with B2B or B2C model, KYC documents



## OpenAPI

````yaml post /api/v2.1/fincard/virtual/card/holder/v2/create
openapi: 3.1.0
info:
  title: Business BFF API
  version: 1.0.0
  description: Backend for Frontend - Business Panels Orchestration Layer
servers:
  - url: https://sandbox.finhub.cloud
    description: Sandbox Environment
security: []
tags:
  - name: AML
    description: Anti-Money Laundering checks and transaction monitoring
  - name: Admin - Consent Management
    description: Operations for managing consent templates and definitions
  - name: B2B Customer - Organization
    description: B2B organization registration and management
  - name: B2C Customer - Individual
    description: Individual customer registration and lifecycle management
  - name: BFF Admin - Tenant Initialization
    description: Lazy tenant initialization for fast startup
  - name: Catalog Hierarchy
    description: Hierarchical catalog management APIs
  - name: Catalog-Process Mapping
    description: APIs for catalog-process relationship management
  - name: Consent
    description: Payment consent creation and approval
  - name: Draft Management
  - name: External Events
    description: Kafka-to-HTTP bridge event ingestion and query
  - name: FinCard Virtual - Webhooks
    description: FinCard Virtual Card Webhook receiver
  - name: FinCard Virtual Account
    description: FinCard Virtual Card Account API proxy
  - name: FinCard Virtual Card Holder
    description: FinCard Virtual Card Holder API proxy
  - name: FinCard Virtual Cards
    description: FinCard Virtual Card API proxy
  - name: FinCard Virtual Common
    description: FinCard Virtual Card Common API proxy
  - name: FinCard Virtual Wallet
    description: FinCard Virtual Card Wallet API v2 proxy
  - name: FinTrans - Operations
    description: Financial transaction operations
  - name: Internal Webhooks
    description: Internal service-to-service webhook trigger (HMAC-secured)
  - name: MFE Preload
    description: MFE preload endpoints for SSR optimization
  - name: MFE Registry
    description: MFE Registry management endpoints
  - name: Payment Consent Management
    description: Operations for managing payment consents and validation
  - name: Person
    description: Person details for process context
  - name: Products
    description: Product Catalog Management API
  - name: Reference Data
    description: Shared reference data (countries, etc.)
  - name: Tenant Lifecycle
    description: Tenant mode transitions and lifecycle management
  - name: Tenant Registration
    description: Self-registration and tenant onboarding
  - name: Transfers
    description: Transfer prepare/execute aliases for muse-proxy compatibility
  - name: Verification
    description: Customer verification (KYC/KYB/AML) management
  - name: Wallet
    description: Wallet operations and balance management
  - name: Webhooks
    description: Webhook subscription and delivery management
paths:
  /api/v2.1/fincard/virtual/card/holder/v2/create:
    post:
      tags:
        - FinCard Virtual Card Holder
      summary: Create Cardholder V2
      description: Create cardholder with B2B or B2C model, KYC documents
      parameters:
        - description: User agent
          name: User-Agent
          in: header
          schema:
            type: string
        - description: Forwarded for
          name: X-Forwarded-For
          in: header
          schema:
            type: string
        - $ref: '#/components/parameters/XForwardedFromHeader'
        - description: Tenant ID
          name: X-Tenant-ID
          in: header
          schema:
            type: string
        - description: Device ID
          name: deviceId
          in: header
          schema:
            type: string
        - description: Platform
          name: platform
          in: header
          schema:
            type: string
      requestBody:
        description: Create cardholder V2 request
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCardholderV2Request'
        required: true
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateCardholderResponse'
        '400':
          description: Bad request
        '500':
          description: Internal server error
components:
  parameters:
    XForwardedFromHeader:
      name: X-Forwarded-From
      in: header
      required: true
      description: Client application identifier
      schema:
        type: string
        example: client-app
  schemas:
    CreateCardholderV2Request:
      type: object
      required:
        - cardholderType
        - merchantOrderNo
        - cardTypeId
        - areaCode
        - mobile
        - email
        - firstName
        - lastName
        - birthday
        - country
        - town
        - address
        - postCode
      description: Create cardholder request (V2)
      properties:
        cardholderType:
          type: string
          description: 'Cardholder business model: B2B or B2C'
        merchantOrderNo:
          type: string
          description: Client transaction reference. length[20...40]
        cardTypeId:
          type: integer
          format: int64
          description: Card type ID (from Support Bins)
        areaCode:
          type: string
          description: Mobile area code. length[2...5]
        mobile:
          type: string
          description: Mobile phone number. length[5...20]
        email:
          type: string
          description: Email. length[5...50]
        firstName:
          type: string
          description: First name. English only. length[2...32]
        lastName:
          type: string
          description: Last name. English only. length[2...32]
        birthday:
          type: string
          description: Date of birth (yyyy-MM-dd)
        nationality:
          type: string
          description: Nationality Code (ISO 3166-1 alpha-2). Required for B2C
        country:
          type: string
          description: Country/Region Code (ISO 3166-1 alpha-2)
        town:
          type: string
          description: City code
        address:
          type: string
          description: Address. length[2...40]
        postCode:
          type: string
          description: Postal code. length[2...15]
        gender:
          type: string
          description: 'Gender: M (male), F (female). B2C only'
        occupation:
          type: string
          description: Occupation code. B2C only
        annualSalary:
          type: string
          description: Annual salary. B2C only
        accountPurpose:
          type: string
          description: Account purpose. B2C only
        expectedMonthlyVolume:
          type: string
          description: Expected monthly trading volume. B2C only
        idType:
          type: string
          description: 'ID type: PASSPORT, HK_HKID, DLN, GOVERNMENT_ISSUED_ID_CARD. B2C only'
        idNumber:
          type: string
          description: ID number. B2C only
        issueDate:
          type: string
          description: ID issuance date (yyyy-MM-dd). B2C only
        idNoExpiryDate:
          type: string
          description: ID expiry date (yyyy-MM-dd). B2C only
        idFrontId:
          type: string
          description: ID front image file ID (from upload API). B2C only
        idBackId:
          type: string
          description: ID back image file ID (from upload API). B2C only
        personalInfo:
          $ref: '#/components/schemas/PersonalInfo'
          type: object
          description: Personal information (BFF structured alternative)
        residentialAddress:
          $ref: '#/components/schemas/AddressInfo'
          type: object
          description: Residential address (BFF structured alternative)
        employmentInfo:
          $ref: '#/components/schemas/EmploymentInfo'
          type: object
          description: Employment information
        kycDocuments:
          type: array
          items:
            $ref: '#/components/schemas/KycDocument'
          description: KYC documents
    CreateCardholderResponse:
      type: object
      description: Create cardholder response
      properties:
        success:
          type: boolean
          examples:
            - true
          description: Success flag
          example: true
        code:
          type: integer
          format: int32
          examples:
            - 200
          description: Response code
          example: 200
        msg:
          type: string
          examples:
            - Success
          description: Response message
          example: Success
        data:
          $ref: '#/components/schemas/CardholderData'
          type: object
          description: Created cardholder data
    PersonalInfo:
      type: object
      description: Personal information
      properties:
        firstName:
          type: string
          examples:
            - John
          description: First name
          example: John
        lastName:
          type: string
          examples:
            - Doe
          description: Last name
          example: Doe
        middleName:
          type: string
          examples:
            - William
          description: Middle name
          example: William
        dateOfBirth:
          type: string
          examples:
            - '1990-01-15T00:00:00.000Z'
          description: Date of birth (YYYY-MM-DD)
          example: '1990-01-15T00:00:00.000Z'
        gender:
          type: string
          examples:
            - MALE
          description: Gender
          example: MALE
        nationality:
          type: string
          examples:
            - US
          description: Nationality
          example: US
        email:
          type: string
          examples:
            - john.doe@example.com
          description: Email
          example: john.doe@example.com
        phoneNumber:
          type: string
          examples:
            - '+1234567890'
          description: Phone number
          example: '+1234567890'
        mobileNumber:
          type: string
          examples:
            - '+1234567890'
          description: Mobile number
          example: '+1234567890'
    AddressInfo:
      type: object
      description: Address information
      properties:
        addressLine1:
          type: string
          examples:
            - 123 Main St
          description: Address line 1
          example: 123 Main St
        addressLine2:
          type: string
          examples:
            - Apt 4B
          description: Address line 2
          example: Apt 4B
        city:
          type: string
          examples:
            - New York
          description: City
          example: New York
        state:
          type: string
          examples:
            - NY
          description: State/Province
          example: NY
        postalCode:
          type: string
          examples:
            - '10001'
          description: Postal code
          example: '10001'
        country:
          type: string
          examples:
            - US
          description: Country
          example: US
        addressType:
          type: string
          examples:
            - RESIDENTIAL
          description: Address type
          example: RESIDENTIAL
        isPrimary:
          type: boolean
          examples:
            - true
          description: Is primary address
          example: true
    EmploymentInfo:
      type: object
      description: Employment information
      properties:
        employerName:
          type: string
          examples:
            - Tech Corp
          description: Employer name
          example: Tech Corp
        occupationCode:
          type: string
          examples:
            - '001'
          description: Occupation code
          example: '001'
        occupationTitle:
          type: string
          examples:
            - Software Engineer
          description: Occupation title
          example: Software Engineer
        industry:
          type: string
          examples:
            - TECHNOLOGY
          description: Industry
          example: TECHNOLOGY
        employmentStatus:
          type: string
          examples:
            - FULL_TIME
          description: Employment status
          example: FULL_TIME
        employmentStartDate:
          type: string
          examples:
            - '2020-01-01T00:00:00.000Z'
          description: Employment start date (YYYY-MM-DD)
          example: '2020-01-01T00:00:00.000Z'
        monthlyIncome:
          type: number
          examples:
            - 5000
          description: Monthly income
          example: 5000
        annualIncome:
          type: number
          examples:
            - 60000
          description: Annual income
          example: 60000
        incomeCurrency:
          type: string
          examples:
            - USD
          description: Income currency
          example: USD
        employerAddress:
          $ref: '#/components/schemas/AddressInfo'
          type: object
          description: Employer address
    KycDocument:
      type: object
      description: KYC document information
      properties:
        documentType:
          type: string
          examples:
            - PASSPORT
          description: Document type
          example: PASSPORT
        documentNumber:
          type: string
          examples:
            - AB123456789
          description: Document number
          example: AB123456789
        documentExpiryDate:
          type: string
          examples:
            - '2030-01-15T00:00:00.000Z'
          description: Document expiry date (YYYY-MM-DD)
          example: '2030-01-15T00:00:00.000Z'
        documentIssueDate:
          type: string
          examples:
            - '2020-01-15T00:00:00.000Z'
          description: Document issue date (YYYY-MM-DD)
          example: '2020-01-15T00:00:00.000Z'
        documentIssuingCountry:
          type: string
          examples:
            - US
          description: Document issuing country
          example: US
        documentFrontImageUrl:
          type: string
          examples:
            - https://example.com/doc-front.jpg
          description: Document front image URL
          example: https://example.com/doc-front.jpg
        documentBackImageUrl:
          type: string
          examples:
            - https://example.com/doc-back.jpg
          description: Document back image URL
          example: https://example.com/doc-back.jpg
        selfieImageUrl:
          type: string
          examples:
            - https://example.com/selfie.jpg
          description: Selfie image URL
          example: https://example.com/selfie.jpg
        verificationStatus:
          type: string
          examples:
            - PENDING
          description: Verification status
          example: PENDING
    CardholderData:
      type: object
      description: Cardholder data
      properties:
        cardholderId:
          type: string
          examples:
            - ch-12345678
          description: Cardholder ID
          example: ch-12345678
        accountId:
          type: string
          examples:
            - wsb-12345678
          description: Account ID
          example: wsb-12345678
        cardholderReference:
          type: string
          examples:
            - REF123456
          description: Cardholder reference
          example: REF123456
        personalInfo:
          $ref: '#/components/schemas/PersonalInfo'
          type: object
          description: Personal information
        residentialAddress:
          $ref: '#/components/schemas/AddressInfo'
          type: object
          description: Residential address
        mailingAddress:
          $ref: '#/components/schemas/AddressInfo'
          type: object
          description: Mailing address
        employmentInfo:
          $ref: '#/components/schemas/EmploymentInfo'
          type: object
          description: Employment information
        kycDocuments:
          type: array
          items:
            $ref: '#/components/schemas/KycDocument'
          description: KYC documents
        cardholderType:
          type: string
          examples:
            - B2B
          description: Cardholder type
          example: B2B
        riskLevel:
          type: string
          examples:
            - LOW
          description: Risk level
          example: LOW
        kycLevel:
          type: string
          examples:
            - STANDARD
          description: KYC level
          example: STANDARD
        sourceOfFunds:
          type: string
          examples:
            - SALARY
          description: Source of funds
          example: SALARY
        purposeOfAccount:
          type: string
          examples:
            - PERSONAL_USE
          description: Purpose of account
          example: PERSONAL_USE
        politicallyExposedPerson:
          type: boolean
          examples:
            - false
          description: Political exposure
          example: false
        sanctionsScreeningRequired:
          type: boolean
          examples:
            - true
          description: Sanctions screening required
          example: true
        cardholderStatus:
          type: string
          examples:
            - ACTIVE
          description: Cardholder status
          example: ACTIVE
        kycStatus:
          type: string
          examples:
            - VERIFIED
          description: KYC status
          example: VERIFIED
        verificationTime:
          type: integer
          format: int64
          examples:
            - 1640995200000
          description: Verification time
          example: 1640995200000
        createTime:
          type: integer
          format: int64
          examples:
            - 1640995200000
          description: Create time
          example: 1640995200000
        updateTime:
          type: integer
          format: int64
          examples:
            - 1640995200000
          description: Update time
          example: 1640995200000
        numberOfCards:
          type: integer
          format: int32
          examples:
            - 2
          description: Number of cards
          example: 2
        activeCards:
          type: integer
          format: int32
          examples:
            - 2
          description: Active cards
          example: 2

````