Mistic Pay

Visão Geral

A MisticPay é uma API completa de pagamentos que permite receber e enviar pagamentos via PIX de forma simples e segura. Nossa plataforma oferece:

Receber Pagamentos (Cash-In)

Gere QR Codes PIX e receba pagamentos de seus clientes instantaneamente

Realizar Saques (Cash-Out)

Transfira fundos para qualquer chave PIX de forma programática

Webhooks em Tempo Real

Receba notificações automáticas de mudanças de status em suas transações

Autenticação

Conceito

A API da MisticPay utiliza autenticação baseada em Client ID + Client Secret. Existem duas formas de credencial, e a diferença entre elas é o que cada uma alcança.

Chave de acesso (recomendada)

Par pk_… / sk_…, emitido no painel em API → Chaves de Acesso. Viaja no header Authorization no formato Basic e carrega escopos escolhidos por você na criação. É a única credencial que alcança toda a API — inclusive saque.

Escopos disponíveis — uma chamada sem o escopo da rota recebe 403 API_SCOPE_DENIED:

  • TRANSACTION_CREATE — criar cobrança PIX
  • TRANSACTION_READ — consultar transação (/api/transactions/check)
  • BALANCE_READ — saldo e dados da conta
  • WITHDRAW_CREATE — saque PIX por chave ou QR Code
  • CRYPTO_WITHDRAW_CREATE — saque em USDT BEP20
  • CRYPTO_RATES_READ — cotação e taxas de cripto
  • MED_READ — listar infrações MED
  • MED_RESPOND — enviar defesa de infração MED

O sk_ aparece uma única vez, no momento da criação. Ele não fica guardado em formato legível em lugar nenhum, nem do nosso lado: se perder, revogue a chave e crie outra.

Credencial ci/cs (legada)

Par ci_… / cs_… nos headers ci e cs. Continua funcionando, mas apenas em dois endpoints:

Endpointci/csChave de acesso
POST /transactions/createSimSim
POST /transactions/checkSimSim
Todos os demais endpointsNãoSim

Uma credencial ci/cs em qualquer outro endpoint responde 403. Saque, saldo, consulta de conta, listagem de transações, cripto e MED exigem chave de acesso.

Desligamento em 30 de setembro de 2026

A partir dessa data a autenticação por ci/cs deixa de funcionar, inclusive nos dois endpoints acima. Migre para chave de acesso antes disso.

Importante

Nunca exponha seu Client Secret no frontend ou em repositórios públicos. Ele deve ser armazenado de forma segura no backend.

URL Base da API

Todas as requisições devem ser enviadas para a seguinte URL base:

URL Base
https://api.misticpay.com/api

Headers Obrigatórios

Headers HTTP
Authorization: Basic BASE64(client_id:client_secret)

Content-Type: application/json

BASE64(client_id:client_secret) é o par unido por dois pontos e codificado em base64 — o mesmo esquema do HTTP Basic. Em Node: Buffer.from(`${clientId}:${clientSecret}`).toString("base64"). A maioria dos clientes HTTP monta isso sozinha: no curl, -u client_id:client_secret.

Migrando de ci/cs

  1. No painel, acesse API → Chaves de Acesso e clique em Criar Chave de Acesso. É exigido código 2FA.
  2. Marque apenas os escopos que a sua integração usa. Escopo não é editável depois: ampliar exige criar outra chave e revogar a antiga.
  3. Copie o sk_ na hora — ele não é exibido de novo.
  4. Troque os headers ci/cs pelo header Authorization: Basic … nas suas chamadas.
  5. Revogue a credencial ci/cs quando não houver mais tráfego nela.

Os endpoints, os corpos de requisição e os formatos de resposta não mudaram — apenas a forma de autenticar.

Erros

Toda resposta com status 4xx ou 5xx traz o mesmo corpo JSON, em qualquer endpoint:

JSON
{
  "code": "INSUFFICIENT_BALANCE",
  "message": "Saldo insuficiente, faltam 12.50 reais",
  "statusCode": 400,
  "details": { "missingAmount": 12.5 },
  "requestId": "04b9d2a5-845f-456d-af0d-8b9922143547"
}

Campos

CampoTipoDescrição
codestringIdentificador estável do erro, em inglês (ex.: API_SCOPE_DENIED). Use-o na lógica da sua integração: um código nunca é renomeado nem muda de significado
messagestringExplicação em português, pronta para exibir. Pode trazer valores da ocorrência; não compare o texto, ele pode mudar
statusCodenumberO mesmo status HTTP da resposta, repetido no corpo
detailsobject | nullDados estruturados da ocorrência, como o valor que falta no saldo. null quando não há nada a acrescentar
requestIdstringIdentificador da requisição nos nossos logs. É o mesmo valor do header X-Request-Id da resposta

