Acting On Behalf Of a Subaccount: x-on-behalf-of

Background

UQPAY accounts are structured into a master account and multiple subaccounts under it. These accounts share the same set of API credentials and webhook configurations, ensuring centralized control and streamlined integration.

In some scenarios, you may need to specify which account (master or sub) is performing an operation via API. For this purpose, UQPAY introduces the x-on-behalf-of request header.

Purpose

The x-on-behalf-of header allows API clients to explicitly indicate the subaccount on whose behalf a request is being made . This helps to distinguish between actions initiated by the master account and subaccounts

Note: While API credentials are shared, the data and transaction context are isolated per account. The x-on-behalf-of header ensures operations are properly scoped.

If the header is not provided, the API request is treated as initiated by the master account by default.

Usage

To act on behalf of a subaccount, include the x-on-behalf-of header in your API request. The value must be the account_id of the subaccount you intend to operate on.

You can retrieve a list of your connected subaccounts using the List Connected Accounts API. Each item in the response will include the account_id field required for this header.

e.g. Use the following request to retrieve the list of cardholders created under the specified subaccount (18523f72-f4de-4f9c-bb8e-ec7d1c4f32be)

curl --request GET \
     --url 'https://api-sandbox.uqpaytech.com/api/v1/issuing/cardholders?page_size=10&page_number=1' \
     --header 'accept: application/json' \
     --header 'x-auth-token: {your-token}' \
     --header 'x-on-behalf-of: 18523f72-f4de-4f9c-bb8e-ec7d1c4f32be'

Error Response

If the provided x-on-behalf-of value is incorrect, invalid, or corresponds to a deactivated subaccount, the API will respond with an error like the following:

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

In this case, please verify that the account_id is correct and that the subaccount is active.