Integre. Automatize.
Receba com Pix.

Para começar, entre no painel Master Wallet, abra API para desenvolvedores, informe um nome para sua integração e crie uma chave no ambiente de teste. A chave completa aparece uma única vez. Guarde-a em um gerenciador de segredos ou em uma variável de ambiente do seu servidor.

Faça sua primeira chamada

curl https://api.masterwallet.app/v1 \
  -H "Authorization: Bearer $MASTER_WALLET_API_KEY"

A resposta informa a versão da API e as rotas disponíveis para a chave autenticada.

A Master Wallet separa testes e operações reais em chaves diferentes. Não use uma chave de produção durante o desenvolvimento.

Uma chave de produção exige conta ativa, e-mail confirmado, perfil completo, CPF e titular maior de 18 anos. A gateway de pagamentos também precisa estar configurada e as operações não podem estar pausadas.

O limite é de 10 chaves ativas por conta. Revogue as chaves que não utiliza mais.

Envie sua chave no cabeçalho HTTP Authorization em todas as chamadas protegidas:

Authorization: Bearer mw_test_SUA_CHAVE_COMPLETA

As chaves são armazenadas como hash no servidor. Não é possível recuperar o segredo depois da criação; gere outra chave se perder a original.

Cria uma cobrança com valor em centavos de real. O cabeçalho de idempotência é obrigatório e deve ser único para cada intenção de cobrança.

Cabeçalhos

Authorization: Bearer SUA_API_KEY
Content-Type: application/json
Idempotency-Key: pedido-2026-000123

Corpo da requisição

{
  "amount": 2590,
  "external_reference": "pedido-2026-000123",
  "description": "Pedido #123"
}

amount é obrigatório, inteiro em centavos, mínimo de 50 (R$ 0,50) e máximo de 100000000 (R$ 1.000.000,00). external_reference aceita até 100 caracteres; description, até 120.

Exemplo de resposta

{
  "data": {
    "id": "UUID-DA-COBRANCA",
    "object": "charge",
    "amount": { "value": 2590, "currency": "BRL" },
    "fee_cents": 0,
    "net_amount_cents": 2590,
    "status": "pending",
    "external_reference": "pedido-2026-000123",
    "description": "Pedido #123",
    "pix": {
      "copy_paste": "000201...",
      "qr_code_base64": "..."
    },
    "created_at": "2026-11-13T20:00:00.000Z",
    "expires_at": null,
    "paid_at": null,
    "sandbox": false
  }
}

A tarifa da plataforma é calculada no servidor conforme as taxas ativas. fee_cents e net_amount_cents são retornados em centavos. No ambiente de teste, pix é null.

Idempotência

Se a mesma Idempotency-Key for enviada novamente com os mesmos dados, a API devolve a resposta previamente salva e inclui Idempotent-Replay: true. Se a chave for reutilizada com dados diferentes, retorna HTTP 409.

Lista as cobranças da conta e do ambiente da chave autenticada. Aceita limit de 1 a 100 (padrão 25).

curl "https://api.masterwallet.app/v1/charges?limit=25" \
  -H "Authorization: Bearer $MASTER_WALLET_API_KEY"

Para continuar a paginação, envie juntos before e before_id retornados na página anterior. O cursor composto evita pular cobranças com a mesma data.

curl "https://api.masterwallet.app/v1/charges/UUID-DA-COBRANCA" \
  -H "Authorization: Bearer $MASTER_WALLET_API_KEY"

A API só retorna cobranças vinculadas à conta e ao ambiente da chave usada.

Status possíveis

Disponível somente com chave de produção. Os valores são apresentados em centavos e separam saldo disponível, saldo retido e pendências MED.

curl https://api.masterwallet.app/v1/balance \
  -H "Authorization: Bearer $MASTER_WALLET_API_KEY"

Campos retornados

• balance_cents: saldo disponível na carteira.
• locked_balance_cents: valores retidos.
• med_fee_debt_cents: tarifas MED pendentes.
• med_amount_debt_cents: valores descobertos de ocorrências MED abertas.

Simula a aprovação de uma cobrança de teste e enfileira um evento charge.paid para o webhook, se configurado.

curl -X POST "https://api.masterwallet.app/v1/sandbox/charges/UUID-DA-COBRANCA/approve" \
  -H "Authorization: Bearer $MASTER_WALLET_API_KEY"

No painel, abra API para desenvolvedores, selecione a chave e configure uma URL pública HTTPS. O segredo de assinatura aparece apenas uma vez. É possível trocar o segredo, consultar tentativas recentes ou desativar o webhook.

Eventos disponíveis

Cabeçalhos enviados

X-Master-Wallet-Event: charge.paid
X-Master-Wallet-Delivery: UUID-DO-EVENTO
X-Master-Wallet-Signature: t=1730000000,v1=ASSINATURA_HEX
Content-Type: application/json

A assinatura é HMAC-SHA256 do texto timestamp + "." + corpo JSON bruto, usando o segredo do webhook. Valide o corpo bruto antes de interpretar o JSON e aplique tolerância de 5 minutos. Deduplique usando X-Master-Wallet-Delivery.

Verificação em Node.js

import crypto from "node:crypto";

export function verifyMasterWalletWebhook(rawBody, signatureHeader, secret) {
  const match = /^t=(\d+),v1=([a-f0-9]{64})$/.exec(signatureHeader || "");
  if (!match) return false;

  const timestamp = Number(match[1]);
  if (!Number.isSafeInteger(timestamp) ||
      Math.abs(Date.now() / 1000 - timestamp) > 300) return false;

  const expected = crypto
    .createHmac("sha256", secret)
    .update(String(timestamp) + ".")
    .update(rawBody)
    .digest();

  const received = Buffer.from(match[2], "hex");
  return received.length === expected.length &&
    crypto.timingSafeEqual(received, expected);
}

O servidor tenta reenviar entregas que falham com atrasos progressivos, até 8 tentativas. Responda com HTTP 2xx depois de validar e registrar o evento. O envio é assíncrono; não use a chegada do webhook como única fonte de verdade: consulte o status da cobrança antes de liberar o pedido.

Erros usam o formato { "error": { "code": "...", "message": "..." } }. Respeite o cabeçalho Retry-After quando fornecido.

• Mantenha as chaves somente no backend. Nunca as inclua em JavaScript público, aplicativos móveis distribuídos ou repositórios.
• Use HTTPS para todas as chamadas e para receber webhooks.
• Valide assinatura, timestamp e duplicidade dos webhooks.
• Não libere produtos apenas porque a API retornou HTTP 201: confirme o status paid.
• Revogue imediatamente chaves vazadas ou não utilizadas.

Consulte a especificação formal OpenAPI 3.1 (YAML) para importar as rotas em ferramentas de desenvolvimento.