Como tratar

  • Decida pelo code e pelo status HTTP, nunca pelo texto de message.
  • Alguns erros trazem campos extras no topo do corpo, ao lado dos cinco acima — por exemplo missingAmount em INSUFFICIENT_BALANCE. Ignore os campos que você não conhece.
  • Ao abrir um chamado, envie o requestId: com ele localizamos a requisição exata. Se você mandar o header X-Request-Id (até 128 caracteres ASCII imprimíveis), usamos o seu valor; caso contrário, geramos um UUID.
  • Um 5xx ou um 429 pode ser repetido. Em saques, repita com o mesmo X-Idempotency-Key para não enviar o pagamento duas vezes.

Códigos mais comuns

CódigoStatusQuando acontece
INVALID_API_CREDENTIAL401Credencial ausente, inválida ou revogada
IP_NOT_ALLOWED401O IP de origem não está na lista de IPs autorizados da conta
API_SCOPE_DENIED403A chave não tem o escopo exigido pela rota
API_CREDENTIAL_REQUIRED400Credencial ci/cs não enviada nos headers
INVALID_JSON400O corpo da requisição não é um JSON válido
VALIDATION_ERROR400Um campo não passou na validação; details.issues lista cada campo e o motivo
AMOUNT_BELOW_MINIMUM400Valor abaixo do mínimo aceito para a operação
PIX_KEY_TYPE_INVALID400pixKeyType fora de CPF, CNPJ, EMAIL, TELEFONE ou CHAVE_ALEATORIA
IDEMPOTENCY_KEY_INVALID400X-Idempotency-Key vazio ou com mais de 255 caracteres
INSUFFICIENT_BALANCE400Saldo disponível não cobre o valor e as taxas da operação
TRANSACTION_NOT_FOUND404Nenhuma transação com o identificador informado
ROUTE_NOT_FOUND404Método ou caminho inexistente; details traz os dois
RATE_LIMITED429Mais de 100 requisições por segundo na chave; aguarde o Retry-After
INTERNAL_ERROR500Falha do nosso lado; tente de novo e envie o requestId ao suporte

Gerar transação

POST

/api/transactions/create

cashin

Cria uma nova transação PIX para receber pagamento de um cliente. Retorna QR Code e dados da transação.

Parâmetros

ParâmetroTipoDescrição
amount *numberValor em reais para receber. Ex: 4.55 = R$ 4,55
payerName *stringNome do pagador da transação
payerDocument *stringDocumento CPF do pagador (sem formatação: 12345678909)
transactionIdstringID da sua aplicação para identificação. Se omitido, a API gera um UUID.
description *stringDescrição do pagamento
projectWebhookstringURL do webhook (opcional)
splitUserstringEmail do usuário na plataforma que receberá a divisão (opcional)
splitTaxnumberPorcentagem da taxa de divisão (opcional)

Exemplo de Requisição

cURL
curl -X POST 'https://api.misticpay.com/api/transactions/create' \
  --header 'Authorization: Basic BASE64(client_id:client_secret)' \
  --header 'Content-Type: application/json' \
  --data '{
  "amount": 5,
  "payerName": "Nome do cliente",
  "payerDocument": "12345678909",
  "transactionId": "id_da_sua_aplicacao_para_identificacao",
  "description": "Pagamento do cliente TAL"
}'

Exemplo de Resposta

JSON
{
  "message": "Transação criada com sucesso",
  "data": {
    "transactionId": "31484480",
    "payer": {
      "name": "Nome do cliente",
      "document": "12345678909"
    },
    "transactionFee": 23,
    "transactionType": "DEPOSITO",
    "transactionMethod": "PIX",
    "transactionAmount": 455,
    "transactionState": "PENDENTE",
    "qrCodeBase64": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAcgAAAHICAY...",
    "qrcodeUrl": "https://api.qrserver.com/v1/create-qr-code/?size=300x300&data=...",
    "copyPaste": "00020101021226820014br.gov.bcb.pix2560qrcode.pagsm.com.br/pix/..."
  }
}

Gerar transação Interna

POST

/api/transactions/withdraw/internal

internal

Cria uma transação interna vinculada a um usuário pelo e-mail.

Headers Obrigatórios

Headers HTTP
Authorization: Basic BASE64(client_id:client_secret)

Content-Type: application/json

Exemplo de Requisição

cURL
curl -X POST 'https://api.misticpay.com/api/transactions/withdraw/internal' \
  --header 'Authorization: Basic BASE64(client_id:client_secret)' \
  --header 'Content-Type: application/json' \
  --data '{
  "email": "emailrecebedor@gmail.com",
  "amount": 2,
  "description": "teste"
}'

