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
• 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

1. 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.

2. 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": "[phone]",
         "email_address": "[e-mail]",
         "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.

3. 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.

4. 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.

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.