> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chargefy.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Escolher uma integração
> Decida entre link de pagamento, checkout hospedado, payment intent, assinatura e organizações conectadas antes de escolher endpoints.
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
| Seu objetivo | Comece por | Por quê |
| ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| Vender sem desenvolver um checkout | [`payment_link`](/payments/create-payment-link) | Uma URL reutilizável, criada uma vez e compartilhada em mensagens, campanhas ou QR codes. |
| Cobrar um pedido específico com uma página pronta | [`checkout.session`](/payments/create-checkout-page) | Uma sessão temporária por compra, com URL hospedada e retorno para o seu site. |
| Desenhar toda a experiência de pagamento | [`payment_intent`](/payments/payment-intents) + [Chargefy.js](/api/chargefy-js) | Seu frontend controla a interface; o browser tokeniza o cartão e o backend controla a cobrança. |
| Cobrar receita recorrente | [`subscription`](/payments/subscriptions) + [`invoice`](/payments/invoices) | A assinatura controla períodos, trial, mudanças e cancelamento; cada ciclo gera uma invoice. |
| Processar pagamentos para sellers ou clientes B2B | [Organizações conectadas](/platforms/connected-organizations) + [`activation_session`](/platforms/activate-with-hosted-session) | Cada seller tem cadastro, ativação e contexto financeiro próprios, operados pela plataforma. |
Essas decisões podem se combinar. Uma plataforma escolhe primeiro a
organização conectada e, dentro dela, ainda decide entre payment link,
checkout session, payment intent ou assinatura. Uma assinatura também pode
começar em um link ou checkout hospedado.
## 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:
| Prioridade | Condição | Integração recomendada |
| ---------- | ---------------------------------------------------------------------------- | ---------------------------- |
| 1 | A cobrança se repete em ciclos | Subscriptions + Invoices |
| 2 | A cobrança não se repete, mas a mesma oferta será compartilhada muitas vezes | Payment Link |
| 3 | A cobrança é individual e você quer uma página pronta | Checkout Session hospedada |
| 4 | A cobrança é individual e você quer controlar a página | Payment Intent + Chargefy.js |
### 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"`.
Somente integrações Chargefy for Platforms acessam `/v1/organizations`. Nessas
rotas, a API key de plataforma autentica a chamada e a coleção ou o ID da URL
define a organização conectada. O header `Organization` entra depois, quando a
plataforma opera recursos pertencentes à conta conectada.
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
Complete o fluxo mais curto em test mode.
Modele uma sessão para cada pedido.
Combine Chargefy.js, payment methods e payment intents.
Implemente trial, renovação e recuperação de pagamento.