Acquiring

[ENHANCED] Create Payout: New payout_account_id Field for Internal Account Transfers

Payout creation now supports an optional payout_account_id parameter, enabling merchants to route payout funds to a UQPAY internal account instead of the pre-configured external bank account.

Affected Endpoints:
- Create Payout, request only
Changes:
- New optional field payout_account_id added to the request body
- When omitted, existing behavior is preserved — funds are sent to the configured external bank account
- When provided, the payout is processed as a UQPAY internal transfer to the specified account
- Both long and short UQPAY account IDs are accepted
Notes:
- The payout_account_id should match the calling account: pass the sub-account ID when calling from a sub-account, or the master account ID when calling from the master account
- This is a non-breaking, backward-compatible change — no action required for existing integrations

Issuing

[ENHANCED] Cardholder KYC System Reform: Multi-Level KYC Support

Cardholder creation, update, and card issuance now support tiered KYC levels based on card BIN requirements. Two new webhook events are introduced for KYC lifecycle tracking.

Create & Update Cardholder: Multi-Level KYC

Affected Endpoints:
- Create Cardholder, request and response
- Update Cardholder, request and response
Changes:
- Three KYC levels now supported:
  - SIMPLIFIED — basic fields only, behavior identical to previous version, cardholder_status set to SUCCESS immediately
  - STANDARD — requires nationality, identity, residential_address, triggers review process
  - ENHANCED — additionally requires kyc_verification, supporting THIRD_PARTY and SUMSUB_REDIRECT methods
- New request fields: gender, nationality, identity (object), residential_address (object), kyc_verification (object)
- New response fields: cardholder_status, idv_verification_url, idv_url_expires_at
Notes:
- When no new fields are provided, behavior remains fully backward compatible
- Updating KYC-related fields is not allowed while cardholder_status is PENDING
- residential_address replaces the previous delivery_address field

Retrieve Cardholder Response: New Fields

Affected Endpoints:
- Retrieve Cardholder, response only
- List Cardholders, request and response
Changes:
- New response fields: gender, nationality, residential_address, cardholder_status, review_status, idv_status, idv_verification_url, idv_url_expires_at
- List Cardholders accepts a new query parameter cardholder_status for filtering by status

Create Card: Supplementary Cardholder KYC

Affected Endpoints:
- Create Card, request and response
Changes:
- New optional request object cardholder_required_fields — allows merchants to supplement missing cardholder KYC fields at card creation time (includes gender, nationality, phone_number, date_of_birth, residential_address, identity, kyc_verification)
- New response fields: cardholder_status, message
Notes:
- If the cardholder does not meet the product's requirements and cardholder_required_fields is not provided, the error kyc_insufficient is returned with missing_fields
- When card creation triggers a KYC review, the card enters PENDING status and is automatically activated upon approval

List Products Response: New required_fields

Affected Endpoints:
- List Products, response only
Changes:
- Each product object now includes a required_fields array indicating cardholder fields required by the card BIN
- Each entry contains: name, type (string or object), required (boolean), description, and fields (sub-fields when type is object)

[NEW] Cardholder KYC Webhook Events

New Webhook Events:
- cardholder.kyc.status_changed — Cardholder KYC status changes
- cardholder.updated — Cardholder information updated