Subscription Transactions - Kushki Developer Portal

La API de Subscription Transactions devuelve los detalles completos de una suscripción junto con la lista de transacciones cobradas contra ella. Úsala para inspeccionar el historial de facturación, auditar cargos individuales y construir dashboards de pagos para tus clientes.

Obtener las transacciones de una suscripción

GET /data/v1/subscription/{subscriptionId}

Envía el subscriptionId como parámetro de ruta. Todos los demás parámetros son opcionales.

Parámetro de ruta

Parámetro	Obligatorio	Descripción
`subscriptionId`	✅	Identificador único de la suscripción. Se devuelve como `subscriptionId` cuando la suscripción se crea con `POST /subscriptions/v1/card`.

Parámetros de consulta

Parámetro	Por defecto	Descripción
`start`	5 días antes de la petición	Inicio del filtro de rango de fechas (`YYYY-MM-DD`). Solo se devuelven las transacciones creadas en esa fecha o después.
`end`	Momento de la petición	Fin del filtro de rango de fechas (`YYYY-MM-DD`). Solo se devuelven las transacciones creadas en esa fecha o antes.
`size`	`100`	Cantidad máxima de transacciones a devolver. Debe ser un entero positivo.

Petición de ejemplo:

GET /data/v1/subscription/177493387604666666?start=2026-01-01&end=2026-03-31&size=50
Private-Merchant-Id: <your-private-key>

Estructura de la respuesta

La respuesta combina dos secciones: los metadatos de la suscripción (detalles estáticos de la suscripción) y un arreglo transactions (los cargos ejecutados dentro del rango de fechas solicitado).

Campos de metadatos de la suscripción

Plan y calendario

Campo	Descripción
`subscription_code`	Identificador único de la suscripción (el mismo que `subscriptionId`)
`plan_name`	Nombre del plan asociado a la suscripción
`active_indicator`	`true` si la suscripción está activa actualmente
`periodicity_type`	Frecuencia del cargo, ver los valores más abajo
`day_of_month`	Día del mes configurado para el cargo. `-2` para las suscripciones on-demand (`custom`)
`day_of_week`	Día de la semana para los cargos semanales. `"-"` cuando no aplica
`month`	Mes configurado para el cargo. `"-"` cuando no aplica
`start_timestamp`	Timestamp Unix (segundos) de la fecha de inicio configurada de la suscripción
`create_timestamp`	Timestamp Unix (segundos) del momento en que se creó la suscripción
`last_charge_timestamp`	Timestamp Unix (segundos) del cargo más reciente

Valores de periodicity_type:

Valor	Descripción
`daily`	Todos los días
`weekly`	Una vez por semana
`biweekly`	Cada dos semanas
`monthly`	Una vez al mes
`threefortnights`	Cada tres quincenas
`bimonthly`	Cada dos meses
`quarterly`	Cada tres meses
`fourmonths`	Cada cuatro meses
`halfyearly`	Cada seis meses
`yearly`	Una vez al año
`custom`	On-demand, se cobra manualmente vía API

Detalles de la tarjeta

Campo	Descripción
`card_holder_name`	Nombre completo del tarjetahabiente
`card_type`	`credit`, `debit` o `prepaid`
`last_four_digit_code`	Últimos cuatro dígitos de la tarjeta registrada
`expiry_month` / `expiry_year`	Vencimiento de la tarjeta (formato MM / YY)
`bin_info_object.bin`	Primeros 6 dígitos de la tarjeta (BIN)
`bin_info_object.brand`	Marca de la red de tarjetas (por ejemplo, `VISA`, `MASTERCARD`)
`bin_info_object.bank`	Nombre del banco emisor de la tarjeta
`bin_info_object.info.type`	Tipo de tarjeta según la base de BIN (`credit`, `debit`, `prepaid`)
`bin_info_object.info.country`	País emisor: código `alpha3` y `name`
`bin_info_object.originalBinFullLength`	BIN completo de 8 dígitos cuando está disponible
`bin_info_object.validBin8`	Indica si el BIN de 8 dígitos se resolvió correctamente

Configuración del monto

Campo	Descripción
`amount_object.currency`	Siempre `COP` para Colombia
`amount_object.subtotalIva`	Subtotal sujeto a IVA
`amount_object.subtotalIva0`	Subtotal no sujeto a IVA
`amount_object.iva`	Monto de IVA
`amount_object.ice`	Monto del impuesto ICE

Contacto y comercio

Campo	Descripción
`contact_details_object.email`	Correo del titular de la suscripción
`contact_details_object.firstName` / `lastName`	Nombre del titular de la suscripción
`merchant_code`	Identificador único del comercio dueño de la suscripción
`merchant_country_name`	País del comercio
`provider_name`	Proveedor de pago (siempre `kushki`)
`reference_transaction_code`	Código de referencia de la transacción inicial de validación de la tarjeta
`metadata_object`	Metadatos personalizados clave-valor adjuntados al crear la suscripción

Campos del arreglo `transactions`

Cada elemento del arreglo transactions representa un cargo ejecutado bajo la suscripción.

Identificadores de la transacción

Campo	Descripción
`ticket_code`	Número de ticket único de Kushki para este cargo
`transaction_code`	Identificador único de la transacción asignado por Kushki
`reference_transaction_code`	Código de referencia basado en UUID
`recap_code`	Código de conciliación
`subscription_code`	La suscripción a la que pertenece esta transacción
`approval_code`	Código de autorización devuelto por el emisor
`response_code`	Código de respuesta del procesador. `"000"` = exitoso
`response_description`	Respuesta del procesador legible para humanos (por ejemplo, `"Transacción aprobada"`)

