Subprofiles let you create separate payment identities for each branch or outlet under a single verified Customer Profile. Each subprofile displays its own trading name on the PayNow QR, so customers see the specific branch they're paying — while all outlets stay under one Customer Profile and one integration.

Use subprofiles when you operate multiple locations or storefronts under the same business entity (same UEN) and want branch-level identities on your PayNow QR codes.

graph TD
    CP["Customer Profile<br/>(verified, 1 UEN)"]
    CP --> S1["Subprofile: Orchard<br/>trading name"]
    CP --> S2["Subprofile: Bugis<br/>trading name"]
    CP --> S3["Subprofile: ...<br/>trading name"]
    S1 --> Q1["PayNow QR<br/>shows 'Orchard'"]
    S2 --> Q2["PayNow QR<br/>shows 'Bugis'"]

Prerequisites

Before creating a subprofile, you must have a verified customer profile. Subprofiles are created under that profile and inherit its verification.

A subprofile represents a branch of the same legal entity (same UEN). If you need to onboard a separate entity with its own UEN, create a separate Customer Profile instead.

How It Works

A single verified customer profile can hold many subprofiles, each with its own payment address and trading name. Create a subprofile, wait for it to activate, then reference it when generating a PayNow QR.

sequenceDiagram
    participant M as Merchant
    participant API as StraitsX API
    M->>API: Create Subprofile (under verified CP)
    API-->>M: status: pending
    Note over API: Registration completes (seconds)
    API-->>M: webhook: subprofileStatusUpdated → active
    M->>API: Create PayNow QR (with subprofile)
    API-->>M: QR resolves to subprofile's trading name

Step 1: Create a Subprofile

Call the Create Subprofile endpoint under your verified customer profile, providing:

referenceId — your unique identifier for the subprofile
tradingName — the display name shown to payers on this branch's PayNow QR
address — the branch address (street, city, and country required; state and postalCode optional)

📘
Notes:

Naming Guidance: Use your full registered company name on the customer profile (it must match your UEN and KYC records), and the short trading name of each branch on its subprofile.

If you call this with a referenceId that already exists under the Customer Profile, the existing subprofile is returned.

Step 2: Wait for Activation

A new subprofile starts in pending and transitions to active within seconds, once registration completes. Only active subprofiles can be used for PayNow.

Track this with the List Subprofiles or Get Subprofile endpoints, or register the subprofileStatusUpdated webhook (see below) to be notified automatically.

Step 3: Use the Subprofile with PayNow

When creating a PayNow QR, include the optional subprofile relationship on either PayNow endpoint:

Create Persistent PayNow QR (POST /v1/payment_methods/paynow)
Create Dynamic PayNow QR Payment (POST /v1/payments/paynow)

The QR then resolves to that subprofile's payment address and shows its trading name. If you omit subprofile, behavior is unchanged and the customer profile's default is used.

📘
Notes:
The subprofile relationship is optional and fully backward compatible. Existing PayNow integrations that don't send it continue to work with no changes.

Subprofile Statuses

Status	Description
`pending`	Created and awaiting activation
`active`	Ready to use for PayNow
`disabled`	Deactivated; cannot be used for new PayNow QR codes

The possible status transitions are:

pending → active
active → disabled
pending → disabled

Webhook Notifications

Register the subprofileStatusUpdated event via the Update Webhooks API to be notified when a subprofile's status changes (for example, pending → active). This lets you start using a subprofile as soon as it activates, without polling.

Related API Endpoints

Subprofiles

Create Subprofile - create a branch/outlet subprofile
List Subprofiles — retrieve all subprofiles for a Customer Profile
Get a Subprofile — retrieve a single subprofile
Update Subprofile — update trading name or address
Disable Subprofile — disable a subprofile

PayNow

Create Persistent PayNow QR — static QR, optionally routed to a subprofile
Create Dynamic PayNow Payment — one-off QR, optionally routed to a subprofile