Pagamentos · modules/billing
Adapter pronto para produçãoPolar,
de ponta a ponta.
O Polar é o mais completo dos três adapters de billing: roda sobre @polar-sh/sdk com checkout, um customer portal hospedado, verificação de webhooks assinados e sync do catálogo de planos, tudo implementado contra o mesmo port IPaymentProvider.
Checkout e webhooks, implementados
Uma única chamada a checkouts.create cuida tanto de produtos de pagamento único quanto de assinatura — o Polar lê a cadência a partir do preço do produto, então o argumento mode é informativo. Os webhooks que chegam são verificados com o helper do SDK (spec Standard Webhooks); uma assinatura inválida mapeia para um ValidationError, então a camada HTTP retorna 400.
1 const checkout = await this.client.checkouts.create({
2 products: [productId],
3 externalCustomerId: input.customer.internalId,
4 successUrl: input.successUrl,
5 });
6
7 // Standard-Webhooks signature verification via the SDK:
8 payload = validateEvent(req.rawBody, req.headers, this.cfg.webhookSecret);
Tudo conectado
Mapeamento de customer lazy
externalCustomerId indexa tudo pelo seu próprio id de usuário/org; o Polar cria seu customer de forma lazy no primeiro checkout — sem passo de pré-provisionamento.
Portal hospedado
createCustomerPortalLink chama customerSessions.create e retorna uma URL de portal hospedado — sem UI de billing para construir.
Mapeamento de eventos
parseWebhook mapeia subscription.created/updated/active/canceled/revoked e order.paid no BillingEvent normalizado.
Sync de planos
listPlans pagina products.list({ isArchived: false }) e lê metadata.features / metadata.highlight para o DTO Plan.
Isolamento do sandbox
POLAR_SERVER (sandbox | production) escolhe o host da API. O padrão é sandbox no schema de env, então um clone novo nunca bate em live por acidente.
O mesmo port que o resto
O Polar retorna os mesmos tipos Result que o Stripe e o MercadoPago, então mudar para ele é uma mudança de um único arquivo.
Referência de configuração
Variáveis de ambiente
PAYMENT_PROVIDERobrigatóriaSet to polar
POLAR_ACCESS_TOKENobrigatóriaPOLAR_WEBHOOK_SECRETobrigatóriaPOLAR_SERVERopcionalsandbox | production — env default: sandbox
Onde ele vive
apps/server/src/modules/billing/infrastructure/providers/polar-payment-provider.tsapps/server/src/modules/billing/infrastructure/providers/index.ts
Publique billing como merchant of record hoje.
O Polar está totalmente conectado — checkout, portal, webhooks e sync de planos — atrás do mesmo contrato que o Stripe e o MercadoPago.