# MisticPay - Guia de Integração para Modelos de Linguagem

## Visão Geral
A MisticPay é uma API completa de pagamentos que permite receber e enviar pagamentos via PIX de forma simples e segura. Também suporta saques em criptomoeda (USDT BEP20).

Principais funcionalidades:
- **Receber Pagamentos (Cash-In):** Gere QR Codes PIX e receba pagamentos instantaneamente.
- **Realizar Saques (Cash-Out):** Transfira fundos para qualquer chave PIX de forma programática.
- **Saques Crypto:** Converta saldo BRL para USDT BEP20 e envie para wallets.
- **Webhooks em Tempo Real:** Receba notificações automáticas de mudanças de status em suas transações.
- **Gestão de Infrações (MED):** Liste e responda a Mecanismos Especiais de Devolução via API.

- **Documentação:** [Documentação Completa](https://docs.misticpay.com/)

## Autenticação
- **Método:** Client ID + Client Secret via Headers
- **Detalhes:** Todas as requisições à API devem incluir dois headers essenciais: `ci` (Client ID) e `cs` (Client Secret).
- **Segurança:** Nunca exponha sua Client Secret no frontend ou em repositórios públicos. Ela deve ser armazenada de forma segura no backend.
- **URL Base:** `https://api.misticpay.com/api`
- **Headers Obrigatórios:**
  ```
  ci: seu_client_id
  cs: seu_client_secret
  Content-Type: application/json
  ```

---

## Endpoints Principais

### Transações (Cash-In)

#### ➤ Gerar Transação PIX

- **Endpoint:** `POST /api/transactions/create`
- **Descrição:** Cria uma nova transação PIX para receber pagamento de um cliente. Retorna QR Code e dados da transação.
- **curl esperado como exemplo:**

```bash
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"
  }'
```

**Explicação de cada parâmetro do Body:**

- **amount** (number, obrigatório): Valor da transação em reais. Exemplo: 5.
- **payerName** (string, obrigatório): Nome completo do cliente pagador. Exemplo: "Nome do cliente".
- **payerDocument** (string, obrigatório): CPF do cliente pagador. Exemplo: "12345678909".
- **transactionId** (string, opcional): Identificador da transação no seu sistema. Exemplo: "id_da_sua_aplicacao_para_identificacao".
- **description** (string, opcional): Descrição da transação. Exemplo: "Pagamento do cliente TAL".

**Modelo 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/..."
  }
}
```

- **Documentação:** [Gerar Transação](https://docs.misticpay.com/#create-transaction)

---

#### ➤ Gerar Transação Interna

- **Endpoint:** `POST /api/transactions/internal`
- **Descrição:** Cria uma transação interna vinculada a um usuário pelo e-mail. Transfere saldo entre contas MisticPay.
- **curl esperado como exemplo:**

```bash
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"
  }'
```

**Explicação de cada parâmetro do Body:**

- **email** (string, obrigatório): E-mail do usuário destinatário. Exemplo: "emailrecebedor@gmail.com".
- **amount** (number, obrigatório): Valor a ser transferido em reais. Exemplo: 2.
- **description** (string, opcional): Descrição da transferência. Exemplo: "teste".

**Modelo de resposta:**

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

- **Documentação:** [Gerar Transação Interna](https://docs.misticpay.com/#create-internal-transaction)

---

#### ➤ Verificar Transação

- **Endpoint:** `POST /api/transactions/check`
- **Descrição:** Consulta o status e detalhes de uma transação específica.
- **⚠️ Rate Limit:** 60 requisições por minuto por IP. Requisições excedentes retornam erro 429.
- **curl esperado como exemplo:**

```bash
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"
  }'
