> ## 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.

# Integration FAQ

> Answers to common questions encountered during Global Account 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.

## Authentication and API Keys

<Accordion title="Where do I find my API credentials (x-client-id and x-api-key)?">
  See [Create API Keys](/account-center/v1.6/guide/create-api-keys) for the step-by-step flow for generating `x-client-id` and `x-api-key` in the Dashboard. If the **Create** button is not visible, your account's API functionality has not been activated yet — contact your account manager to enable it.
</Accordion>

<Accordion title="I get 'API functionality is not activated, please contact the administrator' when creating an API key.">
  This error means the API product has not been enabled for your account. Contact your UQPAY account manager or support team and ask them to activate API access for your merchant account. This is a manual enablement step on the UQPAY side.
</Accordion>

<Accordion title="I'm getting 403 Forbidden when calling the token endpoint. What's wrong?">
  The most common causes are:

  1. **Wrong base URL** — Make sure you are using the correct environment URL. Sandbox: `https://api-sandbox.uqpaytech.com`; Production: `https://api.uqpay.com`.
  2. **Wrong credentials** — Sandbox credentials do not work on production and vice versa. Confirm which environment your `x-client-id` and `x-api-key` were created in.
  3. **IP allowlist** — If you configured an IP restriction when creating the API key, requests from other IPs will be blocked. You can remove or update the IP restriction in the Dashboard API Key settings.
</Accordion>

<Accordion title="I get 'Access to this resource is forbidden from UAT' when calling sandbox.">
  This error (`"error": "Forbidden", "message": "Access to this resource is forbidden from UAT"`) means the credentials you are using were created in the production environment but you are calling the sandbox URL, or the account has not been provisioned for sandbox access. Ask your account manager to enable sandbox access for your account and provide sandbox-specific credentials.
</Accordion>

<Accordion title="How long does the access token last, and when should I refresh it?">
  Access tokens are valid for **30 minutes**. Refresh the token before it expires rather than waiting for a 401 error — a common pattern is to re-fetch every 25–29 minutes. Do not store the token indefinitely; re-fetch it on application start and on a scheduled interval. See [Request Access Token](/account-center/v1.6/api-reference/access-token).
</Accordion>

***

## Sub-accounts and Account Structure

<Accordion title="What is the difference between a house account, a sub-account, and a virtual account (VA)?">
  * **House account** (also referred to as **Master account**): Your primary UQPAY account. All API credentials belong to this account.
  * **Sub-account**: A child account created under your house account, representing one of your end customers or business units. Sub-accounts hold balances and can have their own virtual accounts.
  * **Virtual account (VA)**: A bank account number (e.g., IBAN, account number with sort code) assigned to a sub-account. Incoming funds sent to the VA are deposited into the sub-account's balance.

  To operate on behalf of a sub-account via the API, include the `x-on-behalf-of` header with the sub-account's `account_id` (the long UUID format). See [Virtual Account, Global Account, and Local Account](/global-account/v1.6/guide/virtual-account-global-account-local-account).
</Accordion>

<Accordion title="Can I create a sub-account via API, or does it have to be done through the Dashboard?">
  Both options are available. Both **personal** (individual) and **company** sub-accounts can be created either through the Dashboard or via the Create Sub-Account API. After creation via either method, you can manage the account through the API using the `x-on-behalf-of` header.
</Accordion>

<Accordion title="How does x-on-behalf-of work? Can I pass the parent account ID to query a sub-account's data?">
  Set `x-on-behalf-of` to the sub-account's `account_id` (the long UUID). You must use the sub-account's own ID — passing the parent/house account ID will not return sub-account data on any endpoint.

  For deposit queries: the deposit `account_id` in the webhook notification is the sub-account UUID. You can pass that value in `x-on-behalf-of` when calling the deposit detail endpoint.
</Accordion>

<Accordion title="Which account_id format should I use — the short CB-prefixed ID or the long UUID?">
  * The short `CB`-prefixed ID (e.g., `CB4316632576`) is used in the Dashboard and in some webhook fields as `short_entity_id`.
  * The long UUID is used in API request headers (`x-on-behalf-of`), API response bodies, and as the canonical identifier when calling most endpoints.

  The two formats refer to the same account. Use the long UUID for all API calls.
</Accordion>

<Accordion title="A sub-account I created only has one VA and there is no 'Add VA' button. Why?">
  The ability to create additional virtual accounts depends on the products enabled for that sub-account. If the sub-account was onboarded without certain currency or region configurations, the option to add more VAs may be restricted. Contact your account manager to check which products and currencies are configured for the account.
</Accordion>

***

## Virtual Account Creation

<Accordion title="The Create VA response returns empty results (total_items: 0) when I query with x-on-behalf-of. Why?">
  Common causes:

  1. The `x-on-behalf-of` value is set to the sub-account's ID but the VA was created under a different account.
  2. The sub-account has not been approved / activated yet.
  3. The token used to authenticate the request was issued for the parent account, but `x-on-behalf-of` is set to an unrelated sub-account ID.

  Verify that the `x-on-behalf-of` value matches the `account_id` of the sub-account that owns the VA, and that the account has completed KYC.
</Accordion>

<Accordion title="How do I know which VA the deposit_id in a webhook belongs to?">
  The deposit webhook includes an `account_id` field containing the sub-account UUID that received the funds. Use this UUID in `x-on-behalf-of` when calling `GET /api/v1/deposits/{deposit_id}` to retrieve the full deposit detail, including the receiving account number. You should store the mapping of `account_id` → VA account number in your own system to avoid needing to query on every notification.
</Accordion>

***

## Payouts (POBO)

