Account Onboarding

If you operate a platform or marketplace, you can onboard downstream merchants or customers as subaccounts under your master UQPAY account. Each subaccount has its own identity, verification status, and access to UQPAY products. You manage the subaccounts through the API and can act on their behalf once they are active.

Prerequisites

Before you begin, make sure you have:

An active sandbox account
API keys (x-client-id and x-api-key)

Entity types

When creating a subaccount, you specify the entity type:

Entity type	Description
`INDIVIDUAL`	A personal account for an individual person.
`COMPANY`	A business entity. Additional documents may be required during onboarding.

Onboarding flow

Create the subaccount

Call Create SubAccount with the entity data and entity type. You do not select a business line in this request.

curl -X POST "https://api-sandbox.uqpaytech.com/api/v1/accounts/create_accounts" \
  -H "x-auth-token: YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "entity_type": "INDIVIDUAL",
    "nickname": "John Doe",
    "individual_info": {
      "first_name_english": "John",
      "last_name_english": "Doe",
      "nationality": "SG",
      "phone_number": "+6591234567",
      "email_address": "john.doe@example.com",
      "date_of_birth": "1990-01-15",
      "country_or_territory": "SG",
      "street_address": "1 Raffles Place",
      "city": "Singapore",
      "state": "Singapore",
      "postal_code": "048616",
      "employment_status": "Employed",
      "industry": "Information Technology/IT",
      "job_title": "Business and administration professionals",
      "company_name": "Acme Corp."
    },
    "identity_verification": {
      "identification_type": "PASSPORT",
      "identification_value": "E12345678",
      "identity_docs": ["<BASE64_ENCODED_DOCUMENT>"]
    },
    "expected_activity": {
      "account_purpose": ["PURCHASE"],
      "banking_countries": ["SG"],
      "banking_currencies": ["SGD"],
      "internationally": 1,
      "turnover_monthly": "TM001"
    },
    "proof_documents": {
      "proof_of_address": ["<BASE64_ENCODED_DOCUMENT>"]
    },
    "tos_acceptance": {
      "ip": "203.0.113.42",
      "date": "2026-04-15",
      "user_agent": "Mozilla/5.0"
    }
  }'

A successful response returns the new account details:

{
  "account_id": "7ec16ed4-2efc-4dec-9752-29ab32d6d921",
  "short_reference_id": "CB9221063168",
  "status": "PROCESSING",
  "verification_status": "PENDING"
}

Key fields in the response:

Field	Description
`account_id`	Unique identifier for the subaccount. Use this in subsequent API calls.
`short_reference_id`	Human-readable reference, e.g. `P220406-LLCVLRM`.
`status`	Initial value is `PROCESSING`.
`verification_status`	Initial value is `PENDING`.

Handle the initial response

The account does not become active immediately. After creation:

status is PROCESSING — the account is created but not yet usable.
verification_status is PENDING — identity or business verification is in progress.

Store the account_id for later use. You do not need to poll — use webhooks to receive status updates.

Listen for webhook notifications

UQPAY sends webhook events as the account moves through verification:

Event	When it fires
`onboarding.account.create`	Account creation is completed and processing has begun.
`onboarding.account.update`	Account details or status are updated.

Configure your webhook endpoint in the dashboard. See Webhooks Setting for setup instructions.

Account status lifecycle

After creation, a subaccount moves through two parallel status dimensions:

`status`

Tracks whether the account is operational:

Value	Meaning
`PROCESSING`	Account created; under review. Not yet usable.
`ACTIVE`	Verification approved. The account is fully operational.
`INACTIVE`	Account exists but is currently disabled.
`CLOSED`	Account has been permanently closed.

`verification_status`

Tracks the outcome of identity or business verification:

Value	Meaning
`PENDING`	Verification not yet complete.
`APPROVED`	Verification passed. Account moves to `ACTIVE`.
`REJECT`	Verification failed. The account cannot be activated.
`RETURN`	Submission returned for correction. Resubmit the required information.
`EXPIRED`	Verification window elapsed without completion.

The accountStatus webhook delivers the rejected and returned states as REJECTED and RETURNED (rather than REJECT / RETURN). See Account Status webhook.

Next steps

Connected Accounts

Make API requests on behalf of your subaccounts using the x-on-behalf-of header.

Create SubAccount API

Full parameter reference for the Create SubAccount endpoint.

Account Status webhook

Event payload reference for onboarding.account.create and onboarding.account.update.

Getting Started

Authentication

Account Management

Webhooks

Reference

Prerequisites

Entity types

Onboarding flow

Account status lifecycle

`status`

`verification_status`

Next steps

Connected Accounts

Create SubAccount API

Account Status webhook

​Prerequisites

​Entity types

​Onboarding flow

​Account status lifecycle

​status

​verification_status

​Next steps

Connected Accounts

Create SubAccount API

Account Status webhook

Prerequisites

Entity types

Onboarding flow

Account status lifecycle

`status`

`verification_status`

Next steps