Reporte de fraude

⚠️ Disponibilidad: este reporte solo está disponible para transacciones hechas con tarjetas VISA y MASTERCARD, y solo para la adquirencia de Kushki.

⛔ México: este reporte no está disponible para transacciones domésticas en México (PROSA). 🇲🇽

⚠️ Uso a nivel de customer: la API se autentica y se consume a nivel de customer, no a nivel de un comercio o sucursal individual. Una sola credencial da visibilidad sobre todas las alertas de fraude de las sucursales asociadas a ese customer. Para acotar una consulta a uno o varios comercios específicos, usa el filtro merchant_id (ve Filtrar por comercio (sucursal) más abajo) — no existe una credencial de solo sucursal para este endpoint.

ℹ️ Esta API reemplaza el flujo antiguo del reporte de fraude por SFTP/CSV. Si estás migrando desde ese flujo, contacta a tu representante de Kushki para coordinar la transición.

Consulta por rango de fechas#

POST /data/v1/fraud
{
  "brand": "VISA",
  "country": "CHL",
  "from": "2026-03-02T15:04:05",
  "to": "2026-05-02T15:04:05",
  "limit": 100,
  "page": 1
}

⚠️ Límite de antigüedad: las consultas están limitadas a un máximo de 12 meses desde la fecha actual. Un valor de from con más de 12 meses de antigüedad devuelve un error de validación.

⚠️ Formato de fecha: from y to deben usar exactamente el formato YYYY-MM-DDThh:mm:ss, sin milisegundos y sin zona horaria. Cualquier otro formato devuelve un error de validación.

{
  "data": [
    {
      "source_name": "TC40",
      "transaction_reference": "32160b0d-4591-4691-acc8-44b4c8821627",
      "transaction_arn": "12710244268000000000007",
      "customer_id": "20000000104030134000",
      "merchant_id": "6000000000172710548457113030",
      "merchant_name": "DEMO STORE",
      "acquirer_bin": "021193",
      "masked_pan": "549151XXXXXX7016",
      "reference_number": "426822110550",
      "total_amount": 2900,
      "fraud_type": "00",
      "incoming_date": 1784127600,
      "pos_entry_mode": "81",
      "mcc_code": "5812",
      "purchase_date": "0402"
    },
    {
      "source_name": "SAFE",
      "transaction_reference": "6ef09b5a-6ce6-443e-a7dd-c42024e097b2",
      "transaction_arn": "12231965093000000136802",
      "customer_id": "20000000104030134000",
      "merchant_id": "20000328494375849",
      "merchant_name": "DEMO STORE",
      "acquirer_bin": "026532",
      "masked_pan": "533187XXXXXX2822",
      "reference_number": "509300174610",
      "total_amount": 34761,
      "fraud_type": "06",
      "authorization_code": "556549",
      "card_present_indicator": "0",
      "chargeback_indicator": "3",
      "ecommerce_indicator": "21",
      "reception_date": "20260409",
      "transaction_date": "20260402",
      "transaction_time": "211008"
    }
  ],
  "page": 1,
  "page_size": 100,
  "total": 9,
  "total_pages": 1
}

Consulta por identificador de transacción#

POST /data/v1/fraud
{
  "transaction_reference": "32160b0d-4591-4691-acc8-44b4c8821627"
}

ℹ️ Si envías transaction_arn y transaction_reference al mismo tiempo, transaction_arn tiene precedencia y transaction_reference se ignora. En este modo, from y to no son obligatorios.

Filtrar por comercio (sucursal)#

POST /data/v1/fraud
{
  "from": "2026-01-01T00:00:00",
  "to": "2026-06-30T23:59:59",
  "merchant_id": "20000328494375843,20000328494375845,20000328494375849"
}

⚠️ Se admiten hasta 20 IDs separados por coma. Los valores no deben contener espacios, ni al inicio del valor ni después de una coma — por ejemplo, " 20000349344" y "id1, id2" no son válidos. Enviar merchant_id solo, sin from y to, devuelve un error de validación.

Campos del request#

ℹ️ Enviar cualquier campo que no esté listado arriba también devuelve un error de validación.

Valores de tipo de fraude#

VISA#

Mastercard#

Campos de la respuesta#

Campos de paginación#

Errores#

Autenticación#

ℹ️ ¿Dónde obtener la credencial? La puedes obtener directamente desde la Kushki Console, en Developers → Credentials. No se envía al customer por correo y no requiere ninguna solicitud a un ingeniero de preventa.

⚠️ A pesar del nombre de la cabecera, la credencial que espera este endpoint es la credencial del customer, no la de un comercio o sucursal individual. Autentícate siempre con la credencial privada a nivel de customer; una credencial de sucursal no es válida para este endpoint. Para acotar una consulta a comercios específicos, usa el campo merchant_id en el body en lugar de cambiar de credencial.

Usar la API#

https://api.kushkipagos.com/

Endpoints disponibles#

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