<Accordion title="I'm getting 'beneficiary account not exists' when submitting a payout. The beneficiary ID looks correct.">
  This error occurs when the `beneficiary_id` passed in the payout request does not exist in the sub-account context you are operating under. Check that:

  1. The `x-on-behalf-of` header matches the sub-account that created the beneficiary.
  2. The beneficiary was not deleted. Once deleted, a beneficiary ID is invalid.
  3. You are not mixing sandbox and production beneficiary IDs.
</Accordion>

<Accordion title="What is the correct clearing_system value for South Africa (ZAR) payouts?">
  For South Africa, the required `clearing_system` depends on the payment type. When creating a beneficiary for ZAR via local rails, include `"clearing_system": "LOCAL"` in `bank_details`. Also make sure to include the `routing_code_type1` field. The API error `'bank_details.clearing_system' is required` confirms the field is missing from your request body.
</Accordion>

<Accordion title="Payout to Colombia (COP) fails with 'Field additional_info.msisdn failed on e164 validation'. What format is required?">
  The `msisdn` field for Colombian mobile money payouts must be in E.164 format, which requires the country code prefix. For Colombia, prepend `+57` to the local number. For example, a local number `3122885049` should be submitted as `+573122885049`. Verify this format works for the specific clearing network being used.
</Accordion>

***

## FX Conversion

<Accordion title="I'm getting 'conversion date is invalid' when calling the quote endpoint with a specific date.">
  Call `GET /api/v1/conversion/conversion_dates?currency_to=X&currency_from=Y` to retrieve the list of valid settlement dates for a given currency pair. Only dates returned from this endpoint are acceptable in the `conversion_date` field. Weekends and public holidays are typically excluded.
</Accordion>

<Accordion title="I get 'account not config fx product' when calling the conversion quote endpoint.">
  Your account does not have the FX product enabled. Contact your account manager to activate FX/conversion functionality. This is a product configuration that must be enabled at the account level before the conversion endpoints become available.
</Accordion>

***

## Webhooks

<Accordion title="How do I trigger deposit webhooks in the sandbox for testing?">
  See [Check previous webhooks or re-trigger](/account-center/v1.6/guide/webhooks-setting#check-previous-webhooks-or-re-trigger) for step-by-step instructions on resending webhook events from the Dashboard.
</Accordion>

<Accordion title="I'm not receiving deposit.pending or deposit.completed webhooks. How do I set up webhook endpoints?">
  Configure your webhook URL in the Dashboard under **Settings → Webhooks**. Make sure the endpoint is publicly accessible (UQPAY cannot reach localhost). After configuring, use the **Re-Trigger** function on existing events to verify delivery. If you're not receiving events for new deposits, confirm that the webhook subscription includes the `deposit.pending` and `deposit.completed` event types for the banking product.

  See [Webhooks Setup](/account-center/v1.6/guide/webhooks-setting) and [Webhook Delivery Troubleshooting](/account-center/v1.6/guide/webhook-delivery-troubleshooting-guide).
</Accordion>

<Accordion title="The deposit webhook payload doesn't include the VA account number (IBAN/account number). How do I know which account received the funds?">
  The webhook `deposit` event includes the `account_id` (sub-account UUID) and `deposit_id`. To get the full deposit details including the receiving account number, call `GET /api/v1/deposits/{deposit_id}` with `x-on-behalf-of` set to the `account_id` from the webhook. The response includes the receiver's account number. Consider caching the `account_id` → VA number mapping at onboarding time to avoid repeated lookups.
</Accordion>

***

## Sandbox Testing

<Accordion title="How do I get sandbox access and credentials?">
  Request sandbox access from your UQPAY account manager. They will either:

  * Provision a sandbox account and send you the login credentials, or
  * Guide you to self-register at `https://app-sandbox.uqpaytech.com` and then activate sandbox banking products for your account.

  Once logged in, create an API key from **Settings → API Keys**. Use `https://api-sandbox.uqpaytech.com` as the base URL for all API calls.
</Accordion>

<Accordion title="I created a sub-account in sandbox via KYC API and it's stuck in a non-approved state. How do I get it approved for testing?">
  In the sandbox environment, KYC approval does not happen automatically. Ask your UQPAY technical contact to manually approve the sub-account application in the backend. Provide the `account_id` (CB-prefixed short ID or UUID) and specify the desired end state (e.g., `Active`). Similarly, if you need to test the RFI flow, ask them to set the account to a `Returned` state so you can test the resubmission path.
</Accordion>

<Accordion title="How do I top up sandbox balance for testing payouts and conversions?">
  Sandbox balances are managed by the UQPAY technical team. Request a top-up by providing your sandbox account ID and the currency/amount.
</Accordion>

***

## Balance and Transfers

<Accordion title="How do I query balance for a specific currency?">
  Call [List Balances](/global-account/v1.6/api-reference/list-balances) to list all currency balances, or [Retrieve Balance](/global-account/v1.6/api-reference/retrieve-balance) for a specific currency.
</Accordion>

<Accordion title="How do I transfer funds from a sub-account back to the house account?">
  Use the internal transfer API (`POST /api/v1/transfer`). Set the sub-account as `source_account_id` and the house account as `target_account_id` in the request body. The authenticated account must be one side of the transfer, and direct sub-account to sub-account transfers are not supported. See [Transfer Between Accounts](/global-account/v1.6/guide/transfer-between-accounts).
</Accordion>

<Accordion title="How does the fee_paid_by (OURS vs SHARED) option work for payouts?">
  * `OURS`: The fee is deducted from your account balance separately from the payout amount. The beneficiary receives the full `payout_amount`.
  * `SHARED` (SHA): The fee is deducted from the payout amount in transit. The beneficiary receives `payout_amount` minus intermediary fees.

  For SWIFT payouts where you want the beneficiary to receive the exact specified amount, use `OURS`.
</Accordion>