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...",
  "status": "pending"
}

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

Taxas

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

⭐ 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.