Integrações

Integração PerfectPay

Conecte sua conta PerfectPay ao Synchro Hub para receber vendas em tempo real e consolidar comissões (produtor, coprodutor, afiliados) num único dashboard.

Visão geral

Ao integrar a PerfectPay, o Synchro Hub passa a:

Receber webhooks (Postback) de vendas, reembolsos, chargebacks e mudanças de status em tempo real.
Separar automaticamente a taxa da PerfectPay das comissões dos participantes.
Identificar PIX, cartão (à vista, recorrente e upsell), boleto, PayPal e produtos gratuitos.

Tempo estimado: 10 minutos. O que você vai precisar:

Conta PerfectPay com perfil de Produtor.
Workspace já criado no Synchro Hub.

Pré-requisitos

Estar logado no Synchro Hub com um workspace selecionado.
Ter acesso ao painel da PerfectPay em app.perfectpay.com.br.

Passo 1 — Gerar o Personal Token na PerfectPay

Entre em app.perfectpay.com.br.
Acesse Ferramentas → Api.
Gere (ou copie, se já existir) o Personal Token.
Copie o token — você vai colá-lo no Passo 3.

Importante: o Personal Token dá acesso à sua conta PerfectPay via API. Não compartilhe e não publique em repositório.

Referência oficial: help.perfectpay.com.br/article/599-token-de-acesso.

Passo 2 — Conectar a plataforma no Synchro Hub

No Beacon, acesse Configurações → Integrações → Fontes de Venda.
Clique em + Adicionar Plataforma.
Selecione PerfectPay e clique em Confirmar.
O card da PerfectPay aparece com Ativa e Webhook não configurado.

Passo 3 — Salvar o Personal Token

No card da PerfectPay, clique em Atualizar credenciais.
Cole o Personal Token copiado no Passo 1.
Clique em Salvar.

O Synchro valida o token em tempo real fazendo uma chamada autenticada à API da PerfectPay. Se o token for inválido, você verá um erro — gere outro no painel Ferramentas > Api e tente de novo.

Passo 4 — Configurar o webhook (Postback) no painel PerfectPay

A PerfectPay não permite que o Synchro registre o webhook automaticamente. Você precisa cadastrá-lo manualmente.

No card da PerfectPay no Beacon, clique em Configurar Webhook. Copie a URL do Webhook e o Token exibidos. O formato da URL é:
```
https://api.synchrohub.com.br/v1/webhooks/ecommerce/perfect_pay/{seu-integration-id}
```
Em outra aba, abra app.perfectpay.com.br e vá em Ferramentas → Postback / Webhook.
Clique em + Adicionar Postback (ou equivalente).
Preencha:

Campo Valor
URL de destino A URL copiada do Beacon.
Token O token copiado do Beacon (Passo 4, item 1).
Produto Selecione o produto cujos eventos vão disparar.
Formato JSON (padrão).
Marque os eventos recomendados:
- Venda aprovada (approved)
- Venda autorizada (authorized)
- Venda concluída (completed)
- Pendente (pending) e Em revisão (in_review)
- Boleto pendente e Boleto expirado (expired)
- Recusada (rejected) e Cancelada (cancelled)
- Reembolsada (refunded)
- Chargeback (charged_back)
- Em mediação (in_mediation)
Salve.

Campo	Valor
URL de destino	A URL copiada do Beacon.
Token	O token copiado do Beacon (Passo 4, item 1).
Produto	Selecione o produto cujos eventos vão disparar.
Formato	JSON (padrão).

Importante: a PerfectPay envia um POST de teste assim que você salva. Se a credencial ainda não foi salva no Beacon (Passo 3), o teste pode falhar — salve a credencial e reenvie o teste pelo painel.

Passo 5 — Ativar o webhook no Synchro Hub

Volte para o modal Webhook PerfectPay no Synchro Hub.
Clique em Ativar Webhook.

O card da integração passa a exibir Webhook ativo.

Verificação

Gere uma venda de teste na PerfectPay (PIX é mais rápido — gera o QR Code e marque manualmente como pago no painel se houver ambiente de teste, ou use uma compra real de baixo valor).
Abra Vendas no menu lateral do Synchro Hub.
A venda deve aparecer em até 1 minuto após a confirmação.

Você verá no dashboard:

Valor da venda convertido corretamente (a PerfectPay envia em reais decimais — 423.45 → R$ 423,45).
Comissão do produtor e a taxa da PerfectPay separadas — a taxa aparece como platformFee, não como comissão.
Método de pagamento identificado (PIX, cartão, boleto, etc.).

Limitações conhecidas

Webhook não-automático: a PerfectPay não expõe API pública para registrar webhook — por isso o Passo 4 é manual.
Sem refresh de token: o Personal Token é long-lived. Se for revogado/regenerado no painel da PerfectPay, você precisa atualizar a credencial no Beacon manualmente.
Assinatura recorrente: a PerfectPay envia vendas recorrentes via os eventos normais (credit_card_recurrent). Eventos específicos de assinatura (renovação, cancelamento) ainda dependem de confirmação com payloads reais — abra ticket no suporte do Synchro se notar inconsistência.
Validação HMAC: a PerfectPay autentica o webhook apenas via campo token no body (não há header HMAC documentado). O Synchro compara com timing-safe — basta manter o token sincronizado entre painéis.

Solução de problemas

Sintoma	O que fazer
”Personal Token PerfectPay inválido”	Gere um novo token em Ferramentas → Api no painel da PerfectPay e salve novamente no Beacon.
POST de teste falha com 401	A credencial ainda não foi salva no Beacon. Conclua o Passo 3 e reenvie o teste pelo painel PerfectPay.
Nenhuma venda chega após horas	Confira no painel da PerfectPay se a URL está sem espaços, com `/perfect_pay/` (com underscore) e com seu integration ID no final.
Token inválido reportado no Synchro	O token cadastrado no painel da PerfectPay precisa ser idêntico ao mostrado no Beacon. Copie novamente direto do Beacon.
Valor da venda aparece em centavos certo?	A PerfectPay envia em reais decimais (`423.45`). O Synchro converte para centavos internamente. Se ver valor estranho, abra ticket.
Comissão do produtor incluindo a taxa	A PerfectPay envia a taxa como uma entrada de `commission` com tipo `platform`. O Synchro separa automaticamente — se isso falhar, abra ticket.

Perguntas frequentes

Tenho vários produtos na mesma conta PerfectPay. Preciso configurar um webhook para cada? Sim. No painel da PerfectPay, o postback é por produto — repita o Passo 4 para cada produto, usando a mesma URL e o mesmo token do Beacon.

Sou afiliado de um produto, não produtor. Funciona? Sim. Se você está cadastrado como afiliado e a PerfectPay envia o webhook para o seu painel, o Synchro identifica sua comissão automaticamente. Use o Personal Token da sua conta de afiliado.

Posso reprocessar vendas antigas? A PerfectPay permite reenvio manual de postbacks pelo painel. Vendas anteriores à integração não são importadas automaticamente.

Como desconecto a integração? No card da PerfectPay, clique em Remover. Os dados também serão apagados do Synchro Hub. Remova ou desative o postback no painel da PerfectPay para evitar tentativas de entrega sem destino.