# RevenueCat

Importe compras, renovações e reembolsos do RevenueCat pro Paywallo com um webhook — sem precisar trocar de provider de pagamento.

## Configurar o webhook

> **Pré-requisito:** Ative a integração no dashboard (Configurações → Integrações → RevenueCat) para gerar a URL do webhook e o secret.

1. No dashboard do Paywallo, acesse Configurações > Integrações > RevenueCat, clique em Ativar. Na seção Configuração do Webhook ficam os dois valores que você vai usar: Webhook URL e Authorization (header). Copie cada um pelo botão de copiar ao lado, e não selecionando o texto à mão, para não levar espaço junto.

2. No dashboard do RevenueCat, abra o projeto, clique em Integrations no menu lateral > Webhooks > Add new configuration e cole a URL no formato https://paywallo.com.br/api/webhook/revenuecat/{sua-chave-app}.

3. Ainda na tela de webhook do RevenueCat, preencha o campo de autorização:

| Campo (RevenueCat) | Valor |
| --- | --- |
| `Authorization header value` | {seu-secret} |

Substitua `{seu-secret}` pelo valor copiado do Paywallo, sem espaços extras. O prefixo `Bearer` é opcional: os dois formatos são aceitos. Requisições sem o header correto são rejeitadas com `401`. A assinatura HMAC do RevenueCat ainda não é suportada; o Paywallo valida só esse header.

4. Role até o fim da página e clique no botão de salvar, que fica abaixo de Events filter. Depois recarregue a página e confira se o campo continua preenchido. Se ele mostrar só o texto cinza e.g. Bearer…, o valor não foi salvo: é o exemplo do RevenueCat, e sem valor salvo toda entrega volta com 401. Com o campo salvo, clique em Send test event: a entrega precisa aparecer com status 200 no histórico do webhook.

> **Como confirmar que chegou:** O botão Testar Conexão do Paywallo confirma só que a integração está ativa e o secret está salvo; ele não recebe nenhum evento. A prova é o histórico de entregas do webhook no RevenueCat: 200 quer dizer que chegou. Se vier 401, a resposta lista os headers que chegaram. Sem Authorization na lista, o RevenueCat não está mandando o header: confira se o campo foi salvo na mesma configuração de webhook que está entregando. Depois de corrigir, reenvie pelo histórico as entregas que falharam, porque o RevenueCat desiste depois de 5 tentativas (cerca de 2h30).

## Eventos obrigatórios

Marque todos esses eventos no RevenueCat ao configurar o webhook. Cada um alimenta uma categoria diferente (compras, renovações, reembolsos ou ciclo de vida), listada em detalhe logo abaixo. Faltar um não trava os outros: só a categoria dele para de atualizar no Paywallo.

 `INITIAL_PURCHASE`

 `RENEWAL`

 `NON_RENEWING_PURCHASE`

 `CANCELLATION`

 `UNCANCELLATION`

 `EXPIRATION`

 `BILLING_ISSUE`

 `PRODUCT_CHANGE`

 `REFUND_REVERSED`

## O que é importado

Cada categoria de evento é processada de forma diferente pelo Paywallo:

Compras `INITIAL_PURCHASE · NON_RENEWING_PURCHASE`

Cria uma transação no Paywallo e dispara CAPI para as plataformas de anúncio conectadas (Meta e TikTok).

Renovações `RENEWAL`

Registra a renovação da assinatura como uma nova transação.

Reembolsos `CANCELLATION (com cancel_reason) · REFUND_REVERSED`

Detecta cancelamentos por reembolso e os marca na transação original. Reembolso revertido vira um evento $refund_reversed.

Ciclo de vida `CANCELLATION · EXPIRATION · BILLING_ISSUE · PRODUCT_CHANGE · UNCANCELLATION`

Gera eventos de lifecycle ($subscription_cancelled, $subscription_expired, etc.) para analytics.

## Use o mesmo ID nos dois SDKs

> **Causa mais comum de compra virar “Direto”:** O webhook liga a compra ao usuário pelo app_user_id que o RevenueCat manda (e, quando não bate, pelos aliases do assinante). Se a compra acontece com o RevenueCat ainda anônimo (um id do tipo $RCAnonymousID) e o Paywallo nunca recebeu esse mesmo id via identify, não tem o que casar — a venda aparece como Direto no painel, mesmo vindo de um clique de anúncio, e o Meta recebe a compra sem saber que veio do anúncio (a campanha mostra 0).

1. Antes de mostrar o paywall (ou de processar a compra), chame Purchases.logIn(userId) do RevenueCat e Paywallo.identify({ userId }) — com o mesmo userId nos dois SDKs.

```typescript
import Purchases from "react-native-purchases";
import Paywallo from "@virex-tech/paywallo-sdk";

// Chame os dois ANTES da compra, com o MESMO userId
async function onLoginOrCheckout(userId: string) {
  await Purchases.logIn(userId);
  await Paywallo.identify({ userId });
}
```

> **Fluxo “paga primeiro, cadastra depois”:** Se o app deixa comprar antes do cadastro (onboarding → paywall → cadastro), o RevenueCat ainda está com um id anônimo na hora da compra. Antes de mostrar o paywall, chame o identify do Paywallo com o id que o RevenueCat já está usando (código abaixo). Depois do cadastro, faça o logIn e o identify com o id da conta normalmente: o Paywallo segue no mesmo usuário. Sem esse identify antes do paywall, toda compra feita antes do cadastro vira Direto.

```typescript
// Ainda sem cadastro? Antes do paywall, passe ao Paywallo
// o id que o RevenueCat já está usando (o anônimo).
await Paywallo.identify({ userId: await Purchases.getAppUserID() });

// Depois do cadastro, siga normal com o id da conta.
await Purchases.logIn(accountId);
await Paywallo.identify({ userId: accountId });
```

**Como verificar:** se uma compra que veio de um clique de anúncio aparece como **Direto** em Transações, o motivo mais comum é esse — o id usado no `Purchases.logIn` e no `Paywallo.identify` não era o mesmo no momento da compra.