Issuing

Cardholder Delivery Address Field Added

[ENHANCED] Added delivery_address field to cardholder response objects

• The delivery_address field is now included in cardholder retrieval and listing responses, providing complete delivery address information for cardholders

Affected Endpoints:

• Retrieve Cardholder, response only
• List Cardholders, response only

Changes:

• Added delivery_address field to cardholder response objects
• Field structure includes:
  JSON

  "delivery_address": {
    "city": "Singapore",
    "country": "SG",
    "line1": "9 N Buona Vista Dr",
    "state": "Singapore",
    "line2": "THE METROPOLIS",
    "postal_code": "138666"
  }

Acquiring

Payment Intent IP Address Field Restructure

Moved ip_address field to top level

Affected Endpoints:

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

Changes:

• move browser_info.ip_address field to top level (same level as payment_method)
• Conditional requirement for ip_address field
• Field becomes mandatory when payment_method.card.three_ds_action = enforce_3ds

Acquiring

ENHANCED Payment Intent Billing Address State Validation

• Enhanced billing address validation for US and Canada payments

Affected Endpoints:

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

Changes:

• Changed: payment_method.card.billing.address.state field validation
• Updated: State field is now conditionally required when billing.address.country_code is "US" or "CA"

NEW Multiple Payment Methods Support

• Added support for additional payment methods in Payment Intent creation

Affected Endpoints:

• Create a PaymentIntent
• Confirm a PaymentIntent

Changes:

• Added: Support for new payment methods: TRUEMONEY, TNG, GCASH, DANA, KAKAOPAY, TOSSPAY, NAVERPAY
• Enhanced: payment_method field now accepts expanded payment method options

Notes:

• These new payment methods expand UQPAY's coverage in Southeast Asian markets

NEW Manual Payment Capture

• Added manual capture functionality for card payments

Affected Endpoints:

• Capture a PaymentIntent (POST /v2/payment_intents/{id}/capture), new endpoint

Changes:

• Added: New endpoint for manual payment capture
• Enhanced: Support for auto_capture = false payment flows
• Added: Configurable capture window period (1-24 hours)

Notes:

• Use this endpoint when auto_capture is set to false or empty
• UQPAY will automatically capture funds after the window period if not manually captured
• Merchants can cancel orders within the capture window period

Banking

ENHANCED Beneficiary Entity Type Notification

• Added beneficiary entity type information to webhook notifications

Affected Endpoints:

• beneficiary.* webhooks

Changes:

• Added: beneficiary_entity_type field to webhook payload
• Enhanced: Webhook notifications now include entity type classification

Notes:

• The new field indicates whether the beneficiary is "INDIVIDUAL" or "COMPANY"

Issuing

ENHANCED Cardholder Phone Number Validation Rules

• Updated phone number length validation for multiple countries

Affected Endpoints:

• Create Cardholder, request only

Changes:

• Updated: Phone number validation rules for the following countries:
  • Nigeria (NG): Now accepts 8 or 10 digits (previously 8 only)
  • Bangladesh (BD): Now accepts 8 or 10 digits (previously 8 only)
  • Libya (LY): Now accepts 8 or 9 digits (previously 8 only)
  • Senegal (SN): Now accepts 7 or 9 digits (previously 7 only)
  • Mayotte (YT): Now accepts 8 or 9 digits (previously 8 only)
  • Ecuador (EC): Now accepts 7 or 9 digits (previously 7 only)
• Updated: Republic of the Congo area code changed from 2420 to 242

Notes:

• Length validation applies to the phone number excluding country/region/area codes

Account Center

Enhanced SubAccount Creation for TPSP Master Accounts

Added new fields to support enhanced KYC requirements for TPSP (Third-Party Service Provider) master accounts during sub-account creation.

Affected Endpoints:

• Create SubAccount, request only

Changes:

• Added ownership_details.representatives.face_docs field for company entity types
• Added identity_verification.face_docs field for individual entity types
• Added tos_acceptance.tos_agreement field for both entity types

Notes:

• 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
• For individual entities: Face verification documents are mandatory
• The tos_agreement field is optional, allows automatic signing of TPSP Terms of Service when set to 1

Acquiring

New Account Balance Query Endpoints

[NEW] Added new API endpoints for account balance queries

