Skip to main content

Documentation Index

Fetch the complete documentation index at: https://developers-sandbox.uqpaytech.com/llms.txt

Use this file to discover all available pages before exploring further.

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

​
Authentication and API Keys

See Create API Keys for the step-by-step flow. Your Client ID and API Key are both generated from the Dashboard’s Developer → API Keys page. The API Key is displayed only once — copy it immediately.
The x-auth-token header value must be prefixed with Bearer followed by a space. For example:
x-auth-token: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Omitting Bearer or the space after it causes this error. The token itself comes from the Request Access Token endpoint.
Yes. For acquiring, only one token can be active at a time. When you generate a new token, the previous token is immediately invalidated — even if it has not yet expired.If you have concurrent requests that may still be using the old token when you rotate, coordinate your refresh logic so in-flight requests complete before you issue a new token. Token expiry is indicated by the expired_at field in the token response; the default TTL is 30 minutes. See Request Access Token.
See Idempotent Requests for the full rules — including the 24-hour key lifecycle and retry behavior. Use a fresh UUID for each new operation; reuse the same key only when retrying the same logical request.
This means the x-client-id you are using does not exist or does not match the production environment. Verify that you are using the client ID generated from your production account at https://app.uqpay.com, not from the sandbox portal at https://app-sandbox.uqpaytech.com. The two environments use separate credentials.

​
Sandbox Testing

No. Sandbox KYC is mocked — you can submit any values and they will be approved automatically. The sandbox environment is available at https://app-sandbox.uqpaytech.com. API requests go to https://api-sandbox.uqpaytech.com.
No. In the sandbox, card validation is skipped. You can enter any card number and CVC and the transaction will proceed. Use the test cards listed in the sandbox testing guide to trigger specific scenarios such as 3DS challenge mode, frictionless mode, or failure.
merchant_order_id is not validated for uniqueness by UQPAY — you can submit the same value and multiple PaymentIntents will be created. Use payment_intent_id (the PI... prefix ID returned by our API) as the authoritative order reference within UQPAY.Recommendation: Assign a unique merchant_order_id to every order on your side. This simplifies reconciliation and avoids issues with upstream channels that enforce uniqueness — for example, Alipay CN requires a unique merchant_order_id, and submitting duplicates will cause Alipay-side errors.

​
Payment Lifecycle and Status

See Core Concepts for the complete PI and PA status tables, including which status signals success, which triggers each webhook event, and the PI auto-close behavior after 30 minutes.
For the common case of one PI to one PA, you can treat PI SUCCEEDED as authoritative for payment success. However, because a failed PA causes the PI to revert to REQUIRES_PAYMENT_METHOD rather than immediately FAILED, you should also monitor PA status to detect failure promptly.Recommended approach: subscribe to both acquiring.payment_attempt.succeeded (or acquiring.payment_intent.succeeded) and acquiring.payment_attempt.failed webhooks, and also use acquiring.cancel.succeeded for explicit cancellations.
30 minutes. See Core Concepts — Payment Intent for the full expiration behavior.
  • Cancellation applies to payments that have not yet reached a final state — see Cancellation for eligibility rules per payment method.
  • Refund applies to completed payments — see Refunds for eligibility, refundable amount, and fee handling.
No. For card payments, once a PaymentIntent has been captured and reaches a terminal state (SUCCEEDED), cancellation is not available. You must use the refund API if the original capture has been completed. See Cancellation for which payment methods support cancellation after success.

​
3D Secure Integration

See 3DS Integration Guide — Option 1 and Option 2 for the full request parameters (including three_ds_action, browser_info, ip_address) and response handling (next_action.redirect_iframe vs next_action.redirect_to_url).
Check these:
  1. return_url not set: For 3DS, use the three_ds.return_url field (not the top-level return_url). After a successful 3DS authentication and payment, the user will be redirected to this URL.
  2. Query parameters truncated: If your return_url contains query parameters, verify they are URL-encoded correctly and not stripped. This was a known issue that has been fixed — if you still see truncation, contact support.
  3. Both success and failure redirect: Previously, only successful payments redirected to return_url; failures went to a UQPAY error page. This has been updated — both outcomes now redirect to return_url. Your results page should query the order status via API rather than relying on the redirect itself as confirmation of success.
When making payments from a web browser, device_id is often unavailable. The field is not required for web-context requests. You can omit it for browser-based integrations. Passing a fabricated device ID does not help and may increase rejection rates.

​
Webhooks

See Webhook Settings for the step-by-step flow. Use separate webhook subscriptions per product line (acquiring, issuing, etc.) to keep event filters clean.
  1. IP whitelist: If your server restricts inbound connections by IP, allowlist UQPAY’s webhook source IPs — see the IP whitelist section in Webhooks Overview.
  2. Subscription scope: Confirm that you subscribed to the correct event types in the portal.
  3. Multiple environments: If both your staging and production systems connect to the UQPAY production environment, you can configure multiple webhook URLs in the same subscription. Be aware that both URLs will receive all events — make sure your systems handle this correctly (e.g., avoid duplicate database writes).
See Webhook Delivery Troubleshooting Guide for the full checklist.

​
Refunds

Refunds are debited from your available balance:
  • Already-settled orders: Refunds are deducted from your Available to pay out balance.
  • Not-yet-settled orders: Refunds are deducted from your Available soon (pending) balance.
If you have withdrawn all of your available balance and no pending settlements have arrived yet, you will not have enough funds to process the refund until the next settlement batch runs.
Sandbox refunds require the order to be in SUCCEEDED status. Sandbox orders do not auto-settle, so you may encounter Invalid order status if you try to refund before the order reaches the correct state. Ask support to manually trigger settlement if you need to test the full refund flow in sandbox.If you get Refund is processing, please try again after, it means another refund request for the same order is already in progress. Wait for it to complete before submitting a new one.See Refunds and Testing in Sandbox.
Some issuers (typically the cardholder’s bank) will reject refund requests. This is indicated by a FAILED status on the refund after it was initially PROCESSING or INITIATED. Common reasons include the issuer’s internal fraud or compliance rules — these are not related to your integration parameters.If refunds are failing intermittently rather than consistently, the cause is likely the issuer side rather than a configuration issue. UQPAY will raise a ticket with the card network on your behalf, but final resolution depends on the issuer.

​
Settlement and Reconciliation

See Settlement Report for the downloadable CSV formats (Payment Report and Settlement Report) and a full field-by-field description of each column.

​
POS Integration