Exemplo de Resposta

JSON
{
  "message": "Transferência realizada com sucesso",
  "data": {
    "transactionId": "id-da-transacao",
    "amount": 1,
    "recipientEmail": "emailrecebedor@gmail.com",
    "recipientName": "Nome do recebedor"
  }
}

Consultar saldo

GET

/api/users/balance

cashout ou all

Retorna o saldo disponível na conta.

Exemplo de Requisição

cURL
curl -X GET 'https://api.misticpay.com/api/users/balance' \
  --header 'Authorization: Basic BASE64(client_id:client_secret)'

Exemplo de Resposta

JSON
{
  "message": "Saldo do usuário obtido com sucesso",
  "data": {
    "balance": 0.00
  }
}

Consultar dados do usuário

GET

/api/users/info

consulta

Retorna os dados do usuário autenticado pela chave de acesso. Inclui informações pessoais, status da conta e saldo disponível.

Campos Retornados

CampoTipoDescrição
namestringNome do usuário
emailstringEmail do usuário
documentstringCPF/CNPJ do usuário
phonestringTelefone do usuário
accountVerifiedbooleanSe a conta do usuário está verificada
documentVerifiedbooleanSe o documento do usuário está verificado
withdrawBlockedbooleanSe o saque está bloqueado para o usuário
availableBalancenumberSaldo disponível (saldo total - saldo bloqueado)
blockedBalancenumberSaldo bloqueado por MEDs ou outras restrições

Exemplo de Requisição

cURL
curl -X GET 'https://api.misticpay.com/api/users/info' \
  --header 'Authorization: Basic BASE64(client_id:client_secret)'

Exemplo de Resposta

JSON
{
  "message": "Dados do usuário encontrados com sucesso",
  "data": {
    "name": "João Silva",
    "email": "joao@email.com",
    "document": "12345678909",
    "phone": "11999999999",
    "accountVerified": true,
    "documentVerified": true,
    "withdrawBlocked": false,
    "availableBalance": 850.00,
    "blockedBalance": 150.00
  }
}

Solicitar saque

POST

/api/transactions/withdraw

cashout

Solicita um saque via PIX para uma chave PIX. O valor será debitado do saldo disponível. Suporta chaves PIX tradicionais (CPF, CNPJ, Email, Telefone, Chave Aleatória).

Parâmetros

ParâmetroTipoDescrição
amount *numberValor em reais para receber. Ex: 100 = R$ 100,00
pixKey *stringChave PIX do destinatário (sem formatação: 12345678909).
pixKeyType *stringTipo da chave PIX: "CPF", "CNPJ", "EMAIL", "TELEFONE", "CHAVE_ALEATORIA"
description *stringDescrição do pagamento
projectWebhookstringURL do webhook para notificações (opcional)

Idempotência

O header X-Idempotency-Key é opcional, mas recomendado, aqui e no saque por QR Code. Envie um valor único por saque, de 1 a 255 caracteres: duas requisições com a mesma chave geram um único saque, e a segunda recebe de volta o saque criado pela primeira. Uma chave fora desse tamanho responde 400 IDEMPOTENCY_KEY_INVALID.

Exemplo de Requisição

cURL
curl -X POST 'https://api.misticpay.com/api/transactions/withdraw' \
  --header 'Authorization: Basic BASE64(client_id:client_secret)' \
  --header 'Content-Type: application/json' \
  --data '{
  "amount": 1,
  "pixKey": "12345678909",
  "pixKeyType": "CPF",
  "description": "saque com id",
  "projectWebhook": "https://webhooktrack.com/api/webhook/bZ_7mnNS"
}'

Exemplo de Resposta

JSON
{
  "message": "Saque adicionado à fila de processamento",
  "data": {
    "jobId": "withdraw-4-1764365277110-jxqfvna",
    "transactionId": 54345,
    "status": "QUEUED",
    "message": "Seu saque será processado em breve"
  }
}
POST

/api/transactions/withdraw/qrcode

cashout

Paga um QR Code Pix a partir do código "copia e cola". O valor será debitado do saldo disponível.

Somente QR Code estático. QR Codes dinâmicos (de cobrança) são recusados com HTTP 422, porque o valor deles é definido pelo recebedor no momento da liquidação e pode mudar depois da validação. Os dados do QR são apurados pelo servidor e revalidados imediatamente antes do pagamento.

Parâmetros

