Referencia de API

Endpoints, parámetros y modelos de la API v1 de Cauril.

URL base https://api.cauril.comVersión 2026-06-01

Autenticá con tu API key como Bearer token (Authorization: Bearer sk_test_…), ver Autenticación. Toda mutación requiere Idempotency-Key.

Endpoints

Payments

Crear, listar y consultar pagos.

getListar pagos/v1/payments postCrear un pago/v1/payments getObtener un pago/v1/payments/{id}postReembolsar un pago/v1/payments/{id}/refund

Refunds

Reembolsos totales y parciales.

getObtener un reembolso/v1/refunds/{id}

Checkout

Sesiones de checkout embebido (drop-in): tu server crea la sesión, el drop-in @cauril/checkout-js cobra en el browser sin que toques datos de tarjeta (PCI SAQ-A).

postCrear una sesión de checkout/v1/checkout/sessions getObtener una sesión de checkout/v1/checkout/sessions/{id}postConfirmar una sesión de checkout/v1/checkout/sessions/{id}/confirm postReintentar en otro PSP/v1/checkout/sessions/{id}/reroute postCancelar una sesión de checkout/v1/checkout/sessions/{id}/cancel

Customers

Clientes del negocio que agrupan pagos y métodos.

getListar customers/v1/customers postCrear un customer/v1/customers getObtener un customer/v1/customers/{id}

Routing rules

Reglas declarativas para resolver el PSP de cada pago.

getListar reglas de routing/v1/routing-rules postCrear una regla de routing/v1/routing-rules patchActualizar una regla de routing/v1/routing-rules/{id}deleteEliminar una regla de routing/v1/routing-rules/{id}

Analytics

Métricas agregadas de pagos.

getResumen analítico/v1/analytics/summary

Plans

Planes de cobro recurrente.

getListar planes/v1/plans postCrear un plan/v1/plans getObtener un plan/v1/plans/{id}

Subscriptions

Suscripciones recurrentes normalizadas multi-PSP.

getListar suscripciones/v1/subscriptions postCrear una suscripción/v1/subscriptions getObtener una suscripción/v1/subscriptions/{id}postActualizar una suscripción/v1/subscriptions/{id}postCancelar una suscripción/v1/subscriptions/{id}/cancel

Invoices

Facturas generadas por las suscripciones.

getListar facturas/v1/invoices getObtener una factura/v1/invoices/{id}

Provider connections

Conectar y operar tus cuentas de PSP.

getListar conexiones/v1/provider-connections postConectar un PSP/v1/provider-connections

Webhook endpoints

Suscripciones a eventos salientes.

getListar endpoints/v1/webhooks/endpoints postCrear un endpoint de webhook/v1/webhooks/endpoints

Webhook deliveries

Entregas de eventos salientes y sus reintentos.

getListar entregas de webhook/v1/webhooks/deliveries getObtener una entrega de webhook/v1/webhooks/deliveries/{id}postReenviar una entrega de webhook/v1/webhooks/deliveries/{id}/resend

Events

El feed normalizado de eventos.

getListar eventos/v1/events

Modelos

Los objetos que devuelve y acepta la API.

Money

Monto en la unidad mínima de la moneda (ej. centavos). Nunca decimales.

Currency

Código ISO-4217 de 3 letras.

PaymentStatus

Estado normalizado del pago (igual para todos los PSPs).

createdpendingrequires_actionprocessingsucceededfailedcanceledrefundedpartially_refunded

RefundStatus

pendingprocessingsucceededfailedcanceled

SubscriptionStatus

Estado normalizado de la suscripción (igual para todos los PSPs).

incompleteincomplete_expiredtrialingactivepast_dueunpaidpausedcanceled

InvoiceStatus

Estado normalizado de la factura. Cada transición open→paid se materializa en un Payment.

draftopenpaiduncollectiblevoid

DeliveryStatus

Estado de la entrega de un webhook saliente. exhausted = agotados los reintentos (dead-letter).

pendingdeliveringdeliveredfailedexhausted

BillingInterval

Cadencia de cobro de un plan.

dayweekmonthyear

PaymentMethod

type	string
token	string	Token del método generado del lado del cliente/PSP. Cauril nunca ve datos crudos de tarjeta (PAN/CVV).
brand	string
last4	string

NextAction

Acción requerida para completar el pago (ej. 3DS).

type	string
url	string

Failure

code	string
message	string

CreatePayment

