Skip to main content
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:
FieldDescription
first_nameCardholder’s first name (letters, spaces, and hyphens only)
last_nameCardholder’s last name
emailMust be unique within the same account
country_codeTwo-letter country code (ISO 3166-1 alpha-2)
phone_numberMust 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

StatusDescription
SUCCESSCardholder is active and can be issued cards
PENDINGAwaiting KYC verification
INCOMPLETEKYC documents are missing or require resubmission
FAILEDOnboarding 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"
  }'