Reference

Documentação da API

Base URL: https://nuvixpay.app

Autenticação

Envie /start ao bot @nuvixpay no Telegram. Ele responderá com seu api_key. Use o token em todas as chamadas:

Authorization: Bearer <seu_api_key>

GET/api/public/balance

Retorna saldo atual do usuário autenticado.

Request

curl https://nuvixpay.app/api/public/balance \
  -H "Authorization: Bearer SEU_API_KEY"

Response

{
  "ok": true,
  "telegram_id": 123456789,
  "balance": 42.50,
  "is_vip": false,
  "vip_tx_count": 12
}

POST/api/public/deposit

Cria uma cobrança PIX. Retorna o código copia-e-cola. Ao ser pago, o saldo é creditado automaticamente.

Request

curl -X POST https://nuvixpay.app/api/public/deposit \
  -H "Authorization: Bearer SEU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount": 50.00}'

Response

{
  "ok": true,
  "transaction_id": "uuid...",
  "external_id": "dep_...",
  "amount": 50.00,
  "fee": 1.50,
  "net_credit": 48.50,
  "pix_code": "00020126...",
  "qr_code_base64": "iVBORw0K...",
  "status": "pending",
  "status_url": "https://nuvixpay.app/api/public/status?id=uuid..."
}

GET/api/public/status?id=<transaction_id>

Verifica o PIX gerado. Consulta o provedor em tempo real e, se estiver pago, credita o saldo na hora e notifica o cliente. Use o transaction_id (ou external_id) devolvido no /deposit.

Request

curl "https://nuvixpay.app/api/public/status?id=TRANSACTION_ID" \
  -H "Authorization: Bearer SEU_API_KEY"

Response

{
  "ok": true,
  "transaction_id": "uuid...",
  "external_id": "dep_...",
  "type": "deposit",
  "amount": 50.00,
  "fee": 1.50,
  "net_amount": 48.50,
  "status": "approved",
  "paid": true,
  "provider_status": "PAID",
  "balance": 98.50,
  "is_vip": false
}

POST/api/public/withdraw

Solicita saque PIX. Debita imediatamente do saldo (amount + fee). Se rejeitado, é estornado.

Request

curl -X POST https://nuvixpay.app/api/public/withdraw \
  -H "Authorization: Bearer SEU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 20.00,
    "pix_key": "email@dominio.com",
    "pix_key_type": "email"
  }'

Response

{
  "ok": true,
  "transaction_id": "uuid...",
  "amount": 20.00,
  "fee": 0.50,
  "total_debited": 20.50,
  "new_balance": 22.00,
  "status": "pending"
}

POST/api/public/webhook/misticpay

Webhook de confirmação do PIX. Configure esta URL no painel do gateway: assim que o pagamento é confirmado, o saldo é creditado automaticamente e o cliente recebe a notificação no Telegram.

Request

POST https://nuvixpay.app/api/public/webhook/misticpay
Content-Type: application/json

{
  "transactionId": "dep_...",
  "status": "PAID",
  "amount": 50.00
}

Response

{ "ok": true, "status": "approved", "updated": true }

Taxas

A taxa é composta por porcentagem sobre o valor + taxa fixa, configurável no painel admin do bot. Fórmula: taxa = valor × (percentual ÷ 100) + taxa_fixa.

Tipo	Conta normal	Conta VIP
Depósito	0% + R$ 1,50	0% + R$ 0,50
Saque	0% + R$ 0,50	0% + R$ 0,50

Exemplo com 15% + R$ 1,00: depósito de R$ 100,00 → taxa R$ 16,00 → crédito de R$ 84,00.

⭐ VIP ativado automaticamente após 100 transações aprovadas.

Códigos de erro

401 — API key inválida ou ausente.
400 — Payload inválido / saldo insuficiente / valor abaixo da taxa.
409 — Saldo mudou entre a leitura e o débito. Tente novamente.
502 — Erro no provedor de pagamento.