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
https://api.misticpay.comLimites e ambiente
- Limite de 100 requisições por segundo por chave. Acima disso a API responde
429com o códigoRATE_LIMITEDe o headerRetry-After: 1; aguarde e tente novamente. Os headersRateLimit-LimiteRateLimit-Remainingmostram quanto resta no segundo corrente. - Não há ambiente de testes (sandbox): valide a integração em produção com valores baixos.
- Valores e taxas (
value,fee) são em reais, com casas decimais — por exemplo10.50, não centavos. - Em API → IPs autorizados você restringe a conta a uma lista de IPs. Com a lista preenchida, qualquer chamada de outro IP — inclusive saques — recebe
401. Lista vazia aceita qualquer IP.
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 PIXTRANSACTION_READ— consultar transação (/api/transactions/check)BALANCE_READ— saldo e dados da contaWITHDRAW_CREATE— saque PIX por chave ou QR CodeCRYPTO_WITHDRAW_CREATE— saque em USDT BEP20CRYPTO_RATES_READ— cotação e taxas de criptoMED_READ— listar infrações MEDMED_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:
| Endpoint | ci/cs | Chave de acesso |
|---|---|---|
| POST /transactions/create | Sim | Sim |
| POST /transactions/check | Sim | Sim |
| Todos os demais endpoints | Não | Sim |
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.
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.
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:
https://api.misticpay.com/apiHeaders Obrigatórios
Authorization: Basic BASE64(client_id:client_secret)
Content-Type: application/jsonBASE64(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
- No painel, acesse API → Chaves de Acesso e clique em Criar Chave de Acesso. É exigido código 2FA.
- 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.
- Copie o
sk_na hora — ele não é exibido de novo. - Troque os headers
ci/cspelo headerAuthorization: Basic …nas suas chamadas. - 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:
{
"code": "INSUFFICIENT_BALANCE",
"message": "Saldo insuficiente, faltam 12.50 reais",
"statusCode": 400,
"details": { "missingAmount": 12.5 },
"requestId": "04b9d2a5-845f-456d-af0d-8b9922143547"
}Campos
| Campo | Tipo | Descrição |
|---|---|---|
| code | string | Identificador 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 |
| message | string | Explicação em português, pronta para exibir. Pode trazer valores da ocorrência; não compare o texto, ele pode mudar |
| statusCode | number | O mesmo status HTTP da resposta, repetido no corpo |
| details | object | null | Dados estruturados da ocorrência, como o valor que falta no saldo. null quando não há nada a acrescentar |
| requestId | string | Identificador da requisição nos nossos logs. É o mesmo valor do header X-Request-Id da resposta |
Como tratar
- Decida pelo
codee pelo status HTTP, nunca pelo texto demessage. - Alguns erros trazem campos extras no topo do corpo, ao lado dos cinco acima — por exemplo
missingAmountemINSUFFICIENT_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 headerX-Request-Id(até 128 caracteres ASCII imprimíveis), usamos o seu valor; caso contrário, geramos um UUID. - Um
5xxou um429pode ser repetido. Em saques, repita com o mesmoX-Idempotency-Keypara não enviar o pagamento duas vezes.
Códigos mais comuns
| Código | Status | Quando acontece |
|---|---|---|
| INVALID_API_CREDENTIAL | 401 | Credencial ausente, inválida ou revogada |
| IP_NOT_ALLOWED | 401 | O IP de origem não está na lista de IPs autorizados da conta |
| API_SCOPE_DENIED | 403 | A chave não tem o escopo exigido pela rota |
| API_CREDENTIAL_REQUIRED | 400 | Credencial ci/cs não enviada nos headers |
| INVALID_JSON | 400 | O corpo da requisição não é um JSON válido |
| VALIDATION_ERROR | 400 | Um campo não passou na validação; details.issues lista cada campo e o motivo |
| AMOUNT_BELOW_MINIMUM | 400 | Valor abaixo do mínimo aceito para a operação |
| PIX_KEY_TYPE_INVALID | 400 | pixKeyType fora de CPF, CNPJ, EMAIL, TELEFONE ou CHAVE_ALEATORIA |
| IDEMPOTENCY_KEY_INVALID | 400 | X-Idempotency-Key vazio ou com mais de 255 caracteres |
| INSUFFICIENT_BALANCE | 400 | Saldo disponível não cobre o valor e as taxas da operação |
| TRANSACTION_NOT_FOUND | 404 | Nenhuma transação com o identificador informado |
| ROUTE_NOT_FOUND | 404 | Método ou caminho inexistente; details traz os dois |
| RATE_LIMITED | 429 | Mais de 100 requisições por segundo na chave; aguarde o Retry-After |
| INTERNAL_ERROR | 500 | Falha do nosso lado; tente de novo e envie o requestId ao suporte |
Gerar transação
/api/transactions/create
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. Se omitido, a API gera um UUID. |
| 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 -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
{
"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
/api/transactions/withdraw/internal
Cria uma transação interna vinculada a um usuário pelo e-mail.
Headers Obrigatórios
Authorization: Basic BASE64(client_id:client_secret)
Content-Type: application/jsonExemplo de Requisição
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
{
"message": "Transferência realizada com sucesso",
"data": {
"transactionId": "id-da-transacao",
"amount": 1,
"recipientEmail": "emailrecebedor@gmail.com",
"recipientName": "Nome do recebedor"
}
}Consultar saldo
/api/users/balance
Retorna o saldo disponível na conta.
Exemplo de Requisição
curl -X GET 'https://api.misticpay.com/api/users/balance' \
--header 'Authorization: Basic BASE64(client_id:client_secret)'Exemplo de Resposta
{
"message": "Saldo do usuário obtido com sucesso",
"data": {
"balance": 0.00
}
}Consultar dados do usuário
/api/users/info
Retorna os dados do usuário autenticado pela chave de acesso. Inclui informações pessoais, status da conta e saldo disponível.
Campos Retornados
| Campo | Tipo | Descrição |
|---|---|---|
| name | string | Nome do usuário |
| string | Email do usuário | |
| document | string | CPF/CNPJ do usuário |
| phone | string | Telefone do usuário |
| accountVerified | boolean | Se a conta do usuário está verificada |
| documentVerified | boolean | Se o documento do usuário está verificado |
| withdrawBlocked | boolean | Se o saque está bloqueado para o usuário |
| availableBalance | number | Saldo disponível (saldo total - saldo bloqueado) |
| blockedBalance | number | Saldo bloqueado por MEDs ou outras restrições |
Exemplo de Requisição
curl -X GET 'https://api.misticpay.com/api/users/info' \
--header 'Authorization: Basic BASE64(client_id:client_secret)'Exemplo de Resposta
{
"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
/api/transactions/withdraw
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) |
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 -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
{
"message": "Saque adicionado à fila de processamento",
"data": {
"jobId": "withdraw-4-1764365277110-jxqfvna",
"transactionId": 54345,
"status": "QUEUED",
"message": "Seu saque será processado em breve"
}
}/api/transactions/withdraw/qrcode
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âmetro | Tipo | Descrição |
|---|---|---|
| qrCode * | string | Código Pix copia e cola (BR Code). |
| amount | number | Obrigató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. |
| description | string | Descrição do pagamento (opcional) |
| projectWebhook | string | URL do webhook para notificações (opcional) |
Exemplo de Requisição
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
{
"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
/api/crypto/withdraw-api
Solicita um saque em criptomoeda (USDT BEP20) para uma wallet. O valor será debitado do saldo disponível e convertido para USDT.
- 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â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 -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
{
"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
/api/crypto/fees
Consulta informações sobre as taxas de cripto, incluindo taxa da plataforma, taxa de rede e cotação atual.
- 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 -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
{
"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
/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âmetro | Tipo | Descrição |
|---|---|---|
| transactionId * | string | number | ID da transação a ser verificada |
Exemplo de Requisição
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
{
"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:
"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
| 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 transações
/api/transactions/list
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.
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âmetro | Tipo | Descrição |
|---|---|---|
| page | number | Número da página (padrão: 1) |
Parâmetros (Query String)
| Parâmetro | Tipo | Descrição |
|---|---|---|
| status | string | Filtrar por status (opcional). |
Exemplo de Requisição
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
{
"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
| Campo | Tipo | Descrição |
|---|---|---|
| id | number | ID da transação |
| value | number | Valor da transação em reais |
| fee | number | Taxa cobrada na transação |
| clientName | string | Nome do cliente da transação |
| clientDocument | string | Documento do cliente (pode estar mascarado) |
| description | string | Descrição da transação |
| requestIp | string | IP de origem da requisição |
| transactionState | string | Estado da transação: PENDENTE, COMPLETO, FALHA, CANCELADO, DEVOLVIDO ou DEVOLVIDO_PARCIAL |
| transactionType | string | Tipo da transação (ex: DEPOSITO, RETIRADA) |
| transactionMethod | string | Método da transação (ex: PIX) |
| source | string | Origem da transação (ex: API, CHECKOUT) |
| endToEndId | string | null | Identificador end-to-end do PIX (quando disponível) |
| clientTransactionId | string | ID da transação do cliente |
| createdAt | string | Data de criação (ISO 8601) |
| updatedAt | string | Data da última atualização (ISO 8601) |
| pagination.page | number | Página atual |
| pagination.perPage | number | Itens por página (fixo: 10) |
| pagination.total | number | Total de transações na página atual |
| pagination.totalPages | number | Total de páginas disponíveis |
Filtros de Status
| 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 |
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ódigo | Descrição |
|---|---|
| 400 | Credenciais de integração não enviadas (ci e cs nos headers) |
| 401 | Credenciais inválidas |
Listar infrações
/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.
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â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 -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
{
"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
/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.
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 -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)
{
"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.
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
{
"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
{
"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.
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)
{
"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)
{
"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
| Campo | Tipo | Descrição |
|---|---|---|
| status | string | CONCLUIDO quando o valor foi devolvido; RECUSADO quando um reembolso já notificado foi recusado pelo banco e desfeito |
| refundId | string | null | Identificador do reembolso no banco liquidante (ou o E2E da devolução, conforme o banco) |
| refundedValue | number | Valor devolvido em reais. Num reembolso parcial é menor que value |
| refundedAt | string | Data e hora do reembolso (ISO 8601, UTC) |
Status do Reembolso
| refund.status | status da transação | Descrição |
|---|---|---|
CONCLUIDO | DEVOLVIDO ou DEVOLVIDO_PARCIAL | O reembolso foi concluído e o seu saldo já foi ajustado |
RECUSADO | COMPLETO | O 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.
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)
{
"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)
{
"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
| 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 |