```

**Explicação de cada parâmetro do Body:**

- **transactionId** (string, obrigatório): ID da transação a ser consultada. Exemplo: "54345".

**Modelo 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:** `PENDENTE`, `COMPLETO`, `EXPIRADO`, `CANCELADO`, `QUEUED`.

- **Documentação:** [Verificar Transação](https://docs.misticpay.com/#check-transaction)

---

#### ➤ Listar Transações

- **Endpoint:** `GET /api/users/transactions/list/:page`
- **Descrição:** Lista as transações do usuário com paginação e filtro por status. Retorna no máximo 10 transações por página.
- **curl esperado como exemplo:**

```bash
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'
```

**Explicação de cada parâmetro:**

- **:page** (URL, obrigatório): Número da página (inicia em 1). Exemplo: 1.
- **status** (query string, opcional): Filtro por status da transação. Valores possíveis: `PENDENTE`, `COMPLETO`, `EXPIRADO`, `CANCELADO`.

**Modelo 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
  }
}
```

- **Documentação:** [Listar Transações](https://docs.misticpay.com/#list-transactions)

---

### Conta / Usuário

#### ➤ Consultar Saldo

- **Endpoint:** `GET /api/users/balance`
- **Descrição:** Retorna o saldo disponível na conta.
- **curl esperado como exemplo:**

```bash
curl -X GET 'https://api.misticpay.com/api/users/balance' \
  --header 'ci: seu_client_id' \
  --header 'cs: seu_client_secret'
```

_Esta rota não necessita de body._

**Modelo de resposta:**

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

- **Documentação:** [Consultar Saldo](https://docs.misticpay.com/#get-balance)

---

#### ➤ Consultar Dados do Usuário

- **Endpoint:** `GET /api/users/info`
- **Descrição:** Retorna os dados do usuário autenticado pelas credenciais CI/CS. Inclui informações pessoais, status da conta e saldo disponível.
- **curl esperado como exemplo:**

```bash
curl -X GET 'https://api.misticpay.com/api/users/info' \
  --header 'ci: seu_client_id' \
  --header 'cs: seu_client_secret'
```

_Esta rota não necessita de body._

**Modelo 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
  }
}
```

- **Documentação:** [Consultar Dados do Usuário](https://docs.misticpay.com/#get-user-info)

---

### Saques (Cash-Out)

#### ➤ Solicitar Saque PIX

- **Endpoint:** `POST /api/transactions/withdraw`
- **Descrição:** 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).
- **curl esperado como exemplo:**

```bash
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"
  }'
```

**Explicação de cada parâmetro do Body:**

- **amount** (number, obrigatório): Valor do saque em reais. Exemplo: 1.
- **pixKey** (string, obrigatório): Chave PIX do destinatário. Exemplo: "12345678909".
- **pixKeyType** (string, obrigatório): Tipo da chave PIX. Valores possíveis: `CPF`, `CNPJ`, `EMAIL`, `TELEFONE`, `CHAVE_ALEATORIA`.
- **description** (string, opcional): Descrição do saque.
- **projectWebhook** (string, opcional): URL para receber o webhook de status do saque.

**Modelo 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"
  }
}
```

- **Documentação:** [Solicitar Saque](https://docs.misticpay.com/#create-withdrawal)

---

#### ➤ Solicitar Saque Crypto

- **Endpoint:** `POST /api/crypto/withdraw-api`
- **Descrição:** Solicita um saque em criptomoeda (USDT BEP20) para uma wallet. O valor será debitado do saldo disponível e convertido para USDT.
- **Limites:** Mínimo R$ 20,00 / Máximo R$ 3.000,00
- **Taxas:** 3% sobre o valor (plataforma) + taxa de rede variável (calculada automaticamente)
- **Wallet:** Deve ser válida no formato BEP20 (0x...)
- **curl esperado como exemplo:**

```bash
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"
  }'
```

**Explicação de cada parâmetro do Body:**

- **amount** (number, obrigatório): Valor do saque em reais. Exemplo: 100.
- **wallet** (string, obrigatório): Endereço da wallet BEP20 do destinatário. Exemplo: "0x1234567890123456789012345678901234567890".
- **projectWebhook** (string, opcional): URL para receber o webhook de status do saque crypto.

**Modelo 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"
  }
}
```

- **Documentação:** [Solicitar Saque Crypto](https://docs.misticpay.com/#create-crypto-withdrawal)

---

#### ➤ Consultar Taxas de Cripto

- **Endpoint:** `GET /api/crypto/fees`
- **Descrição:** Consulta informações sobre as taxas de cripto, incluindo taxa da plataforma, taxa de rede e cotação atual BRL/USD.
- **Taxas:** Plataforma: 3% sobre o valor | Rede: R$ 3,00 (fixa, apenas informativa)
- **curl esperado como exemplo:**

```bash
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'
```

_Esta rota não necessita de body._

**Modelo 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
    }
  }
}
```

