> ## Documentation Index
> Fetch the complete documentation index at: https://developers.uqpay.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Account Onboarding
> Create and onboard subaccounts for your merchants or customers using the UQPAY API.
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](/account-center/v1.6/guide/create-a-sandbox-account)
* [API keys](/account-center/v1.6/guide/create-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](/account-center/v1.6/api-reference/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
If you are onboarding a `COMPANY` entity, call [Get Additional Documents](/account-center/v1.6/api-reference/get-additional-documents) to retrieve the list of required and optional document types for the target country and business line.
```bash theme={null}
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.
Call [Create SubAccount](/account-center/v1.6/api-reference/create-sub-account) with the entity data, business line(s), and entity type.
```bash theme={null}
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": [""]
},
"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": [""]
},
"tos_acceptance": {
"ip": "203.0.113.42",
"date": "2026-04-15",
"user_agent": "Mozilla/5.0"
}
}'
```
A successful response returns the new account details:
```json theme={null}
{
"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`. |
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.
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](/account-center/v1.6/guide/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](/account-center/v1.6/webhooks/account-status).
## Next steps
Make API requests on behalf of your subaccounts using the `x-on-behalf-of` header.
Full parameter reference for the Create SubAccount endpoint.
Retrieve required documents for COMPANY onboarding by country and business line.
Event payload reference for `onboarding.account.create` and `onboarding.account.update`.