# Create or update merchant

> Creates a merchant by merchant_ref, the seller ID in your system, or updates the one that already has that reference. Repeating the call does not duplicate.

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

Creates a merchant (store, brand or seller) for your company, or updates the one that already exists with the same `merchant_ref`. The key is the `merchant_ref`, the seller ID in **your** system: sending the same registration again does not create another merchant, and if nothing changed nothing is saved.

For many merchants at once, use the [Merchant batch](https://doc.rapidchargeback.com/en/canais/merchants/lote-de-merchants/). The full flow is in the [Sync guide](https://doc.rapidchargeback.com/en/canais/merchants/guia-de-sincronizacao/).

## Endpoint

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

## Authentication

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

---

## Request body

| Field | Type | Required | Limit and rule |
|---|---|---|---|
| `merchant_ref` | string | Yes | 1 to 100 characters. The seller ID in your system |
| `name` | string | On create | 1 to 255. Unique in your company, ignoring case and accents. Does not accept `null` |
| `status` | enum | No | `active` or `inactive`. On create, `active`. On update, it only changes if sent |
| `store_name` | string | No | up to 255 |
| `merchant_url` | URL | No | up to 500, `http` or `https` only |
| `contact_phone` | string | No | up to 30 |
| `email` | email | No | up to 255 |
| `mcc` | string | No | up to 10 |
| `description` | string | No | up to 10,000 |
| `logo_url` | URL | No | up to 500, `http` or `https` only |
| `terms` | string | No | up to 10,000 |
| `terms_url` | URL | No | up to 500, `http` or `https` only |
| `refund_policy` | string | No | up to 10,000 |
| `refund_policy_url` | URL | No | up to 500, `http` or `https` only |
| `customer_service_instructions` | string | No | up to 10,000 |
| `address_street` | string | No | up to 255 |
| `address_number` | string | No | up to 20 |
| `address_city` | string | No | up to 100 |
| `address_state` | string | No | up to 100 |
| `address_postal_code` | string | No | up to 20 |
| `address_country` | string | No | 3 letters (e.g. `BRA`), saved in uppercase |
| `on_name_conflict` | enum | No | `error` (default) or `append_ref`. See [Repeated name](#repeated-name) |

- Text is trimmed (leading and trailing spaces are removed). `""` and `null` clear the field.
- A field outside the table is rejected with `422 VALIDATION_ERROR` (`Unknown field: <name>`).
- The contact and address data is what **Prevention** uses: to request Prevention on an enrollment, the merchant needs `store_name`, `merchant_url` and `contact_phone` and, depending on the case, a full address and the store details (see [Request enrollment](https://doc.rapidchargeback.com/en/canais/enrollments/pedir-enrollment/)).

---

## How it works

1. Rapid looks for a merchant of your company with that `merchant_ref`.
2. **Found:** updates it. A field that was not sent stays as it is; `null` or `""` clears it (except `name`). `status` only changes if sent. This also applies to an `unverified` merchant created by a transaction with that reference: it is updated and stays `unverified` unless `status` is sent (`active` confirms it).
3. **Not found:** creates it, with the `status` sent or `active`.
4. **Nothing changed:** saves nothing and does not touch `updated_at`. The response says `unchanged`.

That is why you can send your whole base every day: what did not change creates no change, and the `updated_since` filter in [List merchants](https://doc.rapidchargeback.com/en/canais/merchants/listar-merchants/#syncing-what-changed) does not fill up with false changes.

### `merchant_ref` ignores case and accents

`PB-a1` and `pb-A1` are the same reference for Rapid. If you send a reference that differs from the saved one only in case or accents, the API rejects it with `409 MERCHANT_REF_CONFLICT` and updates nothing: two of your sellers never become a single merchant. `params` brings the `merchant_id` and the saved `merchant_ref`.

### Repeated name

The name is unique in your company, ignoring case and accents. If another merchant of yours already has the name:

- with `on_name_conflict: "error"` (default), the API responds `409 MERCHANT_DUPLICATE`, with the `merchant_id` (and the `merchant_ref`, when it has one) of the merchant that already has the name;
- with `on_name_conflict: "append_ref"`, the name is saved as `Name (merchant_ref)`, cutting the name to fit 255 characters. If it still repeats, `409 MERCHANT_DUPLICATE`.

The most common case is a merchant already registered in the dashboard, with no reference. Use the `merchant_id` from the `409` to save the reference on it with [Edit merchant](https://doc.rapidchargeback.com/en/canais/merchants/editar-merchant/) (`PATCH` with `merchant_ref`): from then on this endpoint updates it.

### Notice of data that does not apply right away

If you change `store_name`, `merchant_url`, `contact_phone` or any address field of a merchant that already has an active enrollment, the response brings the `SERVICE_FIELDS_NOT_APPLIED` notice with the fields. The change is saved, but it does not reach the active service right away: contact Rapid support to carry it forward.

---

## Request example

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

---

## Response

### Created

```
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` is the full registration, the same as in [Get merchant](https://doc.rapidchargeback.com/en/canais/merchants/consultar-merchant/).

### Updated or unchanged

`200 OK`, with the same body and `meta.result` equal to `updated` or `unchanged`:

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

| `meta.result` | HTTP | What happened |
|---|---|---|
| `created` | 201 | New merchant |
| `updated` | 200 | Existing merchant, some field changed |
| `unchanged` | 200 | Existing merchant, nothing changed, nothing saved |

### Name of another 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"
    }
  }
}
```

### Reference differing only in case or accents

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

### Invalid field

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

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

### Errors

| HTTP | Code | When |
|---|---|---|
| 422 | `FIELD_REQUIRED` | `merchant_ref` is missing, or `name` on create (`params.field`) |
| 422 | `FIELD_TOO_LONG` | Field above the limit (`params.field`, `params.max`) |
| 422 | `FIELD_INVALID` | URL other than `http`/`https`, invalid email or country (`params.field`) |
| 422 | `FIELD_INVALID_OPTION` | `status` or `on_name_conflict` outside the list (`params.field`, `params.options`) |
| 422 | `VALIDATION_ERROR` | Unknown field, or a body that is not a JSON object (`params.field`) |
| 409 | `MERCHANT_DUPLICATE` | Another merchant of yours already has the name |
| 409 | `MERCHANT_REF_CONFLICT` | Reference differs from the saved one only in case or accents |
| 403 | `KYB_NOT_APPROVED` | Your company's registration has not been approved yet |
| 403 | `COMPANY_NOT_ACTIVE` | The company is not active |
| 403 | `COMPANY_BLOCKED` | Blocked company |
| 429 | `RATE_LIMIT_EXCEEDED` | More than 60 writes per minute (see [Rate limit](https://doc.rapidchargeback.com/en/referencia/codigos-de-resposta/#rate-limit)) |
| 503 | `SERVICE_UNAVAILABLE` | Temporarily unavailable: repeat after `Retry-After` |

---

## Notes

- **Repeating is safe.** After a `503` or a dropped connection, send the same call: the key is the `merchant_ref`, and the result comes back `created`, `updated` or `unchanged`, never a duplicated merchant.
- **`status` is informational.** `inactive` does not stop alerts or transactions. To stop receiving alerts for a merchant, [request the deactivation](https://doc.rapidchargeback.com/en/canais/enrollments/pedir-desativacao/) of its enrollments.
- **Only your company.** The company comes from the credential; there is no field to pick another one.
- **Activity:** every creation and every change shows up in the dashboard Activity as made by the integration.
