> ## Documentation Index
> Fetch the complete documentation index at: https://developers.uqpay.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Changelog
> API and documentation updates for UQPAY products.
# UQPAY System Upgrade and New Webhook Egress IP Notice
Dear Customer,
UQPAY plans to upgrade its production system this Saturday evening, Beijing time. During the upgrade, some services will be temporarily unavailable or may experience brief interruptions. Please make the necessary business arrangements in advance.
## Maintenance Window
* Start: July 25, 2026 (Saturday), 22:00 UTC+8 (July 25, 2026, 14:00 UTC)
* Estimated end: July 26, 2026 (Sunday), 01:00 UTC+8 (July 25, 2026, 17:00 UTC)
* Estimated duration: 3 hours
## Business Impact
### Acquiring
All Acquiring functions will remain available and will not be affected by this upgrade.
### Banking
During the maintenance window, deposit credit processing will remain available; all business functions other than deposits will be temporarily unavailable. To reduce risk, we recommend scheduling deposits outside the maintenance window whenever possible.
### Issuing
All Issuing functions will remain available and will not be affected by this upgrade. Cardholders can continue making card transactions as usual.
### Ramp
During the maintenance window, deposit credit processing will remain available; all business functions other than deposits will be temporarily unavailable. To reduce risk, we recommend scheduling deposits outside the maintenance window whenever possible.
### Permanent Ramp Transfer Adjustment (Effective After the Upgrade)
After the upgrade, the scope of the `POST /v1/ramp/transfer` endpoint will change as follows:
* Fiat transfers between Banking and Ramp accounts will no longer be supported;
* Only XUSD transfers from Ramp to Issuing will remain supported.
After funds are converted to fiat, you can initiate a payout directly without first transferring them to Banking. Please note that Ramp payouts will be temporarily unavailable during the maintenance window and can only be initiated after maintenance is complete.
Affected customers should review and update their existing integration flows in advance.
## Access Token Information
During the system switchover within the maintenance window, existing `x-auth-token` values used to call the Acquiring and Issuing APIs will become invalid at some point, even if the Token has not expired. You do not need to replace the Token in advance. If you receive a Token invalidation or authentication error during the maintenance window:
1. Call the Request Access Token endpoint again to obtain a new Token;
2. Retry the original request using the new Token.
Obtaining a new Token only resolves Token invalidation or authentication errors for the Acquiring and Issuing APIs. It will not restore Banking or Ramp functions that are temporarily unavailable during maintenance.
## Other Integration Configurations
Except for the new Webhook egress IP and Ramp Transfer adjustment explicitly described in this notice, the following configurations remain unchanged:
* API Base URL;
* API Key and Client ID;
* Configured Webhook endpoint.
## New Webhook Egress IP — Customer Action Required
The following Webhook egress IP will be added as part of this system upgrade:
```text theme={null}
56.10.39.6
```
If your firewall or security allowlist restricts Webhook source IPs, add this IP to the allowlist before maintenance begins.
The complete Webhook egress IP list after the upgrade is:
```text theme={null}
18.143.59.64
54.179.248.205
13.250.234.88
18.136.58.213
56.10.39.6
```
Add `56.10.39.6` to your existing configuration and keep all existing IPs. Do not remove any old IPs.
Webhook delivery may be briefly interrupted during the system switchover, and a small number of event notifications may not be delivered. A missing Webhook notification does not mean that business processing failed. Refer to the relevant query API response for the final status. To ensure that your local records are complete, proactively use the relevant query APIs after maintenance to verify the status of key business activities that occurred during the maintenance window and perform a reconciliation. If you find any discrepancies, contact the UQPAY Customer Support Team promptly.
For details and subsequent updates: [https://developers.uqpay.com/changelog#2026-07-25-upcoming-change](https://developers.uqpay.com/changelog#2026-07-25-upcoming-change)
Thank you for your understanding and support. If you encounter an urgent issue during the upgrade, contact the UQPAY Customer Support Team and we will assist you.
UQPAY CST TEAM
July 21, 2026
## Global Account
**\[BREAKING] Beneficiary address validation now applies across all currencies and payment methods**
* Affected endpoints: [Create Beneficiary](/global-account/v1.6/api-reference/create-beneficiary), [Update Beneficiary](/global-account/v1.6/api-reference/update-beneficiary), and [Create Payout](/global-account/v1.6/api-reference/create-payout) when the request submits full `beneficiary` details instead of `beneficiary_id`.
* Affected request fields: `address.street_address`, `address.city`, and `address.state`. For Create Payout with inline beneficiary details, the same fields appear under `beneficiary.address.street_address`, `beneficiary.address.city`, and `beneficiary.address.state`.
* Effective 2026-07-16. Non-empty values in these fields must match `^[A-Za-z0-9\s\-_().,:@#~!$%^&*+={}\[\]\\|"'<>?/・……]+$`. The regex allows English letters, digits, whitespace, and these symbols: `_ - ( ) . , : @ # ~ ! $ % ^ & * + = { } [ ] \ | " ' < > ? / ・ ……`.
* Empty strings and omitted fields skip the character-regex check. Whether the field is required is still determined by the existing required-field rules for the endpoint and payout scenario.
* This tightens validation beyond the previous SGD/SG-specific behavior. `country`, `postal_code`, and non-SGD/SG `bank_details.account_holder` validation are unchanged. [Check Beneficiary](/global-account/v1.6/api-reference/check-beneficiary) is unaffected.
## Card Issuance
**\[Postponed] \[BREAKING] New required `documents` field for third-party Enhanced KYC**
**Postponed.** The previously announced 2026-07-10 effective date no longer applies. This change is on hold and will not take effect on that date — you do not need to make any changes for now. A new effective date will be announced here before it takes effect.
* Affected endpoints: [Create Cardholder](/card-issuance/v1.6/api-reference/create-cardholder), [Update Cardholder](/card-issuance/v1.6/api-reference/update-cardholder). Applies wherever `kyc_verification` is submitted at the `ENHANCED` KYC level.
* When `kyc_verification.method` is `THIRD_PARTY`, `kyc_verification.kyc_proof` adds a required `documents` array that carries the compliance report files behind your verification. Each entry references a file uploaded via [Upload A File](/account-center/v1.6/api-reference/upload-file) and declares its `report_type`:
* `IDV` — an identity verification report only.
* `AML` — an anti-money-laundering screening report only.
* `IDV_AML` — a single file covering both.
* You must include an identity verification report — either a standalone `IDV` report or a combined `IDV_AML`. An `AML` report is optional. Submit the reports as separate files (`IDV` plus `AML`) or as one combined file (`IDV_AML`).
* This is a non-backward-compatible change: once it takes effect, `THIRD_PARTY` requests that omit the identity verification report are rejected. Update your integration before the new effective date, which will be announced here.
* See [Enhanced KYC Card Issuance](/card-issuance/v1.6/guide/enhanced-kyc-card-issuance) for the full flow.
## Card Issuance
**New endpoint: Claim Unsolicited Refund**
* New endpoint: [Claim Unsolicited Refund](/card-issuance/v1.6/api-reference/claim-unsolicited-refund) — `POST /v1/issuing/transactions/unsolicited_refund/release`. Business Visa only.
* Use it when a merchant's refund against your original authorization has not arrived. A `SUCCESS` response confirms the claim was accepted for asynchronous processing, not that the refund has posted.
* Failure reasons are listed under [Error codes](/card-issuance/v1.6/guide/error-codes#transaction-errors).
**New `pos_env` and `eci` fields in the authorization decision request**
* Affected flow: [Authorization decisions](/card-issuance/v1.6/guide/authorization-decisions) — the decrypted request body UQPAY sends to your endpoint.
* Two new fields are passed through so you can tell whether an authorization is a regular purchase or a subscription (recurring) charge, and apply differentiated risk controls and display:
* `pos_env` — POS environment: `C` credential on file, `I` installment, `R` recurring.
* `eci` — mail/phone, e-commerce, and payment indicator (`00`–`08`); `02` marks a recurring transaction.
* Backward compatible — additive fields only. See the guide for the full value tables.
**New `product_id` filter on List Card Arts**
* Affected endpoint: [List Card Arts](/card-issuance/v1.6/api-reference/list-card-arts).
* Optional `product_id` query parameter filters the returned card arts to those available for the given card product. Omitting it keeps the current behavior — all card arts available to the account.
* Backward compatible — additive, optional parameter.
## Account Center
**\[BREAKING] New required `gender` and `annual_income` fields when creating an individual SubAccount**
* Affected endpoint: [Create SubAccount](/account-center/v1.6/api-reference/create-sub-account)
* Effective 2026-07-02. When `entity_type` is `INDIVIDUAL`, the `individual_info` object adds two new required fields:
* `individual_info.gender` — the individual's gender, `MALE` or `FEMALE`.
* `individual_info.annual_income` — the individual's annual income as a string amount, denominated in USD.
* This is a non-backward-compatible change: requests that omit either field are rejected. Update your integration in time before 2026-07-02.
* Company SubAccounts (`entity_type` is `COMPANY`) are unaffected.
**SDK support**
Support for the new required fields is available in the following SDK versions. Upgrade before 2026-07-02:
| SDK | Minimum version | Upgrade |
| ----------------------- | --------------- | ----------------------------------------------------------------------------------------- |
| Node.js (`@uqpay/sdk`) | `0.3.1` | `npm install @uqpay/sdk@latest` |
| Python (`uqpay`) | `0.2.0` | `pip install -U uqpay` |
| Go (`uqpay-sdk-go`) | `v1.1.0` | `go get github.com/uqpay/uqpay-sdk-go@latest && go mod tidy` |
| Java (`uqpay-sdk-java`) | `1.1.0` | Download the JAR from [GitHub Releases](https://github.com/uqpay/uqpay-sdk-java/releases) |
| CLI (`@uqpay/cli`) | `0.3.1` | `npm install -g @uqpay/cli@latest` |
After upgrading, set `individual_info.gender` (`MALE` or `FEMALE`) and `individual_info.annual_income` on Create SubAccount for `INDIVIDUAL` entities.
Node.js / CLI: use `npm install @uqpay/sdk@latest` (not `npm update`) — versions below `0.3.0` are pinned by the `^0.2.x` range and will not upgrade automatically.
## Stablecoin Account
**Binance deposit Travel Rule support**
* New endpoint: [Submit Deposit Sender Travel Rule](/stablecoin-account/v1.6/api-reference/create-deposit-sender) — submit the originator (sender) Travel Rule for an incoming deposit so it, and later deposits from the same source address, can proceed.
* Deposit webhooks (`ramp.deposit.pending`) now include `need_travel_rule`, present and `true` only when a deposit needs originator Travel Rule data before it can proceed. Respond by calling Submit Deposit Sender Travel Rule with the deposit's `from_address`.
* [List Address Book](/stablecoin-account/v1.6/api-reference/list-address-book) adds an optional `address_kind` query parameter (`whitelist` default, or `deposit_sender`) to view the recorded deposit-sender entries.
* All three changes are backward compatible — new endpoint, new optional parameter, and a field that appears only when needed.
## Account Center
**\[UPDATE] New `required_documents` and `reason` fields on the Onboarding RFI webhook**
* Affected webhook: [Onboarding RFI](/account-center/v1.6/webhooks/onboarding-rfi)
* The `rfi.action_required` payload now includes `required_documents` (the document type codes compliance is requesting) and `reason` (a free-text explanation of why the RFI was raised).
* You can read what is required directly from the notification, before calling [Retrieve RFI](/account-center/v1.6/api-reference/retrieve-rfi).
* Backward-compatible — existing handlers that ignore the new fields continue to work unchanged.
## Issuing
**\[UPDATE] Stricter character validation on `residential_address` fields**
* Affected endpoints: [Create Cardholder](/card-issuance/v1.6/api-reference/create-cardholder), [Update Cardholder](/card-issuance/v1.6/api-reference/update-cardholder), [Create Card](/card-issuance/v1.6/api-reference/create-card) (one-step issuance with `cardholder_required_fields`)
* All `residential_address` fields (`line1`, `line2`, `city`, `state`, `postal_code`, etc.) now accept only letters (A-Z, a-z), digits (0-9), spaces, and the following punctuation: `, . ' / # ( ) - &`.
* Requests containing any other character (for example `;`) are rejected — correct the value and resubmit. Empty optional fields are not validated.
* This is a validation tightening: values that previously passed may now be rejected. Review your integration if you send other characters in address fields.
## Issuing
**\[NEW] PIN management for Standard virtual cards**
* New endpoint: [Set or Reset Virtual Card PIN](/card-issuance/v1.6/api-reference/manage-card-pin)
* Set a 4-digit PIN on a Standard virtual card for the first time (`type: SET`), or change it (`type: RESET`).
* `RESET` always requires the card's current PIN via `old_pin` — there is no forgot-PIN flow. If the current PIN is lost, the PIN cannot be reset through the API.
* The flow is asynchronous — the response confirms the request was accepted and returns the PIN operation order (`card_id`, `card_order_id`, `create_time`). A card can have only one PIN operation in flight at a time.
* Physical card PIN management is unchanged — [Reset Card PIN](/card-issuance/v1.6/api-reference/reset-pin) continues to work as before.
## Issuing
**\[NEW] Card art — pick the design shown in Apple Wallet and Google Wallet for Enhanced virtual cards**
* **Scope:** rendered in Apple Wallet and Google Wallet, and only for Enhanced virtual cards added to Apple Pay or Google Pay. Not surfaced in your own UI or on physical cards — see the new [Card art guide](/card-issuance/v1.6/guide/card-art) for the resolution order and limitations.
* New endpoints: [List Card Arts](/card-issuance/v1.6/api-reference/list-card-arts), [Set Default Card Art](/card-issuance/v1.6/api-reference/set-default-card-art)
* Affected endpoints: [Create Card](/card-issuance/v1.6/api-reference/create-card), [Update Card](/card-issuance/v1.6/api-reference/update-card) — new optional `card_art_id` field on the request body.
* Update Card with `card_art_id` is asynchronous (`order_status: PROCESSING`) and applies to `VIRTUAL` cards in `ACTIVE` status only.
* New error codes: `card_art_not_available`, `card_art_not_configured`, `card_art_not_supported` — see [Error codes](/card-issuance/v1.6/guide/error-codes).
* Backward-compatible — existing integrations that omit `card_art_id` continue to work and pick up the account's default.
## Issuing
**\[UPDATE] Extended `duration_in_days` range on Elevate Per-Transaction Limit**
* Affected endpoint: [Elevate Per-Transaction Limit](/card-issuance/v1.6/api-reference/elevate-card-limit)
* The `duration_in_days` field now accepts `1`–`14` (previously `1`–`7`); the default is now `14` (previously `7`).
## Global Acquiring
**\[NEW] `customer` and `customer_id` fields on Create PaymentIntent**
* Affected endpoint: [Create PaymentIntent](/global-acquiring/v1.6/api-reference/create-payment-intent)
* New optional `customer` (inline object) and `customer_id` fields on the request body, and matching top-level `customer_id` and `customer` on the response.
* New optional `external_customer_id` field added to the customer schema, for carrying a merchant-side identifier.
* These fields enable Card on File on the hosted payment page.
* Backward-compatible — existing integrations that omit the fields continue to work unchanged.
## Issuing
**\[NEW] Temporary per-transaction limit elevation**
* New endpoint: [Elevate Per-Transaction Limit](/card-issuance/v1.6/api-reference/elevate-card-limit)
* New webhooks: `card.elevate_limit.succeeded`, `card.elevate_limit.failed`
* Raise a card's per-transaction limit for a bounded duration (1–14 days, default 14) without changing its long-term limit settings. When the elevation expires, the per-transaction limit auto-reverts to the card's standard cap.
* Per-currency maximum elevated cap: `80,000` USD / XUSD; `100,000` SGD.
* A card can hold only one elevation in `processing` or `active` state at a time. Submitting a new request while one is still in effect returns `400`.
* The elevation flow is asynchronous — the API response acknowledges the request; the final outcome arrives on the [`card.elevate_limit.succeeded`](/card-issuance/v1.6/webhooks/card-elevate-limit) or [`card.elevate_limit.failed`](/card-issuance/v1.6/webhooks/card-elevate-limit) webhook.
* Restricted to specific card BINs — contact UQPAY to enable it for your account.
## Issuing
**\[NEW] ASAF Network Protection — enroll lost, stolen, or closed Visa cards with the network**
* New endpoints: [Enroll Card in Network Protection](/card-issuance/v1.6/api-reference/enroll-card-network-protection), [Remove Card from Network Protection](/card-issuance/v1.6/api-reference/remove-card-network-protection)
* New webhooks: `card.risk_control.network_protection.enrolled`, `card.risk_control.network_protection.removed`, `card.risk_control.network_protection.enrollment_fee.charged`, `card.risk_control.network_protection.maintenance_fee.charged`
* Affected endpoints: [Retrieve Card](/card-issuance/v1.6/api-reference/retrieve-card) and [List Cards](/card-issuance/v1.6/api-reference/list-cards) responses now carry a `network_protection` object on each card.
* Enroll a card with an ASAF action code (`04`, `41`, `43`, `46`, `54`) to have authorization attempts declined network-wide once Visa processes the request. Removal moves the card back out of network protection.
* The enrollment and removal flows are asynchronous — the API response acknowledges the request; the final outcome arrives on the lifecycle webhook. Fee charges are reported separately via the enrollment-fee and maintenance-fee webhooks.
* **Visa cards only.** Backward-compatible — existing integrations are unaffected unless they opt in.
## Issuing
**\[NEW] `enable_3ds` field for per-card 3DS registration control**
* Affected endpoints: [Create Card](/card-issuance/v1.6/api-reference/create-card), [Update Card](/card-issuance/v1.6/api-reference/update-card), [Retrieve Card](/card-issuance/v1.6/api-reference/retrieve-card), [List Cards](/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](/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](/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](/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](/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](/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](/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](/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](/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](/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](/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](/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](/global-acquiring/v1.6/api-reference/create-payment-intent), [Retrieve PaymentIntent](/global-acquiring/v1.6/api-reference/retrieve-payment-intent), [Update PaymentIntent](/global-acquiring/v1.6/api-reference/update-payment-intent), [Confirm PaymentIntent](/global-acquiring/v1.6/api-reference/confirm-payment-intent), [Capture PaymentIntent](/global-acquiring/v1.6/api-reference/capture-payment-intent), [Cancel PaymentIntent](/global-acquiring/v1.6/api-reference/cancel-payment-intent), [List PaymentIntents](/global-acquiring/v1.6/api-reference/list-payment-intents), [Retrieve PaymentAttempt](/global-acquiring/v1.6/api-reference/retrieve-payment-attempt), [List PaymentAttempts](/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.