- **Documentação:** [Consultar Taxas de Cripto](https://docs.misticpay.com/#get-crypto-fees)

---

### Infrações (MED - Mecanismo Especial de Devolução)

#### ➤ Listar Infrações

- **Endpoint:** `GET /api/meds/infractions/list`
- **Descrição:** Lista todas as infrações (MEDs) registradas para sua conta, com paginação. Inclui detalhes da transação associada e respostas de defesa enviadas.
- **curl esperado como exemplo:**

```bash
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'
```

**Explicação de cada parâmetro:**

- **page** (query string, opcional): Número da página. Padrão: 1.
- **perPage** (query string, opcional): Itens por página. Padrão: 10.

**Modelo 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:** `WAITING_PSP`, `ACCEPTED`, `REJECTED`, `CANCELLED`.

- **Documentação:** [Listar Infrações](https://docs.misticpay.com/#list-meds)

---

#### ➤ Responder Infração

- **Endpoint:** `POST /api/meds/infractions/:infractionId/defense`
- **Descrição:** 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.
- **curl esperado como exemplo:**

```bash
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"
    ]
  }'
```

**Explicação de cada parâmetro:**

- **:infractionId** (URL, obrigatório): ID da infração a ser respondida. Exemplo: 42.
- **analise** (string, obrigatório): Resultado da análise. Valores possíveis: `"rejeitado"` (discordar da infração) ou `"aceito"` (concordar com a infração).
- **justificativa** (string, obrigatório): Texto justificando a análise.
- **proofs** (array de string, opcional): Lista de URLs de comprovantes/provas.

**Modelo 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"
  }
}
```

- **Documentação:** [Responder Infração](https://docs.misticpay.com/#respond-med)

---

## 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 na `projectWebhook`.

### Webhook de Depósito

Enviado quando um pagamento PIX é confirmado.

```json
{
  "transactionId": 31484480,
  "transactionType": "DEPOSITO",
  "transactionMethod": "PIX",
  "clientName": "Nome do cliente",
  "clientDocument": "12345678909",
  "status": "COMPLETO",
  "value": 455,
  "fee": 23
}
```

---

### Webhook de Saque

Enviado quando um saque PIX é processado.

```json
{
  "transactionId": 31484480,
  "transactionType": "RETIRADA",
  "transactionMethod": "PIX",
  "clientName": "Nome do cliente",
  "clientDocument": "12345678909",
  "status": "COMPLETO",
  "value": 455,
  "fee": 23
}
```

---

### Webhook de MED (Infração Criada)

Enviado quando uma nova 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"
  }
}
```

---

### Webhook de MED (Análise Concluída)

Enviado quando uma infração recebe resultado de análise.

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

---

## Suporte e Contato

- **E-mail:** contato@misticpay.com
- **Telefone:** +55 (53) 3192-1031
- **Documentação:** [https://docs.misticpay.com/](https://docs.misticpay.com/)
- **Site:** [https://misticpay.com](https://misticpay.com)

---

_Este guia foi elaborado para auxiliar modelos de linguagem e desenvolvedores a integrar-se de forma eficaz com a API da MisticPay utilizando os endpoints atualizados._