Integration FAQ

Answers to common questions encountered during card issuance API integration, based on real customer feedback.

Common questions and solutions gathered from real integration experiences. If you don’t find your answer here, contact your UQPAY account manager.

Sandbox testing

Simulation API returns 'Card does not exists'

The sandbox simulation endpoint only accepts cards with a specific BIN. The currently supported BIN for simulation is 40963608. Cards with other BINs will return this error.

Also check:

• The card has not been cancelled. Cancelled cards cannot process authorizations.
• You are using the correct sandbox base URL: https://api-sandbox.uqpaytech.com/api

Cannot create cards in sandbox: 'insufficient_sub_bin'

This means the pre-allocated card pool for your BIN is exhausted. Contact your UQPAY account manager to request additional card allocation for the specific BIN.

The card count shown in the dashboard reflects only active cards, not the total allocated pool. You cannot self-service replenish the pool.

Sandbox deposits require manual approval

In sandbox, simulated deposits require manual approval by UQPAY staff before the balance is credited. Submit the deposit reference ID in your support group and staff will approve it. This approval step does not exist in production.

How do I get physical card numbers for sandbox testing?

You cannot use random card numbers for the Assign Card API. UQPAY provisions a set of physical card numbers for sandbox use and sends them to you. Request these from your UQPAY account manager.

Authentication and API setup

Access token validity period

Access tokens are valid for 30 minutes. Cache only one token at a time — generating a new token immediately invalidates all previously issued tokens, regardless of their remaining expiry time.

Use the expired_at field in the token response to determine when to refresh. See Request Access Token.

Error: 'x-on-behalf-of' validation failed

The x-on-behalf-of header requires strict validation:

• Must be a valid UUID format (e.g., 18523f72-f4de-4f9c-bb8e-ec7d1c4f32be)
• Must correspond to a valid Issuing sub-account ID
• Empty or malformed values return an error

If you receive sub_account_not_found, verify the account ID belongs to the Issuing business line (not Banking), and that the sub-account is activated.

API Key IP whitelist

The IP restriction on the API Key is matched against your server’s actual outbound IP reaching UQPAY. If you are behind a VPN or proxy, ensure the configured IP matches your real outbound IP. Local/private IPs (e.g., 192.168.x.x) are not routable and will always fail.

How does x-idempotency-key work?

Submitting the same x-idempotency-key on a repeat request returns the cached result of the original request — no new operation is created. Important behaviors:

• The cached response persists for 24 hours
• If the original request failed (e.g., insufficient balance), retrying with the same key returns the same failure — even if conditions have changed. Use a new key when retrying after fixing the root cause.
• If you receive a 504 timeout, retry with the same key — the server may have already processed the request

'Parse file failed' when uploading KYC documents

Two common causes:

1. Missing Content-Type: Always include Content-Type: multipart/form-data for file uploads
2. Reused idempotency key: The x-idempotency-key must be a valid UUID and unique for each new request

Cardholders

Cardholder name must be in English

first_name and last_name must be in English (Latin characters). Chinese or other non-Latin characters are not accepted. Address fields within delivery_address do accept Chinese.

Error: 'invalid_phone_number'

The phone number must match the country_code format. Pass the country_code matching the phone number’s dialing region, not the cardholder’s nationality. Numbers should be in international format without the leading zero.

See Phone Number Validation Rules for details.

Can cardholders share the same email or phone number?

Uniqueness is enforced per account. Within the same account_id, email and phone number must each be unique — no two cardholders under that account can share either value. The same email or phone can be reused under a different account_id.

Can cardholders be deleted?

No. There is no Delete Cardholder API. Cardholders cannot be removed once created.

Card creation and configuration

Error: 'risk_control_not_allowed'

The risk_controls parameter (including allow_3ds_transactions) is only supported on specific BINs. Passing this parameter for unsupported BINs returns an error. The same restriction applies to no_pin_payment_amount.

See Supported BINs for Risk Control Configurations for the full list.

Error: 'card quota of account exceeds limit'

