Escolher uma integração

A melhor integração começa pela experiência que você quer entregar — não pelo nome de um endpoint. A Chargefy tem caminhos diferentes para vender uma oferta repetível, cobrar um pedido específico, controlar toda a interface, operar receita recorrente ou processar pagamentos para outras empresas.

​

Resposta curta

​

Decida em duas camadas

​

1. Quem está vendendo?

• Sua própria empresa: use uma API key de organização; ela já fixa o contexto da conta.
• Outra empresa dentro da sua plataforma: crie uma organização conectada e guarde o org_*. Use esse ID na URL para consultar ou atualizar a própria organização e no header Organization para operar os recursos dela.

Não misture sellers diferentes na mesma organização. Produtos, clientes, pagamentos, recebíveis e eventos precisam nascer no contexto de quem efetivamente vende.

​

2. Como a cobrança deve acontecer?

Avalie as linhas de cima para baixo e pare na primeira condição que descreve a sua cobrança:

​

Payment link: uma oferta reutilizável

Escolha um payment link quando produto, preço e regras podem ser reaproveitados por vários compradores. Cada acesso ao link materializa uma checkout session própria, portanto o link é o molde da venda — não a compra em si. É o caminho mais curto para bio, WhatsApp, e-mail, QR code, botão de compra ou campanha. Se cada pedido tem valor, itens, estoque ou metadata próprios, crie uma checkout session no backend.

​

Checkout session: uma compra específica

Escolha uma checkout session quando o seu sistema já conhece o pedido e quer delegar a etapa de pagamento. Seu backend cria a sessão, recebe uma url e redireciona o comprador para a página hospedada. Use a session para carrinho, reserva, proposta ou upgrade específico. Ela não é um widget incorporável: para manter toda a interface na sua aplicação, use o caminho customizado.

​

Payment intent + Chargefy.js: controle total

Escolha um payment intent quando o seu produto precisa controlar campos, layout, validações e sequência da experiência. Para cartão, carregue Chargefy.js no navegador pela URL oficial, gere um token de uso único e envie apenas esse token ao seu backend. Esse caminho dá flexibilidade, mas transfere para sua aplicação mais responsabilidades: UI, mensagens de erro, estados pendentes, retry, acessibilidade e confirmação por webhook.

​

Subscriptions + invoices: recorrência como domínio

Escolha subscriptions quando existe uma relação contínua com período, trial, renovação, troca de plano, proporcionalidade ou cancelamento. Não simule recorrência agendando payment intents manualmente: isso perde o estado da assinatura e a invoice de cada ciclo. A interface de entrada é uma decisão separada. Você pode vender um preço recorrente por payment link, checkout session ou um fluxo customizado; depois da criação, a subscription e suas invoices passam a controlar o ciclo.

​

Connected organizations: a camada de plataforma

Escolha organizações conectadas quando uma plataforma facilita pagamentos para sellers, franquias, lojas ou clientes B2B. Crie uma organização por participante, abra uma activation session e só processe cobranças reais depois de activation_status: "active". Em webhooks de plataforma, o campo top-level organization identifica quem originou o evento.

​

Evite estes atalhos

• Não use payment link como identificador de pedido; correlacione a checkout session criada em cada acesso.
• Não crie uma session nova para cada visitante se a mesma oferta pública e reutilizável resolve o caso.
• Não exponha API keys no browser ou aplicativo mobile. Em checkout customizado, PAN e CVC ficam no browser e são tokenizados com Chargefy.js; nunca os envie ao seu backend.
• Não trate success_url, redirect ou callback do frontend como prova de pagamento.
• Não reconstrua renovação, trial e dunning com tarefas próprias quando o domínio é uma assinatura.
• Não use uma organização única para processar vendas de sellers independentes.

​

Próximos passos