# Crear o actualizar merchant

> Registra un merchant por el merchant_ref, el ID del vendedor en tu sistema, o actualiza el que ya tiene esa referencia. Repetir la llamada no duplica.

Página: https://doc.rapidchargeback.com/es/canais/merchants/criar-ou-atualizar-merchant/

Registra un merchant (tienda, marca o vendedor) de tu empresa, o actualiza el que ya existe con el mismo `merchant_ref`. La clave es el `merchant_ref`, el ID del vendedor en **tu** sistema: enviar el mismo registro de nuevo no crea otro merchant, y si nada cambió no se guarda nada.

Para muchos merchants a la vez, usa el [Lote de merchants](https://doc.rapidchargeback.com/es/canais/merchants/lote-de-merchants/). El flujo completo está en la [Guía de sincronización](https://doc.rapidchargeback.com/es/canais/merchants/guia-de-sincronizacao/).

## Endpoint

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

## Autenticación

```
Authorization: Basic base64(client_id:client_secret)
Content-Type: application/json
```

---

## Cuerpo de la solicitud

| Campo | Tipo | Obligatorio | Límite y regla |
|---|---|---|---|
| `merchant_ref` | string | Sí | 1 a 100 caracteres. El ID del vendedor en tu sistema |
| `name` | string | Al crear | 1 a 255. Único en tu empresa, sin distinguir mayúsculas ni acentos. No acepta `null` |
| `status` | enum | No | `active` o `inactive`. Al crear, `active`. Al actualizar, solo cambia si viene |
| `store_name` | string | No | hasta 255 |
| `merchant_url` | URL | No | hasta 500, solo `http` o `https` |
| `contact_phone` | string | No | hasta 30 |
| `email` | correo | No | hasta 255 |
| `mcc` | string | No | hasta 10 |
| `description` | string | No | hasta 10.000 |
| `logo_url` | URL | No | hasta 500, solo `http` o `https` |
| `terms` | string | No | hasta 10.000 |
| `terms_url` | URL | No | hasta 500, solo `http` o `https` |
| `refund_policy` | string | No | hasta 10.000 |
| `refund_policy_url` | URL | No | hasta 500, solo `http` o `https` |
| `customer_service_instructions` | string | No | hasta 10.000 |
| `address_street` | string | No | hasta 255 |
| `address_number` | string | No | hasta 20 |
| `address_city` | string | No | hasta 100 |
| `address_state` | string | No | hasta 100 |
| `address_postal_code` | string | No | hasta 20 |
| `address_country` | string | No | 3 letras (ej.: `BRA`), guardado en mayúsculas |
| `on_name_conflict` | enum | No | `error` (por defecto) o `append_ref`. Ver [Nombre repetido](#nombre-repetido) |

- El texto se recorta (salen los espacios del inicio y del final). `""` y `null` limpian el campo.
- Un campo fuera de la tabla se rechaza con `422 VALIDATION_ERROR` (`Unknown field: <nombre>`).
- Los datos de contacto y dirección son los que usa la **Prevención**: para solicitar la Prevención en un enrollment, el merchant necesita `store_name`, `merchant_url` y `contact_phone` y, según el caso, dirección completa y los datos de la tienda (ver [Solicitar enrollment](https://doc.rapidchargeback.com/es/canais/enrollments/pedir-enrollment/)).

---

## Cómo funciona

1. Rapid busca un merchant de tu empresa con ese `merchant_ref`.
2. **Lo encontró:** lo actualiza. El campo que no vino queda como está; `null` o `""` lo limpia (menos `name`). El `status` solo cambia si viene. Vale también para el merchant `unverified` creado por una transacción con esa referencia: se actualiza y sigue `unverified`, salvo que venga `status` (`active` lo confirma).
3. **No lo encontró:** lo crea, con el `status` enviado o `active`.
4. **Nada cambió:** no guarda nada y no toca el `updated_at`. La respuesta dice `unchanged`.

Por eso puedes enviar tu base entera todos los días: lo que no cambió no genera modificación, y el filtro `updated_since` de [Listar merchants](https://doc.rapidchargeback.com/es/canais/merchants/listar-merchants/#sincronizar-lo-que-cambió) no se llena de cambios falsos.

### `merchant_ref` no distingue mayúsculas ni acentos

`PB-a1` y `pb-A1` son la misma referencia para Rapid. Si envías una referencia que solo difiere de la guardada en mayúsculas o acentos, la API la rechaza con `409 MERCHANT_REF_CONFLICT` y no actualiza nada: dos vendedores tuyos nunca se vuelven un solo merchant. El `params` trae el `merchant_id` y el `merchant_ref` guardado.

### Nombre repetido

El nombre es único en tu empresa, sin distinguir mayúsculas ni acentos. Si otro merchant tuyo ya tiene el nombre:

- con `on_name_conflict: "error"` (por defecto), la API responde `409 MERCHANT_DUPLICATE`, con el `merchant_id` (y el `merchant_ref`, cuando lo tiene) del merchant que ya tiene el nombre;
- con `on_name_conflict: "append_ref"`, el nombre se guarda como `Nombre (merchant_ref)`, recortando el nombre para que quepa en 255 caracteres. Si aun así se repite, `409 MERCHANT_DUPLICATE`.

El caso más común es el merchant que ya estaba registrado en el panel, sin referencia. Usa el `merchant_id` del `409` para guardar la referencia en él con [Editar merchant](https://doc.rapidchargeback.com/es/canais/merchants/editar-merchant/) (`PATCH` con `merchant_ref`): a partir de ahí este endpoint lo actualiza.

### Aviso de dato que no se aplica en el momento

Si cambias `store_name`, `merchant_url`, `contact_phone` o algún campo de dirección de un merchant que ya tiene un enrollment activo, la respuesta trae el aviso `SERVICE_FIELDS_NOT_APPLIED` con los campos. El cambio queda guardado, pero no llega en el momento al servicio ya activo: habla con el soporte de Rapid para llevarlo adelante.

---

## Ejemplo de solicitud

```bash
curl -X POST https://api.rapidchargeback.com/api/v1/merchants \
  -H "Authorization: Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ=" \
  -H "Content-Type: application/json" \
  -d '{
    "merchant_ref": "PB-1001",
    "name": "Loja Exemplo",
    "store_name": "Loja Exemplo",
    "merchant_url": "https://lojaexemplo.com",
    "contact_phone": "+55 11 99999-0000",
    "address_country": "BRA"
  }'
```

---

## Respuesta

### Creado

```
HTTP/1.1 201 Created
```

```json
{
  "data": {
    "id": "00000000-0000-0000-0000-000000000001",
    "name": "Loja Exemplo",
    "merchant_ref": "PB-1001",
    "status": "active",
    "created_at": "2026-11-06T12:00:00.000Z",
    "updated_at": "2026-11-06T12:00:00.000Z",
    "store_name": "Loja Exemplo",
    "merchant_url": "https://lojaexemplo.com",
    "contact_phone": "+55 11 99999-0000",
    "email": null,
    "mcc": null,
    "description": null,
    "logo_url": null,
    "terms": null,
    "terms_url": null,
    "refund_policy": null,
    "refund_policy_url": null,
    "customer_service_instructions": null,
    "address_street": null,
    "address_number": null,
    "address_city": null,
    "address_state": null,
    "address_postal_code": null,
    "address_country": "BRA"
  },
  "meta": { "result": "created", "warnings": [] }
}
```

`data` es el registro completo, el mismo de [Consultar merchant](https://doc.rapidchargeback.com/es/canais/merchants/consultar-merchant/).

### Actualizado o sin cambios

`200 OK`, con el mismo cuerpo y `meta.result` igual a `updated` o `unchanged`:

```json
{
  "data": { "id": "00000000-0000-0000-0000-000000000001", "...": "registro completo" },
  "meta": {
    "result": "updated",
    "warnings": [{ "code": "SERVICE_FIELDS_NOT_APPLIED", "fields": ["merchant_url"] }]
  }
}
```

| `meta.result` | HTTP | Qué pasó |
|---|---|---|
| `created` | 201 | Merchant nuevo |
| `updated` | 200 | Merchant existente, algún campo cambió |
| `unchanged` | 200 | Merchant existente, nada cambió, nada guardado |

### Nombre de otro merchant

```
HTTP/1.1 409 Conflict
```

```json
{
  "error": {
    "code": "MERCHANT_DUPLICATE",
    "message": "A merchant with this name already exists",
    "params": {
      "name": "Loja Exemplo",
      "merchant_id": "00000000-0000-0000-0000-000000000001"
    }
  }
}
```

### Referencia distinta solo en mayúsculas o acentos

```
HTTP/1.1 409 Conflict
```

```json
{
  "error": {
    "code": "MERCHANT_REF_CONFLICT",
    "message": "A merchant with this merchant_ref already exists with different case or accents",
    "params": {
      "merchant_id": "00000000-0000-0000-0000-000000000001",
      "merchant_ref": "PB-1001"
    }
  }
}
```

### Campo inválido

```
HTTP/1.1 422 Unprocessable Entity
```

```json
{
  "error": {
    "code": "FIELD_INVALID",
    "message": "merchant_url: Invalid url",
    "params": { "field": "merchant_url" }
  }
}
```

### Errores

| HTTP | Código | Cuándo |
|---|---|---|
| 422 | `FIELD_REQUIRED` | Falta `merchant_ref`, o `name` al crear (`params.field`) |
| 422 | `FIELD_TOO_LONG` | Campo por encima del límite (`params.field`, `params.max`) |
| 422 | `FIELD_INVALID` | URL fuera de `http`/`https`, correo o país inválido (`params.field`) |
| 422 | `FIELD_INVALID_OPTION` | `status` u `on_name_conflict` fuera de la lista (`params.field`, `params.options`) |
| 422 | `VALIDATION_ERROR` | Campo desconocido, o cuerpo que no es un objeto JSON (`params.field`) |
| 409 | `MERCHANT_DUPLICATE` | Otro merchant tuyo ya tiene el nombre |
| 409 | `MERCHANT_REF_CONFLICT` | Referencia distinta de la guardada solo en mayúsculas o acentos |
| 403 | `KYB_NOT_APPROVED` | El registro de tu empresa todavía no fue aprobado |
| 403 | `COMPANY_NOT_ACTIVE` | La empresa no está activa |
| 403 | `COMPANY_BLOCKED` | Empresa bloqueada |
| 429 | `RATE_LIMIT_EXCEEDED` | Más de 60 escrituras por minuto (ver [Rate limit](https://doc.rapidchargeback.com/es/referencia/codigos-de-resposta/#rate-limit)) |
| 503 | `SERVICE_UNAVAILABLE` | No disponible temporalmente: repite después del `Retry-After` |

---

## Notas

- **Repetir es seguro.** Después de un `503` o de una caída de conexión, envía la misma llamada: la clave es el `merchant_ref`, y el resultado vuelve `created`, `updated` o `unchanged`, nunca un merchant duplicado.
- **El `status` es informativo.** `inactive` no detiene alertas ni transacciones. Para dejar de recibir alertas de un merchant, [solicita la desactivación](https://doc.rapidchargeback.com/es/canais/enrollments/pedir-desativacao/) de sus enrollments.
- **Solo tu empresa.** La empresa viene de la credencial; no hay campo para elegir otra.
- **Actividad:** cada registro y cada modificación aparece en la Actividad del panel como hecha por la integración.