New Endpoints:

• Retrieve Balance
• List Balances

Description:

• Merchants can retrieve individual currency account balances or list all currency account balances through this series of endpoints

New Payout Management Endpoints

[NEW] Added new Payout management API endpoints

New Endpoints:

• Create Payout
• Retrieve Payout
• List all Payouts

Description:

• Merchants can now initiate payouts through the Create Payout API and receive real-time payout status updates via Payout webhooks
• Merchants can also retrieve payout details and list information through query endpoints

Banking

Enhanced Chinese Character Support for Company Names

[ENHANCED] Added support for Chinese parentheses in company names and account holder names for specific payment conditions

• Enhanced input validation to support Chinese parentheses （） in company_name and account_holder fields when bank_country_code = CN, account_currency_code = CNH, payment_method = LOCAL, entity_type = COMPANY

Affected Endpoints:

• Create Payout, request only
• Create Beneficiary, request only

Changes:

• Added: Support for Chinese parentheses in company_name field
• Added: Support for Chinese parentheses in account_holder field

Notes:

• This enhancement improves user experience for Chinese companies using local payment methods
• Only applies to specific payment conditions

Relaxed Input Validation for Local Payments

[ENHANCED] Removed input validation for certain fields when using local payment methods with non-CNH/SGD currencies

• Disabled input validation for multiple fields when payment_method = LOCAL and account_currency_code is not CNH or SGD

Affected Endpoints:

• Create Payout, request only
• Create Beneficiary, request only

Changes:

• Updated: bank_details.account_holder field validation
• Updated: first_name & last_name field validation
• Updated: company_name field validation
• Updated: address.street_address field validation
• Updated: address.city field validation
• Updated: address.state field validation

Notes:

• Validation is only relaxed for local payments with currencies other than CNH or SGD
• This change provides more flexibility for international local payment processing

Enhanced Payout Reference Validation Rules

[ENHANCED] Updated validation rules for payout_reference field based on payment method and currency

• Adjusted payout_reference field validation to provide different rules for SWIFT payments and LOCAL payments with non-CNH/SGD currencies

Affected Endpoints:

• Create Payout, request only

Changes:

• Updated: payout_reference validation rules based on payment method and currency:
  • SWIFT payments: New validation pattern /^[a-zA-Z0-9/-?:().'+, ]+$/ (supports space and additional special characters)
  • LOCAL payments: No validation when payment_method = LOCAL and account_currency_code is not CNH or SGD

Invoice Document Requirement for INR Cross-Currency Payouts

[NEW] Added mandatory invoice document upload requirement for INR cross-currency payouts

• Cross-currency payouts to INR now require invoice document upload in the documentation field

Affected Endpoints:

• Create Payout, request only

Changes:

• Added: Mandatory invoice document requirement

Notes:

• Applies when beneficiary.bank_details.account_currency_code = "INR" and clearing_system = "IFSC"
• Invoice document must be uploaded in the documentation field

Removed OTHER_SERVICES from Purpose Code Enumeration

[BREAKING] Removed OTHER_SERVICES option from purpose_code field enumeration

• The OTHER_SERVICES value has been removed from the purpose_code field options in Create Payout endpoint

Affected Endpoints:

• Create Payout, request only

Changes:

• Removed: OTHER_SERVICES from purpose_code enumeration

Notes:

• This is a breaking change - existing integrations using OTHER_SERVICES will need to update their purpose_code values

Acquiring

New Webhook Event for Payment Intent

[NEW] Added new webhook event to notify when payment requires customer interaction for authentication

Added Webhook:

• acquiring.payment_intent.requires_action

Notes:

• This webhook is triggered when payment intent status is REQUIRES_CUSTOMER_ACTION and occurs during customer interaction phase for authentication purposes

Account Center

[BREAKING]Changed document-related fields from object to array in Create SubAccount

• Updated the data type for multiple file/document fields in Create SubAccount API, allowing multiple documents to be provided instead of a single object.
• Affected Endpoints:
  • Create SubAccount, request only
• Changes:
  • identity_verification.identity_docs: changed from object → array
  • ownership_details.shareholder_docs: changed from object → array
  • ownership_details.representatives.identity_docs: changed from object → array
  • company_info.certification_of_incorporation: changed from object → array
  • proof_documents.proof_of_address: changed from object → array
  • proof_documents.source_of_funds: changed from object → array
  • proof_documents.proof_of_position_and_income: changed from object → array

Banking

Cross Currency Payout

• To supports customers payout funds in any currency, and recipients receiving funds in any currency
• Supported currencies depend on actual configuration, check here for details

Affected Endpoints：

Create Quote, request only

• Added the transaction_type field with the following enumeration values:
  • conversion: This value is used by default if this field is left blank. It can only be used for currency conversion.
  • payout: Cross-currency payout. Can only be used for payouts.

Create Payout, request only

• Added the payout_currency and payout_amount fields, which represent the actual currency and amount received by the recipient.
• Added quote_id field, which is obtained from the Create Quote API when pre-locking the exchange rate and will be associated with the cross-currency payout.

Retrieve Payout & List Payouts, response only

• Added quote_id field
• Added conversion field
• JSON

  “conversion": {
    "currency_pair": "",
    "client_rate": ""
  }

