MaiPix
API v1 Referência OpenAPI (Swagger) Painel

Introdução

Começando

Esta documentação descreve como integrar o seu sistema com a API pública MaiPix para gerar cobranças PIX (checkout) e receber notificações quando um pagamento é confirmado.

O fluxo é pensado para ser simples: você envia credenciais nos cabeçalhos, cria uma cobrança com valor e identificador único, e recebe na resposta os dados do PIX (incluindo payload da adquirente). Quando o pagamento for liquidado, a MaiPix pode chamar a URL de webhook que configurou no painel.

Autenticação na API de checkout Todas as requisições a POST /api/v1/checkout devem incluir os cabeçalhos x-client-id e x-api-key. Estes valores são gerados no painel do cliente em Configurações → Credenciais (fluxo “Gerar credenciais de integração”).

URL base

Utilize o mesmo domínio (e porta, em desenvolvimento) em que o gateway MaiPix está exposto. Exemplos:

O endpoint de checkout é sempre: POST {BASE_URL}/api/v1/checkout

Autenticação

A integração de checkout não utiliza Bearer JWT. A autenticação é feita com um par de credenciais de integração:

Cabeçalho Descrição
x-client-id Identificador público da sua conta (normalmente o seu nome de utilizador ou um id derivado exibido no painel).
x-api-key Chave secreta maipix_live_… — trate como senha; nunca exponha no front-end.

Requisitos: conta do tipo cliente, estado APPROVED, e credenciais geradas. Se o x-client-id não corresponder à chave informada, a API responde 401.

Respostas HTTP

Código Significado
201 Cobrança criada; corpo inclui ids, valores, taxa e objeto pix (resposta da Pix Up).
400 Corpo inválido (ex.: amount abaixo do mínimo, CPF/CNPJ do cadastro inválido para PIX).
401 Credenciais em falta ou inválidas; x-client-id não coincide com a chave.
409 external_id já utilizado — use outro identificador único por cobrança.
502 / 503 Falha ao comunicar com o serviço PIX externo (Pix Up); mensagem de erro no corpo quando disponível.

Criar cobrança (checkout)

POST /api/v1/checkout

Cabeçalhos

Nome Obrigatório
Content-Type: application/json Sim
x-client-id Sim
x-api-key Sim

Corpo (JSON)

Campo Tipo Descrição
amount number Valor em BRL (mínimo 0,01).
external_id string Identificador único no seu sistema (pedido, fatura, etc.). Não reutilize para nova cobrança.
description string Opcional; descrição exibida/registada na transação.

Exemplo (cURL)

curl -X POST "https://SEU_HOST/api/v1/checkout" \
  -H "Content-Type: application/json" \
  -H "x-client-id: SEU_CLIENT_ID" \
  -H "x-api-key: maipix_live_..." \
  -d '{
    "amount": 10.5,
    "external_id": "pedido-2026-001",
    "description": "Pagamento via loja"
  }'

Exemplo (JavaScript fetch)

const res = await fetch(`${BASE_URL}/api/v1/checkout`, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-client-id": CLIENT_ID,
    "x-api-key": API_KEY,
  },
  body: JSON.stringify({
    amount: 10.5,
    external_id: "pedido-unico-" + Date.now(),
    description: "Checkout MaiPix",
  }),
});
const data = await res.json();
if (!res.ok) throw new Error(data.error || res.statusText);

Resposta (201) — campos principais

Campo Descrição
transaction_id ID interno MaiPix da transação.
external_id O mesmo enviado no pedido.
amount Valor bruto da cobrança.
fee_amount Taxa de entrada (percentual configurado na plataforma).
net_amount Valor líquido após taxa de entrada.
entry_fee_percent Percentual de taxa de entrada aplicado.
pix Objeto devolvido pela Pix Up (QR Code, copia e cola, etc.). Use estes dados para exibir o pagamento ao utilizador final.

Webhook — pagamento confirmado

No painel, em Configurações → Credenciais, pode definir uma webhook_url (HTTPS recomendado). Quando uma transação de checkout passa ao estado pago, a MaiPix envia um POST com JSON para essa URL.

Payload (JSON)

Campo Descrição
event Sempre transaction.paid neste fluxo.
status PAID
external_id Identificador que enviou no checkout.
transaction_id ID interno MaiPix.
amount, fee_amount, net_amount Valores numéricos da transação.
paid_at Data/hora ISO 8601 da confirmação.
description Descrição da transação ou null.

O pedido é feito com Content-Type: application/json e User-Agent: MaiPix-Gateway/1.0. O seu endpoint deve responder com código HTTP 2xx; respostas de erro são registadas nos logs do servidor MaiPix.

Exemplo de payload

{
  "event": "transaction.paid",
  "status": "PAID",
  "external_id": "pedido-2026-001",
  "transaction_id": "clxx…",
  "amount": 10.5,
  "fee_amount": 0.42,
  "net_amount": 10.08,
  "paid_at": "2026-04-25T12:00:00.000Z",
  "description": "Pagamento via loja"
}
Webhook Pix Up (entrada) O gateway MaiPix recebe notificações da Pix Up em POST /webhooks/pixup. Isto é interno ao servidor — não é o URL que configura no painel. O seu sistema integra apenas com /api/v1/checkout e com a sua webhook_url.

Referência OpenAPI

Para explorar todos os esquemas e testar pedidos com a UI Swagger, abra /docs. Esta página é o guia humano; o Swagger é a referência técnica completa (incluindo outras rotas do sistema).