GuidesAPI ReferenceChangelog
Log In
Changelog
Back to All

2026-04-02

3 months ago by marshall

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:

  • 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