Abrir una cuenta
Abre una cuenta para un cliente. Identifica al cliente con customer_id,
o con phone y display_name para crearlo si no existe.
El compromiso de apertura se infiere de lo que envíes: items abre la
cuenta ya con esos consumos, estimated_amount la abre con un monto
estimado sin items, y si no envías ninguno la cuenta queda vacía y le
agregas items después.
La estrategia de cobro es siempre card_on_file: al cerrar se cobra la
tarjeta guardada del cliente (o le entregas un link de pago). La
preautorización con hold solo se puede activar desde el dashboard,
porque requiere una autorización real del procesador.
Usa un Idempotency-Key único por cuenta abierta.
Authentication
Tu clave secreta de API.
Una llave de cuenta (sk_live_..., sk_test_...) opera sobre su propia cuenta y, con X-ACCOUNT-ID, sobre sus cuentas conectadas.
La llave también fija el ambiente: una sk_test_ solo lista y resuelve objetos de prueba (live_mode: false) y una sk_live_ solo objetos reales. Un ID del otro ambiente responde 404 (401 en /customers).
Una llave de organización (sk_org_live_..., sk_org_test_...) alcanza todas las cuentas de una organización y solo sirve para leer: saldos, movimientos y reportes. Para operar sobre una cuenta debe nombrarla con X-ACCOUNT-ID; omitirlo en una lectura devuelve todas las cuentas de la organización. Cualquier otro endpoint responde 403 con code: organization_key_unsupported.
Request
ID del cliente. Si lo omites, se resuelve o crea con phone y display_name.
Nombre con el que identificas la cuenta (mesa, cliente, cuarto)
Teléfono del cliente
Monto estimado de consumo, en unidades de la moneda (no centavos)
Método de pago guardado del cliente que se cobrará al cerrar
Response
Estado de la cuenta. open acepta items; closing ya está cerrada y
espera el pago; paid se cobró; voided se anuló sin cobrar;
abandoned se dejó vencer.
Nombre con el que el comercio identifica la cuenta (mesa, cliente, cuarto)
Teléfono del cliente al momento de abrir la cuenta
ID del cliente dueño de la cuenta
card_on_file cobra al cerrar la tarjeta guardada del cliente.
preauthorization mantiene un hold del monto estimado y solo se
puede activar desde el dashboard, porque requiere una autorización
real del procesador.
Qué se comprometió al abrir la cuenta. Se infiere de la solicitud:
products si mandaste items, manual_amount si mandaste
estimated_amount, none si no mandaste ninguno.
Líneas vigentes de la cuenta (los items anulados no aparecen)
Checkout que cierra la cuenta; pagarlo la marca como paid. Solo
aparece mientras la cuenta se está cobrando (closing o paid): si
un cobro con tarjeta se declina, la cuenta se reabre y el checkout de
ese intento no se publica, porque el cliente no podría pagarlo.
Momento en que se abrió la cuenta
Momento en que se cerró la cuenta