Detalles de la transacción

Campo	Descripción
`create_timestamp`	Timestamp Unix (milisegundos) del momento en que se creó la transacción
`transaction_type`	Tipo de transacción (por ejemplo, `SALE`)
`transaction_status_type`	`APPROVED`, `DECLINED`, `INITIALIZED`, `VOIDED`, or `REFUNDED`
`subscription_trigger_type`	`onDemand` (disparado manualmente) o `scheduled` (automático)
`payment_method_type`	Método de pago: siempre `CARD` para los cargos de suscripción
`payment_submethod_type`	Submétodo de pago (por ejemplo, `CARD VPC`)
`payment_brand_name`	Marca de la tarjeta (por ejemplo, `Visa`, `Mastercard`)
`sync_mode_type`	Modo de procesamiento: `online` u `offline`
`kushki_info_origin_type`	Siempre `SUBSCRIPTION` para los cargos de suscripción

Monto

Campo	Descripción
`currency_code`	Siempre `COP` para Colombia
`request_amount`	Monto solicitado para esta transacción
`approved_transaction_amount`	Monto total aprobado
`subtotal_iva_amount`	Subtotal sujeto a IVA
`subtotal_iva0_amount`	Subtotal no sujeto a IVA
`iva_value`	IVA aplicado a esta transacción
`ice_value`	Impuesto ICE aplicado a esta transacción

Tarjeta y tarjetahabiente

Campo	Descripción
`card_holder_name`	Nombre del tarjetahabiente al momento de la transacción
`card_type`	`credit`, `debit` o `prepaid`
`last_four_digit_code`	Últimos cuatro dígitos de la tarjeta usada
`bin_code`	BIN de la tarjeta usada
`card_country_code`	Código ISO 3166-1 alpha-2 del país emisor de la tarjeta
`card_country_name`	Nombre completo del país emisor de la tarjeta
`foreign_card_indicator`	`true` si la tarjeta fue emitida fuera de Colombia
`prepaid_indicator`	`true` si la tarjeta es prepago
`issuing_bank_name`	Nombre del banco emisor de la tarjeta
`acquirer_bank_name`	Nombre del banco adquirente

Contacto y comercio

Campo	Descripción
`contact_detail.email`	Correo del tarjetahabiente al momento de la transacción
`contact_detail.first_name` / `last_name`	Nombre del tarjetahabiente
`contact_detail.phone`	Teléfono del tarjetahabiente en formato E.164
`contact_email`	Correo de contacto principal (el mismo que `contact_detail.email`)
`merchant_code`	Identificador del comercio
`merchant_name`	Nombre visible del comercio
`country_name`	País donde se procesó la transacción
`processor_name`	Procesador de pago que gestionó la transacción
`processor_type`	Modelo de procesamiento (por ejemplo, `aggregator_formal`, `acquirer`)
`metadata_object`	Metadatos personalizados adjuntados al momento del cargo (puede incluir `fraudData`)
`subscription_metadata_object`	Metadatos almacenados a nivel de la suscripción

Respuesta de ejemplo

{
  "active_indicator": true,
  "subscription_code": "177493387604666666",
  "plan_name": "Plan mensual Colombia",
  "periodicity_type": "monthly",
  "day_of_month": 5,
  "card_holder_name": "Carlos Pérez",
  "card_type": "credit",
  "last_four_digit_code": "4321",
  "expiry_month": "09",
  "expiry_year": "27",
  "amount_object": {
    "currency": "COP",
    "subtotalIva0": 50000,
    "subtotalIva": 0,
    "iva": 0,
    "ice": 0
  },
  "contact_details_object": {
    "email": "carlos.perez@example.com",
    "firstName": "Carlos",
    "lastName": "Pérez"
  },
  "create_timestamp": 1760313600,
  "last_charge_timestamp": 1774459991,
  "merchant_code": "20000000106913436000",
  "merchant_country_name": "Colombia",
  "transactions": [
    {
      "ticket_code": "754812488659082161",
      "transaction_code": "526505389111678151",
      "transaction_status_type": "APPROVED",
      "transaction_type": "SALE",
      "subscription_trigger_type": "scheduled",
      "currency_code": "COP",
      "approved_transaction_amount": 50000,
      "request_amount": 50000,
      "iva_value": 0,
      "card_holder_name": "Carlos Pérez",
      "card_type": "credit",
      "last_four_digit_code": "4321",
      "payment_brand_name": "Visa",
      "response_code": "000",
      "response_description": "Transacción aprobada",
      "approval_code": "123456",
      "create_timestamp": 1774459991000
    }
  ],
  "pagination": null
}

Autenticación

⚠️ Mantén esta credencial segura. Nunca expongas tu Private-Merchant-Id en código del lado del cliente o del frontend.

Uso de la API

🟢 Producción

🧪 Sandbox (UAT)

https://api.kushkipagos.com/

Endpoints disponibles

Consultar transacciones de suscripción

Devuelve los detalles completos de una suscripción y la lista de transacciones cobradas dentro del rango de fechas solicitado.

¿Tienes una sugerencia sobre esta documentación? Contáctanos.

Transacciones de suscripción

Obtener las transacciones de una suscripción#

Parámetro de ruta#

Parámetros de consulta#

Estructura de la respuesta#

Campos de metadatos de la suscripción#

Campos del arreglo transactions#

Respuesta de ejemplo#

Autenticación#

Uso de la API#

Endpoints disponibles#