Cerrar y cobrar una cuenta | Documentación API de Recurrente

{
  "id": "st_du7dnfwt",
  "status": "open",
  "display_name": "Mesa 4",
  "phone": "+50255551234",
  "customer_id": "cus_3jfrywsf",
  "currency": "GTQ",
  "total_in_cents": 12500,
  "payment_strategy": "card_on_file",
  "opening_commitment": "products",
  "items": [
    {
      "id": "it_eyJfcmFpbHMiOnsi",
      "price_id": "price_hguxwfto",
      "name": "Cerveza",
      "quantity": 2,
      "amount_in_cents": 5000,
      "currency": "GTQ"
    }
  ],
  "authorized_amount_in_cents": 0,
  "authorization_expires_at": "2024-01-15T09:30:00Z",
  "checkout_url": "https://app.recurrente.com/checkout-session/ch_ccydxmvm8fvhmxsn",
  "opened_at": "2024-01-15T09:30:00Z",
  "closed_at": "2024-01-15T09:30:00Z",
  "created_at": "2024-01-15T09:30:00Z"
}

Cierra la cuenta: deja de aceptar items y se cobra el total.

Con channel: payment_link (el valor por defecto) la respuesta trae un checkout_url que el cliente puede pagar con cualquier método que tengas habilitado. Con channel: saved_card se cobra de inmediato la tarjeta guardada; si el banco pide autenticación, la cuenta queda en closing y el checkout_url es donde el cliente la completa.

Pagar ese checkout marca la cuenta como paid, sin importar el canal.

Usa un Idempotency-Key único por cierre. Si la respuesta es 422, la llave queda reservada — el cobro pudo haber llegado al procesador antes del error — así que un reintento con la misma llave responde 409. Usa una llave nueva para volver a intentar.

Cierra la cuenta: deja de aceptar items y se cobra el total. Con `channel: payment_link` (el valor por defecto) la respuesta trae un `checkout_url` que el cliente puede pagar con cualquier método que tengas habilitado. Con `channel: saved_card` se cobra de inmediato la tarjeta guardada; si el banco pide autenticación, la cuenta queda en `closing` y el `checkout_url` es donde el cliente la completa. Pagar ese checkout marca la cuenta como `paid`, sin importar el canal. Usa un `Idempotency-Key` único por cierre. Si la respuesta es `422`, la llave queda reservada — el cobro pudo haber llegado al procesador antes del error — así que un reintento con la misma llave responde `409`. Usa una llave nueva para volver a intentar.

Authentication

X-SECRET-KEYstring

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.

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.

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. 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`.

Path parameters

service_tab_idstringRequired

ID de la cuenta abierta

Request

This endpoint expects an object.

channelenumOptionalDefaults to payment_link

Cómo se cobra la cuenta

Allowed values:

payment_method_idstringOptional

Método de pago guardado a cobrar con channel: saved_card. Por defecto, el de la cuenta abierta.

Response

Cuenta cerrada

idstringOptional

ID de la cuenta abierta

statusenumOptional

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.

display_namestringOptional

Nombre con el que el comercio identifica la cuenta (mesa, cliente, cuarto)

phonestring or nullOptional

Teléfono del cliente al momento de abrir la cuenta

customer_idstringOptional

ID del cliente dueño de la cuenta

currencystringOptional

Moneda de la cuenta

total_in_centsintegerOptional

Total consumido hasta ahora, en centavos

payment_strategyenumOptional

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.

opening_commitmentenumOptional

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.

itemslist of objectsOptional

Líneas vigentes de la cuenta (los items anulados no aparecen)

authorized_amount_in_centsintegerOptional

Monto preautorizado con hold sobre la tarjeta, en centavos. 0 cuando no hay preautorización.

authorization_expires_atdatetime or nullOptional

Momento en que expira el hold de la preautorización

checkout_urlstring or nullOptional

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.

opened_atdatetimeOptional

Momento en que se abrió la cuenta

closed_atdatetime or nullOptional

Momento en que se cerró la cuenta

created_atdatetimeOptional

Errors

422

Unprocessable Entity Error

Cierra la cuenta: deja de aceptar items y se cobra el total.

Pagar ese checkout marca la cuenta como paid, sin importar el canal.

$	curl -X POST https://app.recurrente.com/api/service_tabs/service_tab_id/closure \
>	-H "X-SECRET-KEY: <apiKey>" \
>	-H "Content-Type: application/json" \
>	-d '{}'