ParâmetroTipoDescrição
qrCode *stringCódigo Pix copia e cola (BR Code).
amountnumberObrigatório apenas quando o QR Code não define valor. Se o QR já traz valor, este campo é ignorado — e se divergir do valor do QR, a requisição é recusada com HTTP 409.
descriptionstringDescrição do pagamento (opcional)
projectWebhookstringURL do webhook para notificações (opcional)

Exemplo de Requisição

cURL
curl -X POST 'https://api.misticpay.com/api/transactions/withdraw/qrcode' \
  --header 'Authorization: Basic BASE64(client_id:client_secret)' \
  --header 'Content-Type: application/json' \
  --data '{
  "qrCode": "00020126580014BR.GOV.BCB.PIX0136...",
  "description": "pagamento de fornecedor",
  "projectWebhook": "https://webhooktrack.com/api/webhook/bZ_7mnNS"
}'

Exemplo de Resposta

JSON
{
  "message": "Saque adicionado à fila de processamento",
  "data": {
    "jobId": "withdraw-4-1764365277110-jxqfvna",
    "transactionId": 54346,
    "status": "QUEUED",
    "message": "Seu saque será processado em breve"
  }
}

Solicitar saque crypto

POST

/api/crypto/withdraw-api

cashout

Solicita um saque em criptomoeda (USDT BEP20) para uma wallet. O valor será debitado do saldo disponível e convertido para USDT.

💡 Informações importantes:
  • Valor mínimo: R$ 20,00
  • Valor máximo: R$ 3.000,00
  • Taxa da plataforma: 5% sobre o valor
  • Taxa de rede: variável (calculada automaticamente)
  • Wallet deve ser válida no formato BEP20 (0x...)

Parâmetros

ParâmetroTipoDescrição
amount *numberValor em reais para sacar. Ex: 100 = R$ 100,00 (mínimo R$ 20,00, máximo R$ 3.000,00)
wallet *stringEndereço da wallet BEP20 para receber USDT (formato: 0x seguido de 40 caracteres hexadecimais)
projectWebhookstringURL do webhook para notificações (opcional)

Exemplo de Requisição

cURL
curl -X POST 'https://api.misticpay.com/api/crypto/withdraw-api' \
  --header 'Authorization: Basic BASE64(client_id:client_secret)' \
  --header 'Content-Type: application/json' \
  --data '{
  "amount": 100,
  "wallet": "0x1234567890123456789012345678901234567890",
  "projectWebhook": "https://webhook.example.com/api/webhook"
}'

Exemplo de Resposta

JSON
{
  "message": "Saque crypto adicionado à fila de processamento",
  "data": {
    "jobId": "crypto-withdraw-4-1764365277110-jxqfvna",
    "transactionId": 54345,
    "status": "QUEUED",
    "message": "Seu saque crypto será processado em breve"
  }
}

Consultar taxas de cripto

GET

/api/crypto/fees

info

Consulta informações sobre as taxas de cripto, incluindo taxa da plataforma, taxa de rede e cotação atual.

💡 Informações importantes:
  • Taxa da plataforma: 5% sobre o valor informado
  • Taxa de rede: R$ 3,00 (fixa, apenas para informação - já descontada automaticamente pela rede)
  • Inclui cotação atual BRL/USD

Exemplo de Requisição

cURL
curl -X GET 'https://api.misticpay.com/api/crypto/fees' \
  --header 'Authorization: Basic BASE64(client_id:client_secret)' \
  --header 'Content-Type: application/json'

Exemplo de Resposta

JSON
{
  "message": "Taxas obtidas com sucesso",
  "data": {
    "quote": {
      "brlPerUSD": 5.25,
      "networkFee": 3.0,
      "fixedFeeUSDT": 0.5,
      "timestamp": "2024-01-01T00:00:00.000Z"
    },
    "fees": {
      "platformFeePercentage": 3,
      "networkFee": 3.0
    }
  }
}

Verificar transação

POST

/api/transactions/check

Consulte o status e detalhes de uma transação específica. Use o mesmo identificador enviado em transactionId.

O resultado pode ficar em cache por alguns segundos quando a transação ainda está pendente. Para acompanhar mudanças, prefira o webhook configurado no saque ou na cobrança.

Parâmetros

ParâmetroTipoDescrição
transactionId *string | numberID da transação a ser verificada

Exemplo de Requisição

cURL
curl -X POST 'https://api.misticpay.com/api/transactions/check' \
  --header 'Authorization: Basic BASE64(client_id:client_secret)' \
  --header 'Content-Type: application/json' \
  --data '{
  "transactionId": "54345"
}'

Exemplo de Resposta

