Listar merchants
Lista os merchants (lojas, marcas ou vendedores) da sua empresa. É daqui que sai o merchant_id que criar transação, enviar evento pelo servidor e pedir enrollment pedem.
Para cadastrar e editar merchants pela API, veja Criar ou atualizar merchant, Lote de merchants e o 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)Query params
Seção intitulada “Query params”Todos opcionais.
| Param | Tipo | Default | Descrição |
|---|---|---|---|
page | int (≥ 1) | 1 | Página |
per_page | int (1–100) | 20 | Itens por página |
merchant_ref | string (até 100) | - | O ID do vendedor no seu sistema, o mesmo merchant_ref aceito em criar transação. Devolve 0 ou 1 item. A comparação não diferencia maiúsculas nem acentos |
status | enum | - | active, inactive ou unverified |
updated_since | data e hora ISO 8601 com fuso | - | Só os merchants alterados a partir desse instante (ex.: 2026-11-06T12:00:00Z ou 2026-11-06T09:00:00-03:00). Sem fuso, a API recusa com 422 |
Sem updated_since, a lista vem em ordem de cadastro (o mais antigo primeiro). Para percorrer todos, avance page até page chegar a total_pages: merchant cadastrado no meio do caminho entra no fim, sem fazer você pular ou repetir item.
Sincronizar pelo que mudou
Seção intitulada “Sincronizar pelo que mudou”Com updated_since, a lista traz só o que mudou a partir desse instante, do mais antigo para o mais novo (updated_at, depois id). Para acompanhar as mudanças sem perder nenhuma:
- Guarde o maior
updated_atque você recebeu. - Na consulta seguinte, mande esse valor menos 2 minutos como
updated_since. - Ignore o par (
id,updated_at) que você já processou. - Leia as páginas até
total_pages.
A folga de 2 minutos cobre a mudança gravada fora de ordem ou durante a sua leitura.
Exemplos
Seção intitulada “Exemplos”Todos os merchants
Seção intitulada “Todos os merchants”curl -G "https://api.rapidchargeback.com/api/v1/merchants" \ --data-urlencode "per_page=100" \ -H "Authorization: Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ="Pelo ID do vendedor no seu sistema
Seção intitulada “Pelo ID do vendedor no seu sistema”curl -G "https://api.rapidchargeback.com/api/v1/merchants" \ --data-urlencode "merchant_ref=PB-1001" \ -H "Authorization: Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ="O que mudou desde a última leitura
Seção intitulada “O que mudou desde a última leitura”curl -G "https://api.rapidchargeback.com/api/v1/merchants" \ --data-urlencode "updated_since=2026-11-06T11:58:00Z" \ --data-urlencode "per_page=100" \ -H "Authorization: Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ="Resposta
Seção intitulada “Resposta”Sucesso
Seção intitulada “Sucesso”{ "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" } ], "meta": { "page": 1, "per_page": 20, "total": 1, "total_pages": 1 }}| Campo | Descrição |
|---|---|
id | O merchant_id que as outras APIs pedem |
name | Nome do merchant |
merchant_ref | O ID do vendedor no seu sistema, gravado pela API de merchants ou por um merchant_ref novo em criar transação. null quando nunca foi informado |
status | active, inactive ou unverified: a situação do cadastro. unverified é o merchant criado automaticamente por um merchant_ref novo em criar transação, até a Rapid conferir o cadastro ou você o confirmar com status: "active" em Criar ou atualizar merchant ou Editar merchant. A situação não muda nada no funcionamento: transações e eventos do merchant são aceitos do mesmo jeito |
created_at | Quando foi cadastrado |
updated_at | Quando o cadastro mudou pela última vez |
A lista traz só esses campos. O cadastro completo (contato, endereço, termos) está em Consultar merchant.
Sem resultados
Seção intitulada “Sem resultados”{ "data": [], "meta": { "page": 1, "per_page": 20, "total": 0, "total_pages": 0 }}Parâmetro inválido (ex: per_page=500)
Seção intitulada “Parâmetro inválido (ex: per_page=500)”{ "error": { "code": "VALIDATION_ERROR", "message": "Number must be less than or equal to 100" }}updated_since sem fuso
Seção intitulada “updated_since sem fuso”{ "error": { "code": "VALIDATION_ERROR", "message": "updated_since must be an ISO 8601 date and time with a time zone (e.g. 2026-11-06T12:00:00Z)", "params": { "field": "updated_since" } }}- Só os merchants da sua empresa. A empresa vem da credencial; não há parâmetro para escolher outra.
- Parâmetro desconhecido ainda é ignorado nesta rota, mas vai passar a ser recusado com
422, como nas rotas novas: mande só os parâmetros da tabela (ver Novidades da API). - Empresa bloqueada recebe
403 COMPANY_BLOCKED, como nas outras APIs. - Auth, rate limit, códigos de erro: ver Autenticação e Códigos de resposta.