Modelo de objetos

A API modela cinco recursos e a relação entre eles:

• PaymentLink — a cobrança que você cria. Denominada em amount + currency. Gera um checkout_url hospedado. É o ponto de entrada da integração.
• CheckoutSession — a sessão do pagador na página hospedada, criada pela plataforma quando o checkout_url é aberto. Você não a cria diretamente.
• Quote — o preço travado de uma cobrança em um método e momento: câmbio cobrado, taxa total e líquido. Fonte única de preço.
• PaymentIntent — detalhe interno de orquestração criado quando uma Quote é aceita. Não é o vocabulário principal do integrador.
• Payment — o resultado. É o objeto de conciliação: carrega reference, valores cobrados e líquidos, breakdown de taxas, câmbio travado e liquidação.

Fluxo de integração direta: Quote → accept → PaymentLink. O integrador envia o link ao cliente. O PaymentIntent existe por dentro para amarrar cobrança, ledger e conciliação. Fluxo de link hospedado: PaymentLink → (pagador abre) CheckoutSession → (pagador confirma) Quote travada + PaymentIntent → Payment. Cada transição do Payment emite um Event, que é entregue aos seus WebhookEndpoints e registrado em WebhookDeliveries.

POST /v1/quotes/{id}/accept materializa uma cobrança a partir de uma cotação sem recalcular preço e responde com um link de pagamento. O quote precisa pertencer ao tenant da chave, estar dentro de expires_at e ainda não ter sido consumido.

No fluxo legado de POST /v1/payment_intents, legal_entity_id é opcional. Quando omitido, a plataforma usa a única entidade legal ativa do tenant autenticado. Se o tenant não tiver entidade ativa, retorna 400 no_active_legal_entity; se tiver mais de uma ativa, retorna 400 legal_entity_required e o integrador deve informar legal_entity_id. Quando informado, o campo continua validado contra o tenant da chave e entidade de outro tenant retorna 404 legal_entity_not_found.

---