Your account has reached its maximum card creation limit. Contact your UQPAY account manager to increase the quota.

Error: 'card bin not config'

The BIN or sub-BIN has not been configured for your account. Provide your account ID to UQPAY support and they will assign the appropriate sub-BIN pool. This error also recurs when the sub-BIN pool is exhausted.

Card stays in Pending status after creation

Cards are created in PENDING status and transition to ACTIVE once provisioning completes. To detect activation, either listen for the card.create.succeeded webhook or poll the Retrieve Card endpoint — both are supported.

What is the maximum per-transaction spending limit?

Each card has a maximum single-transaction spending cap enforced by the platform. The specific cap depends on your account configuration, and higher caps are available via a VIP whitelist on a per-card basis. Contact your UQPAY account manager to confirm or adjust the limit for your account.

Sub-account creation limit

There is a cap on the number of sub-accounts you can create under a main account. The specific limit depends on your account configuration — contact your UQPAY account manager to confirm or adjust it for your account.

Card status and lifecycle

What are all possible card_status values?

Status	Description	Controlled by
ACTIVE	Card is active and can process transactions	Merchant
FROZEN	Card is temporarily frozen — can be unfrozen via API	Merchant
BLOCKED	Card is blocked by risk controls — requires UQPAY to unlock	System
PRE_CANCEL	Card is scheduled for cancellation (30-day wait)	—
CANCELLED	Card is permanently cancelled	—

See Card Lifecycle for the full state transition diagram.

What is the difference between FROZEN and BLOCKED?

FROZEN is merchant-controlled: you can freeze and unfreeze a card via the API without contacting UQPAY.

BLOCKED is system-triggered by risk controls (e.g., consecutive failed PIN or expiry attempts). BLOCKED cards can only be unlocked by UQPAY operations — submit an email to [e-mail] with the cardholder name, card ID, current status, and reason for unlock.

Refunds and reversals can still post to both FROZEN and BLOCKED cards.

Can I go directly from FROZEN to CANCELLED?

Yes. You can transition a card from FROZEN directly to CANCELLED in a single API call without first reverting to ACTIVE.

What happens after a card is cancelled?

After cancellation is requested, the card enters PRE_CANCEL status for a 30-day waiting period, then automatically transitions to CANCELLED. During PRE_CANCEL:

• The card cannot process new transactions
• Previously authorized transactions may still settle
• For Single cards, UQPAY automatically sweeps remaining balance back to the merchant account after the waiting period

Can I change limits on a FROZEN card?

No. You must unfreeze the card (set to ACTIVE) before assigning or modifying its limit.

Virtual vs physical card activation

Virtual cards are active immediately upon successful creation — no activation step is required. See Issue Virtual Cards.

Physical cards require activation via /api/v1/issuing/cards/activate, using the activation code delivered by the card.activation.code webhook after assignment. See Issue Physical Cards.

Card funding and limits

Single card vs Share card: limit and funding differences

Behavior	Single Card	Share Card
Funding	Use recharge / withdraw APIs	Draws from merchant pool balance
card_limit	Cannot be changed after creation	Can be modified via Update Card API
Fees	Deducted from card balance (may go negative)	Deducted from pool account

See Core Concepts for background on card types.

Error: 'The single card not support changing card limits'

Single-mode cards do not support modifying card_limit after creation. To adjust a Single card’s spendable amount, use the recharge and withdraw APIs instead.

Is there an API to transfer funds from Banking to Issuing?

No. Currently there is no API for transferring funds between the Banking and Issuing business lines. This must be done manually via the Dashboard’s Deposit button in the Issuing section.

Error: 'product_not_found' when transferring between accounts

This means the Issuing transfer product has not been configured for the sub-account. Contact UQPAY operations to activate it.

Transactions and settlement

What are the possible transaction_status values?

Status	Description
APPROVED	Transaction approved
DECLINED	Transaction declined

PENDING is a transient state that exists only briefly during processing — do not act on it. Wait for the issuing.transaction.authorization webhook, which always carries a terminal state. The REFUNDED status was removed as of May 29, 2025.

