Ingestão de eventos

A ingestão é a porta de entrada de fatos financeiros (uma assinatura criada, uma cobrança recorrente, um estorno, um cancelamento) vindos de provedores de pagamento para dentro do Repass. Cada fato é traduzido para um evento normalizado, único e agnóstico de gateway, e encaminhado para o processamento de Conversão e Comissão. Por isso, atribuição, deduplicação e cálculo de comissão são herdados integralmente desses fluxos: a ingestão não grava conversões nem comissões por conta própria. Existem duas superfícies de entrada:

POST /ingest/stripe/{organizationId}: webhook público do Stripe, autenticado pela assinatura HMAC do próprio Stripe (não pela sua API key).
POST /ingest/custom: endpoint server-to-server (S2S), autenticado pela sua API key, para enviar o evento normalizado diretamente quando você não usa um gateway suportado.

E uma superfície de configuração: GET / PUT /settings/stripe, para gravar e ler (mascarado) o segredo de assinatura do webhook do Stripe da sua conta.

A ingestão é a forma recomendada de registrar cobranças recorrentes. Para entender o que acontece depois (atribuição ao Afiliado, criação da Comissão e tratamento de fraude), veja Conversões e fraude.

O evento normalizado

Todo gateway é apenas um tradutor (payload do provedor → evento normalizado) mais uma verificação de assinatura. O Repass conhece um único contrato, uma união discriminada por kind:

`kind`	O que representa	Como referencia a Conversão
`conversion`	Nova relação cliente↔afiliado a atribuir (assinatura criada, compra avulsa).	Carrega os dados de matching (`clickId`, `visitorId`, `emailHash`, `fingerprint`, `couponCode`, `programId`).
`charge`	Cobrança de ciclo 2+ de uma Conversão já existente.	Por `conversionId` ou `customerId`.
`refund`	Estorno total/parcial ou chargeback.	Por `conversionId` ou `customerId`.
`cancellation`	Cancelamento de assinatura.	Por `conversionId` ou `customerId`.

Os eventos charge, refund e cancellation não trazem dados de atribuição: apontam para uma Conversão existente por conversionId (ULID com prefixo conv_) ou por customerId (o id do cliente no gateway). Pelo menos um dos dois é obrigatório.

Dinheiro sempre em centavos (inteiro), nunca em float. Apenas BRL é suportado: eventos em outra moeda são ignorados na tradução.

Deduplicação por `sourceEventId`

A idempotência da ingestão é de negócio e permanente, indexada pelo sourceEventId de cada evento. As rotas de ingestão não usam o header Idempotency-Key: você não precisa enviá-lo. Em vez disso, todo evento carrega um sourceEventId estável, e o processamento de Conversão/Comissão garante que o mesmo sourceEventId produza um único efeito. Isso significa que reentregas do gateway (o Stripe reenvia o mesmo webhook várias vezes, por exemplo) são absorvidas sem duplicar conversões ou comissões: o desfecho é simplesmente replayed, apontando para o efeito original.

O sourceEventId deve identificar o fato financeiro, não a entrega do webhook. No tradutor do Stripe ele é o id do objeto financeiro, a invoice (in_...), o refund (re_...) ou <sub.id>:deleted, justamente para que reentregas do mesmo fato sejam dedupadas e para que um refund referencie a cobrança original.

Desfechos da ingestão

A ingestão não tem máquina de estados própria; ela apenas encaminha o evento. Cada chamada produz exatamente um desfecho terminal (outcome), que descreve como o evento foi tratado:

processed

O evento gerou efeito novo: Conversão criada e atribuída, cobrança registrada com Comissão nova, refund/clawback aplicado, ou cancelamento que anulou comissões. Um cancelamento que não tinha nada a anular continua processed, com reason: "nothing_to_void" (idempotente).

replayed

O mesmo sourceEventId já havia sido processado; nenhum efeito novo. É a reentrega idempotente.

unmatched

Uma Conversão não foi atribuída a nenhum Afiliado (no_attribution), ou um charge/refund/cancellation por customerId não achou Conversão ativa (customer_not_attributed). Nada é persistido.

skipped

Uma regra de negócio impede o efeito de forma legítima: cliente com mais de uma Conversão ativa (ambiguous_customer), chargeback contra Conversão sem comissões (no_commissions), ou um motivo herdado da cobrança (no_rule: nenhuma regra de comissão aplicável; no_eligible_affiliate: nenhum afiliado elegível; recurrence_exhausted: recorrência da regra já esgotada).

ignored

O tradutor decidiu não mapear o evento (tipo não tratado, moeda diferente de BRL, cliente ausente). O reason carrega o motivo. Só ocorre no webhook: o /ingest/custom não aceita esse kind.

Webhook do Stripe

O webhook do Stripe é autenticado pela assinatura HMAC do próprio Stripe, não pela sua API key. A sua conta é identificada no path (organizationId), e a verificação usa o segredo (whsec_...) que você gravou em /settings/stripe.

Comportamento de status

