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

Where do I find my API credentials (x-client-id and x-api-key)?

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

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.

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.

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.

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.

---

Sub-accounts and Account Structure

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.

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.

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.

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.

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.

---

Virtual Account Creation

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.

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.

---

Payouts (POBO)

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.

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.

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 [phone]. Verify this format works for the specific clearing network being used.

---

FX Conversion

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.

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.

---

Webhooks

How do I trigger deposit webhooks in the sandbox for testing?

See Check previous webhooks or re-trigger for step-by-step instructions on resending webhook events from the Dashboard.

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 and Webhook Delivery Troubleshooting.

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.

---

Sandbox Testing

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.

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.

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.

---

Balance and Transfers

How do I query balance for a specific currency?

Call List Balances to list all currency balances, or Retrieve Balance for a specific currency.

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 source account using x-on-behalf-of (sub-account) and specify the destination account ID in the request body. See Create Transfer.

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.