Transacciones

30 octubre 2024

Obtén la lista de todas las transacciones realizadas con tu comercio a través de este servicio. Aplica filtros para obtener mejores resultados.

Este servicio está disponible para integraciones a través de Cloud terminal API, App-to-app, Terminal SDK y Raw card-present API.

Ambientes

Realiza todas las adecuaciones a tu sistema mediante pruebas en el ambiente de desarrollo dev. Recuerda que en este ambiente no se procesarán transacciones reales.

Cuando estés listo, podrás cambiar al ambiente de producción live para procesar transacciones reales.

Ambiente	Url base	Disponibilidad
`dev`	https://valquiria.billpocket.dev	Cloud Terminal API, App to app y Terminal SDK
`dev`	https://api-uat.kushkipagos.com	Raw Card-Present API
`live`	https://valquiria.billpocket.com	Cloud Terminal API, App to app y Terminal SDK
`live`	https://api.kushkipagos.com	Raw Card-Present API

Cloud terminal API, App to app y Terminal SDK

Token

Es necesario generar un token de aplicación a través del endpoint Get token enviando tu token de usuario en el payload. Si la solicitud es correcta, obtendrás el token de aplicación el cuál deberás utilizar al momento de obtener el listado de transacciones.

Ejemplo de solicitud de token:

{
  "token": "48d8fc2257eb61d4814e9cae3fd7385dfedf51133017b35f7a86d113620da413"
}

Ejemplo de respuesta:

{
  "token": "eyJhbGciOiJIUzI1NiIsInC5cCI6LppXVCJ9.eyJ1c2VyX3Rva2VuIjoiNDhkOGZjMjI1N2VjNjFkNDgzNGU5Y2FlM2ZkNzM4NgRmXWRmNTExOTQ8MTdiMzVmN2E4NmQxMTM2MjBkYTQxMyIsImlhdCI6MTY5NDQ3Mjc2NywiZXhwIjoxNak0NDb2Mzs3fQ.KWgOEItUQhjWQR1gp8-lU1CjugQCVRMd4_lHXGGkDac"
}

Revisa la referencia api para más información.

Lista de transacciones

Obtén la lista de transacciones en un rango de fechas específicas. Por defecto, se regresan 100 elementos por solicitud pero puedes configurar hasta un máximo de 600 elementos por solicitud. Las transacciones están ordenadas por la más reciente primero.

Consume el endpoint Get transaction list o Get transaction list v2 enviando tu token de aplicación en el encabezado Authorization y estableciendo los filtros como parámetros en la url.

Descubre todos los filtros que puedes configurar al momento de enviar una solicitud para obtener la lista de transacciones.

V1:

Propiedad	Requerido	Valores permitidos	Descripción
dateFrom	Sí		Busca transacciones desde una fecha específica. Formato yyyy-mm-ddthh:mm:ss.
dateTo	Sí		Busca transacciones hasta una fecha específica. Formato yyyy-mm-ddthh:mm:ss.
bin	No		Filtra por número de BIN.
captureMethod	No	`ec`, `emvf`, `nfc`, `msc`, `key`, `rec`,	Filtra por método de captura.
card	No		Filtra por número de tarjeta enmascarada.
device	No		Filtra por nombre de dispositivo.
page	No		Indica el número de página de los resultados.
size	No		Número de transacciones a devolver. Por defecto: 100, máximo 600.
transactionStatus	No	`aprobada`, `pendiente`, `rechazadaRiesgo`, `rechazada`, `rechazadaProsa`	Filtra por estado de la transacción.
transactionType	No	`venta`, `devolucion`, `checkout`	Filtra por tipo de transacción.
transactionId	No		Filtra por id de la transacción.
reference	No		Filtra por referencia de la transacción.

V2:

Propiedad	Requerido	Valores permitidos	Descripción
dateFrom	Sí		Busca transacciones desde una fecha específica. Formato yyyy-mm-ddthh:mm:ss.
dateTo	Sí		Busca transacciones hasta una fecha específica. Formato yyyy-mm-ddthh:mm:ss.
bin	No		Filtra por número de BIN.
captureMethod	No	`ec`, `emvf`, `nfc`, `msc`, `key`, `rec`,	Filtra por método de captura.
card	No		Filtra por número de tarjeta enmascarada.
device	No		Filtra por nombre de dispositivo.
page	No		Indica el número de página de los resultados.
size	No		Número de transacciones a devolver. Por defecto: 100, máximo 600.
transactionStatus	No	`aprobada`, `pendiente`, `rechazadaRiesgo`, `rechazada`, `rechazadaProsa`	Filtra por estado de la transacción.
transactionType	No	`venta`, `devolucion`, `checkout`	Filtra por tipo de transacción.
transactionId	No		Filtra por id de la transacción.
reference	No		Filtra por referencia de la transacción.
uniqueReference	No		Filtra por referencia única de la transacción. Requerida versión de la aplicación 5.0.3 o superior para recibir esta propiedad a través de integraciones Cloud Terminal API.

Ejemplo de solicitud con filtros:

https://valquiria.billpocket.dev/api/v1/transactions/?dateFrom=2022-01-11T10:20:00&dateTo=2023-06-20T11:59:00&size=4&page=2&device=test&bin=557908&captureMethod=ec&transactionStatus=rechazadaRiesgo&transactionType=devolucion&card=310583******5037

Respuesta

Si la información enviada es correcta y existen transacciones en el rango especificado, recibirás un objeto con la lista de transacciones disponibles.

Ejemplo de solicitud exitosa:

V1:

{
  "data": [
    {
      "transaction_id": 194402170,
      "authorization_number": "",
      "bank": "BANCOMER",
      "card_brand": "Visa",
      "card_type": "DEBIT",
      "capture_method": "nfc",
      "commission": 0.88,
      "countercharged": false,
      "date": "2024-05-14T10:40:57.000Z",
      "details": "Prueba 2",
      "device": "Test device 0001",
      "error_detail": "Transacción no procesada. Fondos insuficientes. Contactar al emisor",
      "masked_card": "424242******4242",
      "msi": null,
      "retention": 0,
      "rejection_code": "51",
      "subtotal": 23.98,
      "surcharge": 0,
      "tip": 0,
      "total_amount": 25,
      "transaction_type": "venta",
      "transaction_status": "rechazadaProsa",
      "vat": 0.14
    },
    {
      "transaction_id": 105242,
      "authorization_number": "BP4460",
      "bank": "BANCOMER",
      "card_brand": "Visa",
      "card_type": "CREDIT",
      "capture_method": "ec",
      "commission": 8.94,
      "countercharged": false,
      "date": "2022-03-11T13:48:12.000Z",
      "details": "Prueba 1",
      "device": "ECOMMDEV01",
      "error_detail": "",
      "masked_card": "424242******4242",
      "msi": null,
      "retention": 0.93,
      "rejection_code": null,
      "subtotal": 437.71,
      "surcharge": 0,
      "tip": 0,
      "total_amount": 449,
      "transaction_type": "venta",
      "transaction_status": "aprobada",
      "vat": 1.43
    }
  ],
  "currentPage": 1,
  "perPage": 4,
  "total": 456
}

V2:

{
  "data": [
    {
      "msi": null,
      "tip": 0,
      "vat": 0.08,
      "bank": null,
      "date": "2024-07-11T16:53:29.000Z",
      "device": "Device 1",
      "details": null,
      "cardType": null,
      "subtotal": 13.48,
      "cardBrand": "Visa",
      "retention": 0,
      "surcharge": 0,
      "chargeback": false,
      "commission": 0.49,
      "maskedCard": "400000******0002",
      "errorDetail": "",
      "totalAmount": 14.05,
      "captureMethod": "msc",
      "rejectionCode": null,
      "transactionId": 130001,
      "transactionType": "devolucion",
      "uniqueReference": "3740d203-c6fb-46fb-83f5-6b29c9195fa8",
      "transactionStatus": "pendiente",
      "authorizationNumber": ""
    },
    {
      "msi": null,
      "tip": 0,
      "vat": 0.08,
      "bank": null,
      "date": "2024-07-11T16:46:18.000Z",
      "device": "Device 1",
      "details": null,
      "cardType": "CREDIT",
      "subtotal": 13.48,
      "cardBrand": "Visa",
      "retention": 0,
      "surcharge": 0,
      "chargeback": false,
      "commission": 0.49,
      "maskedCard": "400000******0002",
      "errorDetail": "",
      "totalAmount": 14.05,
      "captureMethod": "msc",
      "rejectionCode": null,
      "transactionId": 130002,
      "transactionType": "venta",
      "uniqueReference": "2d20aa4b-a26e-4117-90a0-9b0c0d9a19e1",
      "transactionStatus": "aprobada",
      "authorizationNumber": "BP6001"
    },
    {
      "msi": null,
      "tip": 0,
      "vat": 0.56,
      "bank": null,
      "date": "2024-07-11T15:09:44.000Z",
      "device": "ECOMMDEV00061529",
      "details": null,
      "cardType": null,
      "subtotal": 95.94,
      "cardBrand": "Visa",
      "retention": 0,
      "surcharge": 0,
      "chargeback": false,
      "commission": 3.5,
      "maskedCard": "400000******0002",
      "errorDetail": "Rechazo por reglas internas",
      "totalAmount": 100,
      "captureMethod": "ec",
      "rejectionCode": null,
      "transactionId": 130003,
      "transactionType": "devolucion",
      "uniqueReference": "",
      "transactionStatus": "rechazada",
      "authorizationNumber": ""
    }
  ],
  "total": 31,
  "perPage": 100,
  "currentPage": 1
}

Ejemplo de solicitud con error (V1 y V2):

{
  "message": [
    "dateTo is required"
  ]
}

Revisa la referencia de Transacciones para más información.

Raw card-present API

Lista de transacciones

Obtén la lista de transacciones estableciendo el número de elementos a devolver así como la página de los resultados (en caso de que existan varias). Máximo 10,000 resultados devueltos por solicitud.

Consume el endpoint Transaction Search enviando tu clave privada en el encabezado Private-Credential-Id y estableciendo los filtros necesarios en el cuerpo de la petición.

Descubre todos los filtros que puedes configurar al momento de enviar una solicitud para obtener la lista de transacciones.

Propiedad	Requerido	Valores permitidos	Descripción
page	Sí		Establece el número de página de los resultados.
size	Sí		Establece el número de elementos devueltos por solicitud. Máximo 500 elementos por página.
filters.bin	No		Filtra por número de BIN.
filters.client_transaction_id	No		Filtra por id de transacción generado de tu lado.
filters.end_date	No		Establece una rango de fecha para consulta de transacciones.
filters.start_date	No		Establece una rango de fecha para consulta de transacciones.
filters.last_four_digits	No		Filtra por los últimos 4 dígitos de la tarjeta.
filters.transaction_reference	No		Filtra por id de la transacción (generado por Kushki).
filters.transaction_type	No	`balanceInquiry`, `capture`, `charge`, `checkIn`, `checkout`, `preAuth`, `reAuthorization`, `tip`, `posTip`	Filtra por tipo de operación.

Ejemplo de solicitud con filtros:

{
  "page": 1,
  "size": 10,
  "filters": {
    "bin": "541333",
    "end_date": 1712322035152,
    "start_date": 1712286000000,
    "last_four_digits": "0653",
    "transaction_type": "preAuth",
    "client_transaction_id": "5bba557f-3df8-4f07-be20-ed1ad6b28c1d",
    "transaction_reference": "62c64ab2-1b09-48bd-ab98-4fa9b1893250"
  }
}

Respuesta

Si la información enviada es correcta y existen transacciones en el rango especificado, recibirás un objeto con la lista de transacciones disponibles:

{
  "items": [
    {
      "amount": {
        "extra_taxes": {}
      },
      "deferred": {},
      "merchant_id": "20000000106781760000",
      "pos_details": {},
      "reading_type": "ICC",
      "payment_brand": "VISA",
      "transaction_type": "PREAUTH",
      "transaction_status": "DECLINED",
      "transaction_reference": "Test_Webhook_PREAUTH_D"
    }
  ]
}

Revisa la referencia de Transacciones para más información.

Anula un pago

Anula un pago previamente autorizado.