Webhook: payout.*

• Added new fields: conversion, quote_id, payout_amount, and payout_currency

[BREAKING]Added restrictions to basic information input for Recipients

• Affected Endpoints:
  • Create Beneficiary, request only
  • Create Payout, request only
• Affected Fields:
  • bank_details.account_holder
  • first_name & last_name
  • company_name
  • address.street_address
  • address.city
  • address.state
• Added new validation applies to all conditions except:
  • bank_details.account_currency_code = CNH & payment_method = LOCAL & bank_country_code = CN
• Changes/ New validation:
  • Only English, numbers, special characters, and spaces can be included
  • Special characters including -_().,@#~ ! $ % ^ & * + = { } [ ] \ | : " ' \< > ? /・……
• Notes:
  • For specific scenarios (such as when entity_type = INDIVIDUAL, bank_details.bank_country_code = SG, and bank_details.account_currency_code = SGD), stricter account_holder name validation rules will be applied. If such validation is triggered, the error message returned by the API will indicate clearly.

[BREAKING]Added restrictions to Payout reference

• Affected Endpoints:
  • Create Payout, request only
• Affected Fields:
  • payout_reference
• Changes/ New validation:
  • Only alphabetic characters, numbers, spaces, commas ,, and periods . are allowed.

Issuing

Added new fields for reports

• Affected Reports:
  • Card Transaction Report
  • Card Settlement Report
• Changes:
  • Added new field Ori Transaction Id

Introduced Bulk Virtual Card Creation API

• Added a new endpoint to support bulk creation of virtual cards.
• Affected Endpoints/Webhook:
  • Bulk Create Virtual Cards , Endpoint Added
  • issuing.report.succeeded, Webhook Added
  • Assign Card, expanded for bulk-created virtual cards
• Changes:
  • Merchants can now create multiple virtual cards in a single request, without requiring immediate cardholder binding.
  • The Assign Card API has been enhanced to enable binding for bulk-created virtual cards.
  • A report_id is returned after submission. Merchants can retrieve the card number file using the Download Report API before it expires.
  • The card numbers in the file are encrypted.
    • Before calling the Bulk Create Virtual Cards, you must subscribe to the issuing.report.succeeded webhook.
    • This webhook delivers the decryption key required to access the card numbers.

Banking

Made email and nickname optional

• The email and nickname fields for all beneficiaries are now optional.
• Affected Endpoints:
  • Create Beneficiary, request only
  • Create Payout, request only
• Changes:
  • 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, several request fields are adjusted.
• Affected Endpoints:
  • Create Beneficiary, request only
  • Create Payout, request only
• Changes:
  • company_name: Removed
  • first_name: Removed
  • last_name: Removed
  • email: Changed to optional
  • nickname: Changed to optional
  • address.country: Removed
  • address.street_address: Removed
  • address.city: Removed
  • address.state: Removed
  • address.postal_code: Removed

[BREAKING] New validation rule for bank_details.account_holder

• A new format validation applies only when all three conditions are met:
  • entity_type = INDIVIDUAL
  • bank_details.bank_country_code = SG
  • bank_details.account_currency_code = SGD
• Affected Endpoints:
  • Create Beneficiary, request only
  • Create Payout, request only
