# Editar merchant

> Altera o cadastro de um merchant pelo merchant_id e grava o merchant_ref num merchant que ainda não tem. A referência não se troca depois de gravada.

Página: https://doc.rapidchargeback.com/canais/merchants/editar-merchant/

Altera o cadastro de um merchant da sua empresa pelo `merchant_id`. É também o jeito de gravar o `merchant_ref` num merchant que já existia sem referência (por exemplo, um cadastrado no painel): depois disso, [Criar ou atualizar merchant](https://doc.rapidchargeback.com/canais/merchants/criar-ou-atualizar-merchant/) e o [Lote de merchants](https://doc.rapidchargeback.com/canais/merchants/lote-de-merchants/) passam a atualizá-lo pela referência.

## Endpoint

```
PATCH https://api.rapidchargeback.com/api/v1/merchants/:merchant_id
```

## Autenticação

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

---

## Parâmetros de URL

| Param | Tipo | Descrição |
|---|---|---|
| `merchant_id` | string (UUID) | O `id` do merchant |

## Corpo da requisição

Qualquer campo de [Criar ou atualizar merchant](https://doc.rapidchargeback.com/canais/merchants/criar-ou-atualizar-merchant/#corpo-da-requisição), todos opcionais, com os mesmos limites. `on_name_conflict` não existe aqui.

- Mande só o que muda. Campo que não veio fica como está; `null` ou `""` limpa (menos `name`).
- Corpo vazio (`{}`): `422 VALIDATION_ERROR` "Send at least one field".
- Nome de outro merchant seu: `409 MERCHANT_DUPLICATE`, com o `merchant_id` dele.

### `merchant_ref`: grava uma vez

| Situação | Resposta |
|---|---|
| O merchant não tem referência | Grava a enviada |
| A enviada é igual à gravada | Nada muda (`unchanged`, se nenhum outro campo mudou) |
| O merchant já tem outra referência | `409 MERCHANT_REF_IMMUTABLE`: a referência não se troca |
| Outro merchant seu já usa essa referência | `409 MERCHANT_REF_TAKEN`, com o `merchant_id` dele |

A referência não se troca porque transações e entregas de webhook já feitas com ela continuam apontando para o mesmo merchant. Se dois merchants precisam virar um, fale com o suporte da Rapid.

### `status`

`active` ou `inactive`. É informativo: `inactive` não para alertas nem transações. Para deixar de receber alertas de um merchant, [peça a desativação](https://doc.rapidchargeback.com/canais/enrollments/pedir-desativacao/) dos enrollments dele.

---

## Exemplo de requisição

Gravar a referência do seu sistema num merchant que veio do painel:

```bash
curl -X PATCH https://api.rapidchargeback.com/api/v1/merchants/00000000-0000-0000-0000-000000000001 \
  -H "Authorization: Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ=" \
  -H "Content-Type: application/json" \
  -d '{ "merchant_ref": "PB-1001" }'
```

---

## Resposta

### Sucesso

```
HTTP/1.1 200 OK
```

```json
{
  "data": {
    "id": "00000000-0000-0000-0000-000000000001",
    "name": "Loja Exemplo",
    "merchant_ref": "PB-1001",
    "status": "active",
    "created_at": "2026-03-10T12:00:00.000Z",
    "updated_at": "2026-11-06T12:00:00.000Z",
    "...": "cadastro completo"
  },
  "meta": { "result": "updated", "warnings": [] }
}
```

`data` é o cadastro completo, o mesmo de [Consultar merchant](https://doc.rapidchargeback.com/canais/merchants/consultar-merchant/). `meta.result` é `updated` ou `unchanged` (nada mudou, nada gravado); `meta.warnings` pode trazer o aviso `SERVICE_FIELDS_NOT_APPLIED` (ver [Aviso de dado que não vale na hora](https://doc.rapidchargeback.com/canais/merchants/criar-ou-atualizar-merchant/#aviso-de-dado-que-não-vale-na-hora)).

### Referência já gravada

```
HTTP/1.1 409 Conflict
```

```json
{
  "error": {
    "code": "MERCHANT_REF_IMMUTABLE",
    "message": "merchant_ref cannot be changed once set"
  }
}
```

### Erros

| HTTP | Código | Quando |
|---|---|---|
| 404 | `MERCHANT_NOT_FOUND` | O merchant não existe, é de outra empresa, ou o id não é um UUID |
| 409 | `MERCHANT_DUPLICATE` | Outro merchant seu já tem o nome |
| 409 | `MERCHANT_REF_IMMUTABLE` | O merchant já tem outra referência |
| 409 | `MERCHANT_REF_TAKEN` | Outro merchant seu já usa a referência (`params.merchant_id`) |
| 422 | `VALIDATION_ERROR`, `FIELD_REQUIRED`, `FIELD_TOO_LONG`, `FIELD_INVALID`, `FIELD_INVALID_OPTION` | Ver [Criar ou atualizar merchant](https://doc.rapidchargeback.com/canais/merchants/criar-ou-atualizar-merchant/#erros) |
| 403 | `KYB_NOT_APPROVED`, `COMPANY_NOT_ACTIVE`, `COMPANY_BLOCKED` | Empresa sem cadastro aprovado, inativa ou bloqueada |
| 429 | `RATE_LIMIT_EXCEEDED` | Mais de 60 escritas por minuto |
| 503 | `SERVICE_UNAVAILABLE` | Indisponibilidade temporária: repita depois do `Retry-After` |

---

## Notas

- **Repetir é seguro:** a mesma edição de novo volta `unchanged`.
- **Atividade:** cada alteração aparece na Atividade do painel como feita pela integração.
