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. Only available under the `BANKING` business line.
`COMPANY`	A business entity. Requires additional documents that vary by country and business line.

For COMPANY accounts, call Get Additional Documents before creating the account to find out which documents are required or optional for the target country and business line.

Business lines

A subaccount can be onboarded under one or more business lines:

ACQUIRING — accept card and e-wallet payments
BANKING — send payouts and manage global accounts
ISSUING — issue and manage cards

Onboarding flow

Check required documents (COMPANY only)

If you are onboarding a COMPANY entity, call Get Additional Documents to retrieve the list of required and optional document types for the target country and business line.

curl -X GET "https://api-sandbox.uqpaytech.com/api/v1/accounts/get_additional?country=SG&business_code=BANKING" \
  -H "x-auth-token: YOUR_ACCESS_TOKEN"

This step applies only to COMPANY entity types. INDIVIDUAL accounts do not require additional documents at creation time.

Create the subaccount

Call Create SubAccount with the entity data, business line(s), and entity type.

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",
      "turnover_monthly_currency": "USD"
    },
    "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.

Get Additional Documents API

Retrieve required documents for COMPANY onboarding by country and business line.

Account Status webhook

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

Getting Started

Authentication

Account Management

Webhooks

Reference

Prerequisites

Entity types

Business lines

Onboarding flow

Account status lifecycle

`status`

`verification_status`

Next steps

Connected Accounts

Create SubAccount API

Get Additional Documents API

Account Status webhook

​Prerequisites

​Entity types

​Business lines

​Onboarding flow

​Account status lifecycle

​status

​verification_status

​Next steps

Connected Accounts

Create SubAccount API

Get Additional Documents API

Account Status webhook

Prerequisites

Entity types

Business lines

Onboarding flow

Account status lifecycle

`status`

`verification_status`

Next steps