Checkout e assinaturas

Checkout hospedado oferece uma página de pagamento do Stripe na conta conectada da organização. Produtos e preços devem existir nessa mesma conta.

Prepare o catálogoCopiar link da seção

Configure o client e o organizationId conforme a primeira integração. Crie um produto com client.products.create e depois um preço com client.prices.create. Cada mutação exige sua própria chave de idempotência.

O guia Clientes, produtos e preços mostra essa preparação passo a passo. Sua API key precisa de products:write para criar o catálogo e payments:write para abrir o checkout.

Exemplo de preço recorrente:

{
  "product": "prod_EXEMPLO",
  "currency": "brl",
  "unit_amount": 4990,
  "recurring": { "interval": "month" }
}

4990 representa R$49,90. Para pagamento único, crie o preço sem recurring.

Abra uma sessãoCopiar link da seção

Persista uma chave para esta operação antes da primeira tentativa. Reutilize a mesma chave e os mesmos parâmetros se precisar tentar novamente:

const session = await client.checkout.create({
  organizationId,
  "idempotency-key": "checkout-pedido-001",
  mode: "subscription",
  line_items: [{ price: "price_EXEMPLO", quantity: 1 }],
});

if (typeof session.url !== "string") {
  throw new Error("A sessão não retornou uma URL de checkout");
}

// Envie session.url ao frontend para encaminhar o cliente ao pagamento.

Use mode: "payment" para pagamento único. Uma assinatura exige preço recorrente, payments:write e subscriptions:write.

O servidor define as URLs de sucesso e cancelamento. Redirecione o pagador para a URL retornada pela sessão; não registre essa URL em logs públicos. O redirecionamento de sucesso não substitui a confirmação do pagamento.

Consulte e gerencieCopiar link da seção

Use os métodos do SDK, sempre com o organizationId da organização autorizada:

• Consulte a sessão com client.checkout.retrieve({ organizationId, id: "cs_EXEMPLO" }).
• Liste assinaturas com client.subscriptions.list({ organizationId, limit: 10 }) e consulte uma assinatura com client.subscriptions.retrieve({ organizationId, id: "sub_EXEMPLO" }).
• Use client.subscriptions.update com cancel_at_period_end: true para cancelar ao final do período, ou false para retirar essa programação quando aplicável.
• Crie uma sessão do portal com client.billingPortal.create, informando customer e uma chave de idempotência. O Customer Portal deve estar configurado na conta conectada.

Por exemplo, para programar o cancelamento:

const subscription = await client.subscriptions.update({
  organizationId,
  id: "sub_EXEMPLO",
  "idempotency-key": "cancelamento-assinatura-001",
  cancel_at_period_end: true,
});

Substitua os identificadores pelos retornados nas suas operações e use uma nova chave para cada alteração lógica.

A criação de assinaturas acontece via Checkout. Outros ajustes de assinatura são feitos pelo Customer Portal. O backend não expõe criação arbitrária de assinaturas ou alteração completa de itens.

Dados de pagamentoCopiar link da seção

Não envie números de cartão ou CVV ao backend Adila Pay. Use Checkout hospedado ou Stripe.js/Payment Element corretamente configurado para a conta conectada. Pix e boleto dependem das capabilities e da habilitação dessa conta.