JSON
{
  "message": "Transação encontrada com sucesso!",
  "transaction": {
    "transactionId": "301124932.60430735",
    "value": 1.12,
    "fee": 0.31,
    "transactionState": "COMPLETO",
    "transactionType": "DEPOSITO",
    "transactionMethod": "PIX",
    "createdAt": "2025-12-02T01:20:18.475Z",
    "updatedAt": "2025-12-02T01:20:53.002Z"
  }
}

Saques: dados do beneficiário

Quando a transação é um saque (RETIRADA), transaction também traz beneficiary, o mesmo objeto enviado no webhook de saque:

JSON
"beneficiary": {
  "name": "Empresa Recebedora LTDA",
  "document": "12345678000195",
  "documentType": "cnpj",
  "ispb": "00360305",
  "bankName": "CAIXA ECONOMICA FEDERAL"
}

beneficiary identifica quem recebeu o saque: name, document, documentType (cpf ou cnpj), ispb e bankName. Os dados são os informados pelo banco liquidante; quando ele não os informa, cada campo vem como null.

Status Possíveis

StatusDescrição
PENDENTETransação pendente, aguardando pagamento
COMPLETOTransação aprovada e concluída com sucesso
FALHATransação falhou ou foi rejeitada

Listar transações

GET

/api/transactions/list

consulta

Lista as transações da sessão autenticada com paginação e filtros. Esta rota exige um JWT de usuário; para integrações com chave de acesso, use /api/transactions/check. Use os filtrossearch, type (entrada ousaida), status e limit.

Autenticação

Esta rota utiliza autenticação via Bearer JWT no header Authorization. Ela não aceitaci/cs nem chave de acesso Basic.

Parâmetros (Query String)

ParâmetroTipoDescrição
pagenumberNúmero da página (padrão: 1)

Parâmetros (Query String)

ParâmetroTipoDescrição
statusstringFiltrar por status (opcional).

Exemplo de Requisição

cURL
curl -X GET 'https://api.misticpay.com/api/transactions/list?page=1&limit=10&status=COMPLETO' \\
  --header 'Authorization: Bearer SEU_TOKEN_JWT' \\
  --header 'Content-Type: application/json'

Exemplo de Resposta

JSON
{
  "message": "Lista de transações obtida com sucesso",
  "data": [
    {
      "id": 934866,
      "value": 2,
      "fee": 0.15,
      "clientName": "Gustavo",
      "clientDocument": "15810217478",
      "description": "Checkout 1042 - teste",
      "requestIp": "::1",
      "updatedAt": "2026-03-04T23:47:23.257Z",
      "transactionState": "COMPLETO",
      "transactionType": "DEPOSITO",
      "transactionMethod": "PIX",
      "source": "CHECKOUT",
      "endToEndId": null,
      "clientTransactionId": "checkout-1042-1772668040504-1awhmwv",
      "createdAt": "2026-03-04T23:47:23.257Z"
    }
  ],
  "pagination": {
    "page": 1,
    "perPage": 10,
    "total": 10,
    "totalPages": 5
  }
}

Campos Retornados

CampoTipoDescrição
idnumberID da transação
valuenumberValor da transação em reais
feenumberTaxa cobrada na transação
clientNamestringNome do cliente da transação
clientDocumentstringDocumento do cliente (pode estar mascarado)
descriptionstringDescrição da transação
requestIpstringIP de origem da requisição
transactionStatestringEstado da transação: PENDENTE, COMPLETO, FALHA, CANCELADO, DEVOLVIDO ou DEVOLVIDO_PARCIAL
transactionTypestringTipo da transação (ex: DEPOSITO, RETIRADA)
transactionMethodstringMétodo da transação (ex: PIX)
sourcestringOrigem da transação (ex: API, CHECKOUT)
endToEndIdstring | nullIdentificador end-to-end do PIX (quando disponível)
clientTransactionIdstringID da transação do cliente
createdAtstringData de criação (ISO 8601)
updatedAtstringData da última atualização (ISO 8601)
pagination.pagenumberPágina atual
pagination.perPagenumberItens por página (fixo: 10)
pagination.totalnumberTotal de transações na página atual
pagination.totalPagesnumberTotal de páginas disponíveis

Filtros de Status

StatusDescrição
PENDENTE
Transação pendente, aguardando pagamento
COMPLETO
Transação aprovada e concluída com sucesso
FALHA
Transação falhou ou foi rejeitada
CANCELADO
Transação cancelada
DEVOLVIDO
Transação reembolsada integralmente (veja o Webhook de Reembolso)
DEVOLVIDO_PARCIAL
Transação reembolsada em parte do valor

Erros Possíveis

CódigoDescrição
400Credenciais de integração não enviadas (ci e cs nos headers)
401Credenciais inválidas

