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

Versão da API

Esta documentação refere-se à API v1. Todas as requisições devem ser feitas para o endpoint base: https://api.misticpay.com

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âmetro	Tipo	Descrição
amount *	number	Valor em reais para receber. Ex: 4.55 = R$ 4,55
payerName *	string	Nome do pagador da transação
payerDocument *	string	Documento CPF do pagador (sem formatação: 12345678909)
transactionId *	string	ID da sua aplicação para identificação da transação
description *	string	Descrição do pagamento
projectWebhook	string	URL do webhook (opcional)
splitUser	string	Email do usuário na plataforma que receberá a divisão (opcional)
splitTax	number	Porcentagem 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",
    "newBalance": "seu saldo atual"
  }
}

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

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âmetro	Tipo	Descrição
amount *	number	Valor em reais para receber. Ex: 100 = R$ 100,00
pixKey *	string	Chave PIX do destinatário (sem formatação: 12345678909).
pixKeyType *	string	Tipo da chave PIX: "CPF", "CNPJ", "EMAIL", "TELEFONE", "CHAVE_ALEATORIA"
description *	string	Descrição do pagamento
projectWebhook	string	URL 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âmetro	Tipo	Descrição
amount *	number	Valor em reais para sacar. Ex: 100 = R$ 100,00 (mínimo R$ 20,00, máximo R$ 3.000,00)
wallet *	string	Endereço da wallet BEP20 para receber USDT (formato: 0x seguido de 40 caracteres hexadecimais)
projectWebhook	string	URL 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âmetro	Tipo	Descrição
transactionId *	string \| number	ID 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

Status	Descrição
PENDENTE	Transação pendente, aguardando pagamento
COMPLETO	Transação aprovada e concluída com sucesso
FALHA	Transação falhou ou foi rejeitada

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âmetro	Tipo	Descrição
page	number	Página atual (padrão: 1)
perPage	number	Itens 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

Status	Descriçã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âmetro	Tipo	Descrição
infractionId *	number	ID da infração (obtido na listagem)

Parâmetros (Body JSON)

Parâmetro	Tipo	Descrição
analise *	string	Posicionamento: `"rejeitado"` ou `"aceito"`
justificativa *	string	Texto 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ódigo	Descrição
400	Campos obrigatórios ausentes, valor inválido para analise, ou infração já resolvida
403	A infração não pertence à sua conta
404	Infração não encontrada
409	Já 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,
}

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

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

Campo	Tipo	Descrição
id	number	ID interno da infração
externalId	string	ID externo da infração (gateway)
type	string	Tipo da infração (ex: FRAUD, REFUND_REQUEST)
status	string	WAITING_PSP, ACCEPTED, REJECTED ou CANCELLED
amount	number	Valor da infração em reais
currency	string	Moeda (padrão: BRL)
analysisResult	string \| null	Resultado: AGREED (aceita) ou DISAGREED (rejeitada)
analysisDetails	string \| null	Detalhes adicionais da análise
reportedBy	string \| null	Quem reportou: DEBITED_PARTICIPANT, CREDITED_PARTICIPANT ou ACCOUNT_HOLDER
reportDetails	string \| null	Detalhes do reporte
createdAt	string	Data de criação (ISO 8601)

Campos do objeto transaction

Campo	Tipo	Descrição
transactionId	string	ID da transação (clientTransactionId ou externalId)
endToEndId	string \| null	Identificador end-to-end do PIX
value	number	Valor original da transação
status	string	Estado atual da transação

Status da Infração

Status	Descriçã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