Fraud Report

ℹ️ Esta API reemplaza el flujo legado de reporte de fraude por SFTP/CSV. Si estás migrando desde ese flujo, confirma con tu representante de Kushki si aún es necesario para tu cuenta.

Consulta por rango de fechas#

POST /data/v1/fraud
{
  "brand": "VISA",
  "country": "PER",
  "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 6 meses de antigüedad respecto a la fecha actual. Un from con más de 6 meses de antigüedad devuelve un error de validación.
⚠️ Formato de fecha: from y to deben usar el formato exacto YYYY-MM-DDThh:mm:ss (sin milisegundos ni zona horaria). Cualquier otro formato devuelve un error de validación.
Respuesta:

{
  "data": [
    {
      "source_name": "TC40",
      "transaction_reference": "32160b0d-4591-4691-acc8-44b4c8821627",
      "transaction_arn": "12710244268000000000007",
      "customer_id": "20000000104030134000",
      "merchant_id": "6000000000172710548457113030",
      "merchant_name": "PEAKY BLINDERS COLOMBIA",
      "acquirer_bin": "021193",
      "masked_pan": "549151XXXXXX7016",
      "reference_number": "426822110550",
      "total_amount": 2900,
      "fraud_type": "00",
      "incoming_date": 1784127600,
      "pos_entry_mode": "81"
    },
    {
      "source_name": "SAFE",
      "transaction_reference": "6ef09b5a-6ce6-443e-a7dd-c42024e097b2",
      "transaction_arn": "12231965093000000136802",
      "customer_id": "20000000104030134000",
      "merchant_id": "20000328494375849",
      "merchant_name": "20004375749838594",
      "acquirer_bin": "026532",
      "masked_pan": "533187XXXXXX2822",
      "reference_number": "509300174610",
      "total_amount": 34761,
      "fraud_type": "06",
      "authorization_code": "556549",
      "card_present_indicator": "0",
      "ecommerce_indicator": "21",
      "transaction_date": "20250402",
      "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": "ba353f86-1ef4-test-test-test"
}

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

Filtrar por comercio (branch)#

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 (ej. " 20000349344" o "id1, id2" son inválidos). Enviar merchant_id solo, sin from/to, devuelve un error de validación.

Campos del request#

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

Valores de fraud_type#

VISA#

Mastercard#

⚠️ Los valores 9 (VISA) y 57 (Mastercard) se observaron en el conjunto de validación de la API, pero no están completamente documentados aún. No asumas que son válidos hasta confirmarlo.

Campos de la respuesta#

Campos de paginación#

Errores#

⚠️ Las siguientes causas de validación fueron confirmadas durante el diseño, pero aún no tienen un código de error confirmado — se agregarán apenas estén disponibles: from con más de 6 meses de antigüedad; formato de from/to inválido; brand inválido; country inválido; fraud_type que no corresponde al brand; merchant_id con espacios; más de 20 valores en merchant_id; limit mayor a 100; parámetros del body no soportados; header Private-merchant-id ausente o inválido (401).

Autenticación#

ℹ️ A pesar del nombre del header, este endpoint espera la credencial privada a nivel customer, no una credencial de branch/merchant. Los branches se filtran después usando el campo merchant_id del body.

Uso de la API#

Pendiente de confirmar — el dominio final de producción todavía no está disponible.

Endpoints disponibles#

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