# Separating stores and branches in one account (/en/docs/pix-processamento/best-practices/multi-tenant)

<QuickLinks>
  <QuickLink href="/docs/pix-processamento/endpoints/pix-operations/post_pix" title="POST /pix" />

  <QuickLink href="/docs/pix-processamento/endpoints/reports/get_user_transactions" title="GET /user/transactions" />

  <QuickLink href="/docs/pix-processamento/glossary" title="Glossary" />
</QuickLinks>

If you operate multiple brands, stores, branches, or partners under a single PayZu account, pass `virtualAccount` (up to 50 characters) on each creation. This field:

* **Returns in every callback**, so you immediately know which tenant the transaction belongs to.
* **Can be filtered** in `GET /user/transactions` and `GET /pix`, with lists isolated per tenant.
* **Removes the need for child accounts**, a single PayZu account serves N tenants.

<Mermaid
  chart="`
flowchart LR
  L1[&#x22;Store RJ&#x22;] -->|&#x22;virtualAccount=loja-rj-01&#x22;| API[&#x22;PayZu API&#x22;]
  L2[&#x22;Store SP&#x22;] -->|&#x22;virtualAccount=loja-sp-02&#x22;| API
  L3[&#x22;Marketplace&#x22;] -->|&#x22;virtualAccount=mkt-acme&#x22;| API
  API --> CB[&#x22;Callbacks preserve virtualAccount&#x22;]
  CB --> R[&#x22;You route by tenant&#x22;]

  click API &#x22;/en/docs/pix-processamento/endpoints/pix-operations/post_pix&#x22; &#x22;POST /pix&#x22;
  click CB &#x22;/en/docs/pix-processamento/webhooks&#x22; &#x22;Webhooks&#x22;

  style API fill:#14ce71,stroke:#0eb464,color:#ffffff
  style R fill:#3b82f6,stroke:#1d4ed8,color:#ffffff
`"
/>

## Naming conventions [#naming-conventions]

| Pattern                  | When to use                        |
| ------------------------ | ---------------------------------- |
| `tenant-{slug}`          | Multi-customer SaaS platform.      |
| `loja-{cidade}-{numero}` | Network with physical stores.      |
| `mkt-{partner}`          | Marketplace with multiple sellers. |
| `filial-{codigo}`        | Branches of the same company.      |
| `branch-{branchId}`      | Generic, in English.               |

<Callout type="info">
  Maximum length: **50 characters**. Use a stable, readable format. Avoid special characters and spaces.
</Callout>

## Create with `virtualAccount` [#create-with-virtualaccount]

<Tabs items="['Request', 'Response', 'Callback']">
  <Tab value="Request">
    ```json
    {
      "amount": 99.90,
      "clientReference": "order-1234",
      "virtualAccount": "loja-rj-01",
      "callbackUrl": "https://seusite.com.br/webhooks/payzu"
    }
    ```
  </Tab>

  <Tab value="Response">
    ```json
    {
      "id": "PAYZU20260811K7M2X9QP4T000000",
      "status": "PENDING",
      "amount": 99.90,
      "clientReference": "order-1234",
      "virtualAccount": "loja-rj-01",
      "qrCodeText": "00020126870014br.gov.bcb.pix..."
    }
    ```
  </Tab>

  <Tab value="Callback">
    ```json
    {
      "id": "PAYZU20260811K7M2X9QP4T000000",
      "type": "DEPOSIT",
      "status": "COMPLETED",
      "amount": 99.90,
      "clientReference": "order-1234",
      "virtualAccount": "loja-rj-01",
      "paidAt": "2026-08-11T10:46:26.986Z"
    }
    ```
  </Tab>
</Tabs>

## List only one tenant [#list-only-one-tenant]

<Tabs items="['curl', 'Node.js']">
  <Tab value="curl">
    ```bash
    curl "https://api.payzu.processamento.com/v1/user/transactions?virtualAccount=loja-rj-01&dateFrom=2025-11-01" \
      -H "Authorization: Bearer $TOKEN" \
      -H "Content-Type: application/json"
    ```
  </Tab>

  <Tab value="Node.js">
    ```ts
    const url = new URL('https://api.payzu.processamento.com/v1/user/transactions');
    url.searchParams.set('virtualAccount', 'loja-rj-01');
    url.searchParams.set('dateFrom', '2025-11-01');

    const res = await fetch(url, {
      headers: {
        Authorization: `Bearer ${process.env.PAYZU_TOKEN}`,
        'Content-Type': 'application/json',
      },
    });
    ```
  </Tab>
</Tabs>

## Route the callback [#route-the-callback]

```ts
async function payzuWebhook(tx: PayzuCallback) {
  const tenantId = tx.virtualAccount;
  if (!tenantId) {
    log.warn('callback without virtualAccount', { id: tx.id });
    return;
  }

  const handler = tenantHandlers[tenantId];
  if (!handler) {
    log.error('unknown tenant', { tenantId, id: tx.id });
    return;
  }

  await handler.process(tx);
}
```

## `virtualAccount` vs `clientReference` [#virtualaccount-vs-clientreference]

The two are **independent and complementary** fields. Always use both.

| Field             | Granularity     | Purpose                         |
| ----------------- | --------------- | ------------------------------- |
| `clientReference` | Per transaction | Idempotência + lookup by order. |
| `virtualAccount`  | Per tenant      | Routing + listing filter.       |

Just send both fields in the same creation payload, as shown in the example above.

## Common pitfalls [#common-pitfalls]

| Pitfall                                                        | Symptom                                         |
| -------------------------------------------------------------- | ----------------------------------------------- |
| Using `clientReference` to identify the tenant                 | Does not filter in listings, complicates lookup |
| `virtualAccount` changes every time (timestamp, variable slug) | Listing becomes fragmented                      |
| Not handling callbacks without `virtualAccount`                | Routing crashes on legacy transactions          |
| Hardcoding tenants in the handler                              | Manual onboarding for every new customer        |