The 'failure_reason' field is empty in transaction responses

The failure_reason field was renamed to description as of May 29, 2025. Update your integration to read the description field instead.

This change affects:

• List Cards Transactions API
• Retrieve Cards Transaction API
• card.transaction.* webhook events
• Exported transaction reports

How do I distinguish ATM withdrawals from regular purchases?

Both ATM withdrawals and regular purchases return AUTHORIZATION as the transaction_type. To differentiate, check merchant_data.category_code:

• MCC 6011 = ATM cash withdrawal
• MCC 6011 with billing_amount == 0 = ATM balance inquiry
• Other MCC values = regular purchase

Error: 'card credit limit greater than max Limit'

This means the card’s card_limit exceeds the platform’s maximum allowed single-transaction cap configured for your account. Contact your UQPAY account manager to raise the cap via a VIP whitelist, or keep per-card limits within the configured cap.

Error: 'Exceed Pin Free Amount'

This decline indicates the transaction exceeded the configured contactless/no-PIN limit for the card. The cardholder should retry with PIN entry.

Should I trust a 200 response from recharge/withdraw as confirmation?

No. A 200 response only confirms UQPAY received your request. The actual business result is only guaranteed by the webhook callback. Always use webhooks as the authoritative source of truth.

Webhooks

Not receiving webhook notifications

Check these common causes:

1. Event subscription: Verify you have subscribed to the specific event type. For example, wallet binding OTPs require card.verification.otp; transaction validation requires issuing.transaction.validation.
2. HTTP 200 response: Your endpoint must return HTTP 200 within the timeout period.
3. URL accessibility: Ensure your webhook URL is publicly accessible from UQPAY’s source IPs.

See Webhook Delivery Troubleshooting Guide for the full checklist.

What is the webhook retry schedule?

See Retry logic for the current retry behavior.

What are UQPAY's webhook source IP addresses?

See the IP whitelist section in Webhooks Overview for the current list of source IPs to allowlist on your firewall.

Can failed webhooks be resent?

Yes. Re-send individual events yourself from the Dashboard using the Re-Trigger button. See Check previous webhooks or re-trigger for step-by-step instructions.

3D Secure and wallet payments

Why are 3DS fees charged when allow_3ds_transactions is set to N?

Whether 3D Secure is triggered for a transaction is decided on the acquirer side at checkout time, not on the issuer side. The issuer-side switch allow_3ds_transactions only controls how the cardholder authenticates once 3DS has been triggered — specifically, whether a frictionless (no interaction) flow is permitted, or whether a challenge flow with manual OTP entry is required.

Because the trigger happens at the acquirer, a transaction can still enter the 3DS flow even when allow_3ds_transactions is N, which is why 3DS verification fees may still be incurred.

To bypass 3DS entirely (and avoid the associated verification fees), set enable_3ds to N on the card. This unregisters the card from 3DS so the acquirer cannot trigger 3DS authentication on it. See 3D Secure for the full two-field model.

No OTP webhook received for wallet binding

Wallet binding OTPs require subscribing to the card.verification.otp event type specifically. Standard ISSUING webhook subscriptions do not include this.

Can cardholder email notifications be disabled?

Yes. UQPAY can disable email sending to cardholders (activation codes, 3DS OTPs) at the account level. You then receive these via webhook and deliver them through your own channel. Contact your account manager to configure.

Secure iFrame and PCI

Retrieve Card Secure requires ACTIVE status

The /cards/:id/secure endpoint requires the card to be in ACTIVE status. Calling it on a PENDING card returns Card does not exists. Wait for the card to activate first.

Physical cards

Error: 'card has been assigned' on duplicate assign

If the card has already been assigned successfully, a second Assign Card call returns this error. The assign operation is not idempotent — use the error response to detect duplicates.

Error: 'card number not available for this account'

The physical card number being assigned belongs to a batch not allocated to your account. Physical card inventory is account-specific. Verify that the card batch was registered under the correct merchant account.