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. Cada requisição deve incluir dois headers essenciais:

Importante

Nunca exponha sua Client Secret no frontend ou em repositórios públicos. Ela deve ser armazenada 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
ci: seu_client_id
cs: seu_client_secret

Content-Type: application/json

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)
transactionId *stringID da sua aplicação para identificação da transação
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 'ci: seu_client_id' \
  --header 'cs: seu_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
ci: seu_client_id
cs: seu_client_secret

Content-Type: application/json

Exemplo de Requisição

cURL
curl -X POST 'https://api.misticpay.com/api/transactions/internal' \
  --header 'ci: seu_client_id' \
  --header 'cs: seu_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 'ci: seu_client_id' \
  --header 'cs: seu_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 pelas credenciais CI/CS. 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 'ci: seu_client_id' \
  --header 'cs: seu_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)

Exemplo de Requisição

cURL
curl -X POST 'https://api.misticpay.com/api/transactions/withdraw' \
  --header 'ci: seu_client_id' \
  --header 'cs: seu_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"
  }
}

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: 3% 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 'ci: seu_client_id' \
  --header 'cs: seu_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: 3% 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 'ci: seu_client_id' \
  --header 'cs: seu_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.

⚠️ Rate Limit: Esta rota possui rate limit de 60 requisições por minuto por IP. Requisições que excederem este limite retornarão erro 429.

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 'ci: seu_client_id' \
  --header 'cs: seu_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"
  }
}

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/users/transactions/list/:page

consulta

Lista as transações do usuário com paginação e filtro por status. Retorna no máximo 10 transações por página.

Autenticação

Esta rota utiliza autenticação via CI/CS (Client ID / Client Secret) nos headers da requisição.

Parâmetros (URL)

ParâmetroTipoDescrição
page *numberNúmero da página (ex: 1, 2, 3...)

Parâmetros (Query String)

ParâmetroTipoDescrição
statusstringFiltrar por status: PENDENTE, COMPLETO, FALHA ou CANCELADO (opcional)

Exemplo de Requisição

cURL
curl -X GET 'https://api.misticpay.com/api/users/transactions/list/1?status=COMPLETO' \\
  --header 'ci: seu_client_id' \\
  --header 'cs: seu_client_secret' \\
  --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 ou CANCELADO
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

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 CI/CS (Client ID / Client Secret) nos headers da requisição.

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 'ci: seu_client_id' \
  --header 'cs: seu_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.

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 'ci: seu_client_id' \
  --header 'cs: seu_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.

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"
}

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"
}

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"
  }
}

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"
  }
}

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