Settlement - Kushki Developer Portal

El API de Settlement te permite obtener los registros de liquidación en formato JSON, sin esperar la entrega diaria del archivo CSV. Úsalo para conciliar transacciones, auditar comisiones y armar procesos automáticos de reportería.

Consultar liquidación

POST /merchant-settlement/v1/settlement

El endpoint admite dos modos de consulta mutuamente excluyentes: elige uno por solicitud.

Modo 1 — Consulta por rango de fechas

Envía startDate y endDate para obtener todos los registros de liquidación del periodo indicado. Los resultados se devuelven paginados.

Campo	Obligatorio	Descripción
`startDate`	✅	Inicio del periodo de liquidación, en formato `YYYY-MM-DD`
`endDate`	✅	Fin del periodo de liquidación, en formato `YYYY-MM-DD`
`page`		Número de página a obtener. Por defecto: `1`
`limit`		Registros por página. Por defecto: `100`

Ejemplo:

{
  "startDate": "2026-01-01",
  "endDate": "2026-01-31",
  "page": 1,
  "limit": 50
}

Modo 2 — Consulta por número de ticket

Envía un único ticketNumber para obtener el registro de liquidación de una transacción específica. Devuelve exactamente un registro en el array data. Incluye también el parámetro de consulta switch.

Campo	Obligatorio	Descripción
`ticketNumber`	✅	Número de ticket que Kushki devuelve al momento del cargo o de la captura

Parámetro de consulta:

Parámetro	Valor	Descripción
`switch`	`ecommerce`	Alcance del canal de pago — usa `ecommerce` para transacciones en línea

Ejemplo:

POST /merchant-settlement/v1/settlement?switch=ecommerce

{
  "ticketNumber": "821775714399469939"
}

Respuesta

La respuesta contiene un array data con los registros de liquidación y un objeto pagination.

Campos de `pagination`

Campo	Descripción
`page`	Número de la página actual
`limit`	Cantidad máxima de registros por página
`total`	Total de registros disponibles para el periodo consultado
`totalPages`	Total de páginas según el `limit` actual

Campos del registro de liquidación

Identificadores de la transacción

Campo	Descripción
`ticket_number`	Número de ticket único de Kushki para esta transacción
`sale_ticket_number`	Ticket de la venta original. Se llena en anulaciones y reembolsos; va vacío en las ventas
`buy_order`	Referencia de la orden que envía el comercio
`recap`	Código de conciliación de la transacción
`document_number`	Número de documento asociado a la transacción, si aplica
`approval_code`	Código de autorización que devuelve el emisor

Detalle de la transacción

Campo	Descripción
`created`	Fecha en que se creó la transacción (`YYYY-MM-DD`)
`payment_date`	Fecha en que se pagó la liquidación al comercio (`YYYY-MM-DD`)
`day` / `month`	Día y mes extraídos de la fecha de creación de la transacción
`transaction_type`	`SALE`, `VOID`, `REFUND`, `PREAUTHORIZATION` o `CAPTURE`
`transaction_status`	`APPROVED`, `DECLINED`, `VOIDED` o `REFUNDED`
`payment_method`	Método de pago usado (por ejemplo, `CARD`)
`number_of_months`	Meses de diferido aplicados. `"0"` en transacciones sin diferido
`metadata`	Metadata personalizada adjuntada al momento del cargo, si hay
`observation`	Notas adicionales sobre el registro, si hay

Datos del comercio y de la credencial

Campo	Descripción
`merchant_id`	Identificador único de tu cuenta de comercio
`merchant_name`	Nombre visible de tu cuenta de comercio
`credential_alias`	Alias de la credencial usada en la transacción
`processor_type`	Modelo de procesamiento (por ejemplo, `AGGREGATOR_FORMAL`, `ACQUIRER`)
`country`	País donde se procesó la transacción
`currency_code`	Siempre `COP` para Colombia

Detalle de la tarjeta