Listar infrações

GET

/api/meds/infractions/list

Lista todas as infrações (MEDs) registradas para sua conta, com paginação. Inclui detalhes da transação associada e respostas de defesa enviadas.

Autenticação

Esta rota utiliza autenticação via Chave de acesso via HTTP Basic nos headers da requisição, com o escopo MED_READ.

Para casar a infração com a transação original, use transaction.clientTransactionId — o transactionId que você enviou na criação — ou o endToEndId do PIX.

Parâmetros (Query String)

ParâmetroTipoDescrição
pagenumberPágina atual (padrão: 1)
perPagenumberItens por página (padrão: 20)

Exemplo de Requisição

cURL
curl -X GET 'https://api.misticpay.com/api/meds/infractions/list?page=1&perPage=10' \
  --header 'Authorization: Basic BASE64(client_id:client_secret)'

Exemplo de Resposta

JSON
{
  "data": {
    "infractions": [
      {
        "id": 42,
        "externalId": "INF-2026-001",
        "type": "FRAUD",
        "status": "WAITING_PSP",
        "source": "ONLYUP",
        "endToEndId": "E00000000202602161750abcdef123456",
        "reportedBy": "DEBITED_PARTICIPANT",
        "reportDetails": "Transação não reconhecida",
        "analysisResult": null,
        "amount": 150.00,
        "currency": "BRL",
        "createdAt": "2026-02-16T17:50:00.000Z",
        "transaction": {
          "id": 31484,
          "value": 150.00,
          "externalId": "TXN-12345",
          "clientTransactionId": "301124932.60430735",
          "endToEndId": "E00000000202602161750abcdef123456",
          "transactionState": "COMPLETO",
          "transactionType": "DEPOSITO",
          "createdAt": "2026-02-16T17:45:00.000Z"
        },
        "defenseResponses": []
      }
    ],
    "pagination": {
      "page": 1,
      "perPage": 10,
      "total": 1,
      "totalPages": 1
    }
  }
}

Status Possíveis da Infração

StatusDescrição
WAITING_PSP
Aguardando análise — você pode enviar defesa
ACCEPTED
Infração aceita — devolução será realizada
REJECTED
Infração rejeitada — saldo desbloqueado
CANCELLED
Infração cancelada

Responder infração

POST

/api/meds/infractions/:infractionId/defense

Envia uma resposta de defesa para uma infração específica. Só é possível responder infrações com status WAITING_PSP e cada infração aceita apenas uma resposta. Exige uma chave de acesso com o escopo MED_RESPOND.

Importante

A defesa só pode ser enviada uma única vez por infração. Certifique-se de que a justificativa esteja completa antes de enviar.

Parâmetros (URL)

ParâmetroTipoDescrição
infractionId *numberID da infração (obtido na listagem)

Parâmetros (Body JSON)

ParâmetroTipoDescrição
analise *stringPosicionamento: "rejeitado" ou "aceito"
justificativa *stringTexto da defesa (mínimo 10 caracteres)
proofs *string[]Array de URLs das provas (mínimo 1, máximo 10)

Exemplo de Requisição

cURL
curl -X POST 'https://api.misticpay.com/api/meds/infractions/42/defense' \
  --header 'Authorization: Basic BASE64(client_id:client_secret)' \
  --header 'Content-Type: application/json' \
  --data '{
  "analise": "rejeitado",
  "justificativa": "Transação legítima realizada pelo titular da conta.",
  "proofs": [
    "https://exemplo.com/comprovante1.png",
    "https://exemplo.com/comprovante2.pdf"
  ]
}'

Exemplo de Resposta (201)

JSON
{
  "message": "Defesa enviada com sucesso",
  "data": {
    "id": 7,
    "infractionId": 42,
    "analise": "rejeitado",
    "justificativa": "Transação legítima realizada pelo titular da conta.",
    "proofs": [
      {
        "url": "https://exemplo.com/comprovante1.png",
        "fileName": "prova-1",
        "mimeType": "url"
      },
      {
        "url": "https://exemplo.com/comprovante2.pdf",
        "fileName": "prova-2",
        "mimeType": "url"
      }
    ],
    "createdAt": "2026-02-25T19:30:00.000Z"
  }
}

Erros Possíveis

CódigoDescrição
400Campos obrigatórios ausentes, valor inválido para analise, ou infração já resolvida
403A infração não pertence à sua conta
404Infração não encontrada
409Já existe uma resposta de defesa para esta infração

Webhook de Depósito

Conceito de Webhooks

Webhooks são notificações automáticas enviadas pela MisticPay quando há mudanças no status de transações. São requisições HTTP POST enviadas para a URL configurada.

