Create and manage cardholders

A cardholder represents the person who will use a card. You must create a cardholder before issuing any card to them. Once a card is linked to a cardholder, the association cannot be changed.

Prerequisites

A UQPAY account with Card Issuance enabled
An API token from the Access Token endpoint

Create a cardholder

Send a POST request to the Create Cardholder endpoint with the cardholder’s identity information. Required fields:

Field	Description
`first_name`	Cardholder’s first name (letters, spaces, and hyphens only)
`last_name`	Cardholder’s last name
`email`	Must be unique within the same account
`country_code`	Two-letter country code (ISO 3166-1 alpha-2)
`phone_number`	Must be unique within the same account. Length validated by country — see Phone number validation rules

Optional fields: date_of_birth, gender, nationality, residential_address, identity, kyc_verification, document_type, document

The cardholder’s email and phone number must be unique across all cardholders under the same account. Duplicate values will be rejected.

Request

curl -X POST https://api-sandbox.uqpaytech.com/api/v1/issuing/cardholders \
  -H "x-auth-token: YOUR_API_TOKEN" \
  -H "x-idempotency-key: $(uuidgen | tr '[:upper:]' '[:lower:]')" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Alex",
    "last_name": "Chen",
    "email": "alex.chen@example.com",
    "country_code": "SG",
    "phone_number": "91234567"
  }'

Response

{
  "cardholder_id": "25ea804d-7fd5-43d5-8792-0fc0214cdb2f",
  "cardholder_status": "SUCCESS"
}

The result is returned synchronously — no webhook is triggered for cardholder creation.

If the card product requires Enhanced KYC, cardholder_status returns PENDING instead of SUCCESS. The cardholder must complete identity verification before a card can be issued. See the KYC verification guide.

Cardholder status

Status	Description
`SUCCESS`	Cardholder is active and can be issued cards
`PENDING`	Awaiting KYC verification
`INCOMPLETE`	KYC documents are missing or require resubmission
`FAILED`	Onboarding failed

Retrieve a cardholder

Use the Retrieve Cardholder endpoint to get full cardholder details.

curl https://api-sandbox.uqpaytech.com/api/v1/issuing/cardholders/25ea804d-7fd5-43d5-8792-0fc0214cdb2f \
  -H "x-auth-token: YOUR_API_TOKEN"

{
  "cardholder_id": "25ea804d-7fd5-43d5-8792-0fc0214cdb2f",
  "email": "alex.chen@example.com",
  "first_name": "Alex",
  "last_name": "Chen",
  "country_code": "SG",
  "phone_number": "91234567",
  "number_of_cards": 1,
  "cardholder_status": "SUCCESS",
  "create_time": "2026-04-10T18:03:47+08:00"
}

List cardholders

Use the List Cardholders endpoint to paginate through all cardholders. You can filter by cardholder_status.

curl "https://api-sandbox.uqpaytech.com/api/v1/issuing/cardholders?page_number=1&page_size=10" \
  -H "x-auth-token: YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

Update a cardholder

Use the Update Cardholder endpoint to modify cardholder details. You can update email, phone_number, country_code, date_of_birth, gender, nationality, residential_address, and identity/KYC fields.

first_name and last_name cannot be updated after creation.

curl -X POST https://api-sandbox.uqpaytech.com/api/v1/issuing/cardholders/25ea804d-7fd5-43d5-8792-0fc0214cdb2f \
  -H "x-auth-token: YOUR_API_TOKEN" \
  -H "x-idempotency-key: $(uuidgen | tr '[:upper:]' '[:lower:]')" \
  -H "Content-Type: application/json" \
  -d '{
    "country_code": "SG",
    "phone_number": "98765432"
  }'

KYC verification — Enhanced KYC flow for card products that require identity verification
Phone number validation rules — Country-specific phone number length requirements
Create Cardholder API
Cardholder webhooks

Getting Started

Cardholders

Cards

Funding

Controls & Security

Integration

Reference

Create a cardholder

Request

Response

Cardholder status

Retrieve a cardholder

List cardholders

Update a cardholder

​Create a cardholder

​Request

​Response

​Cardholder status

​Retrieve a cardholder

​List cardholders

​Update a cardholder

​Related

Create a cardholder

Request

Response

Cardholder status

Retrieve a cardholder

List cardholders

Update a cardholder

Related