Por que integrações de payout controladas por Webhook são importantes
Comerciantes que pagam comissões de parceiros automaticamente reduzem o esforço manual, evitam erros e aceleram os fechamentos. Affilentra fornece exportações de payout e webhooks como pontos de transferência. Na prática, é necessário uma pequena middleware de integração que receba os dados de exportação, os encaminhe aos provedores externos de payout (PayPal Payouts, Wise, Stripe Connect), reporte alterações de estado de volta e gere comprovantes contabilísticos. Este artigo mostra com precisão quais configurações e passos são necessários.
Visão geral: arquitetura e responsabilidades
- Affilentra: Gera exportações de payout e dispara eventos Webhook com os lotes de pagamento.
- Middleware (o seu sistema ou um pequeno serviço conector): Valida o Webhook, mapeia campos, chama as APIs dos provedores, processa callbacks dos provedores, cria comprovativos e grava o estado de volta no Affilentra.
- Provedores de payout (PayPal, Wise, Stripe Connect): Executam os pagamentos e fornecem referências de pagamento / Webhooks para o estado final.
Requisitos antes da integração
- Instalação do Affilentra (self‑hosted) com sistema de Webhook e função de exportação ativados. SSL para o endpoint do Webhook.
- Conta e credenciais API nos provedores de destino (acesso Sandbox para testes).
- Middleware com endpoint HTTPS, armazenamento persistente (BD) e capacidade de gerar ficheiros/PDFs e anexá‑los ao Affilentra.
Passo 1: definir corretamente a exportação de payout no Affilentra
Configure no Affilentra uma exportação de payout que forneça todos os campos necessários. Formato recomendado: JSON ou CSV com UTF‑8. Campos importantes:
- payout_id (ID interna única)
- partner_id / partner_identifier
- payee_type (email | iban | account_id)
- payee_address (E‑Mail, IBAN, ID de conta bancária)
- amount (decimal, p. ex. 123.45)
- currency (código ISO, p. ex. EUR)
- gross / net / fee (caso queiram discriminar separadamente)
- description / reference
Importante: Defina um campo para uma referência externa (provider_reference) e um campo de estado (pending / sent / failed / reconciled) — a middleware preencherá estes.
Passo 2: configurar o Webhook no Affilentra
- Crie um endpoint de Webhook no Affilentra que envie um evento ao executar uma exportação de payout (p. ex. payout_exported).
- Proteja o evento de Webhook com uma assinatura HMAC (Shared Secret). A middleware verifica esta assinatura contra os payloads recebidos.
- Configure tentativas de repetição no Affilentra (p. ex. 3 tentativas com backoff exponencial) e documente mensagens de erro em logs.
Passo 3: Middleware – fluxo e pontos de implementação
A middleware é o elemento central. Tarefas principais:
- Validação de webhook (assinatura, esquema, verificação de duplicados).
- Mapeamento: converter o exporte do Affilentra para o payload do provedor.
- Chamada ao provedor: criar lotes, definir idempotency‑keys, tratar erros de API.
- Gestão de estado: processar as respostas do provedor e reportar o estado de volta ao Affilentra.
- Geração de comprovativos: criar PDF/CSV/JSON, anexar ao pagamento e encaminhar à contabilidade.
Exemplos de mapeamento (orientados à prática)
- PayPal: mapear payee_address → receiver_email, amount + currency → amount; utilize sender_batch_id = payout_id.
- Wise: se houver IBAN, crie o Recipient, gere a Quote (no caso de conversão de moeda) e o Transfer com reference = payout_id.
- Stripe Connect: para contas conectadas, utilize o parâmetro destination ou envie pagamentos em nome da Conta Conectada; se necessário, execute primeiro um Transfer.
Especificidades dos provedores & dicas
- PayPal Payouts: utilize payouts em lote para eficiência; defina sender_batch_id para idempotência; armazene payout_item_id e batch_status para reconciliações posteriores.
- Wise: crie o destinatário (recipient) uma vez e reutilize a recipient_id; tenha em conta o possível passo de Quote em caso de conversão de moeda.
- Stripe Connect: verifique se o seu fluxo deve usar Transfers para contas conectadas ou contas bancárias externas; utilize Idempotency‑Keys e liste balance_transfers.
Retorno de status ao Affilentra e reconciliação
Assim assegura-se processos de contabilização confiáveis:
- Imediatamente após a resposta do provedor: atualize os payouts no Affilentra com provider_reference, status = sent (ou failed) e informações de taxas.
- Implemente um listener para webhooks do provedor (por exemplo, webhooks do PayPal/Stripe). Ao receber um estado final (SUCESSO/FALHOU/CONCLUÍDO) a middleware atualiza o estado no Affilentra.
- Realize reconciliações regulares: confronto do exporte do Affilentra, relatórios do provedor e extratos bancários; registe e alerte sobre diferenças.
Geração automatizada de comprovativos contábeis
Comprovativos automatizados são pré‑requisito para contabilidade auditável. Procedimento:
- Gere por cada pagamento um comprovativo em PDF com os seguintes dados: payout_id, partner_id, nome/endereço do parceiro, bruto/líquido/taxas, moeda, referência de pagamento do provedor, timestamp.
- Anexe adicionalmente o recibo do provedor (download via API do PayPal/Stripe/Wise) como anexo ao payout no Affilentra ou armazene‑o no sistema de contabilidade.
- Formatos de exporte: CSV para importações em massa, PDF para comprovativos individuais, opcionalmente XML/compatível com DATEV conforme a contabilidade destino.
Tratamento de erros, idempotência e operação
- Idempotência: Utilize chaves únicas no provedor (p. ex. payout_id como sender_batch_id) para evitar pagamentos duplicados.
- Retentativas: Implemente estratégias de backoff para erros temporários e uma fila de revisão manual para erros persistentes.
- Monitorização e Alertas: Registe payloads de webhook, respostas do provedor e diffs de reconciliação; configure alertas em caso de divergências.
- Testes em Sandbox: Execute integrações no modo Sandbox dos três provedores antes de iniciar operações em produção.
Caso prático: Fluxo de uma liquidação (Descrição breve)
1) A Affilentra gera um Payout‑Export e dispara payout_exported para a sua middleware. 2) A middleware valida, mapeia campos e chama a API do provedor. 3) O provedor confirma com uma referência → a middleware atualiza a Affilentra com status=sent e provider_reference. 4) O provedor envia o webhook final (p. ex. completed) → a middleware define status=reconciled, aplica as taxas e gera um comprovativo em PDF que é anexado à Affilentra.
Conclusão e próximo passo
A integração técnica dos payouts da Affilentra com PayPal, Wise e Stripe Connect através de webhooks é um processo claramente estruturado: exporte limpo, transferência segura do webhook, middleware com mapeamento para o provedor, retorno de estado fiável e geração automática de comprovativos. Assim, os comerciantes mantêm o controlo sobre condições e rastreabilidade, enquanto os parceiros recebem históricos de pagamentos transparentes.
Atue agora: Escolha o ponto de entrada: discuta os seus requisitos e ambiente de testes com a equipa Affilentra e inicie a integração. Mais informações e contato: https://affilentra.de
Próximo passo
Experimentar a Affilentra
Plataforma unificada que reúne de forma transparente a disponibilização de produtos, tracking, validação de conversões, cálculo de comissões e pagamento com papéis claramente separados; opção de instalação self-hosted com licença perpétua sem participação na faturação; os comerciantes mantêm controlo sobre produtos, condições e materiais promocionais; os parceiros recebem links de tracking pessoais e um histórico de pagamentos verificável.