Responda com HTTP 2xx assim que receber e processe a notificação de forma idempotente: o mesmo webhook pode chegar mais de uma vez.

Estrutura do Webhook de Depósito

JSON
{
  "transactionId": 31484480,
  "transactionType": "DEPOSITO",
  "transactionMethod": "PIX",
  "clientName": "Nome do cliente",
  "clientDocument": "12345678909",
  "status": "COMPLETO",
  "value": 455,
  "fee": 23,
  "e2e": "1234567890987654321098765432109876543210987654321098765432109876",
  "ispb": "18236120",
  "bankName": "NU PAGAMENTOS - IP"
}

ispb e bankName identificam o banco da contraparte — o pagador no depósito, o beneficiário no saque. Os dois vêm como null quando o banco não informa a instituição de origem ou destino.

Webhook de Saque

Estrutura do Webhook de Saque

JSON
{
  "transactionId": 31484480,
  "transactionType": "RETIRADA",
  "transactionMethod": "PIX",
  "clientName": "Nome do cliente",
  "clientDocument": "12345678909",
  "status": "COMPLETO",
  "value": 455,
  "fee": 23,
  "e2e": "1234567890987654321098765432109876543210987654321098765432109876",
  "ispb": "18236120",
  "bankName": "NU PAGAMENTOS - IP",
  "beneficiary": {
    "name": "Maria Silva",
    "document": "12345678909",
    "documentType": "cpf",
    "ispb": "18236120",
    "bankName": "NU PAGAMENTOS - IP"
  }
}

ispb e bankName identificam o banco da contraparte — o pagador no depósito, o beneficiário no saque. Os dois vêm como null quando o banco não informa a instituição de origem ou destino.

beneficiary identifica quem recebeu o saque: name, document, documentType (cpf ou cnpj), ispb e bankName. Os dados são os informados pelo banco liquidante; quando ele não os informa, cada campo vem como null.

Webhook de Reembolso

Quando uma transação é reembolsada, total ou parcialmente, a MisticPay envia um webhook para oprojectWebhookinformado na criação da transação e para o webhook cadastrado na credencial ou chave de acesso que a criou. Isso vale para o reembolso de um depósito feito pelo painel da MisticPay e para a devolução que chega pelo banco, seja de um depósito estornado ao pagador ou de um saque devolvido pelo banco de destino.

Importante

O webhook de reembolso tem o mesmo formato dos webhooks de depósito e de saque, com o objetorefund a mais. Identifique o reembolso pelostatusda transação (DEVOLVIDOouDEVOLVIDO_PARCIAL) ou pela presença derefund. Se o banco recusar depois um reembolso já notificado, você recebe um novo webhook comrefund.statusigual aRECUSADOe a transação de volta emCOMPLETO.

Estrutura do Webhook de Reembolso (Depósito)

JSON
{
  "transactionId": "pedido-123",
  "transactionType": "DEPOSITO",
  "transactionMethod": "PIX",
  "clientName": "Nome do cliente",
  "clientDocument": "12345678909",
  "status": "DEVOLVIDO",
  "value": 455,
  "fee": 23,
  "e2e": "E18236120202610191200abcdef123456",
  "payer": {
    "name": "Nome do cliente",
    "document": "12345678909",
    "documentType": "cpf"
  },
  "refund": {
    "status": "CONCLUIDO",
    "refundId": "refund:31484480",
    "refundedValue": 455,
    "refundedAt": "2026-10-19T12:00:00.000Z"
  },
  "ispb": "18236120",
  "bankName": "NU PAGAMENTOS - IP"
}

ispb e bankName identificam o banco da contraparte — o pagador no depósito, o beneficiário no saque. Os dois vêm como null quando o banco não informa a instituição de origem ou destino.

Estrutura do Webhook de Reembolso (Saque Devolvido)

JSON
{
  "transactionId": "saque-456",
  "transactionType": "RETIRADA",
  "transactionMethod": "PIX",
  "clientName": "Maria Silva",
  "clientDocument": "12345678909",
  "status": "DEVOLVIDO",
  "value": 455,
  "fee": 23,
  "e2e": "E18236120202610191200abcdef123456",
  "refund": {
    "status": "CONCLUIDO",
    "refundId": "D18236120202610191300abcdef654321",
    "refundedValue": 455,
    "refundedAt": "2026-10-19T13:00:00.000Z"
  },
  "ispb": "18236120",
  "bankName": "NU PAGAMENTOS - IP",
  "beneficiary": {
    "name": "Maria Silva",
    "document": "12345678909",
    "documentType": "cpf",
    "ispb": "18236120",
    "bankName": "NU PAGAMENTOS - IP"
  }
}

