> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wepayout.co/llms.txt
> Use this file to discover all available pages before exploring further.

# List Merchant Pix Keys

> Consolidated list of the Pix keys of a merchant and its submerchants, with search filters and result counters. Read-only.

<Info>
  Returns **one row per account** — the merchant identified by `we_id` plus every submerchant registered under it — together with the Pix key held by that account. There is **no pagination**: the response always covers the whole hierarchy, and the filters narrow down the rows that are returned.

  Accounts with no Pix key are **not** listed. A merchant with no eligible account still answers `200` with an empty `data` array and zeroed counters — never `404`.
</Info>

## Query Parameters

<ParamField query="we_id" type="integer" required>
  WE ID of the merchant whose hierarchy is listed. The response covers this merchant **and** its submerchants.

  Must be within the scope of the authenticated credentials, otherwise the request is rejected with `403`.

  Example: `1020100`
</ParamField>

<ParamField query="merchant_id" type="string">
  Narrows the result down to the accounts whose WE ID **starts with** the supplied value, so the search box of a panel filters the list while the ID is being typed.

  Digits only, up to 20 characters. `10201` matches `1020101`; `0101` does **not**.

  Example: `1020101`
</ParamField>

<ParamField query="name" type="string">
  Narrows the result down to the accounts whose company name **contains** the supplied value. Case and accent insensitive: `jose` matches `JOSÉ`.

  Up to 150 characters.

  Example: `retail`
</ParamField>

<ParamField query="document" type="string">
  Narrows the result down to the accounts whose company document **contains** the supplied digits. Both sides are compared digits only, so a mask is accepted: `34.881.207/0001-46`, `34881207000146` and `34881` all match the same account.

  Up to 20 characters. A value with no digit at all is treated as no filter, instead of matching everything.

  Example: `34.881`
</ParamField>

<ParamField query="status" type="string" default="active">
  Status of the Pix key. Applied by default even when omitted, so a request with no `status` returns the active keys.

  Allowed values: `active`

  This is currently the only accepted value — any other value is rejected with `422`. Consequently, `pix_key.status` always comes back as `ACTIVE`.
</ParamField>

<Note>
  Filters are combined with **AND**: an account is returned only when it satisfies every supplied filter.
</Note>

## Response

