Cobrança de SaaS com um merchant of record: planos, testes, cobrança por uso e webhooks
A Skalp pode cobrar o seu SaaS como merchant of record. O seu app abre um checkout de assinatura, a Skalp recebe o pagamento, soma o IVA do país do cliente e emite cada fatura, e webhooks assinados mantêm o seu banco de dados em dia. O uso acima do plano vai para o mesmo cartão.
Planos
Cada plano é um produto cobrado por semana, mês ou ano, com teste opcional de até 14 dias. Os preços são líquidos e na moeda da sua loja. Você também pode dar a um plano um preço redondo em até três outras moedas para clientes na Polônia, na zona do euro, nos EUA e no Brasil.
Abrir o checkout
client := skalp.New(skalp.Options{})
session, err := client.CreateSubscriptionCheckout(ctx, skalp.CreateSubscriptionCheckoutParams{
ProductSlug: "pro-monthly",
ExternalRef: orgID,
ReturnURL: "https://app.example.com/billing?checkout=success",
})
if err != nil {
return err
}
http.Redirect(w, r, session.URL, http.StatusSeeOther)
Em Node, a mesma chamada é skalp.subscriptions.createCheckout(...). O cliente paga na página da Skalp, então o seu app nunca mostra um formulário de cartão. Uma empresa da UE pode informar ali o número de IVA e compra com autoliquidação. ExternalRef volta em todo evento da assinatura, o que dispensa guardar ids da Skalp antes do primeiro pagamento.
Webhooks para o ciclo de vida inteiro
| Evento | Quando chega |
|---|
subscription.created | A assinatura começou. |
subscription.renewed | Um período foi pago. Traz o id da fatura, o valor e a nova data de fim. |
subscription.past_due | Uma renovação falhou. Traz o número de tentativas e a próxima. |
subscription.updated | Algo mudou, por exemplo o plano ou um cancelamento marcado para o fim do período. |
subscription.canceled | O plano terminou. Traz cancelReason. |
subscription.refunded, subscription.disputed | Um pagamento foi reembolsado, ou o banco do cliente abriu uma disputa. |
Cada requisição traz uma assinatura HMAC-SHA256 no cabeçalho Skalp-Signature. skalp.webhooks.constructEvent em Node e client.ConstructEvent em Go conferem essa assinatura e recusam entregas com mais de cinco minutos.
Troca de plano e cancelamento
subscriptions.changePlan passa um cliente para outro plano e calcula a diferença de forma proporcional. subscriptions.cancel encerra o plano no fim do período pago, então o cliente mantém o acesso até lá.
Cobranças por uso
const charge = await skalp.subscriptions.createUsageCharge(subscription.id, {
amount: 12.34,
currency: 'EUR',
description: 'Seats over the plan, September 2026',
idempotencyKey: `seats:${orgId}:2026-09`,
periodStart: new Date('2026-09-01T00:00:00Z'),
periodEnd: new Date('2026-10-01T00:00:00Z'),
})
if (charge.status === 'open') await sendPaymentLink(charge.hostedUrl)
As cobranças por uso são feitas na moeda da sua loja, no cartão salvo. O mesmo idempotencyKey sempre devolve a mesma cobrança, então você pode tentar de novo depois de um timeout ou de um 5xx sem cobrar duas vezes. Cada assinatura tem um teto diário de cobranças por uso, que o suporte da Skalp pode aumentar.
Pagamentos que falham
Quando uma renovação falha, o cliente recebe uma fatura em aberto que pode pagar com qualquer cartão, e esse cartão passa a ser usado nas próximas renovações. Você recebe subscription.past_due e pode mostrar um aviso no seu app até chegar subscription.renewed.
Faturas, cupons e impostos
A Skalp emite uma fatura em PDF para cada pagamento com o IVA do país do cliente, e subscriptions.listInvoices devolve as faturas para a sua página de cobrança. Os cupons de um plano podem valer para o primeiro pagamento, para um número de meses ou para a assinatura inteira.
Perguntas frequentes
Em nome de quem sai a fatura?
Da Skalp. A Skalp é a merchant of record, então ela vende o plano ao seu cliente e repassa a sua parte.
Posso manter a minha própria página de preços?
Sim. A sua página de preços chama a API e manda o cliente para o checkout que volta.
O cliente precisa de uma conta na Skalp?
Não. Clientes que chegam pela API gerenciam a assinatura com um código enviado por e-mail.
Quanto custa?
10% de cada pagamento, ou 7% quando as suas vendas dos últimos 30 dias passam de US$ 20.000, com o processamento incluído e sem mensalidade.