Pular para o conteúdo

↑↓ navegar ↵ abrir Ctrl↵ nova aba esc fechar

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.

POST https://api.rapidchargeback.com/api/v1/merchants
Authorization: Basic base64(client_id:client_secret)
Content-Type: application/json

CampoTipoObrigatórioLimite e regra
merchant_refstringSim1 a 100 caracteres. O ID do vendedor no seu sistema
namestringAo criar1 a 255. Único na sua empresa, sem diferenciar maiúsculas nem acentos. Não aceita null
statusenumNãoactive ou inactive. Ao criar, active. Ao atualizar, só muda se vier
store_namestringNãoaté 255
merchant_urlURLNãoaté 500, só http ou https
contact_phonestringNãoaté 30
emaile-mailNãoaté 255
mccstringNãoaté 10
descriptionstringNãoaté 10.000
logo_urlURLNãoaté 500, só http ou https
termsstringNãoaté 10.000
terms_urlURLNãoaté 500, só http ou https
refund_policystringNãoaté 10.000
refund_policy_urlURLNãoaté 500, só http ou https
customer_service_instructionsstringNãoaté 10.000
address_streetstringNãoaté 255
address_numberstringNãoaté 20
address_citystringNãoaté 100
address_statestringNãoaté 100
address_postal_codestringNãoaté 20
address_countrystringNão3 letras (ex.: BRA), gravado em maiúsculas
on_name_conflictenumNãoerror (padrão) ou append_ref. Ver 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).

  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 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.

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 (PATCH com merchant_ref): daí em diante este endpoint o atualiza.

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.


Janela do terminal
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"
}'

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.

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.resultHTTPO que aconteceu
created201Merchant novo
updated200Merchant existente, algum campo mudou
unchanged200Merchant existente, nada mudou, nada gravado
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"
}
}
}
HTTP/1.1 422 Unprocessable Entity
{
"error": {
"code": "FIELD_INVALID",
"message": "merchant_url: Invalid url",
"params": { "field": "merchant_url" }
}
}
HTTPCódigoQuando
422FIELD_REQUIREDFalta merchant_ref, ou name ao criar (params.field)
422FIELD_TOO_LONGCampo acima do limite (params.field, params.max)
422FIELD_INVALIDURL fora de http/https, e-mail ou país inválido (params.field)
422FIELD_INVALID_OPTIONstatus ou on_name_conflict fora da lista (params.field, params.options)
422VALIDATION_ERRORCampo desconhecido, ou corpo que não é um objeto JSON (params.field)
409MERCHANT_DUPLICATEOutro merchant seu já tem o nome
409MERCHANT_REF_CONFLICTReferência só diferente da gravada em maiúsculas ou acentos
403KYB_NOT_APPROVEDO cadastro da sua empresa ainda não foi aprovado
403COMPANY_NOT_ACTIVEA empresa não está ativa
403COMPANY_BLOCKEDEmpresa bloqueada
429RATE_LIMIT_EXCEEDEDMais de 60 escritas por minuto (ver Rate limit)
503SERVICE_UNAVAILABLEIndisponibilidade temporária: repita depois do Retry-After

  • 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 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.