amountreq	Money
currencyreq	Currency
payment_methodreq	PaymentMethod
provider	string	Forzar un PSP. Si se omite, se usa el provider por defecto de la organización.
customer_id	string
description	string
capture	boolean	Default: `true`.
return_url	string
metadata	object

Payment

object	string
id	string
status	PaymentStatus
amount	Money
amount_refunded	Money
currency	Currency
provider	string
provider_payment_id	stringnull
payment_method	PaymentMethod
customer_id	stringnull
description	stringnull
metadata	object
next_action	NextAction
failure	Failure
attempts	PaymentAttempt[]	Solo con expand=attempts.
created_at	string · date-time
updated_at	string · date-time
livemode	boolean

PaymentAttempt

object	string
id	string
provider	string
status	string
provider_payment_id	stringnull
error_code	stringnull
latency_ms	integernull
created_at	string · date-time

CreateRefund

amount	Money
reason	string
metadata	object

Refund

object	string
id	string
payment_id	string
amount	Money
currency	Currency
status	RefundStatus
reason	stringnull
provider_refund_id	stringnull
metadata	object
created_at	string · date-time
updated_at	string · date-time

CheckoutSessionStatus

Estado de la sesión de checkout.

openprocessingcompletedexpiredcanceled

CheckoutSessionUi

Datos que el drop-in usa para montar el campo de pago del PSP en el browser.

provider	string
publishable_key	stringnull	Clave pública del PSP (ej. `pk_test_...` de Stripe). El drop-in la usa para montar el campo seguro.
methods	string[]

CreateCheckoutSession

amountreq	Money
currencyreq	Currency
success_urlreq	string · uri	A dónde vuelve el comprador tras pagar. Debe estar en el allowlist de redirección de la organización.
cancel_urlreq	string · uri	A dónde vuelve el comprador si cancela.
allowed_methods	arraynull	Métodos a ofrecer. Si se omite, se usan los del PSP resuelto.
return_url	string · uri
customer_email	string · email
locale	string
provider	string	Forzar un PSP. Si se omite, se resuelve por routing (con `routing_hint`).
routing_hint	object	Pistas para resolver el PSP (ej. país del comprador).
appearance	object	Estilo del drop-in (colores, bordes).
metadata	object

ConfirmCheckout

Lo envía el drop-in al confirmar; los campos dependen del método y el PSP.

provider_token	string	Token del método generado por el PSP del lado del cliente.
method	string
customer_email	string · email
installments	integer
payer_name	string
payer_document	string	Documento del pagador (ej. CPF) cuando el método/país lo requiere.
payment_method_id	string
country	string

RerouteCheckout

exclude_provider

string

PSP a excluir en el reintento (el que acaba de fallar).

CheckoutSession

Vista server de la sesión (con sk_). El drop-in en el browser ve el subconjunto CheckoutSessionPublic.

object	string
id	string
status	CheckoutSessionStatus
amount	Money
currency	Currency
client_secret	string	Se devuelve una sola vez, al crear. Pasalo al drop-in en el browser; autentica las llamadas del comprador. No es una API key (`cs_..._secret_...`).
ui	CheckoutSessionUi
allowed_methods	arraynull
success_url	string
cancel_url	string
return_url	stringnull
locale	stringnull
customer_email	stringnull
metadata	object
payment_id	stringnull	El Payment generado cuando la sesión se completa.
payment	object	Solo con `expand=payment`.
expires_at	string · date-time
created_at	string · date-time
updated_at	string · date-time
livemode	boolean

CheckoutSessionPublic

Subconjunto que ve el drop-in en el browser (auth por client_secret). Sin metadata ni ids internos.

object	string
id	string
status	CheckoutSessionStatus
amount	Money
currency	Currency
ui	CheckoutSessionUi
allowed_methods	arraynull
locale	stringnull
success_url	string
cancel_url	string
return_url	stringnull
payment	object	Espejo normalizado del pago: estado, `next_action` (3DS/voucher) y `failure`. Nunca un string crudo del PSP.
expires_at	string · date-time

ConnectProvider

providerreq	string
credentialsreq	object	Credenciales del PSP. Se cifran at-rest y nunca se devuelven.
mode	string
label	string

ProviderConnection

object	string
id	string
provider	string
mode	string
status	string
label	stringnull
capabilities	object
webhook_path	string	Configurá esta URL como destino de webhooks en el PSP.
created_at	string · date-time

CreateWebhookEndpoint

urlreq	string · uri
enabled_events	string[]	Tipos de evento a recibir. Vacío = todos.
description	string

WebhookEndpoint

