Devolver lo que pagó una cita

POST

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

POST

/api/bookings/:booking_id/refund

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

{
  "id": "bk_9f8e7d6c",
  "account_id": "ac_4b3a2c1d",
  "status": "cancelled",
  "source": "storefront",
  "starts_at": "2024-01-15T09:30:00Z",
  "ends_at": "2024-01-15T10: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_90ab12cd",
      "staff_member_id": "stf_3456efgh",
      "resource_id": "res_7890ijkl",
      "kind": "service",
      "starts_at": "2024-01-15T09:30:00Z",
      "ends_at": "2024-01-15T10:00:00Z"
    }
  ],
  "staff_member_id": "stf_3456efgh",
  "resource_id": "res_7890ijkl",
  "class_session_id": "cls_1122aabb",
  "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": "tab_55667788",
    "registered_guests": [
      {
        "name": "Lucía Pérez",
        "document": "DPI 1234 56789 0101",
        "nationality": "Guatemalteca"
      }
    ],
    "guests_registered_at": "2024-01-15T09:30:00Z"
  },
  "payment_policy": "deposit",
  "currency": "GTQ",
  "total_in_cents": 20000,
  "paid_in_cents": 15000,
  "balance_in_cents": 5000,
  "balance_paid_outside_at": "2024-01-10T14:00:00Z",
  "checkout_id": "chk_99887766",
  "checkout_url": "https://app.recurrente.com/payments/checkout/chk_99887766",
  "balance_checkout_id": "chk_11223344",
  "balance_checkout_url": "https://app.recurrente.com/payments/checkout/chk_11223344",
  "no_show_fee_checkout_id": "chk_55664433",
  "booking_series_id": "ser_33445566",
  "access_url": "https://app.recurrente.com/bookings/access/bk_9f8e7d6c?token=abc123xyz",
  "customer_note": "Por favor, confirmar si hay disponibilidad para cambio de horario.",
  "merchant_note": "Cliente solicitó reembolso parcial por cambio de planes.",
  "accepted_at": "2024-01-10T08:00:00Z",
  "hold_expires_at": "2024-01-12T08:00:00Z",
  "cancelled_by": "merchant",
  "cancellation_reason": "Cliente solicitó cancelación y reembolso parcial.",
  "rescheduled_from_id": "bk_7e6d5c4b",
  "metadata": {},
  "created_at": "2024-01-01T12:00:00Z"
}

Devuelve lo que la cita cobró (anticipo, pago total, protección, saldo) por los mismos pagos por los que entró. Si la cita sigue vigente, la cancela como el negocio y devuelve, como “Cancelar y devolver el pago” en el panel; si ya estaba cancelada, solo devuelve. Emite booking.refund. Requiere que la llave pueda mover dinero.

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

Request

This endpoint expects an object.

reasonstringOptional

Por qué se cancela, si la cita seguía vigente.

Response

Pago devuelto

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

403

Forbidden Error

422

Unprocessable Entity Error