Desenvolvedores

API de pagamentos e saques

Para marketplaces, ERPs, SaaS e parceiros: crie cobranças PIX, acompanhe pagamentos, consulte saldo, solicite saques e receba webhooks em tempo real.

Base URL

https://app.velsiq.com/api/v1

Autenticação

X-Public-Key

X-Secret-Key

Formato

REST + JSON, com sandbox e webhooks assinados.

Integração em 5 passos

01Obtenha Public key e Secret key no painel, em Chaves da API.
02Provisione o webhook com PUT /webhook (parceiros) ou configure no painel.
03Chame POST /payments/pix com customer.email e amount (ou product_id).
04Exiba copy_paste e/ou qrcode para o cliente final.
05Confirme o pagamento pelo webhook order.completed (polling só como fallback).

Prefira o webhook order.completed para liberar o produto. O GET /payments/{order_id} serve como fallback de reconciliação, não como substituto.

Endpoints

Método	Endpoint	Descrição
POST	/payments/pix	Criar cobrança PIX
GET	/payments	Listar pedidos
GET	/payments/{order_id}	Consultar status do pedido
POST	/pix/{order_id}/cancel	Cancelar PIX pendente
POST	/pix/{order_id}/refund	Estornar PIX pago
GET	/balance	Consultar saldo disponível
POST	/withdrawals	Solicitar saque
GET	/withdrawals	Listar saques
GET	/withdrawals/{id}	Consultar saque
PUT	/payout-destination	Configurar chave PIX de destino
GET	/webhook	Consultar configuração do webhook
PUT	/webhook	Provisionar webhook (retorna secret na 1ª vez)
POST	/webhook/rotate-secret	Rotacionar secret do webhook

Criar cobrança PIX

POST /payments/pix

curl -X POST 'https://app.velsiq.com/api/v1/payments/pix' \
  -H 'Content-Type: application/json' \
  -H 'X-Public-Key: gpk_sua_public_key' \
  -H 'X-Secret-Key: gsk_sua_secret_key' \
  -H 'Idempotency-Key: pedido-1001-pix' \
  -d '{
    "customer": { "email": "cliente@exemplo.com", "name": "Cliente Teste" },
    "amount": 97.90,
    "currency": "BRL",
    "metadata": { "external_id": "ped-1001" }
  }'

Resposta 201

{
  "order_id": 456,
  "transaction_id": "tx-abc123",
  "qrcode": "data:image/png;base64,...",
  "copy_paste": "00020126580014br.gov.bcb.pix...",
  "status": "pending"
}

Para alto volume, envie o header X-Async: true e receba 202 com status: processing.

Campos do request (PIX)

Campo	Tipo	Obrigatório	Descrição
customer.email	string	Sim	E-mail do comprador.
customer.name	string	Não	Nome; se vazio, usamos o e-mail.
customer.cpf	string	Não	CPF, com ou sem formatação.
amount	number	Sim*	Valor em reais (ex.: 97.90). Ignorado quando product_id define o preço.
currency	string	Não	BRL, USD ou EUR. Padrão: BRL.
product_id	uuid	Não	Produto do catálogo; o preço vem do produto/oferta/plano.
metadata	objeto	Não	Dados livres devolvidos no webhook e nas consultas.
partner_checkout_url	url https	Não	URL do checkout do parceiro. Recomendado em produção.
idempotency_key	string	Não	Chave única (máx. 128) — também aceita no header Idempotency-Key.

Status do pedido

Status	Quando ocorre
pending	PIX gerado, aguardando pagamento.
processing	Pedido criado, PIX ainda sendo gerado (modo assíncrono).
completed	Pagamento confirmado.
cancelled	Cancelado via API ou por expiração.
refunded	Estorno concluído.
disputed	Disputa em andamento.

Saldo e saques

GET /balance devolve saldo disponível por carteira (PIX, cartão e boleto) e o valor ainda em liquidação. Antes do primeiro saque, configure o destino com PUT /payout-destination informando pix_key, pix_key_type e o CPF/CNPJ do titular quando a chave for e-mail, telefone ou aleatória. Em seguida use POST /withdrawals com Idempotency-Key para evitar saques duplicados.

Webhooks

Evento	Descrição
order.pending	Pedido criado, aguardando pagamento.
pix.generated	QR Code e copia e cola disponíveis.
order.completed	Pagamento confirmado — libere o produto.
order.refunded	Estorno concluído.
order.cancelled	Pedido cancelado.
order.expired	PIX expirou sem pagamento.
withdrawal.completed	Saque concluído, PIX enviado.
withdrawal.failed	Falha no saque, saldo restaurado.

Payload

{
  "event": "order.completed",
  "event_id": "550e8400-e29b-41d4-a716-446655440000",
  "order_id": 456,
  "amount": 97.90,
  "status": "completed",
  "payment_method": "pix",
  "paid_at": "2026-06-13T14:05:12.000000Z",
  "metadata": { "external_id": "ped-1001" }
}

Validação HMAC-SHA256 (Node.js)

import crypto from 'crypto';

const expected = crypto
  .createHmac('sha256', process.env.VELSIQ_WEBHOOK_SECRET)
  .update(rawBody)
  .digest('hex');

if (expected !== req.headers['x-webhook-signature']) {
  return res.status(401).end();
}

Cada entrega envia X-Webhook-Signature, X-Webhook-Id (use para deduplicar) e X-Webhook-Timestamp. Falhas são reenviadas com backoff exponencial — responda 2xx rapidamente.

Hub de integração via IA

Integrar com IA

Baixe o pacote Markdown completo da API e do SDK para usar em ChatGPT, Claude Code ou Cursor. O arquivo inclui instruções para o modelo, boas práticas de fluxo e segurança (webhook + reconciliação) e a referência completa dos endpoints.

Baixar documentação para IA

Pacote Markdown completo da API e integração. Ideal para janelas de contexto longas em assistentes de código e chat.

Baixar velsiq-api-integracao-llm.md

Segurança e boas práticas

A Secret key vive apenas no backend — nunca no frontend ou em repositórios públicos.
Use HTTPS em produção e restrinja os IPs permitidos no painel.
Crie chaves adicionais com permissões mínimas: payments:read, payments:write, payments:refund, withdrawals:read, withdrawals:write, webhooks:read e webhooks:write.
Valide a assinatura de todo webhook antes de processar o evento.

Referência completa e ambiente de testes em app.velsiq.com/docs/api-pagamentos.