• Changes:
  • New validation requirements for bank_details.account_holder:
    • Only English letters (A–Z, a–z) and spaces are allowed
    • Length must be 2–140 characters
    • Must include a space separating first and last name
  • If any condition is not met, the previous validation rules remain unchanged

Card Issuing

Added consumed_amount field

• Introduced new field consumed_amount in List and Retrieve Card API responses, representing the cumulative amount of the card limit that has already been used.
• Affected Endpoints:
  • List Cards, response only
  • Retrieve Card, response only
• Changes:
  • Added consumed_amount field

Account Center

Supportbusiness_code in Account retrieval and listing

• Enable querying sub-accounts across Acquiring, Banking, and Card Issuing.
• Affected Endpoints:
  • Retrieve Account, request and response
  • List Connected Accounts, response only
• Changes:
  • Request (Retrieve Account only): Add optional business_code with enum values BANKING, ISSUING, ACQUIRING. If omitted, default to BANKING.
  • Response: Add business_code to indicate business line for both Retrieve and List.

Addemail_address for representatives in Create SubAccount

• Affected Endpoints:
  • Create SubAccount, request only
• Changes:
  • Request: Add optional fieldemail_address to ownership_details.representatives[].

Makewebsite_url and company_description optional in Create SubAccount

• Relax requiredness for business_details fields.
• Affected Endpoints:
  • Create SubAccount, request only
• Changes:
  • Request: Change business_details.website_url and business_details.company_description from required to optional.

Card Issuing

Simulate Authorization now supports card BIN40963608

• Added support to run authorization simulations in sandbox
• Affected Endpoints:
  • Simulate Authorization
• Changes:
  • No request/response schema changes.

Acquiring

New Payment Attempt webhook events

• Added new Payment Attempt (PA) webhooks to improve the timeliness of payment result notifications.

• Added Webhoooks:

  • acquiring.payment_attempt.created: triggered when PA status is INITIATED.
  • acquiring.payment_attempt.capture_requested: triggered when PA status is CAPTURE_REQUESTED. Receiving this event indicates the consumer has completed the payment, and 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 mapping (one PI contains only one PA): the corresponding PI can be considered failed as well (actually the PI itself transitions to FAILED after the system auto-close the PI).
    • For one-to-many mapping (one PI may include multiple PAs): the failure of one PA does not mean the PI has failed, and merchants can still initiate other PAs under the same PI.

• Doc link: https://docs.uqpay.com/reference/paymentattempt-result#/
  Note: To receive these notifications, please subscribe to the corresponding events in your Dashboard.

New Settlements API

• Introduced a new API to query settlement detail records that have been successfully settled.
• Added Endpoints:
  • Get list of settlements: GET /api/v2/payment/settlements
• Feature:
  • Supports optional parameters settlement_batch_id or payment_intent_id to query corresponding settlement records.
  • Supports pagination and time range filters.
  • Returns settlement detail records with settlement_status = success.
  • Refer to the Get list of settlements for full schema and examples.

Banking

[BREAKING]Added format restriction foraccount_number field

• Affected Endpoints:
  • Create Payout, request only
  • Create Beneficiary, request only
• Changes:
  • The bank_details.account_number field now only accepts alphanumeric characters (letters A–Z/a–z and digits 0–9).
  • Spaces, hyphens, and other special symbols are not allowed. If provided, the request will be rejected with a format error.
• Notes:
  • Applies to both INDIVIDUAL and COMPANY entity type beneficiaries.

Card Issuing

Addedupdate_reason field in Card APIs and Webhook

• Added a new field update_reason in both Card APIs and webhook events to indicate the reason for a card status change.
• Affected Endpoints:
  • List Cards, response only
  • Retrieve Card, response only
  • Update Card Status, response only
• Affected Webhooks:
  • card.status.update.*
• Changes:
  • New field update_reason is added to the API responses and webhook payload.

Card Recharge and Withdraw now support SHARE cards

• Affected Endpoints:
  • Card Recharge, request only
  • Card Withdraw, request only
• Changes:
  • SHARE cards now can adjust card_available_balance by
    • Card Recharge: increasing card_available_balance.
    • Card Withdraw: decreases card_available_balance.
• Notes:
  • For SINGLE cards: behavior remains unchanged.