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

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.

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 (ex: "CPF", "CNPJ", "EMAIL", "PHONE", "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"
  }
}

Verificar transação

POST

/api/transactions/check

Consulte o status e detalhes de uma transação específica.

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

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.

Importante

Sempre retorne HTTP 200-299 para confirmar recebimento. Se não retornar sucesso, o webhook será reenviado automaticamente (até 5 tentativas).

Estrutura do Webhook de Depósito

JSON

{
  "transactionId": 31484480,
  "transactionType": "DEPOSITO",
  "transactionMethod": "PIX",
  "status": "COMPLETO",
  "value": 455,
  "fee": 23,
}

Webhook de Saque

Estrutura do Webhook de Saque

JSON

{
  "transactionId": 31484480,
  "transactionType": "RETIRADA",
  "transactionMethod": "PIX",
  "status": "COMPLETO",
  "value": 455,
  "fee": 23,
}