API pública — Pagos (payments)

Miguel Gómez Pérez · Equipo Bukyapp· 3 min de lectura·Actualizado 21 may 2026

Consulta pagos mediante la API pública de Buky: endpoint, campos del modelo, filtros por fecha o método, paginación y ejemplos curl listos para usar.

Esta página explica cómo consultar los pagos de tu cuenta mediante la API pública de Buky. Los pagos son los cobros individuales asociados a cada reserva: un mismo pedido puede tener varios pagos (anticipo, segundo pago, devolución parcial...).

Antes de empezar

• Necesitas un API Token activo. Si aún no lo has creado, sigue la guía Conectar Buky con herramientas externas (API Tokens).
• El token es de solo lectura: puedes listar y consultar pagos, pero no modificarlos.
• La función está en fase beta. Si no ves la pestaña "API Tokens" en tu configuración, contacta con soporte.

Autenticación

El token se envía en cada petición mediante la cabecera auth:

curl "https://app.bukyapp.com/api/payments" \
  -H "auth: bk_TU_TOKEN"

También se acepta como parámetro token en la URL, aunque la cabecera es la opción recomendada. Más detalles en API pública — Introducción y primeros pasos.

Listar pagos

curl "https://app.bukyapp.com/api/payments" \
  -H "auth: bk_TU_TOKEN"

La respuesta es un array JSON de pagos, ordenado por fecha de pago descendente (el más reciente primero):

[
  {
    "_id": "65f1a2b3c4d5e6f7a8b9c0d1",
    "receipt_number": 1042,
    "mode": "stripe",
    "description": {
      "name": "Tarjeta online",
      "color": "green"
    },
    "status": "completed",
    "date": "2026-05-14T10:30:00.000Z",
    "createdAt": "2026-05-14T10:30:00.000Z",
    "total": 90,
    "refunded": 0,
    "_order": {
      "_id": "65f1a2b3c4d5e6f7a8b9c0a0",
      "product_title": "Clase de surf 2h",
      "name": "Laura",
      "surname": "García",
      "products": [
        {
          "product_title": "Clase de surf 2h",
          "product_internalName": "surf-2h-adultos"
        }
      ]
    }
  },
  ...
]

Cada pago viene acompañado de un objeto _order con los datos básicos de la reserva a la que pertenece.

Paginación

En las cabeceras de la respuesta recibes el total de resultados y el número de páginas:

• X-Count: total de pagos que coinciden con el filtro.
• X-Page-Count: número de páginas.

Por defecto el endpoint devuelve como máximo 100 pagos por página. Para paginar:

curl "https://app.bukyapp.com/api/payments?page=1&limit=50" \
  -H "auth: bk_TU_TOKEN"

• limit: pagos por página (máximo 100).
• page: número de página, empezando en 1.

Filtrar pagos

El parámetro filter acepta un objeto JSON con sintaxis MongoDB. Envíalo codificado en la URL.

Por fecha del pago

# Pagos del último mes
curl -G "https://app.bukyapp.com/api/payments" \
  -H "auth: bk_TU_TOKEN" \
  --data-urlencode 'filter={"payments.date":{"$gte":"2026-04-01T00:00:00Z"}}'

Por estado

# Solo pagos completados
--data-urlencode 'filter={"payments.status":"completed"}'

# Pagos devueltos (refunded)
--data-urlencode 'filter={"payments.status":"refunded"}'

Por método de pago

# Pagos con Stripe
--data-urlencode 'filter={"payments.mode":"stripe"}'

# Pagos en efectivo
--data-urlencode 'filter={"payments.mode":"cash"}'

Los valores posibles de mode son:

Por reserva

# Pagos de una reserva concreta
--data-urlencode 'filter={"_id":"65f1a2b3c4d5e6f7a8b9c0a0"}'

Combinando filtros

Cualquier combinación funciona — se aplica como AND:

--data-urlencode 'filter={"payments.status":"completed","payments.mode":"stripe","payments.date":{"$gte":"2026-04-01"}}'

Incluir facturas en la respuesta

Si necesitas saber qué factura cubre cada pago, añade el parámetro withInvoices:

curl "https://app.bukyapp.com/api/payments?withInvoices=true&page=1&limit=50" \
  -H "auth: bk_TU_TOKEN"

Cada pago incluirá un array _order.invoices con las facturas asociadas a esa reserva:

{
  "_order": {
    "_id": "65f1a2b3c4d5e6f7a8b9c0a0",
    "invoices": [
      {
        "_id": "66a1b2c3d4e5f6a7b8c9d0e1",
        "number": 42,
        "prefix": "F-2026",
        "issuedDate": "2026-05-14T12:00:00.000Z",
        "isRectification": false,
        "isCancelled": false
      }
    ]
  }
}

Para consultar facturas en detalle, revisa API pública — Facturas (customerInvoices).

Campos del objeto Payment

Campos de la reserva asociada (_order)

Estados del pago (status)

Consejos

• Filtra siempre por fecha. Sin filtro recibes todos los pagos históricos y paginarás mucho. Un payments.date: {$gte: ...} reduce resultados y acelera la respuesta.
• Usa `withInvoices` solo cuando lo necesites. Añade un join extra a la consulta. Si solo necesitas importes y métodos, omítelo.
• El campo `meta` contiene datos internos de la pasarela (IDs de Stripe, códigos de Redsys, etc.). Su estructura puede cambiar sin previo aviso — no construyas lógica sobre sus campos internos.
• Guarda el último `date` procesado. Para sincronizaciones incrementales, pide solo pagos posteriores al último timestamp que ya procesaste.
• Respeta el ritmo. Usa limit=100 y espacia las peticiones para no saturar.

Preguntas frecuentes

¿Puedo registrar pagos por la API?

No. Los API Tokens son de solo lectura. Sirven para consultar datos, no para modificarlos.

¿Por qué un pago tiene `mode: "issued"` y `status: "pending"`?

Es un enlace de pago pendiente: se generó un cobro programado (segundo pago, por ejemplo) pero el cliente aún no ha pagado. Cuando pague, el mode cambiará al método que use (Stripe, Redsys...) y el status pasará a completed.

¿Cómo sé cuánto queda por cobrar en una reserva?

Puedes sumar los total de los pagos con status: "completed" y compararlo con el total de la reserva. O directamente consultar el campo amountPending del order (ver API pública — Reservas).

¿Los importes llevan IVA?

Los importes de total son los que aparecen en Buky — si tu configuración incluye IVA en el precio, estarán con IVA incluido. Para desglose fiscal, consulta la factura asociada.