Subscription Transactions - Kushki Developer Portal

Consulta las transacciones cobradas en una suscripción.

Este servicio permite a los comercios obtener el detalle completo de una suscripción junto con la lista de transacciones que se han cobrado en ella, filtradas por un rango de fechas y con un límite opcional de resultados.

¡Ten en cuenta!

Este endpoint requiere tu Private Key (Private-Merchant-Id) para autenticarte. Guarda esta credencial de forma segura y nunca la expongas en el código del lado del cliente.

Cómo funciona

Envía una solicitud GET a /data/v1/subscription/{subscriptionId} usando como parámetro de ruta el ID de la suscripción que quieres consultar. La respuesta contiene dos secciones principales:

Detalles de la suscripción

Metadatos estáticos de la suscripción — datos de la tarjeta, nombre del plan, periodicidad, datos de contacto, desglose del monto y marcas de tiempo.

Arreglo de transacciones

La lista de cargos ejecutados en esa suscripción dentro del rango de fechas solicitado, con estado, montos y detalles del procesador.

El parámetro de ruta subscriptionId es el valor que se devuelve como subscriptionId al crear una suscripción con POST /subscriptions/v1/card.

Parámetros de consulta

Todos los parámetros de consulta son opcionales. Si los omites, se aplican estos valores por defecto:

Parámetro	Tipo	Por defecto	Descripción
`size`	integer	`100`	Número máximo de transacciones a devolver. Debe ser un entero positivo.
`start`	date (`YYYY-MM-DD`)	5 días antes de la solicitud	Inicio del rango de fechas. Solo se devuelven las transacciones creadas en esta fecha o después.
`end`	date (`YYYY-MM-DD`)	Momento de la solicitud	Fin del rango de fechas. Solo se devuelven las transacciones creadas en esta fecha o antes.

Ejemplo de solicitud:

Estructura de la respuesta

Detalles de la suscripción

Los campos del nivel raíz describen la suscripción en sí — estos datos son estáticos y reflejan la configuración de la suscripción al momento de la consulta.

Identificación y estado

Periodicidad y programación

Tarjeta y contacto

Monto

Campo	Tipo	Descripción
`subscription_code`	string	Identificador único de la suscripción. Es el mismo valor que `subscriptionId`.
`active_indicator`	boolean	Indica si la suscripción está activa actualmente.
`plan_name`	string	Nombre del plan asociado a la suscripción.
`provider_name`	string	Proveedor de pagos que procesa la suscripción (por ejemplo, `kushki`).
`reference_transaction_code`	string	Código de referencia de la transacción de validación inicial usada para registrar la tarjeta.

Arreglo de transacciones

Cada objeto dentro del arreglo transactions[] representa un cargo ejecutado en la suscripción.

Identificación y estado

Montos e impuestos

Tarjeta y procesador

Contacto y metadatos

Campo	Tipo	Descripción
`_id`	string	Identificador único interno del registro de la transacción.
`ticket_code`	string	Número de ticket asignado por Kushki.
`transaction_code`	string	Identificador único de la transacción asignado por Kushki.
`approval_code`	string	Código de autorización que devuelve el emisor cuando aprueba el cargo.
`recap_code`	string	Código de conciliación de la transacción.
`reference_transaction_code`	string	Código de referencia de esta transacción, basado en UUID.
`subscription_code`	string	Identificador de la suscripción a la que pertenece esta transacción.
`transaction_status_type`	string	Estado final de la transacción. Revisa los valores más abajo.
`transaction_type`	string	Tipo de transacción ejecutada. Revisa los valores más abajo.
`subscription_trigger_type`	string	Cómo se disparó el cargo: `onDemand` o `scheduled`.
`create_timestamp`	number	Marca de tiempo Unix (en milisegundos) de cuándo se creó la transacción.

Valores de estado de la transacción:

`transaction_status_type`	Significado
`APPROVED`	El cargo se autorizó y capturó correctamente
`DECLINED`	El emisor rechazó el cargo
`INITIALIZED`	El cargo se creó pero aún no se resuelve
`VOIDED`	El cargo se anuló antes de la liquidación
`REFUNDED`	El cargo se reembolsó al tarjetahabiente después de la liquidación

Valores de tipo de transacción:

`transaction_type`	Significado
`SALE`	Cargo estándar
`PREAUTHORIZATION`	Retención de autorización sin captura
`CAPTURE`	Confirmación de una preautorización previa
`VOID`	Anulación de un cargo
`REFUND`	Reembolso posterior a la liquidación

Códigos de error

HTTP	Código	Mensaje	Causa
`400`	`K001`	El cuerpo de la petición es inválido	Parámetros de la solicitud inválidos o mal formados
`401`	`K004`	Id de comercio no válido	Falta el `Private-Merchant-Id` o no es válido
`404`	`K037`	Subscripción no encontrada	El `subscriptionId` enviado no existe
`500`	`K002`	Ha ocurrido un error inesperado	Error inesperado del lado del servidor

Usar la API

🟢 Producción

🧪 Sandbox (UAT)

https://api.kushkipagos.com/

Endpoints disponibles

Consultar transacciones de suscripción

Devuelve los detalles de la suscripción y la lista de cargos ejecutados dentro de un rango de fechas. Requiere el Private Merchant ID.

¿Tienes una sugerencia sobre esta documentación? Contact us.

Transacciones de suscripción

Cómo funciona#

Parámetros de consulta#

Estructura de la respuesta#

Detalles de la suscripción#

Arreglo de transacciones#

Códigos de error#

Usar la API#

Endpoints disponibles#

Cómo funciona

Parámetros de consulta

Estructura de la respuesta

Detalles de la suscripción

Arreglo de transacciones

Códigos de error

Usar la API

Endpoints disponibles