O webhook responde 200 sempre que a assinatura é válida, mesmo para eventos não tratados, sem match ou rejeitados por regra de negócio. Isso é deliberado: um 4xx faria o Stripe reentregar o evento indefinidamente. O campo outcome no corpo da resposta diz o que realmente aconteceu.

HTTP	Quando
`200`	Assinatura válida. O corpo traz `received: true` e o `outcome` real (incluindo `ignored`, `unmatched`, `skipped`).
`200` (`outcome: "skipped"`)	Erro de negócio durante o processamento (ex.: cobrança contra Conversão já estornada). É reconhecido como `skipped`, com `reason` descrevendo o motivo.
`401`	Conta sem o webhook do Stripe configurado ou inexistente; header `Stripe-Signature` ausente; ou assinatura inválida.

Conta inexistente e conta sem configuração retornam o mesmo 401 que uma assinatura inválida: decisão de segurança para não revelar quais contas existem.

Exemplo de resposta:

{
  "received": true,
  "outcome": "processed",
  "reason": null,
  "conversionId": "conv_01J9Z6F8K2M3N4P5Q6R7S8T9V0",
  "commissionIds": ["comm_01J9Z6F8K2M3N4P5Q6R7S8T9W1"]
}

Eventos do Stripe suportados

O tradutor é determinístico: tudo que não casa com uma regra explícita vira ignored, e o webhook responde 200 para o Stripe parar de reentregar.

Tipo Stripe	Condição	Vira	Observação
`invoice.paid` / `invoice.payment_succeeded`	`billing_reason = subscription_create`	`conversion` (assinatura criada)	`amountCents = invoice.amount_paid`; cliente por `invoice.customer`.
`invoice.paid` / `invoice.payment_succeeded`	ciclo recorrente / update / threshold	`charge`	Cobrança de ciclo 2+ resolvida por `customerId`.
`checkout.session.completed`	`mode = payment`, BRL	`conversion` (compra avulsa)	Cliente por `customer`, senão e-mail, senão id da sessão.
`checkout.session.completed`	`mode = subscription`	`ignored`	A conversão canônica vem do `invoice.paid subscription_create`.
`charge.refunded`	tem refund e customer	`refund` (`chargeback: false`)	Usa o refund mais recente como delta; `sourceEventId = refund.id`.
`charge.dispute.created`	com `secretKey` (`sk_…`)	`refund` (`chargeback: true`)	Lookup do charge na API Stripe; sem `secretKey` → `ignored` (`dispute_requires_api_lookup`).
`customer.subscription.deleted`	tem customer	`cancellation`	`sourceEventId = <sub.id>:deleted`.
qualquer outro	n/a	`ignored`	`unhandled_event_type`.

A atribuição de uma assinatura vem da metadata do objeto Stripe. O tradutor procura repass_cid (clickId) e repass_pid (programId) na metadata da invoice, do line item e do subscription_details (incluindo o layout da API Stripe 2025+). O clickId só é aceito se prefixado clk_; o programId, se prefixado prog_.

Conectar o webhook não atribui afiliados sozinho. Seu checkout precisa propagar repass_cid (o clk_... capturado no tracking) — e, opcionalmente, repass_pid — na metadata da assinatura (subscription_data.metadata) ou da session (mode: payment). Sem isso, o desfecho é unmatched. Guia completo com snippets: Integrar Stripe.

Ingestão custom (S2S)

Quando você não usa um gateway suportado, envie o evento normalizado diretamente para POST /ingest/custom. Diferente do webhook, este endpoint é autenticado pela sua API key e propaga erros de negócio como 4xx normais (404/409) em vez de mascará-los como skipped. O body é a mesma união discriminada por kind, sem a variante ignored.

conversion
charge
refund
cancellation

curl https://api.userepass.com/ingest/custom \
  -H "Authorization: Bearer rstr_..." \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "conversion",
    "type": "subscription_created",
    "amountCents": 9990,
    "currency": "BRL",
    "sourceEventId": "billing_2026_06_13_abc",
    "customer": { "id": "cus_ext_42", "email": "[email protected]" },
    "emailHash": "a665a45920422f9d417e4867efdc4fb8a04a1f3fff1fa07e998e86f7f7a27ae3",
    "clickId": "clk_01J9Z6F8K2M3N4P5Q6R7S8T9V0",
    "programId": "prog_01J9Z6F8K2M3N4P5Q6R7S8T9V0"
  }'

curl https://api.userepass.com/ingest/custom \
  -H "Authorization: Bearer rstr_..." \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "charge",
    "customerId": "cus_ext_42",
    "amountCents": 9990,
    "currency": "BRL",
    "sourceEventId": "invoice_2026_07_13_abc",
    "occurredAt": "2026-07-13T00:00:00Z"
  }'

curl https://api.userepass.com/ingest/custom \
  -H "Authorization: Bearer rstr_..." \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "refund",
    "conversionId": "conv_01J9Z6F8K2M3N4P5Q6R7S8T9V0",
    "refundedAmountCents": 9990,
    "sourceEventId": "refund_2026_07_20_xyz",
    "chargeSourceEventId": "invoice_2026_07_13_abc",
    "chargeback": false
  }'