Campo	Descripción
`bin_card`	Primeros 6 dígitos de la tarjeta (BIN)
`card_brand`	Franquicia de la tarjeta (por ejemplo, `VISA`, `MASTERCARD`)
`card_type`	`CREDIT`, `DEBIT` o `PREPAID`
`foreign_card`	`"TRUE"` si la tarjeta se emitió fuera de Colombia
`issuing_bank`	Nombre del banco emisor de la tarjeta

Campos de transacciones en efectivo

Campo	Descripción
`cash_pin`	PIN de efectivo de la transacción, si aplica
`payment_point`	Identificador del punto de pago en efectivo, si aplica

Desglose del monto

Campo	Descripción
`approved_transaction_amount`	Monto total aprobado de la transacción
`subtotal_iva`	Subtotal gravado con IVA
`subtotal_iva0`	Subtotal no gravado con IVA
`iva_value`	Valor del IVA aplicado a la transacción
`ice_value`	Valor del impuesto ICE (Impuesto a Consumos Especiales)

Desglose de comisiones

Campo	Descripción
`variable_fee`	Monto de la comisión variable que cobra Kushki
`variable_percentage`	Tasa de la comisión variable aplicada, en porcentaje
`static_amount`	Comisión fija que se cobra por transacción
`min_fee_amount`	Monto mínimo de comisión aplicado
`kushki_commission`	Comisión total de Kushki (`variable_fee` + `static_amount`)
`iva_kushki_commission`	IVA sobre la comisión de Kushki
`kushki_amount`	Total retenido por Kushki (`kushki_commission` + `iva_kushki_commission`)
`commission_msi`	Comisión de los diferidos sin intereses
`iva_msi`	IVA sobre la comisión MSI
`fraud_retention`	Monto retenido por prevención de fraude
`adjustment`	Ajuste manual aplicado al registro
`wallet`	Monto asociado a operaciones de wallet, si aplica
`fund_release`	Monto liberado de fondos retenidos previamente
`pay_amount`	Monto neto pagado al comercio — `approved_transaction_amount` menos todas las comisiones y retenciones

Ejemplo de respuesta

{
  "data": [
    {
      "payment_date": "2026-03-10",
      "created": "2026-03-08",
      "country": "Colombia",
      "currency_code": "COP",
      "merchant_name": "Mi Comercio Colombia",
      "transaction_status": "APPROVED",
      "ticket_number": "821773035999295672",
      "transaction_type": "SALE",
      "payment_method": "CARD",
      "card_brand": "VISA",
      "card_type": "DEBIT",
      "approval_code": "000314",
      "approved_transaction_amount": "105000.00",
      "subtotal_iva": "0.0",
      "subtotal_iva0": "105000.00",
      "iva_value": "0.0",
      "variable_fee": "2993.85",
      "variable_percentage": "2.85309",
      "kushki_commission": "2993.85",
      "iva_kushki_commission": "569.83",
      "kushki_amount": "3563.68",
      "fraud_retention": "0.00",
      "adjustment": "0.00",
      "pay_amount": "101436.32"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 1245,
    "totalPages": 25
  }
}

Autenticación

⚠️ Mantén esta credencial segura. Nunca expongas tu private-merchant-id en código del cliente ni del frontend.

Usar la API

🟢 Producción

🧪 Sandbox (UAT)

https://api.kushkipagos.com/

Endpoints disponibles

Consultar liquidación

Obtiene los registros de liquidación de tu comercio por rango de fechas o por número de ticket. Devuelve el desglose completo de comisiones y el monto neto a pagar por transacción.

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

Liquidación

Consultar liquidación#

Modo 1 — Consulta por rango de fechas#

Modo 2 — Consulta por número de ticket#

Respuesta#

Campos de pagination#

Campos del registro de liquidación#

Ejemplo de respuesta#

Autenticación#

Usar la API#

Endpoints disponibles#

Consultar liquidación

Modo 1 — Consulta por rango de fechas

Modo 2 — Consulta por número de ticket

Respuesta

Campos de `pagination`

Campos del registro de liquidación

Ejemplo de respuesta

Autenticación

Usar la API

Endpoints disponibles