Nó PagBank

O nó de workflow PagBank cria um pedido de pagamento usando a API de Pedidos do PagBank (PagSeguro). Use-o para gerar links de checkout para cartão de crédito, PIX e outros métodos habilitados na sua conta PagBank.

ID do nó no editor: pagbank_checkout
Endpoint da API: POST https://api.pagseguro.com/orders

O que faz

• Cria um pedido com itens de linha, dados do cliente e URLs de notificação opcionais
• Retorna o id do pedido, status e links (incluindo URLs de checkout/pagamento)
• Autentica com um Bearer token do PagBank

Pré-requisitos

1. Uma conta de desenvolvedor PagBank / PagSeguro
2. Connect token ou token de API com permissão para criar pedidos
3. Chave de integração pagbank_token em Configurações → Chaves de API

Como configurar

Etapa 1 — Obter token da API

1. Acesse o portal de desenvolvedor PagBank → Tokens ou Connect
2. Gere ou copie um token com permissão de escrita em Orders
3. No WhatsWave Configurações → Chaves de API, adicione:
   • Nome: pagbank_token
   • Valor: seu Bearer token

Etapa 2 — Adicionar o nó

1. Abra Automações
2. Arraste PagBank de Payments para o canvas

Etapa 3 — Configurar os campos

Exemplo de items:

[
  {
    "name": "Premium plan — {{contact.name}}",
    "quantity": 1,
    "unit_amount": 9900
  }
]

Exemplo de customer:

{
  "name": "{{contact.name}}",
  "email": "{{contact.email}}",
  "tax_id": "{{variables.customer_cpf}}"
}

Exemplo de notification URLs:

["https://your-webhook-endpoint.whatswave.com.br/..."]

Use a URL do gatilho Webhook do WhatsWave para receber notificações do PagBank em um workflow de confirmação separado.

Etapa 4 — Extrair e enviar o link de checkout

A saída links contém URLs de pagamento. Inspecione a saída da execução ou use JavaScript para encontrar o link com relação PAY ou tipo checkout.

Exemplo de mensagem (após extrair a URL para uma variável):

Complete your PagBank payment: {{variables.checkout_url}}

Etapa 5 — Testar no sandbox

O PagBank fornece credenciais de sandbox. Use token de sandbox e contas de comprador de teste antes da produção.

Saídas do nó

O corpo completo da resposta fica disponível nos detalhes da execução para dados aninhados de cobrança e QR code.

Dicas e boas práticas

• Valores em centavos — R$ 99,00 = 9900 em unit_amount
• Use um reference_id único por pedido para evitar duplicatas e facilitar conciliação
• Registre notification_urls para confirmação confiável de pagamento em vez de polling
• Inclua tax_id válido para clientes brasileiros quando exigido pela sua configuração PagBank
• Combine com nó Condition para tratar pagamentos parciais ou pedidos expirados
• Mantenha o token com o escopo mínimo de permissões necessário

Exemplos de casos de uso

Checkout de pedido de e-commerce

1. Webhook da loja com itens do carrinho e cliente
2. PagBank — itens do payload do pedido, referência = ID do pedido
3. Variable — extrair link PAY de links
4. Enviar WhatsApp com URL de checkout

Primeiro pagamento de assinatura

1. Gatilho manual com preço do plano
2. PagBank — item único, cliente do contato
3. Send message com link de pagamento
4. Workflow de webhook atualiza o CRM em PAID

FAQ

Por que unit_amount é rejeitado?
Deve ser inteiro em centavos. Não use reais decimais (use 9900, não 99.00).

Onde está a URL de checkout?
Dentro do array links na resposta da API. Faça o parse em um nó JavaScript se necessário.

Posso dividir o pagamento entre métodos?
A escolha do método de pagamento costuma ser feita na página de checkout do PagBank conforme a configuração da sua conta.

401 Unauthorized?
Token expirado ou chave de integração pagbank_token ausente.

Referência da API

Relacionados

• Visão geral de pagamentos
• Webhooks recebidos
• Nós de e-commerce