object	string
id	string
url	string
enabled_events	string[]
status	string
secret	string	Solo en la respuesta de creación. Verificá la firma Cauril-Signature con este secreto.
created_at	string · date-time

Event

id	string
object	string
type	string
api_version	string
created_at	string · date-time
livemode	boolean
data	object

PaymentList

object	string
data	Payment[]
has_more	boolean
next_cursor	stringnull

EventList

object	string
data	Event[]
has_more	boolean
next_cursor	stringnull

CreateCustomer

email	string · email
name	string
metadata	object

Customer

object	string
id	string
email	stringnull
name	stringnull
metadata	object
created_at	string · date-time

CustomerList

object	string
data	Customer[]
has_more	boolean
next_cursor	stringnull

RoutingRuleConditions

Condiciones en whitelist. Una condición presente debe cumplirse (AND entre campos; OR dentro de cada lista). currency/country se comparan en mayúsculas, method en minúsculas; amount usa lte/gte en unidades mínimas.

currency	string[]
country	string[]
method	string[]
amount	object

RoutingRuleAction

providerreq

string

CreateRoutingRule

priorityreq	integer	Se evalúan de menor a mayor; la más baja primero.
conditionsreq	RoutingRuleConditions
actionreq	RoutingRuleAction
enabled	boolean	Default: `true`.

UpdateRoutingRule

priority	integer
conditions	RoutingRuleConditions
action	RoutingRuleAction
enabled	boolean

RoutingRule

object	string
id	string
priority	integer
conditions	RoutingRuleConditions
action	RoutingRuleAction
enabled	boolean
created_at	string · date-time

AnalyticsProviderBreakdown

provider	string
count	integer
volume	Money
approval_rate	number	Proporción de pagos aprobados (0–1).
fees_estimated	Money

AnalyticsSummary

object	string
range	object
totals	object	Métricas del período en una sola `currency`.
fees_estimated	Money
available_currencies	object[]	Monedas con actividad en el período, la más activa primero.
by_provider	AnalyticsProviderBreakdown[]

CreatePlan

amountreq	Money
currencyreq	Currency
intervalreq	BillingInterval
interval_count	integer	Número de intervalos por período de cobro. Default: `1`.
trial_days	integer
metadata	object

Plan

object	string
id	string
amount	Money
currency	Currency
interval	BillingInterval
interval_count	integer
trial_days	integernull
metadata	object
created_at	string · date-time

PlanList

object	string
data	Plan[]
has_more	boolean
next_cursor	stringnull

CreateSubscription

customerreq	string	Id del customer.
planreq	string	Id del plan.
payment_methodreq	string	Token del método generado del lado del cliente/PSP.
provider	string	Forzar un PSP. Si se omite, se resuelve por routing.
trial_days	integer
metadata	object

UpdateSubscription

plan	string	Cambio de plan; aplica al próximo período.
cancel_at_period_end	boolean
metadata	object

CancelSubscription

at_period_end boolean Si es true, la cancelación se programa para el final del período actual. Default: false.

Subscription

object	string
id	string
status	SubscriptionStatus
customer_id	string
plan_id	string
provider	string
engine	string	Quién corre el cobro recurrente: el PSP (native) o el scheduler de Cauril.
current_period_start	string · date-time
current_period_end	string · date-time
cancel_at_period_end	boolean
trial_end	string,null · date-time
provider_subscription_id	stringnull
metadata	object
latest_invoice	object	Solo con expand=latest_invoice. La última factura, con su `payment` (que puede llevar `next_action`).
created_at	string · date-time
updated_at	string · date-time

SubscriptionList

object	string
data	Subscription[]
has_more	boolean
next_cursor	stringnull

Invoice

object	string
id	string
subscription_id	string
amount	Money
currency	Currency
status	InvoiceStatus
period_start	string · date-time
period_end	string · date-time
payment_id	stringnull	El Payment que materializa el cobro de esta factura.
attempt_count	integer
created_at	string · date-time

InvoiceList

object	string
data	Invoice[]
has_more	boolean
next_cursor	stringnull

WebhookDelivery

object	string
id	string
event_id	string
endpoint_id	string
type	string
status	DeliveryStatus
attempt_count	integer
last_response_status	integernull	Código HTTP del último intento.
last_error	stringnull
next_attempt_at	string,null · date-time
delivered_at	string,null · date-time
created_at	string · date-time
payload	object	Cuerpo del evento enviado. Solo presente en el detalle (GET por id).

WebhookDeliveryList

object	string
data	WebhookDelivery[]
has_more	boolean
next_cursor	stringnull

Error

Forma única de error en toda la API.

error

object