📅 Pagos Programados

Programación y ejecución de cobros diferidos asociados a reservas.

Flujo típico (EPN + Payphone):

1. POST /schedule — crea una reserva con N pagos programados a fecha futura.

2. Cada schedule se registra en AWS EventBridge Scheduler para ejecución automática.

3. Se ejecuta el cobro vía EPN (SOAP TokenOperations Sale).

4. Si el pago es exitoso y el comercio tiene payphone_enabled=true, se encolan automáticamente las dispersiones Payphone (Pagos Masivos / Payouts) según la configuración de splits.

Reprogramación: enviar un nuevo POST /schedule con el mismo reservation.id reemplaza los schedules pendientes.

Cancelación: DELETE /reservations/{id} cancela todos los schedules pendientes en AWS.

Listar pagos programados del usuario

get

Lista los pagos programados. Admin ve todos, usuarios ven solo los suyos.

Authorizations

OAuth2PasswordBearer

OAuth2passwordRequired

Token URL:

Query parameters

executedany ofOptional

integerOptional

or

nullOptional

limitintegerOptionalDefault: 100

offsetintegerOptionalDefault: 0

Responses

200

Successful Response

application/json

anyOptional

422

Validation Error

application/json

get

/admin/schedules

HTTPcURLJavaScriptPython

GET /admin/schedules HTTP/1.1
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

No content

Cancelar un pago programado

delete

Elimina un pago programado pendiente. Solo admin o dueño.

Authorizations

OAuth2PasswordBearer

OAuth2passwordRequired

Token URL:

Path parameters

schedule_idintegerRequired

Responses

200

Successful Response

application/json

anyOptional

422

Validation Error

application/json

delete

/admin/schedules/{schedule_id}

HTTPcURLJavaScriptPython

DELETE /admin/schedules/{schedule_id} HTTP/1.1
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

No content

Programar pagos futuros para una reserva

post

Programa uno o más pagos futuros asociados a una reserva.

Comportamiento:

• Si la reserva (reservation.id) no existe, se crea automáticamente.

• Si la reserva ya existe, se eliminan todos los schedules pendientes (no ejecutados) tanto en la base de datos como en AWS EventBridge/Scheduler, y se crean los nuevos.

• Schedules con fecha en el pasado (< ahora - 5 segundos) se ignoran silenciosamente.

• Cada schedule crea una regla en AWS EventBridge Scheduler para ejecución automática.

Body (ScheduledPayment):

{
  "reservation": {
    "id": "BOOK-123",
    "card": "FCE5AB1B-5608-4EC3-9168-247CB19B2D16",
    "cancellation_fee": 50.0,
    "cancellation_fee_reimbursable": true,
    "auto_reimburse": false
  },
  "schedules": [
    {
      "scheduled_at": 1735689600,
      "amount": 150.00,
      "currency": "EUR",
      "description": "Primera cuota"
    },
    {
      "scheduled_at": 1738368000,
      "amount": 150.00,
      "currency": "EUR",
      "description": "Segunda cuota"
    }
  ],
  "gateway": {
    "id": "77",
    "moto": true,
    "mit": false,
    "operative": "AUTHORIZATION"
  }
}

Campos de reservation:

• id (string) — identificador de la reserva en el sistema cliente (bookingId).

• card (string, opcional) — UUID de tarjeta tokenizada (Paylands) o token Base64 JSON (EPN).

• cancellation_fee (float) — fee de cancelación en unidades monetarias.

• cancellation_fee_reimbursable (bool) — si el fee es reembolsable.

• auto_reimburse (bool) — si se reembolsa automáticamente al cancelar.

Campos de cada schedule:

• scheduled_at (int) — timestamp UNIX (segundos) de la fecha de ejecución.

• amount (float) — importe en unidades monetarias (ej: 150.00 = 150€).

• currency (string) — código ISO 4217 (EUR, USD, GBP).

• description (string, opcional) — descripción del pago.

Campos de gateway:

• id (string) — ID del comercio previamente registrado.

• moto (bool) — ejecutar como Mail Order / Telephone Order.

• mit (bool) — ejecutar como Merchant Initiated Transaction.

• operative (string) — AUTHORIZATION o DEFERRED.

Authorizations

OAuth2PasswordBearer

OAuth2passwordRequired

Token URL:

Body

application/json

Payload completo para programar pagos futuros.

Responses

200

Schedules programados exitosamente. Devuelve el payload original.

application/json

Payload completo para programar pagos futuros.

400

Comercio no encontrado o datos inválidos.

401

Token JWT inválido o ausente.

422

Validation Error

application/json

post

/schedule

HTTPcURLJavaScriptPython

POST /schedule HTTP/1.1
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 432

{
  "gateway": {
    "id": "77",
    "mit": false,
    "moto": true,
    "operative": "AUTHORIZATION"
  },
  "reservation": {
    "auto_reimburse": false,
    "cancellation_fee": 50,
    "cancellation_fee_reimbursable": true,
    "card": "FCE5AB1B-5608-4EC3-9168-247CB19B2D16",
    "id": "BOOK-2025-00123"
  },
  "schedules": [
    {
      "amount": 150,
      "currency": "EUR",
      "description": "Primera cuota",
      "scheduled_at": 1735689600
    },
    {
      "amount": 150,
      "currency": "EUR",
      "description": "Segunda cuota",
      "scheduled_at": 1738368000
    }
  ]
}

{
  "gateway": {
    "id": "77",
    "mit": false,
    "moto": true,
    "operative": "AUTHORIZATION"
  },
  "reservation": {
    "auto_reimburse": false,
    "cancellation_fee": 50,
    "cancellation_fee_reimbursable": true,
    "card": "FCE5AB1B-5608-4EC3-9168-247CB19B2D16",
    "id": "BOOK-2025-00123"
  },
  "schedules": [
    {
      "amount": 150,
      "currency": "EUR",
      "description": "Primera cuota",
      "scheduled_at": 1735689600
    },
    {
      "amount": 150,
      "currency": "EUR",
      "description": "Segunda cuota",
      "scheduled_at": 1738368000
    }
  ]
}

Eliminar una reserva y cancelar sus pagos pendientes

delete

Elimina una reserva y cancela todos sus pagos programados pendientes.

Acciones realizadas:

1. Busca la reserva por res_id y user_id del token JWT.

2. Consulta todos los schedules con executed=0 asociados a la reserva.

3. Para cada schedule pendiente, cancela la regla/schedule en AWS EventBridge Scheduler.

4. Elimina la reserva de la base de datos (cascade: elimina schedules, policies, cards).

Path parameters:

• res_id (string) — ID de la reserva (el mismo reservation.id usado en /schedule).

⚠️ Esta operación es irreversible. Los schedules ya ejecutados (executed=1) no se ven afectados pero se eliminan de la base de datos igualmente.

Respuesta: 204 No Content (sin body).

Authorizations

OAuth2PasswordBearer

OAuth2passwordRequired

Token URL:

Path parameters

res_idstringRequired

Responses

204

Reserva eliminada. Todos los schedules pendientes cancelados en AWS.

401

Token JWT inválido o ausente.

404

Reserva no encontrada para el usuario autenticado.

422

Validation Error

application/json

delete

/reservations/{res_id}

HTTPcURLJavaScriptPython

DELETE /reservations/{res_id} HTTP/1.1
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

No content