Visão Geral da API

A API Monetarie permite integrar pagamentos PIX ao seu sistema. Todas as operações exigem API Key e IP Whitelist; endpoints POST adicionam HMAC-SHA512 sobre o body.

URL Base

Ambiente	URL
Produção	https://api.monetarie.com
Homologação	https://api-h.monetarie.com

Autenticação

Camadas de segurança (por tipo de requisição):

1. IP Whitelist (todas) -- IP de origem deve estar na whitelist configurada na API Key
2. API Key (todas) -- Header Authorization: ApiKey {client_id}:{client_secret} em todas as requisições
3. HMAC-SHA512 (apenas POST) -- Assinatura do body da requisição; obrigatório em POST /pix/cash-in, POST /pix/cash-out, POST /cpf/validate, POST /webhooks, POST /pix/refund. Requisições GET e DELETE não carregam HMAC (não possuem body a assinar).

Ordem alfabética obrigatória no body HMAC

Requests POST que exigem HMAC devem assinar o body com chaves em ordem alfabética. O backend faz Jason.decode + Jason.encode! no body para validação, o que reordena as chaves. Se seu client não alfabetizar antes de assinar, o HMAC computado localmente não bate com o do servidor → HTTP 401.

Detalhes completos: HMAC-SHA512.

Veja Autenticação e HMAC-SHA512 para detalhes.

Formato

Campo	Formato
Content-Type	application/json
Valores de entrada (request)	Inteiros em centavos (R$ 1,00 = 100)
Valores de resposta	Inteiros em subcentavos (unidades base; R$ 1,00 = 10000, ÷ 10.000 para reais)
Datas	ISO 8601 em UTC com sufixo Z (2026-03-09T15:30:00Z)
IDs	UUID v4 ou string alfanumérica
E2E ID	^E\d{8}[a-zA-Z0-9]{22,26}$ (padrão BACEN, 31-35 chars, sufixo pode conter letras)

Terminologia

Nesta documentação, subcentavos e unidades base referem-se à mesma unidade (10.000 = R$ 1,00). O termo "unidades base" aparece em alguns exemplos herdados; considere-o sinônimo de subcentavos. Sempre divida o valor da resposta por 10.000 para obter reais.

E2E pode conter letras

O sufixo após E + ISPB + timestamp é alfanumérico de 9 a 13 caracteres (não só dígitos). Bancos como Nubank emitem E2Es com letras no final. Sempre valide com a regex completa. Detalhes em PIX Cash-In por E2E ID.

Conversão de valores

Para enviar: multiplique reais por 100. R$ 1,00 = 100. Para ler respostas: divida por 10.000. 10000 ÷ 10.000 = R$ 1,00. Nunca use ponto flutuante -- sempre inteiros.

Documento de terceiro vem MASCARADO

Por determinação do Banco Central (Pix/Operacional, ofício de 04/08/2026), a resposta entregue à sua aplicação não contém o número completo do documento quando o titular é pessoa natural. O CPF de um terceiro sai no formato 123***01 (3 primeiros dígitos + *** + 2 últimos).

Situação	O que você recebe
CPF de terceiro (pagador ou recebedor)	Mascarado: 123***01
CNPJ (11+ dígitos que não são CPF)	Íntegro: 12345678000190
Documento da sua própria conta	Íntegro (é PJ)
Chave PIX e recipient_key	Íntegros, mesmo quando a chave é um CPF -- foi você quem informou
Nome da contraparte (counterparty_name, recipient.name)	Íntegro -- você tem direito de saber para quem pagou

