# Criar ou atualizar merchant

> Cadastra um merchant pelo merchant_ref, o ID do vendedor no seu sistema, ou atualiza o que já tem essa referência. Repetir a chamada não duplica.

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

Cadastra um merchant (loja, marca ou vendedor) da sua empresa, ou atualiza o que já existe com o mesmo `merchant_ref`. A chave é o `merchant_ref`, o ID do vendedor no **seu** sistema: mandar o mesmo cadastro de novo não cria outro merchant, e se nada mudou nada é gravado.

Para muitos merchants de uma vez, use o [Lote de merchants](https://doc.rapidchargeback.com/canais/merchants/lote-de-merchants/). O fluxo completo está no [Guia de sincronização](https://doc.rapidchargeback.com/canais/merchants/guia-de-sincronizacao/).

## Endpoint

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

## Autenticação

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

---

## Corpo da requisição

| Campo | Tipo | Obrigatório | Limite e regra |
|---|---|---|---|
| `merchant_ref` | string | Sim | 1 a 100 caracteres. O ID do vendedor no seu sistema |
| `name` | string | Ao criar | 1 a 255. Único na sua empresa, sem diferenciar maiúsculas nem acentos. Não aceita `null` |
| `status` | enum | Não | `active` ou `inactive`. Ao criar, `active`. Ao atualizar, só muda se vier |
| `store_name` | string | Não | até 255 |
| `merchant_url` | URL | Não | até 500, só `http` ou `https` |
| `contact_phone` | string | Não | até 30 |
| `email` | e-mail | Não | até 255 |
| `mcc` | string | Não | até 10 |
| `description` | string | Não | até 10.000 |
| `logo_url` | URL | Não | até 500, só `http` ou `https` |
| `terms` | string | Não | até 10.000 |
| `terms_url` | URL | Não | até 500, só `http` ou `https` |
| `refund_policy` | string | Não | até 10.000 |
| `refund_policy_url` | URL | Não | até 500, só `http` ou `https` |
| `customer_service_instructions` | string | Não | até 10.000 |
| `address_street` | string | Não | até 255 |
| `address_number` | string | Não | até 20 |
| `address_city` | string | Não | até 100 |
| `address_state` | string | Não | até 100 |
| `address_postal_code` | string | Não | até 20 |
| `address_country` | string | Não | 3 letras (ex.: `BRA`), gravado em maiúsculas |
| `on_name_conflict` | enum | Não | `error` (padrão) ou `append_ref`. Ver [Nome repetido](#nome-repetido) |

- O texto é aparado (espaços no começo e no fim saem). `""` e `null` limpam o campo.
- Campo fora da tabela é recusado com `422 VALIDATION_ERROR` (`Unknown field: <nome>`).
- Os dados de contato e endereço são os que a **Prevenção** usa: para pedir a Prevenção num enrollment, o merchant precisa de `store_name`, `merchant_url` e `contact_phone` e, conforme o caso, de endereço completo e dos dados da loja (ver [Pedir enrollment](https://doc.rapidchargeback.com/canais/enrollments/pedir-enrollment/)).

---

## Como funciona

1. A Rapid procura um merchant da sua empresa com esse `merchant_ref`.
2. **Achou:** atualiza. Campo que não veio fica como está; `null` ou `""` limpa (menos `name`). O `status` só muda se vier. Vale também para o merchant `unverified` criado por uma transação com essa referência: ele é atualizado e continua `unverified`, a menos que venha `status` (`active` o confirma).
3. **Não achou:** cria, com o `status` enviado ou `active`.
4. **Nada mudou:** não grava nada e não mexe no `updated_at`. A resposta diz `unchanged`.

Por isso dá para mandar a sua base inteira todo dia: o que não mudou não gera alteração, e o filtro `updated_since` de [Listar merchants](https://doc.rapidchargeback.com/canais/merchants/listar-merchants/#sincronizar-pelo-que-mudou) não se enche de falsas mudanças.

### `merchant_ref` não diferencia maiúsculas nem acentos

`PB-a1` e `pb-A1` são a mesma referência para a Rapid. Se você mandar uma referência que só difere da gravada em maiúsculas ou acentos, a API recusa com `409 MERCHANT_REF_CONFLICT` e não atualiza nada: dois vendedores seus nunca viram um merchant só. O `params` traz o `merchant_id` e o `merchant_ref` gravado.

### Nome repetido

O nome é único na sua empresa, sem diferenciar maiúsculas nem acentos. Se outro merchant seu já tem o nome:

- com `on_name_conflict: "error"` (padrão), a API responde `409 MERCHANT_DUPLICATE`, com o `merchant_id` (e o `merchant_ref`, quando tiver) do merchant que já tem o nome;
- com `on_name_conflict: "append_ref"`, o nome é gravado como `Nome (merchant_ref)`, cortando o nome para caber em 255 caracteres. Se ainda assim repetir, `409 MERCHANT_DUPLICATE`.

O caso mais comum é o merchant que já estava cadastrado no painel, sem referência. Use o `merchant_id` do `409` para gravar a referência nele com [Editar merchant](https://doc.rapidchargeback.com/canais/merchants/editar-merchant/) (`PATCH` com `merchant_ref`): daí em diante este endpoint o atualiza.

### Aviso de dado que não vale na hora

Se você mudar `store_name`, `merchant_url`, `contact_phone` ou algum campo de endereço de um merchant que já tem enrollment ativo, a resposta traz o aviso `SERVICE_FIELDS_NOT_APPLIED` com os campos. A mudança fica gravada, mas não chega na hora ao serviço já ativo: fale com o suporte da Rapid para levá-la adiante.

---

## Exemplo de requisição

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

---

## Resposta

### Criado

```
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` é o cadastro completo, o mesmo de [Consultar merchant](https://doc.rapidchargeback.com/canais/merchants/consultar-merchant/).

### Atualizado ou sem mudança

`200 OK`, com o mesmo corpo e `meta.result` igual a `updated` ou `unchanged`:

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

| `meta.result` | HTTP | O que aconteceu |
|---|---|---|
| `created` | 201 | Merchant novo |
| `updated` | 200 | Merchant existente, algum campo mudou |
| `unchanged` | 200 | Merchant existente, nada mudou, nada gravado |

### Nome de outro 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"
    }
  }
}
```

### Referência só diferente em maiúsculas ou 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" }
  }
}
```

### Erros

| HTTP | Código | Quando |
|---|---|---|
| 422 | `FIELD_REQUIRED` | Falta `merchant_ref`, ou `name` ao criar (`params.field`) |
| 422 | `FIELD_TOO_LONG` | Campo acima do limite (`params.field`, `params.max`) |
| 422 | `FIELD_INVALID` | URL fora de `http`/`https`, e-mail ou país inválido (`params.field`) |
| 422 | `FIELD_INVALID_OPTION` | `status` ou `on_name_conflict` fora da lista (`params.field`, `params.options`) |
| 422 | `VALIDATION_ERROR` | Campo desconhecido, ou corpo que não é um objeto JSON (`params.field`) |
| 409 | `MERCHANT_DUPLICATE` | Outro merchant seu já tem o nome |
| 409 | `MERCHANT_REF_CONFLICT` | Referência só diferente da gravada em maiúsculas ou acentos |
| 403 | `KYB_NOT_APPROVED` | O cadastro da sua empresa ainda não foi aprovado |
| 403 | `COMPANY_NOT_ACTIVE` | A empresa não está ativa |
| 403 | `COMPANY_BLOCKED` | Empresa bloqueada |
| 429 | `RATE_LIMIT_EXCEEDED` | Mais de 60 escritas por minuto (ver [Rate limit](https://doc.rapidchargeback.com/referencia/codigos-de-resposta/#rate-limit)) |
| 503 | `SERVICE_UNAVAILABLE` | Indisponibilidade temporária: repita depois do `Retry-After` |

---

## Notas

- **Repetir é seguro.** Depois de um `503` ou de uma queda de conexão, mande a mesma chamada: a chave é o `merchant_ref`, e o resultado vem `created`, `updated` ou `unchanged`, nunca um merchant duplicado.
- **`status` é 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.
- **Só a sua empresa.** A empresa vem da credencial; não há campo para escolher outra.
- **Atividade:** cada cadastro e cada alteração aparece na Atividade do painel como feita pela integração.