<ResponseField name="summary" type="object">
  Counters of the listing, meant to feed a "X of Y accounts" label.

  <Expandable title="summary object">
    <ResponseField name="total_accounts" type="integer">
      Number of accounts in the hierarchy holding a Pix key, **before** the `merchant_id`, `name` and `document` filters. This is the denominator: an account with no key is neither listed nor counted.
    </ResponseField>

    <ResponseField name="filtered" type="integer">
      Number of accounts left **after** every filter. Always equal to the length of `data`.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="data" type="array">
  Accounts and their Pix keys. The queried merchant always comes first, followed by the submerchants ordered by ascending WE ID.

  <Expandable title="account object">
    <ResponseField name="merchant_id" type="integer">
      WE ID of the account.
    </ResponseField>

    <ResponseField name="is_main" type="boolean">
      `true` on the merchant supplied as `we_id`, `false` on its submerchants. Lets the client render the main account apart without comparing IDs.
    </ResponseField>

    <ResponseField name="name" type="string">
      Legal name of the **company** that owns the account.
    </ResponseField>

    <ResponseField name="document" type="string">
      Document (CNPJ) of the **company** that owns the account, digits only.
    </ResponseField>

    <ResponseField name="pix_key" type="object">
      The Pix key held by the account.

      <Expandable title="pix_key object">
        <ResponseField name="key" type="string">
          Value of the Pix key, as registered at the DICT.
        </ResponseField>

        <ResponseField name="type" type="string">
          Type of the key.

          Values: `CPF`, `CNPJ`, `EVP`, `EMAIL`, `PHONE`
        </ResponseField>

        <ResponseField name="status" type="string">
          Status of the key, reported in upper case.

          Values: `ACTIVE`
        </ResponseField>

        <ResponseField name="owner_name" type="string">
          Name of the Pix key holder registered at the DICT.
        </ResponseField>

        <ResponseField name="owner_document" type="string">
          Document of the Pix key holder registered at the DICT, digits only.
        </ResponseField>

        <ResponseField name="ispb" type="string">
          ISPB of the institution holding the key. Always `32708748` (WEpayments).
        </ResponseField>

        <ResponseField name="bank_name" type="string">
          Name of the institution holding the key. Always `WEpayments`.
        </ResponseField>

        <ResponseField name="created_at" type="string | null">
          When the key was created. ISO 8601 with offset. `null` when the date is unknown.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "summary": {
      "total_accounts": 3,
      "filtered": 3
    },
    "data": [
      {
        "merchant_id": 1020100,
        "is_main": true,
        "name": "Example Fictitious Corp",
        "document": "11111111000111",
        "pix_key": {
          "key": "a3f1c8e2-0000-4000-8000-000000000000",
          "type": "EVP",
          "status": "ACTIVE",
          "owner_name": "Example Fictitious Corp",
          "owner_document": "11111111000111",
          "ispb": "32708748",
          "bank_name": "WEpayments",
          "created_at": "2025-03-01T10:00:00-03:00"
        }
      },
      {
        "merchant_id": 1020101,
        "is_main": false,
        "name": "Fictitious Retail Ltda",
        "document": "22222222000122",
        "pix_key": {
          "key": "22222222000122",
          "type": "CNPJ",
          "status": "ACTIVE",
          "owner_name": "Fictitious Retail Ltda",
          "owner_document": "22222222000122",
          "ispb": "32708748",
          "bank_name": "WEpayments",
          "created_at": "2025-04-12T09:31:20-03:00"
        }
      },
      {
        "merchant_id": 1020102,
        "is_main": false,
        "name": "Fictitious Cross Border Ltda",
        "document": "33333333000133",
        "pix_key": {
          "key": "b7d4e5a1-1111-4111-8111-111111111111",
          "type": "EVP",
          "status": "ACTIVE",
          "owner_name": "WE PAY OUT INSTITUICAO DE PAGAMENTO LTDA",
          "owner_document": "32708748000130",
          "ispb": "32708748",
          "bank_name": "WEpayments",
          "created_at": "2025-06-20T14:05:00-03:00"
        }
      }
    ]
  }
  ```

  ```json 200 Empty result theme={null}
  {
    "summary": {
      "total_accounts": 0,
      "filtered": 0
    },
    "data": []
  }
  ```

  ```json 401 Unauthenticated theme={null}
  {
    "error_code": "authentication",
    "error_description": "Unauthenticated."
  }
  ```

  ```json 403 Access denied theme={null}
  {
    "message": "You are not allowed to access this merchant"
  }
  ```

  ```json 422 Validation error theme={null}
  {
    "error_code": "validation",
    "error_description": "Validation error",
    "fields": {
      "we_id": [
        "The we id field is required."
      ]
    }
  }
  ```

  ```json 502 Upstream unavailable theme={null}
  {
    "message": "Could not retrieve the Pix keys right now"
  }
  ```
</ResponseExample>

## Errors

| Status | When                                                                                                                                                |
| ------ | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `401`  | Missing or invalid credentials.                                                                                                                     |
| `403`  | `we_id` is outside the scope of the authenticated credentials. The message is deliberately generic and never discloses whether the merchant exists. |
| `422`  | `we_id` is missing or not a positive integer, or a filter does not match its expected format.                                                       |
| `502`  | The Pix keys could not be retrieved from the upstream service. Retry — this never means the merchant has no keys.                                   |
| `400`  | Unexpected error while listing the keys.                                                                                                            |

<Note>
  Because the response depends on the scope of the caller, it is **never cached** at the gateway. Two different credentials asking for the same `we_id` may legitimately receive different results.
</Note>

## Example request

```bash cURL theme={null}
curl -X GET "https://api.sandbox.wepayout.com.br/v2/register/pix-keys?we_id=1020100&merchant_id=10201" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"
```

## Related Resources

<CardGroup cols={2}>
  <Card title="List Account Opening Requests" icon="list" href="/api-reference/account/list-accounts">
    Find the WE IDs of the accounts in your hierarchy
  </Card>

  <Card title="Create Company" icon="building" href="/api-reference/account/create">
    Register a new submerchant
  </Card>
</CardGroup>