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

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

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

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

​
FX Conversion

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

See Check previous webhooks or re-trigger for step-by-step instructions on resending webhook events from the Dashboard.
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 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

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

Call List Balances to list all currency balances, or Retrieve Balance for a specific currency.
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.
  • 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.