Generar el link para cobrar el saldo

POST

https://app.recurrente.com/api/bookings/:booking_id/balance_charge

POST

/api/bookings/:booking_id/balance_charge

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

{
  "id": "bk_9f8e7d6c",
  "account_id": "ac_4b3a2c1d",
  "status": "pending",
  "source": "storefront",
  "starts_at": "2024-05-20T14:00:00Z",
  "ends_at": "2024-05-20T15:00:00Z",
  "customer": {
    "id": "cus_7a6b5c4d",
    "name": "María González",
    "email": "maria.gonzalez@example.com",
    "phone": "+502 5555 1234"
  },
  "segments": [
    {
      "service_id": "svc_1234abcd",
      "product_id": "prd_5678efgh",
      "product_variant_id": "var_9abcde01",
      "staff_member_id": "stf_2345bcde",
      "resource_id": "res_6789fabc",
      "kind": "service",
      "starts_at": "2024-05-20T14:00:00Z",
      "ends_at": "2024-05-20T15:00:00Z"
    }
  ],
  "staff_member_id": "stf_2345bcde",
  "resource_id": "res_6789fabc",
  "class_session_id": null,
  "stay": {
    "room_type_id": "svc_ab12cd34",
    "unit_id": "res_ab12cd34",
    "unit_name": "Cabaña 1",
    "check_in_on": "2026-10-09",
    "check_out_on": "2026-10-11",
    "nights": 2,
    "guests": 2,
    "service_tab_id": null,
    "registered_guests": [
      {
        "name": "Lucía Pérez",
        "document": "DPI 1234 56789 0101",
        "nationality": "Guatemalteca"
      }
    ],
    "guests_registered_at": "2024-05-20T14:00:00Z"
  },
  "payment_policy": "deposit",
  "currency": "GTQ",
  "total_in_cents": 20000,
  "paid_in_cents": 10000,
  "balance_in_cents": 10000,
  "balance_paid_outside_at": null,
  "checkout_id": "chk_9876fedc",
  "checkout_url": "https://checkout.recurrente.com/pay/chk_9876fedc",
  "balance_checkout_id": "chk_bal_1234abcd",
  "balance_checkout_url": "https://checkout.recurrente.com/pay/chk_bal_1234abcd",
  "no_show_fee_checkout_id": null,
  "booking_series_id": null,
  "access_url": "https://app.recurrente.com/bookings/bk_9f8e7d6c/access?token=abc123xyz",
  "customer_note": "Por favor, confirmar disponibilidad de estacionamiento.",
  "merchant_note": "Cliente frecuente, aplicar descuento en próxima cita.",
  "accepted_at": "2024-05-10T10:00:00Z",
  "hold_expires_at": "2024-05-15T10:00:00Z",
  "cancelled_by": null,
  "cancellation_reason": null,
  "rescheduled_from_id": null,
  "metadata": {
    "promo_code": "MAYO2024",
    "internal_notes": "Cliente VIP"
  },
  "created_at": "2024-05-01T09:00:00Z"
}

Crea el checkout por lo que falta de la cita (el precio congelado al reservar menos lo pagado) y responde la cita con balance_checkout_url, el link que el cliente paga. No cobra nada por sí mismo. Si ya hay un link sin pagar por el mismo monto, devuelve ese. Al pagarse, se suma a paid_in_cents.

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.

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.

Path parameters

booking_idstringRequired

Response

La cita, con el link del saldo

idstringOptional

account_idstringOptional

Cuenta (sucursal) de la cita.

statusenumOptional

pending mientras el cliente paga o el negocio decide; confirmed cuando la hora es del cliente.

sourceenumOptional

Por dónde entró la reserva.

starts_atdatetimeOptional

ends_atdatetimeOptional

customerobjectOptional

segmentslist of objectsOptional

Los tramos de la cita, uno por servicio (dos si el servicio tiene tiempo de proceso). Vacío en un lugar de una clase.

staff_member_idstring or nullOptional

resource_idstring or nullOptional

class_session_idstring or nullOptional

La sesión, si la cita es un lugar en una clase.

stayobject or nullOptional

Las noches en una habitación, si la reserva es una estadía de alojamiento.

payment_policyenumOptional

Allowed values:

currencystringOptional

total_in_centsintegerOptional

Lo que cuesta la cita.

paid_in_centsintegerOptional

Lo que el cliente ya pagó (anticipo, total o protección).

balance_in_centsintegerOptional

Lo que falta cobrar el día de la cita. 0 en una sesión de paquete o un saldo cobrado afuera.

balance_paid_outside_atdatetime or nullOptional

Cuándo el negocio marcó el saldo como cobrado fuera de Recurrente.

checkout_idstring or nullOptional

checkout_urlstring or nullOptional

Donde el cliente paga lo que la política pide, o deja su tarjeta.

balance_checkout_idstring or nullOptional

balance_checkout_urlstring or nullOptional

El link del saldo, después de POST /bookings/{booking_id}/balance_charge.

no_show_fee_checkout_idstring or nullOptional

El checkout del cargo por inasistencia, cobrado o rechazado.

booking_series_idstring or nullOptional

La serie que la reservó, si se repite.

access_urlstringOptional

La página del cliente para ver, pagar o cancelar su cita (link firmado).

customer_notestring or nullOptional

merchant_notestring or nullOptional

accepted_atdatetime or nullOptional

hold_expires_atdatetime or nullOptional

Hasta cuándo se aparta la hora si nadie paga.

cancelled_byenum or nullOptional

Allowed values:

cancellation_reasonstring or nullOptional

rescheduled_from_idstring or nullOptional

La cita que esta reemplazó al moverse de hora.

metadataobjectOptional

created_atdatetimeOptional

Errors

422

Unprocessable Entity Error