ispb e bankName identificam o banco da contraparte — o pagador no depósito, o beneficiário no saque. Os dois vêm como null quando o banco não informa a instituição de origem ou destino.

beneficiary identifica quem recebeu o saque: name, document, documentType (cpf ou cnpj), ispb e bankName. Os dados são os informados pelo banco liquidante; quando ele não os informa, cada campo vem como null.

Campos do objeto refund

CampoTipoDescrição
statusstringCONCLUIDO quando o valor foi devolvido; RECUSADO quando um reembolso já notificado foi recusado pelo banco e desfeito
refundIdstring | nullIdentificador do reembolso no banco liquidante (ou o E2E da devolução, conforme o banco)
refundedValuenumberValor devolvido em reais. Num reembolso parcial é menor que value
refundedAtstringData e hora do reembolso (ISO 8601, UTC)

Status do Reembolso

refund.statusstatus da transaçãoDescrição
CONCLUIDO
DEVOLVIDO ou DEVOLVIDO_PARCIALO reembolso foi concluído e o seu saldo já foi ajustado
RECUSADO
COMPLETOO banco recusou um reembolso já notificado. Nada foi devolvido e o valor voltou ao seu saldo

Webhook de MED

Quando uma infração (MED - Mecanismo Especial de Devolução) é registrada ou atualizada para uma transação, o sistema envia automaticamente uma notificação via webhook para a URL configurada na projectWebhook da credencial ou da transação.

Importante

O webhook de MED é disparado tanto na criação da infração quanto em atualizações (ex: quando o resultado da análise é informado). Utilize o campo infraction.status para identificar o estado atual.

Estrutura do Webhook de MED (Infração Criada)

JSON
{
  "event": "INFRACTION",
  "infraction": {
    "id": 42,
    "externalId": "INF-2026-001",
    "type": "FRAUD",
    "status": "WAITING_PSP",
    "amount": 150.00,
    "currency": "BRL",
    "analysisResult": null,
    "analysisDetails": null,
    "reportedBy": "DEBITED_PARTICIPANT",
    "reportDetails": "Transação não reconhecida pelo titular da conta",
    "createdAt": "2026-02-16T17:50:00.000Z"
  },
  "transaction": {
    "transactionId": "TXN-12345",
    "endToEndId": "E00000000202602161750abcdef123456",
    "value": 150.00,
    "status": "COMPLETO",
    "ispb": "18236120",
    "bankName": "NU PAGAMENTOS - IP"
  }
}

Estrutura do Webhook de MED (Análise Concluída)

JSON
{
  "event": "INFRACTION",
  "infraction": {
    "id": 42,
    "externalId": "INF-2026-001",
    "type": "FRAUD",
    "status": "ACCEPTED",
    "amount": 150.00,
    "currency": "BRL",
    "analysisResult": "AGREED",
    "analysisDetails": "Fraude confirmada após análise",
    "reportedBy": "DEBITED_PARTICIPANT",
    "reportDetails": "Transação não reconhecida pelo titular da conta",
    "createdAt": "2026-02-16T17:50:00.000Z"
  },
  "transaction": {
    "transactionId": "TXN-12345",
    "endToEndId": "E00000000202602161750abcdef123456",
    "value": 150.00,
    "status": "COMPLETO",
    "ispb": "18236120",
    "bankName": "NU PAGAMENTOS - IP"
  }
}

Campos do objeto infraction

CampoTipoDescrição
idnumberID interno da infração
externalIdstringID externo da infração (gateway)
typestringTipo da infração (ex: FRAUD, REFUND_REQUEST)
statusstringWAITING_PSP, ACCEPTED, REJECTED ou CANCELLED
amountnumberValor da infração em reais
currencystringMoeda (padrão: BRL)
analysisResultstring | nullResultado: AGREED (aceita) ou DISAGREED (rejeitada)
analysisDetailsstring | nullDetalhes adicionais da análise
reportedBystring | nullQuem reportou: DEBITED_PARTICIPANT, CREDITED_PARTICIPANT ou ACCOUNT_HOLDER
reportDetailsstring | nullDetalhes do reporte
createdAtstringData de criação (ISO 8601)

Campos do objeto transaction

CampoTipoDescrição
transactionIdstringID da transação (clientTransactionId ou externalId)
endToEndIdstring | nullIdentificador end-to-end do PIX
valuenumberValor original da transação
statusstringEstado atual da transação

Status da Infração

StatusDescrição
WAITING_PSP
Aguardando análise da instituição
ACCEPTED
Infração aceita — devolução será realizada
REJECTED
Infração rejeitada
CANCELLED
Infração cancelada