# List merchants

> Lists your company's merchants, paginated, with the merchant_id that creating a transaction and sending a capture event require.

Página: https://doc.rapidchargeback.com/en/canais/merchants/listar-merchants/

Lists your company's merchants (stores, brands or sellers). This is where the `merchant_id` comes from, which [create transaction](https://doc.rapidchargeback.com/en/canais/transactions/criar-transacao/) and [send event from the server](https://doc.rapidchargeback.com/en/canais/capture/enviar-evento-servidor/) require.

Read only: creating and editing merchants is done in the dashboard.

## Endpoint

```
GET https://api.rapidchargeback.com/api/v1/merchants
```

## Authentication

```
Authorization: Basic base64(client_id:client_secret)
```

---

## Query params

All optional.

| Param | Type | Default | Description |
|---|---|---|---|
| `page` | int (≥ 1) | `1` | Page |
| `per_page` | int (1–100) | `20` | Items per page |
| `merchant_ref` | string (up to 100) | - | The seller ID in **your** system, the same `merchant_ref` accepted in [create transaction](https://doc.rapidchargeback.com/en/canais/transactions/criar-transacao/). Returns 0 or 1 item |
| `status` | enum | - | `active` or `inactive` |

The list is always paginated, in registration order (oldest first). To go through all of them, advance `page` until `page` reaches `total_pages`: a merchant registered along the way is added at the end, so you never skip or repeat an item.

---

## Examples

### All merchants

```bash
curl -G "https://api.rapidchargeback.com/api/v1/merchants" \
  --data-urlencode "per_page=100" \
  -H "Authorization: Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ="
```

### By the seller ID in your system

```bash
curl -G "https://api.rapidchargeback.com/api/v1/merchants" \
  --data-urlencode "merchant_ref=seller-77" \
  -H "Authorization: Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ="
```

---

## Response

### Success

```json
{
  "data": [
    {
      "id": "00000000-0000-0000-0000-000000000001",
      "name": "Loja Exemplo",
      "merchant_ref": null,
      "status": "active",
      "created_at": "2026-03-10T12:00:00.000Z"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 20,
    "total": 1,
    "total_pages": 1
  }
}
```

| Field | Description |
|---|---|
| `id` | The `merchant_id` the other APIs require |
| `name` | Merchant name in the dashboard |
| `merchant_ref` | The seller ID in your system, when the merchant was created through `merchant_ref`. `null` for those registered in the dashboard |
| `status` | `active` or `inactive`: the registration status in the dashboard |
| `created_at` | When it was registered |

These are the only fields: the merchant's contact details, address and terms stay in the dashboard.

### No results

```json
{
  "data": [],
  "meta": { "page": 1, "per_page": 20, "total": 0, "total_pages": 0 }
}
```

### Invalid parameter (e.g. `per_page=500`)

```json
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Number must be less than or equal to 100"
  }
}
```

---

## Notes

- **Only your company's merchants.** The company comes from the credential; there is no parameter to choose another one.
- **A blocked company** receives `403 COMPANY_BLOCKED`, as in the other APIs.
- **Auth, rate limit, error codes:** see [Authentication](https://doc.rapidchargeback.com/en/referencia/autenticacao/) and [Response codes](https://doc.rapidchargeback.com/en/referencia/codigos-de-resposta/).