Documentação de integração PixWiki

Autenticação

Envie sua chave no cabeçalho Authorization. Guarde pw_live_… somente no backend.

Authorization: Bearer pw_live_...

Endpoints

• GET /companies
• GET /summary
• GET /receipts
• GET /receipts/:id
• GET /checkouts
• POST /checkouts
• GET /checkouts/:id
• POST /checkouts/:id/cancel

Criar Checkout

POST /checkouts exige Idempotency-Key. Repetir a mesma chave para o mesmo usuário devolve o mesmo Checkout, evitando duplicidade em retries.

POST /api/v1/checkouts
Authorization: Bearer pw_live_...
Idempotency-Key: pedido-8742
Content-Type: application/json

{
  "company_id": "...",
  "amount_cents": 14990,
  "external_id": "pedido-8742",
  "description": "Pedido 8742",
  "customer": { "name": "Cliente" },
  "metadata": { "erp": "meu-sistema" },
  "success_url": "https://exemplo.com/pago"
}

Webhook pix.received

O contrato atual usa versão 2026-10-01. O payload mantém os campos básicos do recebimento e, quando houver Checkout/API, inclui contexto com checkout_id, external_id, customer e metadata.

Cabeçalhos relevantes: X-PixWiki-Event, X-PixWiki-Event-Id, X-PixWiki-Timestamp, X-PixWiki-Version, X-PixWiki-Signature e Idempotency-Key.

Validação da assinatura

Calcule HMAC SHA-256 usando o segredo do Webhook sobre <timestamp>.<raw_body> e compare em tempo constante com o valor v1=<hex> recebido.

Retries e idempotência

Falhas temporárias podem gerar novas tentativas aproximadamente em 1, 5, 30 e 120 minutos, até cinco tentativas no total. Trate o X-PixWiki-Event-Id/Idempotency-Key como chave de deduplicação.

Modelo de consumo

GETs não consomem Automação PixWiki. Criar um Checkout que não é pago também não consome. Quando um pagamento automatizado é concluído, ele gera no máximo uma unidade de uso, independentemente da quantidade de canais usados no mesmo recebimento.