> ## Documentation Index
> Fetch the complete documentation index at: https://developers-sandbox.uqpaytech.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Changelog
> API and documentation updates for UQPAY products.
## Issuing
**\[NEW] `enable_3ds` field for per-card 3DS registration control**
* Affected endpoints: [Create Card](/docs/card-issuance/v1.6/api-reference/create-card), [Update Card](/docs/card-issuance/v1.6/api-reference/update-card), [Retrieve Card](/docs/card-issuance/v1.6/api-reference/retrieve-card), [List Cards](/docs/card-issuance/v1.6/api-reference/list-cards)
* Affected webhooks: `card.create.succeeded`, `card.update.succeeded`
* New `risk_controls.enable_3ds` field controls whether a card is registered for 3DS at all. Combine with the existing `allow_3ds_transactions` for full 3DS behavior — see the updated [3D Secure guide](/docs/card-issuance/v1.6/guide/3d-secure).
* Visa BINs only. Modifiable when the card is in `PENDING` or `ACTIVE` status.
* Returned in card responses only when explicitly set on the card. When absent, the card follows the account-level 3DS configuration.
* Backward-compatible — existing integrations that do not pass `enable_3ds` continue to work unchanged.
## Issuing
**\[BREAKING] Secure Iframe rendering behavior changes**
The [Secure Iframe](/docs/card-issuance/v1.6/guide/secure-iframe-guide) integration ships a set of layout and control changes that may visibly affect existing integrations even without any client-side code update. We recommend verifying the rendering in sandbox before the production rollout.
* Effective: 2026-05-07, \~20:00 Beijing time (UTC+8)
* Changes that may visibly affect existing integrations:
* **Page max-width**: `512px` → `1280px`. Cards in parent containers wider than 512px will render wider than before.
* **Iframe content height**: previously content-driven (auto) → fixed at `300px`. Content exceeding 300px may be clipped or scrolled.
* **Iframe container minimum height**: previously unrestricted → `min-height: 400px`. Containers with shorter content will be expanded to 400px.
* **Bottom "Show / Hide data" toggle button has been removed.** Sensitive data visibility (card number, expiry, CVV) is now toggled via the eye icon next to the `CVV` label, which is persistently visible. Clicking on the masked values (`****`, `**/**`, `***`) also toggles visibility.
* To preserve the previous fixed dimensions, pass `width` / `height` through the `styles` parameter on `.uq-card-container` — see the [Secure Iframe Guide](/docs/card-issuance/v1.6/guide/secure-iframe-guide) for usage.
***
**\[NEW] `show_data` URL parameter for the Secure Iframe**
Pass `show_data=true` on the [Secure Iframe](/docs/card-issuance/v1.6/guide/secure-iframe-guide) URL to reveal card number, expiry, and CVV on load without a user action. Default: `false`. Recommended for trusted environments only.
***
**\[NEW] `cardholder_name` URL parameter for the Secure Iframe**
Pass `cardholder_name=true` on the [Secure Iframe](/docs/card-issuance/v1.6/guide/secure-iframe-guide) URL to render the cardholder name field. Default: `false` (hidden). Backward-compatible.
***
**\[ENHANCED] New `styles` selectors and properties for the Secure Iframe**
The [Secure Iframe](/docs/card-issuance/v1.6/guide/secure-iframe-guide) `styles` parameter now supports:
* New selectors: `.uq-card-cardholder` (cardholder name styling) and `.uq-page-background` (iframe page background; default `transparent`).
* `.uq-card-container` accepts `width`, `height`, `min-height`, `max-width`, `min-width` — useful for restoring the previous fixed dimensions.
* `.uq-card-row` accepts `display`, `justify-content`, `align-items`, `flex-direction`, `gap` — useful for label/value alignment.
## Issuing
**\[NEW] One-step card issuance — create a cardholder and card in a single call**
* Affected endpoint: [Create Card](/docs/card-issuance/v1.6/api-reference/create-card) (request and response)
* `cardholder_id` is now optional. When omitted, provide a complete `cardholder_required_fields` block and the system creates the cardholder and issues the card in the same request.
* Backward-compatible — existing integrations that pass `cardholder_id` continue to work unchanged.
* See [One-Step Card Issuance](/docs/card-issuance/v1.6/guide/one-step-card-issuance) for the full integration flow.
***
**\[ENHANCED] `card.verification.otp` webhook now supports Apple Pay binding**
* Affected webhook: `card.verification.otp`
* The verification OTP event is now published for both Google Pay and Apple Pay wallet bindings. Previously, it was only published for Google Pay bindings.
* No action required for existing integrations — merchants already subscribed to `card.verification.otp` will automatically receive OTPs for Apple Pay bindings.
***
**\[NEW] Kosovo added to supported countries for cardholder phone validation**
* Affected endpoint: [Create Cardholder](/docs/card-issuance/v1.6/api-reference/create-cardholder)
* Cardholders with Kosovo (ISO 3166-1 alpha-2 `XK`, alpha-3 `XKX`) phone numbers can now be created successfully.
* Phone prefix: `+383`. Valid phone number length (excluding country code): 8–9 digits.
* See [Phone Number Validation Rules](/docs/card-issuance/v1.6/guide/phone-number-validation-rules-for-cardholder) for the full country list.
## Issuing
**\[NEW] `issuing.transfer.status_changed` webhook**
* New webhook event published when an issuing transfer status changes (e.g., from `pending` to `succeeded` or `failed`).
* Subscribe to `issuing.transfer.status_changed` in your webhook configuration to receive this notification.
***
**\[ENHANCED] `available_balance` and `currency` fields in `card.status.update` webhooks**
* Affected webhooks: `card.status.update.succeeded`, `card.status.update.failed`
* Added `available_balance` — the card's current available balance at the time of the status change.
* Added `currency` — the card's currency in ISO 4217 format.
## 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 endpoint: [Create Payout](/docs/global-acquiring/v1.6/api-reference/create-payout) (request)
* 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), 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 endpoint: 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 endpoint: List Products (response)
* 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
## Acquiring
**\[BREAKING] API response structure updated: risk and authentication fields added for card transactions**
* Affected endpoints (response only): [Create PaymentIntent](/docs/global-acquiring/v1.6/api-reference/create-payment-intent), [Retrieve PaymentIntent](/docs/global-acquiring/v1.6/api-reference/retrieve-payment-intent), [Update PaymentIntent](/docs/global-acquiring/v1.6/api-reference/update-payment-intent), [Confirm PaymentIntent](/docs/global-acquiring/v1.6/api-reference/confirm-payment-intent), [Capture PaymentIntent](/docs/global-acquiring/v1.6/api-reference/capture-payment-intent), [Cancel PaymentIntent](/docs/global-acquiring/v1.6/api-reference/cancel-payment-intent), [List PaymentIntents](/docs/global-acquiring/v1.6/api-reference/list-payment-intents), [Retrieve PaymentAttempt](/docs/global-acquiring/v1.6/api-reference/retrieve-payment-attempt), [List PaymentAttempts](/docs/global-acquiring/v1.6/api-reference/list-payment-attempts)
* 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
## 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 endpoint: Create Card (request)
* 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 endpoint: Create SubAccount (request)
* 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
**`billing.phone_number` is now optional**
The `billing.phone_number` field has been changed from required to optional.
* Affected endpoints: Create PaymentIntent (request), Confirm PaymentIntent (request)
* The `billing.phone_number` field is no longer required.
***
**\[NEW] Google Pay and Apple Pay payment methods**
* Affected endpoints: Create PaymentIntent (request), Confirm PaymentIntent (request)
* Added `googlepay` and `applepay` as new available payment method options.
## Banking
**\[BREAKING] `x-idempotency-key` is now required for Create Transfer**
* Affected endpoint: Create Transfer (request)
* Added new **required** request header parameter: `x-idempotency-key`
* 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**
* Affected endpoint: Create SubAccount (request)
* The `proof_documents.proof_of_address` field is no longer required when creating a sub-account.
## Issuing
**\[ENHANCED] Additional filter parameters for List Issuing Balances Transactions**
* Affected endpoint: List Issuing Balances Transactions (request)
* Added four new optional filter parameters:
* `transaction_type` — filter by transaction type (e.g., authorization, reversal, refund, fee, settlement)
* `transaction_status` — filter by status: `COMPLETED`, `PENDING`, or `FAILED`
* `currency` — filter by 3-letter ISO 4217 currency code (e.g., `USD`, `EUR`, `GBP`)
* `transaction_id` — filter by exact transaction ID
* All parameters are optional and can be used independently or in combination.
## Acquiring
**\[NEW] Bank Account Management APIs**
Four new endpoints for managing acquiring settlement bank accounts:
* Create Bank Account
* Retrieve Bank Account
* Update Bank Account
* List Bank Accounts
Notes:
* Each account can only have one settlement bank account per currency.
* Created bank accounts cannot be deleted.
## Issuing
**\[NEW] Authorization Decision Function**
Partners can now implement real-time authorization decision logic for card transactions by providing a webhook server to receive authorization requests from UQPAY.
## Account Center
**\[BREAKING] Enum validation enforced for `business_details.industry` in Create SubAccount**
* Affected endpoint: Create SubAccount (request)
* The `business_details.industry` field now must contain a valid code from the industry code list.
* Previously, the field only checked for non-empty values.
* **Transition period**: 2025-12-25 to 2026-01-01 accepts both old and new values. Enforcement begins 2026-01-01.
***
**\[BREAKING] `business_code` response type changed from string to array**
* Affected endpoints: Retrieve Account (response), List Connected Accounts (response)
* `business_code` changed from `string` to `array[string]`.
* Example: `"business_code": "BANKING"` → `"business_code": ["BANKING"]`
* Possible values: `BANKING`, `ACQUIRING`, `ISSUING`
* Existing integrations expecting a single string value must be updated.
***
**\[DEPRECATED] `business_type` field deprecated in Create SubAccount**
* Affected endpoint: Create SubAccount (request)
* The `business_type` field is deprecated and will be removed.
## Acquiring
**\[ENHANCED] Relaxed `browser_info.mobile` validation in 3DS scenarios**
* Affected endpoints: Create PaymentIntent (request), Confirm PaymentIntent (request)
* `browser_info.mobile` is now only required when the client is mobile. It is no longer required for PC web clients in 3DS scenarios.
## Acquiring
**\[ENHANCED] Static QR code fields added to Payment Intent and Payment Attempt webhooks**
* Affected webhooks: `acquiring.payment_intent.*`, `acquiring.payment_attempt.*`
* 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
**\[ENHANCED] `update_reason` field length restriction in Update Card Status**
* Affected endpoint: Update Card Status (request)
* Maximum length: 50 Chinese characters or 100 characters.
***
**\[NEW] `card.verification.otp` webhook**
* Triggered when a card binding to Google Pay requires OTP verification.
* Subscribe to the `card.verification.otp` event type in your webhook configuration to receive this notification.
## Banking
**\[ENHANCED] INVOICE type filtering in List Balances Transactions**
* Affected endpoint: List Balances Transactions (request)
* Added support for `INVOICE` type in the `transaction_type` filter parameter.
## Issuing
**\[ENHANCED] `delivery_address` field in Retrieve Cardholder and List Cardholders**
* Affected endpoints: Retrieve Cardholder (response), List Cardholders (response)
* Added `delivery_address` field to cardholder response objects. Field structure:
```json theme={null}
"delivery_address": {
"city": "Singapore",
"country": "SG",
"line1": "9 N Buona Vista Dr",
"line2": "THE METROPOLIS",
"state": "Singapore",
"postal_code": "138666"
}
```
## Acquiring
**`ip_address` field moved to top level in PaymentIntent**
* Affected endpoints: Create PaymentIntent (request), Confirm PaymentIntent (request)
* `browser_info.ip_address` moved to top level (same level as `payment_method`).
* `ip_address` is **mandatory** when `payment_method.card.three_ds_action = enforce_3ds`.
## Acquiring
**\[ENHANCED] Billing address `state` field conditionally required for US and CA**
* Affected endpoints: Create PaymentIntent (request), Confirm PaymentIntent (request)
* `payment_method.card.billing.address.state` is now conditionally required when `billing.address.country_code` is `"US"` or `"CA"`.
***
**\[NEW] TRUEMONEY, TNG, GCASH, DANA, KAKAOPAY, TOSSPAY, and NAVERPAY payment methods**
* Affected endpoints: Create PaymentIntent, Confirm PaymentIntent
* Added support for seven new payment methods, expanding coverage in Southeast Asian markets.
***
**\[NEW] Manual payment capture endpoint**
* New endpoint: `POST /v2/payment_intents/{id}/capture`
* Supports `auto_capture = false` payment flows with a configurable 1–24 hour capture window.
* UQPAY auto-captures funds after the window period if not manually captured.
* Merchants can cancel orders within the capture window period.
## Banking
**\[ENHANCED] `beneficiary_entity_type` field in beneficiary webhooks**
* Affected webhooks: `beneficiary.*`
* Added `beneficiary_entity_type` field to webhook payloads. Values: `"INDIVIDUAL"` or `"COMPANY"`.
## Issuing
**\[ENHANCED] Phone number validation rules updated**
* Affected endpoint: Create Cardholder (request)
* Updated length validation for the following countries (excluding country/region/area codes):
* Nigeria (NG): 8 or 10 digits
* Bangladesh (BD): 8 or 10 digits
* Libya (LY): 8 or 9 digits
* Senegal (SN): 7 or 9 digits
* Mayotte (YT): 8 or 9 digits
* Ecuador (EC): 7 or 9 digits
* Republic of Congo area code changed from 2420 to 242.
## Account Center
**\[ENHANCED] Enhanced SubAccount creation for TPSP master accounts**
* Affected endpoint: Create SubAccount (request)
* Added `ownership_details.representatives.face_docs` for company entity types.
* Added `identity_verification.face_docs` for individual entity types.
* Added `tos_acceptance.tos_agreement` for both entity types (optional; set to `1` to auto-sign TPSP Terms of Service).
* `face_docs` are mandatory when creating sub-accounts under TPSP master accounts.
* For company entities: at least one representative with specific job titles must provide face verification documents.
## Acquiring
**\[NEW] Account balance and payout endpoints**
Five new endpoints released:
* Retrieve Balance
* List Balances
* Create Payout
* Retrieve Payout
* List Payouts — real-time payout status updates available via webhooks.
## Banking
**\[ENHANCED] Chinese parentheses support in company name and account holder fields**
* Affected endpoints: Create Payout (request), Create Beneficiary (request)
* Added support for Chinese parentheses `（）` in `company_name` and `account_holder` fields.
* Applies only when `bank_country_code = CN`, `account_currency_code = CNH`, `payment_method = LOCAL`, `entity_type = COMPANY`.
***
**\[ENHANCED] Relaxed input validation for local payments**
* Affected endpoints: Create Payout (request), Create Beneficiary (request)
* Removed input validation for `bank_details.account_holder`, `first_name`, `last_name`, `company_name`, `address.street_address`, `address.city`, and `address.state` when `payment_method = LOCAL` and `account_currency_code` is not CNH or SGD.
***
**\[ENHANCED] Updated `payout_reference` validation rules**
* Affected endpoint: Create Payout (request)
* SWIFT payments: new pattern `/^[a-zA-Z0-9/-?:().'+, ]+$/` (supports space and additional special characters).
* LOCAL payments with non-CNH/non-SGD currency: no validation applied.
***
**\[NEW] Invoice document required for INR cross-currency payouts**
* Affected endpoint: Create Payout (request)
* Invoice document upload is now mandatory when `beneficiary.bank_details.account_currency_code = "INR"` and `clearing_system = "IFSC"`.
* Document must be uploaded in the `documentation` field.
***
**\[BREAKING] `OTHER_SERVICES` removed from `purpose_code` enumeration**
* Affected endpoint: Create Payout (request)
* Removed `OTHER_SERVICES` from the `purpose_code` field. Existing integrations using this value must update.
## Acquiring
**\[NEW] `acquiring.payment_intent.requires_action` webhook**
* Triggered when payment intent status is `REQUIRES_CUSTOMER_ACTION` during the customer authentication phase.
## Account Center
**\[BREAKING] Document fields changed from object to array in Create SubAccount**
* Affected endpoint: Create SubAccount (request)
* The following fields now accept an array instead of a single object:
* `identity_verification.identity_docs`
* `ownership_details.shareholder_docs`
* `ownership_details.representatives.identity_docs`
* `company_info.certification_of_incorporation`
* `proof_documents.proof_of_address`
* `proof_documents.source_of_funds`
* `proof_documents.proof_of_position_and_income`
## Banking
**\[NEW] Cross-currency payout support**
* Create Quote: added `transaction_type` field — `conversion` (default) for currency conversion; `payout` for cross-currency payouts.
* Create Payout: added `payout_currency`, `payout_amount`, and `quote_id` fields.
* Retrieve Payout / List Payouts: added `quote_id` and `conversion` fields (`currency_pair`, `client_rate`).
* Webhooks `payout.*`: added `conversion`, `quote_id`, `payout_amount`, and `payout_currency` fields.
***
**\[BREAKING] Input validation added for recipient basic information fields**
* Affected endpoints: Create Beneficiary (request), Create Payout (request)
* Affected fields: `bank_details.account_holder`, `first_name`, `last_name`, `company_name`, `address.street_address`, `address.city`, `address.state`
* New validation applies to all conditions **except** when `bank_details.account_currency_code = CNH`, `payment_method = LOCAL`, and `bank_country_code = CN`.
* Only English characters, numbers, special characters, and spaces are allowed.
* For Singapore SGD individual accounts (`entity_type = INDIVIDUAL`, `bank_country_code = SG`, `account_currency_code = SGD`), stricter `account_holder` validation applies.
***
**\[BREAKING] Input validation added for `payout_reference`**
* Affected endpoint: Create Payout (request)
* Only alphabetic characters, numbers, spaces, commas (`,`), and periods (`.`) are allowed.
## Issuing
**\[NEW] Bulk Create Virtual Cards endpoint**
* New endpoint added: Bulk Create Virtual Cards
* New webhook: `issuing.report.succeeded` — delivers the decryption key for the card numbers file.
* Assign Card API expanded to support binding of bulk-created virtual cards.
* A `report_id` is returned after submission; retrieve the card number file using the Download Report API before expiry.
* You must subscribe to `issuing.report.succeeded` before calling Bulk Create Virtual Cards.
***
**\[ENHANCED] `Ori Transaction Id` field added to card reports**
* Affected reports: Card Transaction Report, Card Settlement Report
* Added new field `Ori Transaction Id`.
## Banking
**`email` and `nickname` fields changed to optional**
* Affected endpoints: Create Beneficiary (request), Create Payout (request)
* `email`: required → optional
* `nickname`: required → optional
***
**Field adjustments for Singapore (SGD) accounts**
When `bank_details.bank_country_code = SG` and `bank_details.account_currency_code = SGD`:
* Affected endpoints: Create Beneficiary (request), Create Payout (request)
* Removed: `company_name`, `first_name`, `last_name`, `address.country`, `address.street_address`, `address.city`, `address.state`, `address.postal_code`
* Changed to optional: `email`, `nickname`
***
**\[BREAKING] New `bank_details.account_holder` validation for SGD individual accounts**
* Affected endpoints: Create Beneficiary (request), Create Payout (request)
* Applies when `entity_type = INDIVIDUAL`, `bank_country_code = SG`, and `account_currency_code = SGD`.
* New validation: only English letters (A–Z, a–z) and spaces; 2–140 characters; must include a space separating first and last name.
## Issuing
**\[NEW] `consumed_amount` field in List Cards and Retrieve Card**
* Affected endpoints: List Cards (response), Retrieve Card (response)
* Added `consumed_amount` field, representing the cumulative card limit that has already been used.
## Account Center
**\[ENHANCED] `business_code` filter and field added to account endpoints**
* Affected endpoints: Retrieve Account (request and response), List Connected Accounts (response)
* Added optional `business_code` filter parameter to Retrieve Account — values: `BANKING`, `ISSUING`, `ACQUIRING` (default: `BANKING`).
* Added `business_code` field to Retrieve Account and List Connected Accounts responses.
***
**\[ENHANCED] `email_address` field added to representatives in Create SubAccount**
* Affected endpoint: Create SubAccount (request)
* Added optional field `email_address` to `ownership_details.representatives[]`.
***
**`website_url` and `company_description` changed to optional in Create SubAccount**
* Affected endpoint: Create SubAccount (request)
* `business_details.website_url`: required → optional
* `business_details.company_description`: required → optional
## Issuing
**Simulate Authorization now supports card BIN `40963608`**
* Affected endpoint: Simulate Authorization
* Added sandbox authorization simulation support for BIN `40963608`. No schema changes.
## Acquiring
**\[NEW] Payment Attempt webhook events**
Four new webhooks added for Payment Attempt (PA) status transitions:
* `acquiring.payment_attempt.created` — triggered when PA status is `INITIATED`
* `acquiring.payment_attempt.capture_requested` — triggered when PA status is `CAPTURE_REQUESTED` (consumer completed payment; the corresponding PI transitions to `SUCCESS`)
* `acquiring.payment_attempt.cancelled` — triggered when PA status is `CANCELLED`
* `acquiring.payment_attempt.failed` — triggered when PA status is `FAILED`
For one-to-one PI/PA mapping, a failed PA means the PI also fails. For one-to-many mapping, a failed PA does not fail the PI.
Subscribe to these events in your Dashboard to receive them.
***
**\[NEW] Settlements API**
* New endpoint: `GET /api/v2/payment/settlements`
* Supports optional `settlement_batch_id` or `payment_intent_id` parameters, pagination, and time range filters.
* Returns records with `settlement_status = success`.
## Banking
**\[BREAKING] `bank_details.account_number` restricted to alphanumeric characters**
* Affected endpoints: Create Payout (request), Create Beneficiary (request)
* Accepts only letters A–Z/a–z and digits 0–9. Spaces, hyphens, and other special symbols are rejected.
## Issuing
**\[NEW] `update_reason` field in Card APIs and webhooks**
* Affected endpoints: List Cards (response), Retrieve Card (response), Update Card Status (response)
* Affected webhooks: `card.status.update.*`
* Added `update_reason` field indicating the reason for a card status change.
***
**\[ENHANCED] Card Recharge and Withdraw now support SHARE cards**
* Affected endpoints: Card Recharge (request), Card Withdraw (request)
* SHARE cards can now adjust `card_available_balance` via Recharge (increase) and Withdraw (decrease).
* SINGLE card behavior remains unchanged.
## Issuing
**Updated `card_limit` validation in Create Card**
* Affected endpoint: Create Card (request)
* BINs 527735, 555071, 555243: `card_limit` is mandatory and must be ≥ 0.01.
* Other BINs: `card_limit` is optional; defaults to 0 if omitted; must be ≥ 0 and up to two decimal places if provided.
***
**\[NEW] Account-level transaction types added**
* Affected endpoints/reports: List Issuing Balances Transactions (response), Account Transaction Report
* Added: `FUNDS_TRANSFER_IN`, `FUNDS_TRANSFER_OUT`, `FEE_REFUND`, `FEE_DEDUCTION`, `MARGIN_PAYMENT`, `MARGIN_REFUND`, `OTHER`
***
**\[NEW] Card-level chargeback transaction types added**
* Affected endpoints: Retrieve Cards Transaction (response), List Cards Transactions (response)
* Added: `CHARGEBACK_DEBIT`, `CHARGEBACK_CREDIT`
***
**\[NEW] Chargeback webhooks**
* `issuing.transaction.chargeback.credit` — triggered when a chargeback credit is posted to a card transaction
* `issuing.transaction.chargeback.debit` — triggered when a chargeback debit is posted to a card transaction
## Banking
**\[NEW] `deposit_reference` field in Deposit APIs and webhooks**
* Affected endpoints: Retrieve Deposit (response), List Deposits (response)
* Affected webhooks: `deposit.pending`, `deposit.compliance.rejected`, `deposit.completed`
* Added `deposit_reference` field to carry a custom reference.
## Issuing
**\[NEW] `card.update.succeeded` and `card.update.failed` webhooks**
* `card.update.succeeded` — triggered when a card order from Update Card reaches `SUCCESS`
* `card.update.failed` — triggered when a card order from Update Card reaches `FAILED`
***
**\[ENHANCED] `ending_balance` and `description` fields in List Issuing Balances Transactions**
* Affected endpoint: List Issuing Balances Transactions (response)
* `ending_balance` — balance after the transaction is completed
* `description` — short description of the transaction
***
**Card Settlement Report: `ATM Withdraw` renamed to `Authorization`**
* Affected report: Card Settlement Report
* The `Transaction Type` enum value `ATM Withdraw` has been renamed to `Authorization`.
## Banking
**\[NEW] `purpose_code` in Retrieve Payout and List Payouts**
* Affected endpoints: Retrieve Payout (response), List Payouts (response)
* Added `purpose_code` field.
***
**Check Beneficiary now supports PayNow recipients**
* Affected endpoint: Check Beneficiary (request)
* Added `additional_info.proxy_id` parameter accepting a PayNow proxy identifier.
## Issuing
**Card Settlement Report: `Purchase` renamed to `Authorization`**
* Affected report: Card Settlement Report
* The `Transaction Type` value `Purchase` has been renamed to `Authorization`.
## Account Center
**\[NEW] `other_documents` field under `ownership_details.representatives`**
* Affected endpoints: Create SubAccount — `POST /v1/accounts/create_accounts` (request); Retrieve Account — `GET /v1/accounts/{id}` (response)
* A new optional field `other_documents` allows uploading proof of address or supplemental documents for representatives.
* Note: field name differs between request (`doc_str`) and response (`front`).
Create SubAccount request:
```json theme={null}
"other_documents": [
{
"type": "PROOF_OF_ADDRESS",
"doc_str": "base64 string or file ID"
}
]
```
Retrieve Account response:
```json theme={null}
"other_documents": [
{
"type": "PROOF_OF_ADDRESS",
"front": "base64 string or file ID"
}
]
```
Supported `type` values: `"PROOF_OF_ADDRESS"`, `"OTHERS"`.
## Account Center
**\[NEW] Create SubAccount endpoint**
* New endpoint: `POST /api/v1/accounts/create_accounts`
* Supports sub-account creation under ACQUIRING, BANKING, and ISSUING business lines.
* Supports both `COMPANY` and `INDIVIDUAL` entity types.
* Sub-accounts created here can still be queried via List Connected Accounts and Retrieve Account.
***
**\[NEW] Get Additional Documents endpoint**
* New endpoint: `GET /api/v1/accounts/get_additional`
* Returns required and optional document types for COMPANY sub-account creation, based on country and business code.
* Retrieve this list before initiating sub-account creation.
***
**Note on legacy endpoint**: The legacy `Create Account` (`POST /api/v1/accounts`) remains available. It only supports the BANKING business line. For new integrations, use Create SubAccount.
## Acquiring
**\[NEW] `acquiring.payment_intent.failed` webhook**
* Triggered when a Payment Intent is automatically closed upon expiry.
* Not triggered for manually cancelled orders.
* Subscribe to this event in your Dashboard to receive it.
## Issuing
**\[ENHANCED] `PENDING` status added to `transaction_status`**
* Affected endpoints: List Cards Transactions (response), Retrieve Cards Transaction (response)
* Added `PENDING` as a new valid value for `transaction_status`.
## Banking
**\[NEW] PayNow support in Payout and Beneficiary APIs**
* Affected endpoints: Create Payout, Retrieve Payout, Create Beneficiary, List Beneficiaries, Retrieve Beneficiary, Update Beneficiary, Check Beneficiary
* Added `PayNow` as a new enum value for `bank_details.clearing_system`.
* Added `additional_info.proxy_id` field supporting UEN, phone number, or VPA.
## Acquiring / Account
**\[BREAKING] UUID format validation enforced for `x-idempotency-key`**
* Affected endpoints: All POST endpoints (request headers)
* `x-idempotency-key` must now be a valid UUID format.
## Acquiring
**\[NEW] `failure_code` field in PaymentAttempt**
* Added `failure_code` to the PaymentAttempt response, indicating the reason for payment attempt failure.
## Banking
**\[NEW] Optional `documentation` field in Create Payout**
* Affected endpoint: `POST /api/v1/payouts` (request)
* Added optional `documentation` field to allow uploading supporting documents with a payout request.
## Issuing
**\[NEW] `risk_controls` module in `card.create.succeeded` webhook**
* Added `risk_controls` module to the `card.create.succeeded` webhook payload. Returned values (e.g., `3ds`, `mcc`) vary by card product.
## Issuing
**\[NEW] `wallet_type` field in card transaction APIs and reports**
* Affected endpoints: List Cards Transactions (response), Retrieve Cards Transaction (response)
* Affected webhooks: `issuing.transaction.*`
* Affected reports: Card Transactions Report, Card Settlement Report
* Added `wallet_type` field identifying the digital wallet used (e.g., `ApplePay`, `GooglePay`).
## Acquiring
**\[BREAKING] Webhook event type renamed from `acquiring.payment.*` to `acquiring.payment_intent.*`**
***
**\[NEW] `acquiring.payout.created` webhook** — triggered when a merchant initiates a payout request.
**\[NEW] `acquiring.refund.created` webhook** — triggered when a merchant initiates a refund request.
## Banking
**\[NEW] `other_documentation` field for representatives in Create Account**
* Affected endpoint: `POST /api/v1/accounts` (request)
* Added optional `other_documentation` field under `representatives[]` to support proof of address and other supplemental documents during account creation.
## Issuing
**\[NEW] `card_available_balance` field in card-related webhooks**
* Affected webhooks: `card.create.*`, `card.recharge.*`, `card.withdraw.*`
* Added `card_available_balance` indicating the card's available balance at the time of the event.
## Banking
**\[ENHANCED] `additional_info.organization_code` field in Create Beneficiary**
* Affected endpoint: `POST /api/v1/beneficiaries` (request)
* Added optional `additional_info.organization_code` field (Unified Social Credit Identifier) for company-type beneficiaries.
***
**\[NEW] `failure_reason` field in Retrieve Payout and List Payouts**
* Affected endpoints: `GET /api/v1/payouts/{id}` (response), `GET /api/v1/payouts` (response)
* Added `failure_reason` field to payout response objects.
## Issuing
**\[NEW] `card_currency` field in List Card Products**
* Affected endpoint: `GET /api/v1/issuing/products` (response)
* Added `card_currency` field — an array of strings specifying currencies available for each card product. Example: `["SGD", "USD"]`.
***
**\[ENHANCED] `card_form` and `max_card_quota` fields in List Card Products**
* Affected endpoint: `GET /api/v1/issuing/products` (response)
* `card_form` — supported card form(s): `["VIR", "PHY"]` or `["VIR"]`.
* `max_card_quota` — maximum number of cards that can be issued under the current account for the product.
***
**\[BREAKING] `failure_reason` renamed to `description` in card transaction APIs and webhooks**
* Affected endpoints: `GET /api/v1/issuing/transactions` (response), `GET /api/v1/issuing/transactions/{id}` (response)
* Affected webhooks: `issuing.transaction.*`
* If `transaction_status = DECLINED`: field contains the failure reason.
* If `transaction_status = APPROVED`: field contains supplementary remarks (e.g., `3DS Fee` for 3DS transactions).
* All transaction report files previously using `failure_reason` column header are now updated to `description`.
***
**\[BREAKING] Simplified `transaction_status` in `issuing.transaction.refund` webhook**
* Removed `REFUNDED` from valid values for `transaction_status`.
* Previous `REFUNDED` transactions now map to `transaction_type: REFUND` + `transaction_status: APPROVED`.
***
**\[BREAKING] Card status values updated**
* Affected endpoints: `GET /api/v1/issuing/cards/{id}` (response), `GET /api/v1/issuing/cards` (response), `POST /api/v1/issuing/cards/{id}/status` (request), `card.status.update.*` webhooks
* `INACTIVE` renamed to `FROZEN` — card is temporarily disabled but can be reactivated.
* New `BLOCKED` status added — card is administratively blocked by UQPAY; unblocking requires a formal email request.
## Banking
**\[BREAKING] `SUBMISSION_FAILED` removed from payout status values**
* Affected endpoints: `POST /api/v1/payouts` (response), `GET /api/v1/payouts` (request and response), `GET /api/v1/payouts/{id}` (response)
* Removed `SUBMISSION_FAILED` from the `payout_status` field.
## Issuing
**\[ENHANCED] `cardholder_id` parameter in List Cards**
* Affected endpoint: `GET /api/v1/issuing/cards` (request)
* Added optional `cardholder_id` query parameter to filter cards by cardholder.
***
**\[NEW] `no_pin_payment_amount` field in Retrieve Card**
* Affected endpoint: `GET /api/v1/issuing/cards/{id}` (response)
* Added `no_pin_payment_amount` field indicating the allowed amount for transactions without PIN verification. Format: `` (e.g., `2000USD`).
***
**\[ENHANCED] `no_pin_payment_amount` in List Card Products**
* Affected endpoint: `GET /api/v1/issuing/products` (response)
* Added `no_pin_payment_amount` array specifying configured NO-PIN payment amount limits per product.
## Acquiring
**\[BREAKING] Revised status field enum values for Payment objects**
* Affected endpoints: Payment Intents, Payment Attempts, and Payment Refunds endpoints
* Revised enumerated values and definitions for `intent_status`, `attempt_status`, and `refund_status`. Refer to the API reference pages for the latest enumerations.
***
**Supported `payment_method` values restricted**
* Affected endpoints: Payment Intents endpoints
* Supported values: `card`, `card_present`, `alipaycn`, `alipayhk`, `unionpay`, `wechat`. All other types are not yet supported.
## Issuing
**\[ENHANCED] `cardholder_id` filter in List Cards**
* Added optional `cardholder_id` query parameter to `GET /api/v1/issuing/cards`.
***
**\[NEW] `no_pin_payment_amount` in Retrieve Card**
* Added `no_pin_payment_amount` field to `GET /api/v1/issuing/cards/{id}` response. Format: `` (e.g., `2000USD`).
***
**\[ENHANCED] `no_pin_payment_amount` limits in List Card Products**
* Added `no_pin_payment_amount` array to `GET /api/v1/issuing/products` response, indicating maximum allowable NO-PIN payment amounts per currency.
## Acquiring
Initial official release of the Acquiring API. This version provides endpoints for Payment Intents, Attempts, Refunds, and webhook notifications.
## Banking
**\[NEW] `nationality` and `id_number` fields in Beneficiary APIs**
* Affected endpoints: Create Beneficiary, Update Beneficiary, Retrieve Beneficiary, List Beneficiaries
* Added `nationality` — two-letter country code for the beneficiary's nationality.
* Added `id_number` — conditionally required for `INDIVIDUAL` type beneficiaries who are Mainland China residents using CNH currency and LOCAL payment method.
## Issuing
**\[NEW] MCC management in risk control settings**
* Affected endpoints: `POST /api/v1/issuing/cards` (Create Card), `POST /api/v1/issuing/cards/{id}` (Update Card)
* Added optional `allowed_mcc` and `blocked_mcc` fields to the `risk_controls` object.
* Only one of the two can be set per card. MCCs must be provided as an array of strings (e.g., `["5999", "6011"]`).
## Issuing
**\[NEW] `number_of_cards` field in Cardholder APIs**
* Affected endpoints: List Cardholders (response), Retrieve Cardholder (response)
* Added `number_of_cards` field.
## Issuing
**\[BREAKING] `x-on-behalf-of` header must be a valid UUID**
* Affected endpoints: all endpoints supporting the `x-on-behalf-of` header
* If provided, the value must be a valid UUID format corresponding to an existing sub-account. Invalid values are rejected.
## Issuing
**\[BREAKING] Required `pin` field added to Activate Card**
* Affected endpoint: `POST /api/v1/issuing/cards/activate` (request)
* Added required field `pin`.
* Added optional field `no_pin_payment_amout`.
* This is a breaking change — existing integrations must be updated to include `pin`.
## Issuing
**\[NEW] 3DS control support in Create Card and Update Card**
* Affected endpoints: `POST /api/v1/issuing/cards`, `POST /api/v1/issuing/cards/{id}`
* Added optional `risk_controls` field. Backward-compatible — existing cards are unaffected unless explicitly configured.
## Banking
**\[NEW] Exchange rates endpoint**
* New endpoint: `GET /api/v1/exchange/rates`
* Returns current exchange rates. Reference only — use the Create Quote API for rate-locking.
## Banking
**\[NEW] Transaction-type RFI support**
* Added new webhook event type: `rfi.transaction.action_required` for deposit and payout RFI scenarios.
* Affected endpoints: `GET /api/v1/rfis/{id}` (Retrieve RFI), `POST /api/v1/rfis/answer` (Answer RFI)
* Added `rfi_type` and `transaction_type` fields to both endpoints.
* The original onboarding RFI flow (`event_type = rfi.action_required`) remains unchanged.
## Issuing
**\[NEW] `email` field in Update Cardholder**
* Affected endpoint: `POST /api/v1/issuing/cardholders/{id}` (request)
* Added optional `email` field. Backward-compatible.
## Banking
**Initial changelog entry**
* Added changelog.
* New deposit webhooks: `deposit.pending`, `deposit.compliance.rejected`, `deposit.completed`
* New deposit endpoints:
* `GET /api/v1/deposit` — list deposits
* `GET /api/v1/deposit/{id}` — retrieve a deposit by ID
* `POST /api/v1/simulation/desposit` — simulate deposits into global account (sandbox only)
* Documentation corrections to descriptions and parameter restrictions.