Acting on behalf of child accounts

Before you begin

Delegated child-account access must be enabled by Azupay. Contact Azupay Support or your account representative if you need this capability enabled.

A delegated request is allowed only when:

• The parent client and API key are enabled.
• Delegated child-account access is enabled for the parent.
• The selected account is an enabled direct child of the parent.
• The requested operation is permitted for the parent API key.

Delegated access currently supports direct children only. You cannot select:

• The parent account itself
• A grandchild or deeper descendant
• An account belonging to another parent

Select a child account

To make a request on behalf of a direct child, append the child’s client ID to the parent API key in the Authorization value:

Authorization: <parent-api-key>,<direct-child-client-id>

The parent API key authenticates the request, while the appended child client ID selects the account context in which the operation runs.

Payment Request example

The following example creates a Payment Request for the selected child account:

POST /v1/paymentRequest
Authorization: <parent-api-key>,<direct-child-client-id>
Content-Type: application/json

{
  "PaymentRequest": {
    "clientId": "<direct-child-client-id>",
    "clientTransactionId": "INV-0000001-1",
    "paymentAmount": 32.12,
    "paymentDescription": "Payment for invoice INV-0000001"
  }
}

The clientId in the request body must match the child client ID selected in the Authorization value.

Reports example

The Reports API requires the child client ID in the clientId query parameter. The value must match the child client ID selected in the Authorization value:

GET /v1/report?clientId=<direct-child-client-id>&month=2026-10&timezone=Australia%2FSydney
Authorization: <parent-api-key>,<direct-child-client-id>

For example:

GET /v1/report?clientId=CHILD_A1&month=2026-10&timezone=Australia%2FSydney
Authorization: <parent-api-key>,CHILD_A1

The request may proceed when:

• The child client ID in the Authorization value is valid.
• The clientId query parameter identifies the same child.
• The parent is authorised to act on behalf of that child.
• The parent API key has permission to use the Reports API.

Matching client IDs

The child client ID in the Authorization value is authoritative. If a client ID also appears in the request path, query parameters, or request body, it must identify the same child.

A mismatched client ID does not create, return, or change resources for either account

Client and API-key management endpoints

Parent clients must use their existing parent-management authorisation format when managing child clients or their API keys:

Authorization: <parent-api-key>

Do not append a child selector to the Authorization value for these endpoints:

Client management

API-key management

For example:

GET /client/CHILD_A1/apiKeys
Authorization: PARENT_A_API_KEY

The following format is not supported for client or API-key management endpoints:

Authorization: PARENT_A_API_KEY,CHILD_A1

These endpoints use the existing parent-management contract. The child account is identified by the endpoint path or request body, depending on the operation.

Permissions

Delegated access does not increase the permissions of an API key.

The requested operation must be included in the parent API key’s permitted operations. If it is not permitted, the request is denied even when delegated child-account access is enabled.

Requests without a child selector

When the API key is used without a child selector, the request continues to run in the API key owner’s account context:

Authorization: PARENT_A_API_KEY

Suggested change management plan

Existing clients can adopt delegated child-account access in stages.

1. Update your integration

Update your integration to identify the child client when making delegated requests with the parent API key.

2. Confirm configuration with Azupay

Contact Azupay when you are ready to enable the feature.

Before enabling it, confirm that:

• The parent client is eligible.
• The parent API key is enabled and the required business API operations are permitted for the parent API key.

3. Use delegated access for new clients

When onboarding a new child client, use the parent API key and the child client ID for supported business API requests.

4. Continue using existing child API keys

Existing or “backbook” clients can continue using their current child API keys. No immediate migration is required.

5. Migrate existing clients when ready

You can decide when to move each existing client from its child API key to the parent API key.

Migration reminder

Keep the existing child API key available until the client has been successfully migrated and tested. Do not disable or remove it until you have confirmed that it is no longer required.

Glossary

The following terms are used throughout this guide to describe parent accounts, child accounts, and delegated API requests.