# Listar merchants

> Lista los merchants de tu empresa, paginado, con el merchant_id que crear transacción y enviar evento de captura requieren.

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

Lista los merchants (tiendas, marcas o vendedores) de tu empresa. De aquí sale el `merchant_id` que [crear transacción](https://doc.rapidchargeback.com/es/canais/transactions/criar-transacao/) y [enviar evento desde el servidor](https://doc.rapidchargeback.com/es/canais/capture/enviar-evento-servidor/) requieren.

Solo lectura: registrar y editar merchants se hace en el panel.

## Endpoint

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

## Autenticación

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

---

## Query params

Todos opcionales.

| Param | Tipo | Default | Descripción |
|---|---|---|---|
| `page` | int (≥ 1) | `1` | Página |
| `per_page` | int (1–100) | `20` | Ítems por página |
| `merchant_ref` | string (hasta 100) | - | El ID del vendedor en **tu** sistema, el mismo `merchant_ref` aceptado en [crear transacción](https://doc.rapidchargeback.com/es/canais/transactions/criar-transacao/). Devuelve 0 o 1 ítem |
| `status` | enum | - | `active` o `inactive` |

La lista viene siempre paginada, en orden de registro (el más antiguo primero). Para recorrerlos todos, avanza `page` hasta que `page` llegue a `total_pages`: un merchant registrado en el camino entra al final, sin que saltes ni repitas ítems.

---

## Ejemplos

### Todos los merchants

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

### Por el ID del vendedor en tu sistema

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

---

## Respuesta

### Éxito

```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
  }
}
```

| Campo | Descripción |
|---|---|
| `id` | El `merchant_id` que las otras APIs requieren |
| `name` | Nombre del merchant en el panel |
| `merchant_ref` | El ID del vendedor en tu sistema, cuando el merchant se creó por `merchant_ref`. `null` en los registrados por el panel |
| `status` | `active` o `inactive`: la situación del registro en el panel |
| `created_at` | Cuándo se registró |

Son solo esos campos: los datos de contacto, dirección y términos del merchant quedan en el panel.

### Sin resultados

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

### Parámetro inválido (ej.: `per_page=500`)

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

---

## Notas

- **Solo los merchants de tu empresa.** La empresa viene de la credencial; no hay parámetro para elegir otra.
- **Una empresa bloqueada** recibe `403 COMPANY_BLOCKED`, como en las otras APIs.
- **Auth, rate limit, códigos de error:** ver [Autenticación](https://doc.rapidchargeback.com/es/referencia/autenticacao/) y [Códigos de respuesta](https://doc.rapidchargeback.com/es/referencia/codigos-de-resposta/).