curl https://api.userepass.com/ingest/custom \
  -H "Authorization: Bearer rstr_..." \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "cancellation",
    "customerId": "cus_ext_42",
    "sourceEventId": "sub_ext_99:deleted"
  }'

Erros do /ingest/custom:

HTTP	code	Quando
`400`	`parameter_invalid`	`kind` desconhecido, `charge`/`refund`/`cancellation` sem `conversionId` nem `customerId`, ou valores fora de faixa.
`401`	`unauthorized`	Sem API key válida.
`404`	`not_found`	`conversionId` explícito informado, mas inexistente.
`409`	`conflict`	Conflito de negócio (ex.: cobrança nova contra Conversão já estornada).

Chargebacks via charge.dispute.created entram pelo webhook quando a secretKey (sk_…) está configurada. Sem ela, o evento é ignored (dispute_requires_api_lookup) e você pode registrar o chargeback pelo /ingest/custom com "chargeback": true. Veja Refund e clawback e Integrar Stripe.

Resolução de Conversão e casos de borda

Para charge, refund e cancellation, a Conversão é resolvida assim:

conversionId explícito

Busca por id. Se não existir, retorna 404: a referência enviada está errada.

customerId

Busca Conversões ativas do cliente: zero ⇒ unmatched (customer_not_attributed); exatamente uma ⇒ usa essa; mais de uma ⇒ skipped (ambiguous_customer). Nunca chuta.

Quando uma “nova assinatura” chega para um cliente que já tem Conversão ativa no mesmo Programa, a ingestão não cria Conversão nova: trata o evento como uma cobrança de ciclo subsequente da Conversão original.

Configuração do Stripe

O segredo de assinatura do webhook (whsec_...) é gravado por conta. Ele é usado apenas para a verificação HMAC dos webhooks recebidos do Stripe.

curl -X PUT https://api.userepass.com/settings/stripe \
  -H "Authorization: Bearer rstr_..." \
  -H "Content-Type: application/json" \
  -d '{ "webhookSecret": "whsec_AbC123..." }'

curl https://api.userepass.com/settings/stripe \
  -H "Authorization: Bearer rstr_..."

A resposta é sempre mascarada, nunca devolve o segredo completo:

{
  "configured": true,
  "webhookSecretLast4": "C123"
}

O webhookSecret deve começar com whsec_ e ter no máximo 255 caracteres, senão a gravação falha com 400. O segredo nunca é devolvido em claro nas respostas nem aparece no histórico de eventos, onde é registrado apenas de forma mascarada (whsec_***<last4>).

Suporte a outros gateways

O modelo do Repass é deliberadamente agnóstico de gateway: o contrato normalizado e o processamento de Conversão/Comissão são únicos, e cada provedor entra apenas como uma tradução do seu payload para o evento normalizado mais a verificação de assinatura do webhook. Na prática, isso significa que:

A atribuição, o cálculo de comissão, o clawback e o void de comissões funcionam da mesma forma, independentemente de qual gateway originou o fato financeiro.
Enquanto o seu gateway não tiver um webhook nativo no Repass, você pode integrá-lo hoje enviando os mesmos eventos normalizados (conversion / charge / refund / cancellation) pelo /ingest/custom. Use o id do fato financeiro do provedor como sourceEventId para herdar a deduplicação.

Próximos passos

Integrar Stripe

Metadata repass_cid, Connect vs manual e checklist de atribuição.

Conversões e fraude

O que acontece depois da ingestão: atribuição, criação da Conversão e filtros antifraude.

Comissões

Como uma cobrança vira Comissão, e como refund vira void ou clawback.

Conversões server-to-server

Guia prático de envio de eventos pelo /ingest/custom.

Refund e clawback

Registrar estornos e chargebacks de ponta a ponta.

Introdução

Convenções da API

Conceitos

Webhooks & Eventos

Guias

Ingestão de eventos

O evento normalizado

Deduplicação por `sourceEventId`

Desfechos da ingestão

Webhook do Stripe

Comportamento de status

Eventos do Stripe suportados

Ingestão custom (S2S)

Resolução de Conversão e casos de borda

Configuração do Stripe

Suporte a outros gateways

Próximos passos

Integrar Stripe

Conversões e fraude

Comissões

Conversões server-to-server

Refund e clawback

​O evento normalizado

​Deduplicação por sourceEventId

​Desfechos da ingestão

​Webhook do Stripe

​Comportamento de status

​Eventos do Stripe suportados

​Ingestão custom (S2S)

​Resolução de Conversão e casos de borda

​Configuração do Stripe

​Suporte a outros gateways

​Próximos passos

Integrar Stripe

Conversões e fraude

Comissões

Conversões server-to-server

Refund e clawback

O evento normalizado

Deduplicação por `sourceEventId`

Desfechos da ingestão

Webhook do Stripe

Comportamento de status

Eventos do Stripe suportados

Ingestão custom (S2S)

Resolução de Conversão e casos de borda

Configuração do Stripe

Suporte a outros gateways

Próximos passos