n8n-nodes-hubpay

Community node n8n para Hubpay — API unificada PIX com múltiplos PSPs: Asaas, Mercado Pago, Efí, Pagar.me, Starkbank, Stripe, Iugu e PagSeguro, sob um único contrato.

Inclui dois nodes + uma credencial reaproveitável:

• HubPay (action) — cria, busca e cancela cobranças PIX
• HubPay Trigger (webhook) — recebe eventos charge.* validando HMAC-SHA256 do header X-Hubpay-Signature
• HubPay API (credentials) — API Key (hpx_test_... / hpx_live_...) + Webhook Signing Secret

Mesmo padrão dos outros módulos do repositório: helpers puros testados em Jest, validação HMAC em tempo constante, idempotency-key determinística quando há reference.

Estrutura

hubpay-n8n/
├── package.json                          (n8n-community-node-package)
├── tsconfig.json / tsconfig.test.json
├── jest.config.js
├── scripts/copy-icons.js                 (copia .svg para dist/)
├── credentials/
│   └── HubPayApi.credentials.ts          API Key + Webhook Secret
├── nodes/HubPay/
│   ├── HubPay.node.ts                    Action: Charge → Create/Get/Cancel
│   ├── HubPayTrigger.node.ts             Trigger: webhook signed
│   ├── GenericFunctions.ts               HTTP, HMAC, idempotency, helpers
│   ├── GenericFunctions.test.ts          Jest (47 cases)
│   └── hubpay.svg                        Logo (verde + raio branco)
└── README.md

Instalação

Opção 1 — Via npm publish + UI do n8n (recomendado se você publicar)

1. npm publish no diretório hubpay-n8n/.
2. No n8n: Settings → Community Nodes → Install → digita n8n-nodes-hubpay.

Opção 2 — Local custom (sem publicar no npm)

# Build do módulo
cd hubpay-n8n
npm install
npm run build

# Aponta o n8n pro custom dir
mkdir -p ~/.n8n/custom
cd ~/.n8n/custom
npm init -y
npm install /caminho/para/hubpay-n8n

# Reinicia o n8n

Os nodes "HubPay" e "HubPay Trigger" aparecem na lista do editor.

Opção 3 — Docker / N8N_CUSTOM_EXTENSIONS

Se você roda n8n em Docker, monte um volume com o pacote já buildado e exporte:

environment:
  - N8N_CUSTOM_EXTENSIONS=/data/custom
volumes:
  - ./hubpay-n8n:/data/custom/n8n-nodes-hubpay

Roda npm install && npm run build dentro do container antes de subir.

Configuração da credencial

No editor do n8n: Credentials → New → HubPay API.

| Campo | Descrição | |---|---| | API Key | Chave gerada em Hubpay Dashboard → API Keys. Prefixo (hpx_test_ / hpx_live_) define o ambiente. | | Webhook Signing Secret | Apenas para o trigger node. Pegue em Hubpay Dashboard → Webhooks → (seu endpoint) → Signing Secret. |

O botão "Test" aciona um GET /v1/charges/_credential_test e falha se a API Key for inválida (HTTP 401).

Uso — node action HubPay

Resource único: Charge. Operações:

Create

| Parâmetro | Obrigatório | Descrição | |---|---|---| | Amount (BRL) | sim | Valor em reais — convertido pra centavos automaticamente | | Provider | sim | asaas, mercadopago, efi, pagarme, starkbank, stripe, iugu, pagseguro ou random (enviado à API; round-robin entre os PSPs conectados na Hubpay) | | Reference | recomendado | Identificador estável seu (gera Idempotency-Key determinística baseada em n8n\|reference\|cents\|provider, incluindo a string random quando for o caso). Vazio = UUID novo a cada execução. | | Description | opcional | Texto que aparece no extrato/PSP | | Expires In | opcional | Validade do QR em segundos (default 86400, mínimo 60) | | Payer (collection) | opcional | Nome / e-mail / documento (CPF 11 ou CNPJ 14 dígitos — pontuação é stripada) | | Metadata (fixedCollection) | opcional | Pares chave/valor que o Hubpay devolve nos webhooks |

Output: o objeto charge cru retornado pelo Hubpay (id, status, pix.copy_paste, pix.qr_code_base64, expires_at, ...).

Get

Recebe o chargeId (chg_...) e retorna o estado atual do charge — útil pra polling manual.

Cancel

DELETE /v1/charges/:id. Só funciona quando o charge ainda está pending.

Uso — node trigger HubPay Trigger

Recebe webhooks signados em https://SEU-N8N/webhook/hubpay (n8n cria a URL automaticamente; você cola ela em Hubpay Dashboard → Webhooks → Novo Endpoint).

| Parâmetro | Default | Descrição | |---|---|---| | Events | charge.paid | Apenas eventos marcados disparam o workflow. Os demais respondem 200 OK silenciosamente — Hubpay não retenta. | | Allow Unsigned Webhooks | off | Desligar SEMPRE em produção. Só liga em testes locais com curl. |

Output: o body do webhook + um _meta com event_id, event_type, received_at.

A validação usa crypto.timingSafeEqual (constant-time) e aceita o formato canônico v1=<hex>, listas multi-versão t=...,v1=...,v0=... e digest hex puro de 64 chars como fallback — espelho do que rodamos nos outros módulos.

Provider random

Com Provider = random, o node envia provider: "random" no corpo do POST /v1/charges. A Hubpay escolhe o PSP (round-robin entre os PSPs conectados na sua conta).

Se você informar Reference, a Idempotency-Key usa esse valor literal random na assinatura interna — retries com o mesmo reference permanecem idempotentes. Sem reference, cada execução gera uma nova chave (UUID).

Para forçar sempre o mesmo PSP em um pedido, escolha um provedor fixo na lista em vez de random.

Desenvolvimento

npm install
npm run build         # tsc + copia hubpay.svg para dist/
npm test              # Jest — 47+ casos cobrindo HMAC, idempotency, helpers
npm run dev           # tsc --watch

Os testes não exigem n8n rodando — exercitam só GenericFunctions.ts. Os nodes em si dependem de n8n-workflow apenas como peer dependency.

Eventos suportados

| Evento | Quando dispara | |---|---| | charge.pending | Cobrança criada, aguardando pagamento | | charge.paid | Cliente pagou e o PSP confirmou | | charge.expired | QR expirou sem pagamento | | charge.cancelled | Cancelada via API ou pelo PSP | | charge.failed | Falha no processamento | | charge.refunded | Estornada |

Limitações

• Só PIX, só BRL — limitação da API Hubpay.
• Não testado contra api.hubpay.dev real — Jest cobre helpers puros (HMAC, idempotency). Validar com webhooks reais em sandbox antes de produção.
• Logo — recriado em SVG a partir da imagem do site (quadrado verde arredondado com raio branco). Substitua nodes/HubPay/hubpay.svg se você obtiver o original com a marca registrada.

Licença

MIT.