Skip to main content
Before you can issue a card to an individual, you must create a Card Holder profile. Card holders represent the identities attached to your issued cards and serve as the anchor for Know Your Customer (KYC) documentation and programmatic card controls.

​
Creating a Card Holder

To construct a robust identity, you should provide detailed demographic and address information. The POST /card-holders endpoint accepts multipart/form-data, which uniquely enables you to submit both structured demographic JSON data and binary document uploads in a single request.

​
The Payload Structure

Instead of standard nested JSON, the API requires complex nested objects to be sent as stringified JSON under specific form fields.
  • name: A plain string representing the user’s full name.
  • person: A JSON-encoded string with demographic details:
    • firstName, lastName, email, phoneNumber, dateOfBirth, gender, nationality.
  • address: A JSON-encoded string representing the physical or mailing address:
    • line1, city, state, postalCode, countryCode.
  • identification: A JSON-encoded string tracking identity documents and proof of address configurations.
A typical curl request for a text-only profile looks like this: 
curl -X POST https://api-dev.paygen.online/card-holders \
  -H "x-api-key: <your_api_key>" \
  -F "name=Alex Johnson" \
  -F 'person={"firstName":"Alex","lastName":"Johnson","dateOfBirth":"1990-04-12","email":"alex.johnson@example.com"}' \
  -F 'address={"line1":"210 West 77th Street","city":"New York","state":"New York","postalCode":"10024","countryCode":"US"}'

​
Uploading KYC Documents

Some card programs or jurisdictions mandate strict document collection before card issuance. Because POST /card-holders accepts multipart/form-data, you can append binary files such as documentMain or proofOfAddress directly to the creation request: 
curl -X POST https://api-dev.paygen.online/card-holders \
  -H "x-api-key: <your_api_key>" \
  -F "name=Alex Johnson" \
  -F 'person={"firstName":"Alex","lastName":"Johnson"}' \
  -F "documentMain=@/path/to/passport.jpg" \
  -F "proofOfAddress=@/path/to/utility_bill.pdf" \
  -F 'identification={"document":{"type":"international_passport"},"proofOfAddress":{"type":"utility_bill"}}'
Alternatively, you can upload or update documents on an existing card holder using POST /card-holders/{cardHolderId}/documents.

​
Managing the Profile

Once a Card Holder is established, they can be referenced when calling POST /cards to link issued cards to their identity. If their email, phone number, or address changes over time, you can update their existing file using PUT /card-holders/{cardHolderId}. Unlike the creation endpoint, updates can be performed with standard application/json when file uploads are not required. For full schema details, review the Card Holders API Reference.