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
  
  

Card Issuing

Add usage_type, auto_cancel_trigger, and expiry_at to Create Card

• Introduces support for one-time-use cards by adding three optional fields to the Create Card request body.
• Affected Endpoints:
  • Create Card (request only)
• Changes:
  • Added optional field usage_type (enum: NORMAL, ONE_TIME; default: NORMAL). When omitted, the card behaves as a standard reusable card.
  • Added optional field auto_cancel_trigger (enum: ON_AUTH, ON_CAPTURE). Required when usage_type is ONE_TIME. Defines the transaction event that triggers automatic card cancellation: ON_AUTH cancels the card immediately after the first authorization is approved; ON_CAPTURE cancels the card after the first transaction's capture (settlement) succeeds.
  • Added optional field expiry_at (date-time string with timezone offset, e.g. 2026-03-19T18:46:43+08:00). If the card has not been cancelled by a first-transaction event before this datetime, it is automatically cancelled and any unused balance is released.

Banking

Add X-Request-Id header to Create Virtual Account

• Introduces an optional X-Request-Id request header to Create Virtual Account, allowing callers to pass a custom identifier that is echoed back in the associated webhook event.
• Affected Endpoints:
  • Create Virtual Account
  • webhook: virtual.account.*
• Changes:
  • Added optional request header X-Request-Id (string, max 64 characters).
  • If provided, the value is returned in the associated webhook event as request_id.

Account Center

Add four required fields to individual_info in Create SubAccount

• Four new required fields are added to the individual_info object for individual account creation. Requests missing any of these fields will return a validation error after the effective date.
• Affected Endpoints:
  • Create SubAccount (request only)
• Changes:
  • Added required field individual_info.employment_status — employment status of the individual.
  • Added required field individual_info.industry — industry the individual works in.
  • Added required field individual_info.job_title — job title of the individual.
  • Added required field individual_info.company_name — name of the company the individual works for.
• Effective date: 2026-03-19

Acquiring

[BREAKING] Acquiring API Response Structure Updated: Risk and Authentication Fields Added for Card Transactions

• Affected Endpoints (response only):
  • Create a PaymentIntent
  • Retrieve a PaymentIntent
  • Update a PaymentIntent
  • Confirm a PaymentIntent
  • Capture a PaymentIntent
  • Cancel a PaymentIntent
  • List all PaymentIntents
  • Retrieve a PaymentAttempt
  • List all PaymentAttempts
• Changes:
  • PaymentIntent endpoints: latest_payment_attempt.payment_method type changed from string to object
  • PaymentAttempt endpoints: payment_method type changed from string to object
  • PaymentIntent — new fields added to latest_payment_attempt: auth_code, arn, rrn, advice_code
  • PaymentAttempt — new top-level fields: auth_code, arn, rrn, advice_code
  • PaymentIntent — new object added: latest_payment_attempt.authentication_data
    • Fields: cvv_result, avs_result
    • authentication_data.three_ds fields: ds_transaction_id, three_ds_version, eci, cavv, three_ds_authentication_status, three_ds_cancellation_reason
  • PaymentAttempt — new object added: authentication_data (same structure as above)
• Notes: Effective 2026-03-26

[NEW] PaymentAttempt Webhooks: New Risk and Authentication Fields for Card Transactions

• Affected Webhooks:
  • acquiring.payment_attempt.created
  • acquiring.payment_attempt.capture_requested
  • acquiring.payment_attempt.cancelled
  • acquiring.payment_attempt.failed
• Scope: Card payment transactions only (payment_method.type = "card" or "card_present")
• Changes:
  • New fields added to the notification body: auth_code, arn, rrn, advice_code
  • New object added: authentication_data
    • Fields: cvv_result, avs_result
    • authentication_data.three_ds fields: ds_transaction_id, three_ds_version, eci, cavv, three_ds_authentication_status, three_ds_cancellation_reason
• Notes: Effective 2026-03-26

Acquiring

billing.phone_number is Now Optional

The billing.phone_number field has been changed from required to optional.

• Affected Endpoints:
  • Create a PaymentIntent, request only
  • Confirm a PaymentIntent, request only
• Changes:
  • The billing.phone_number field is no longer required.

[NEW]Added Google Pay and Apple Pay payment methods

The Create a PaymentIntent API now supports Google Pay and Apple Pay as new payment methods.

• Affected Endpoints:
  • Create a PaymentIntent, request only
  • Confirm a PaymentIntent, request only
• Changes:
  • Added googlepay and applepay as new available payment method options.
  • For detailed integration instructions, please refer to the API documentation.

Banking

[BREAKING]Added required x-idempotency-key header for Create Transfer

The Create Transfer API now requires an x-idempotency-key parameter in the request header to ensure idempotent operations.

• Affected Endpoints:
  • Create Transfer, request only
• Changes:
  • Added new required request header parameter: x-idempotency-key
• Notes:
  • This is a backward-incompatible change. All API consumers must include this header in their Create Transfer requests.
  • Effective date: March 19

Account Center

