Modelo de objetos
La API modela cinco recursos y la relación entre ellos:
- PaymentLink — el cobro que usted crea. Denominado en
amount+currency. Genera uncheckout_urlalojado. Es el punto de entrada de la integración. - CheckoutSession — la sesión del pagador en la página alojada, creada por la plataforma cuando se abre el
checkout_url. Usted no la crea directamente. - Quote — el precio bloqueado de un cobro para un método y un momento: tipo de cambio cobrado, tarifa total y neto. Fuente única de precio.
- PaymentIntent — detalle interno de orquestación creado cuando se acepta una
Quote. No es el vocabulario principal del integrador. - Payment — el resultado. Es el objeto de conciliación: lleva
reference, montos cobrados y netos, desglose de tarifas, tipo de cambio bloqueado y liquidación.
Flujo de integración directa: Quote → accept → PaymentLink. El integrador envía el link al cliente. El PaymentIntent existe por dentro para atar cobro, ledger y conciliación. Flujo de link alojado: PaymentLink → (el pagador abre) CheckoutSession → (el pagador confirma) Quote bloqueada + PaymentIntent → Payment. Cada transición del Payment emite un Event, que se entrega a sus WebhookEndpoints y se registra en WebhookDeliveries.
POST /v1/quotes/{id}/accept materializa un cobro a partir de una cotización sin recalcular el precio y responde con un link de pago. La quote debe pertenecer al tenant de la clave, estar dentro de expires_at y no haber sido consumida todavía.
En el flujo legado de POST /v1/payment_intents, legal_entity_id es opcional. Cuando se omite, la plataforma usa la única entidad legal activa del tenant autenticado. Si el tenant no tiene entidad activa, devuelve 400 no_active_legal_entity; si tiene más de una activa, devuelve 400 legal_entity_required y el integrador debe informar legal_entity_id. Cuando se informa, el campo sigue validado contra el tenant de la clave, y una entidad de otro tenant devuelve 404 legal_entity_not_found.