Os campos afetados são payer_document e recipient_document nas consultas (GET /transactions/*, GET /statement). Se a sua conciliação casava pelo CPF completo, migre a chave de casamento para o end_to_end_id ou o external_id, que são estáveis e não mascarados.

O WEBHOOK é exceção desde 08/08/2026

No corpo entregue por webhook, nome e documento da contraparte saem COMPLETOS, sem máscara, em todos os eventos e independente do tipo de chave PIX. O webhook é o desfecho de uma transação concluída da qual você é parte, e não uma consulta a alguém com quem você ainda não transacionou. As consultas acima seguem mascaradas.

Isto é diferente do corte de agência e conta

O corte de agência e número de conta do recebedor resolvido pelo DICT vale para qualquer resposta ao cliente, com fundamento no Manual Operacional do DICT, seções 8.1 e 13.2.5 (na mesma redação desde a versão 7.3, de 02/09/2024). As duas valem juntas: agência/conta não saem, e o CPF sai mascarado nas consultas.

Case das chaves (camelCase opcional)

Respostas JSON usam snake_case por padrão (ex.: transaction_id, end_to_end_id). Se o seu cliente preferir camelCase, envie o header:

X-Key-Case: camelCase

O backend converte todas as chaves do JSON de resposta (incluindo objetos aninhados) automaticamente. Exemplo: transaction_id → transactionId, pix_key_type → pixKeyType. Desde 08/08/2026 o header também converte o body de entrada: chaves em camelCase (por exemplo externalId, pixKey) são aceitas e convertidas para snake_case antes do processamento. Chaves já em snake_case passam intactas, com ou sem o header.

Padrão de Resposta

Sucesso

{
  "worked": true,
  "transaction_id": "PIXOUT20260309abcdef123456",
  "status": "processing"
}

Erro

O formato do erro varia conforme a camada que rejeitou a requisição:

// Plug HMAC (401 assinatura inválida)
{ "worked": false, "detail": "Invalid HMAC signature" }

// ApiKeyAuth (401 / 403)
{ "error": { "status": 401, "message": "Invalid API key" } }

// Respostas de erro da API (404 / 400 / 409 / 422 / 500)
{ "errors": { "not_found": "transaction not found" } }

Veja a tabela completa em Autenticação -- Respostas de Erro.

Códigos HTTP

Código	Significado
200	Sucesso
201	Recurso criado (webhook)
400	Parâmetros inválidos
401	API Key ausente ou inválida / HMAC inválido
403	IP não autorizado na whitelist
404	Recurso não encontrado
422	Validação falhou (saldo insuficiente, chave inválida)
429	Rate limit excedido
500	Erro interno

Rate Limiting

Tipo	Limite
Por IP (autenticado)	90.000 requisições/minuto (1.500 req/s)
Por IP (autenticação / login)	5 requisições/minuto
GET /balance	sem rate limit (polling alta frequência permitido)

Headers de resposta:

X-RateLimit-Remaining: 59997
Retry-After: 3  (apenas quando 429)

Idempotência

Requisições POST aceitam o header Idempotency-Key (máx. 256 caracteres) para evitar processamento duplicado. Somente respostas 2xx (sucesso) são cacheadas por 24 horas. Se a mesma chave for reenviada para o mesmo método e endpoint, a API retorna a resposta original com o header X-Idempotent-Replay: true.

Idempotency-Key: unique-request-id-123

Escopo da chave

A chave é vinculada a método + path + Idempotency-Key. A mesma chave pode ser reutilizada em endpoints diferentes sem colidir. Respostas de erro (4xx/5xx) não são cacheadas -- o cliente pode retentar após corrigir a falha.

GET/DELETE e Idempotency-Key

Requisições GET e DELETE ignoram silenciosamente o header Idempotency-Key -- o plug só atua em POST. Enviar a chave nesses métodos não causa erro, mas não gera cache nem replay.

Políticas de retry e quarentena

• Quarentena (stage=5): PIX Cash-Out preso em status: "processing" por mais de 30 minutos é movido para quarentena, onde permanece aguardando resolução manual pela equipe Monetarie. O status continua "processing" da perspectiva do cliente até a finalização. Detalhes no fluxo: PIX Lifecycle.
• Retry automático de webhooks: deliveries com falha (timeout, 5xx, conexão fechada) são reagendadas em até 7 tentativas (intervalos [0, 30s, 2min, 10min, 30min, 1h, 2h, 4h]). Veja Webhooks.
• Retry do client: ao receber 429, respeite Retry-After. Ao receber 500 ou timeout, use backoff exponencial + Idempotency-Key para evitar duplicação. Veja Autenticação para detalhes.
• Janela anti-replay do webhook: o header X-Monetarie-Timestamp é Unix time em segundos. O servidor não rejeita webhooks antigos; cabe ao seu endpoint descartar entregas com |now - timestamp| > 300s (± 5 minutos) como defense-in-depth contra replay. Veja Webhooks -- Validando a Assinatura.

External ID

Campo opcional external_id aceito em cash-in e cash-out e retornado em respostas e webhooks. Após trim, aceita 1 a 128 bytes e a-zA-Z0-9._:-; quando presente, é uma identidade durável, única e idempotente por (account_id, external_id) nos dois fluxos. Repita o mesmo valor somente para o mesmo comando. Permite consulta por referência:

GET /api/external/transactions/ref/{external_id}

Veja Conceitos para detalhes.

Endpoints

PIX Cash-Out (Envio)

Método	Endpoint	Descrição
POST	/api/external/pix/cash-out	Enviar PIX por chave ou copia-e-cola

PIX Cash-In (Recebimento)

Método	Endpoint	Descrição
POST	/api/external/pix/cash-in	Gerar QR Code para recebimento

Consultas

Método	Endpoint	Descrição
GET	/api/external/transactions	Listar transações
GET	/api/external/transactions/:id	Consultar transação por ID
GET	/api/external/transactions/e2e/:e2e_id	Consultar por E2E ID
GET	/api/external/transactions/tag/:tag	Consultar por tag (prefixo)
GET	/api/external/transactions/ref/:external_id	Consultar por external_id
GET	/api/external/transactions/:id/receipt	Comprovante

Conta

Método	Endpoint	Descrição
GET	/api/external/balance	Saldo da conta
GET	/api/external/statement	Extrato

Chaves PIX

Método	Endpoint	Descrição
GET	/api/external/pix/keys	Listar chaves PIX da conta

Devolução

Método	Endpoint	Descrição
POST	/api/external/pix/refund	Devolução PIX (total ou parcial)
GET	/api/external/pix/refund/:id	Consultar devolução pelo transaction_id (PIXRET)

MED

Método	Endpoint	Descrição
GET	/api/external/med	Listar MEDs
GET	/api/external/med/:id	Detalhes de um MED
POST	/api/external/med/:id/defense	Submeter defesa MED com justificativa e evidências

Validação

Método	Endpoint	Descrição
POST	/api/external/cpf/validate	Validar CPF

Webhooks

Método	Endpoint	Descrição
GET	/api/external/webhooks	Listar webhooks (é aqui que você recupera o secret)
GET	/api/external/webhooks/events	Catálogo autoritativo dos eventos assináveis
POST	/api/external/webhooks	Cadastrar webhook
DELETE	/api/external/webhooks/:id	Remover webhook

Não existe GET /api/external/webhooks/:id. A leitura é sempre a listagem.

Diagnóstico

Método	Endpoint	Descrição
GET	/api/external/ping	Confirma que a sua credencial está válida e o IP autorizado. Passa pela mesma autenticação dos demais endpoints, então um 200 aqui prova ApiKey + whitelist de IP antes de você depurar HMAC
GET	/health	Probe de disponibilidade, fora de /api/external e sem autenticação

Comece o debug pelo /ping

GET /api/external/ping é GET, logo não exige HMAC. Se ele responde 200 e o seu POST responde 401, o problema está na assinatura, não na credencial nem na whitelist de IP. Se o /ping já falha, o problema é credencial ou IP.