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. O fluxo completo está no Guia de sincronização.
Endpoint
Seção intitulada “Endpoint”https://api.rapidchargeback.com/api/v1/merchantsAutenticação
Seção intitulada “Autenticação”Authorization: Basic base64(client_id:client_secret)Content-Type: application/jsonCorpo da requisição
Seção intitulada “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 | 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 |
- O texto é aparado (espaços no começo e no fim saem).
""enulllimpam 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_urlecontact_phonee, conforme o caso, de endereço completo e dos dados da loja (ver Pedir enrollment).
Como funciona
Seção intitulada “Como funciona”- A Rapid procura um merchant da sua empresa com esse
merchant_ref. - Achou: atualiza. Campo que não veio fica como está;
nullou""limpa (menosname). Ostatussó muda se vier. Vale também para o merchantunverifiedcriado por uma transação com essa referência: ele é atualizado e continuaunverified, a menos que venhastatus(activeo confirma). - Não achou: cria, com o
statusenviado ouactive. - Nada mudou: não grava nada e não mexe no
updated_at. A resposta dizunchanged.
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 não se enche de falsas mudanças.
merchant_ref não diferencia maiúsculas nem acentos
Seção intitulada “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
Seção intitulada “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 responde409 MERCHANT_DUPLICATE, com omerchant_id(e omerchant_ref, quando tiver) do merchant que já tem o nome; - com
on_name_conflict: "append_ref", o nome é gravado comoNome (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 (PATCH com merchant_ref): daí em diante este endpoint o atualiza.
Aviso de dado que não vale na hora
Seção intitulada “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
Seção intitulada “Exemplo de requisição”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
Seção intitulada “Resposta”HTTP/1.1 201 Created{ "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.
Atualizado ou sem mudança
Seção intitulada “Atualizado ou sem mudança”200 OK, com o mesmo corpo e meta.result igual a updated ou unchanged:
{ "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
Seção intitulada “Nome de outro merchant”HTTP/1.1 409 Conflict{ "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
Seção intitulada “Referência só diferente em maiúsculas ou acentos”HTTP/1.1 409 Conflict{ "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
Seção intitulada “Campo inválido”HTTP/1.1 422 Unprocessable Entity{ "error": { "code": "FIELD_INVALID", "message": "merchant_url: Invalid url", "params": { "field": "merchant_url" } }}| 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) |
| 503 | SERVICE_UNAVAILABLE | Indisponibilidade temporária: repita depois do Retry-After |
- Repetir é seguro. Depois de um
503ou de uma queda de conexão, mande a mesma chamada: a chave é omerchant_ref, e o resultado vemcreated,updatedouunchanged, nunca um merchant duplicado. statusé informativo.inactivenão para alertas nem transações. Para deixar de receber alertas de um merchant, peça a desativação 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.