Connected Accounts

UQPAY uses a master account and subaccounts model. Your master account holds the API credentials, and all subaccounts under it share those same credentials. This page explains how to list connected subaccounts and make API requests on their behalf.

Account architecture

Account type	Role
Master account	Top-level account that holds API credentials and webhook configuration
Subaccount	An individual or company entity (merchant, customer, or subsidiary) operating under the master account

All API credentials and webhook settings are configured once at the master account level and apply to all subaccounts. To create subaccounts, see Account Onboarding.

List connected accounts

Call the List Connected Accounts API to retrieve all subaccounts linked to your master account.

curl -X GET "https://api-sandbox.uqpaytech.com/api/v1/accounts?page_size=10&page_number=1" \
  -H "x-auth-token: YOUR_ACCESS_TOKEN"

The response contains an array of account objects. Each object includes an account_id field — you’ll use this value when making requests on behalf of that subaccount.

Acting on behalf of a subaccount

To scope an API request to a specific subaccount, include the x-on-behalf-of header set to the subaccount’s account_id.

curl -X GET "https://api-sandbox.uqpaytech.com/api/v1/issuing/cardholders?page_size=10&page_number=1" \
  -H "x-auth-token: YOUR_ACCESS_TOKEN" \
  -H "x-on-behalf-of: SUBACCOUNT_ID"

If you omit x-on-behalf-of, the request is treated as initiated by the master account by default.

Although API credentials are shared, data and transaction context are isolated per account. The x-on-behalf-of header ensures that operations are scoped to the correct account.

When NOT to send `x-on-behalf-of`

The header is intended for endpoints that operate on subaccount-scoped resources. Do not include it on master-account-level operations — for example, listing connected accounts or minting an access token. If a request does not target a subaccount-scoped resource, omit x-on-behalf-of.

Error handling

If the x-on-behalf-of value is invalid or the subaccount is deactivated, the API returns:

{
  "type": "account_error",
  "code": "sub_account_not_found",
  "message": "sub-account associated with the on-behalf-of not found or deactivated"
}

To resolve this, verify that the account_id is correct and that the target subaccount is active.

The account_id must be in UUID format (e.g. 18523f72-f4de-4f9c-bb8e-ec7d1c4f32be), not the short reference ID.

Getting Started

Authentication

Account Management

Webhooks

Reference

Account architecture

List connected accounts

Acting on behalf of a subaccount

When NOT to send `x-on-behalf-of`

Error handling

​Account architecture

​List connected accounts

​Acting on behalf of a subaccount

​When NOT to send x-on-behalf-of

​Error handling

​Related

Account architecture

List connected accounts

Acting on behalf of a subaccount

When NOT to send `x-on-behalf-of`

Error handling

Related