proof_documents.proof_of_address is Now Optional in Create SubAccount

The proof_documents.proof_of_address field has been changed from required to optional in the Create SubAccount API.

• Affected Endpoints:
  • Create SubAccount, request only
• Changes:
  • The proof_documents.proof_of_address field is no longer required when creating a sub-account.

Issuing

Enhanced: Additional Filter Parameters for Balance Transactions

The "List Issuing Balances Transactions" API now supports additional filter parameters to help you query and analyze transaction data more efficiently.

Affected Endpoints:

• List Issuing Balances Transactions, request only

New Filter Parameters:

• transaction_type - Filter by transaction type (e.g., authorization, reversal, refund, fee, settlement, etc.). See API documentation for full list of supported values.

• transaction_status - Filter by transaction status: COMPLETED, PENDING, or FAILED.

• currency - Filter by currency code (3-letter ISO 4217 currency code, e.g., USD, EUR, GBP).

• transaction_id - Filter by exact transaction ID (long ID format).

Notes:

• All filter parameters are optional and can be used independently or in combination
• When using multiple filters, only transactions matching all specified criteria will be returned

Acquiring

New: Bank Account Management APIs

We have released a new set of APIs for managing acquiring settlement bank accounts:

• Create Bank Account - Create a new settlement bank account
• Retrieve Bank Account - Retrieve details of a specific bank account
• Update Bank Account - Update an existing bank account
• List Bank Accounts - List all bank accounts

Note:

• Each account can only have one settlement bank account per currency.
• Created bank accounts cannot be deleted.

Issuing

New: Authorization Decision Function

The Authorization Decision Function is now live. Partners can now implement real-time authorization decision logic for card transactions by providing a webhook server to receive authorization requests from UQPAY.

📖 Authorization Decision Integration Guide

Account Center

[BREAKING] Enforced Enum Validation for industry field

[BREAKING] The business_details.industry field in Create SubAccount now enforces validation against a specific set of enum codes.

• Previously, this field only checked for non-empty values.
• Now, it must contain a valid code from the industry code list: Industry Code Mapping.

Affected Endpoints:

• Create SubAccount, request only

Changes:

• [Modified behavior] The business_details.industry must strictly match a valid enum code.

Notes:

• Transition Period: From 2025-12-25 to 2026-01-01, both old and new values will be accepted for compatibility.
• Enforcement: After 2026-01-01, only valid enum codes will be accepted.

[BREAKING] Response Type Change for business_code

[BREAKING] The data type of the business_code field in the response has changed from a string to an array of strings.

• Existing integrations expecting a single string value will need to be updated to handle an array.
• Example: "business_code": "BANKING" becomes "business_code": ["BANKING"].

Affected Endpoints:

• Retrieve Account, response only
• List Connected Accounts, response only

Changes:

• [Modified behavior] Response field business_code changed from string to array[string].
• Possible values include: BANKING, ACQUIRING, ISSUING.

[DEPRECATED] Removal of business_type field

[DEPRECATED] The business_type field in the Create SubAccount request is deprecated and will be removed.

Affected Endpoints:

• Create SubAccount, request only

Changes:

• [Removed fields] business_type

Acquiring

Optimized Mobile Parameter Validation Rules in 3DS Scenarios

[ENHANCED] Relaxed validation rules for mobile parameter in 3DS scenarios.

Affected APIs:

• Create a PaymentIntent, request only
• Confirm a PaymentIntent, request only

Affected Fields:

• browser_info.mobile

Changes:

• Before: Required in 3DS scenarios
• After: Only required when the client is mobile; not required for PC web clients in 3DS scenarios

Acquiring

Static QR Code Fields Added to Payment Intent and Payment Attempt Webhooks

[ENHANCED] Added static QR code related fields to Payment Intent and Payment Attempt webhook notifications.

Affected Webhooks:

• acquiring.payment_intent.*
• acquiring.payment_attempt.*

Changes:

• Added static_qrcode, static_qrcode_extension, and static_qrcode_number_plate fields to webhook notification bodies
• These fields are only returned in static QR code payment scenarios

Issuing

Added Card Status Field Length Restriction

[ENHANCED] Added length validation for the update_reason field in Update Card Status endpoint.

• The update_reason field now has a maximum length restriction.

Affected Endpoints:

• Update Card Status, request only

Changes:

• Added length validation for update_reason field
• Maximum length: 50 Chinese characters or 100 characters

New Webhook: card.verification.otp

[NEW] Added a new webhook event card.verification.otp for Google Pay card binding verification.

• This webhook is triggered when a card binding to Google Pay requires OTP verification code input.
• Notification format: See Verification OTP Webhook Reference
• If you need to receive this webhook notification, please subscribe to the card.verification.otp event type in your webhook configuration.

Banking

Enhanced Transaction Type Filtering

[ENHANCED] Added support for filtering INVOICE type transactions in List Balances Transactions endpoint.

Affected Endpoints:

• List Balances Transactions, request only

Changes:

• Added support for INVOICE type in transaction_type filter parameter