---
title: "Cria sessão de Stripe Checkout (assinatura ou recarga one-time)"
method: POST
path: "/v1/payments/create-checkout-session"
tags: ["payments"]
---

# Cria sessão de Stripe Checkout (assinatura ou recarga one-time)

`POST /v1/payments/create-checkout-session`

- `uiMode = "hosted"` retorna `url`; redirecione o cliente.
- `uiMode = "embedded"` retorna `clientSecret`; renderize com `<EmbeddedCheckout>`.

## Request body

- PaymentRequestDTO
  - `planKey` string, required
  - `billingCycle` 'MONTHLY' | 'YEARLY'
  - `uiMode` 'hosted' | 'embedded'
  - `rechargeAmountCents` integer, nullable — Topup one-time cobrado junto com o primeiro invoice da assinatura.

## Response `200`

Sessão criada

- CheckoutSessionResponse
  - `url` string, nullable — Populado quando uiMode=hosted.
  - `clientSecret` string, nullable — Populado quando uiMode=embedded.

## Other responses

- `401` — Token ausente ou inválido
- `500` — Erro interno do servidor

---

[API](https://skmtc.net/ararahq/apis/ararahq-api.md) · [All operations](https://skmtc.net/ararahq/apis/ararahq-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/ararahq/ararahq-api/revisions/174c89e36a13/schema)