One-time payments - Kushki Developer Portal

El endpoint de pagos únicos procesa cargos presenciales directamente desde tu terminal POS en Chile. Un solo endpoint maneja todos los canales de lectura y variantes de cargo: cargos estándar, diferido en cuotas (Cuotas Comercio y Cuotas Emisor), cashback y propina.

Tipos de cargo

Tipo	Cómo activarlo
Cargo único	`transaction_type: "charge"`, `transaction_mode: "Authorization"`
Cuotas Emisor (Issuer Installments)	Igual que el anterior + `is_deferred: true` + `deferred.months`
Cuotas Comercio (Merchant Installments)	Igual que el anterior + `is_deferred: true` + `deferred.months` + `deferred.credit_type: "03"`
Cashback	Igual que el cargo único + `is_cashback: true` + `cashback_amount`
Propina	Igual que el cargo único + `amount.tip`

Canales de lectura

Valor	Canal
`ICC`	Chip (Integrated Circuit Card)
`MCR`	Banda magnética
`NFC`	Contactless

Cargo único

Los campos del request varían un poco según el canal de lectura (card_details.reading_type): elige una pestaña para ver los campos exactos de chip (ICC), banda magnética (MCR) o contactless (NFC).

ICC (Chip)

MCR (Banda magnética)

NFC (Contactless)

{
"amount": {
"currency": "CLP",
"iva": 0,
"subtotal_iva": 0,
"subtotal_iva0": 60000,
"tip": 0,
"extra_taxes": {
  "airport_tax": 0,
  "iac": 0,
  "ice": 0,
  "travel_agency": 0
}
},
"card_details": {
"enc_tlv": "CE447A062C49774934E42A7F826668C0C478E38402C158062EE794C0E471B43EA8CE49C256C2C8B157526B0B2BE74FC23F65E18D4F52B99A1A0910E6CCD9B11A32D6D537E2B6E2B011C89569DE6A3D53318080BC77E0E70B398ED3083FD7366CCF8FB4DBF34A116E6D52CFBEF26371878D842034E5029EF62DF235D2C427F04102E451773D9E8975978917E3BC531327702967052E239F8C592734AE14688E603C52B858FC1D97B763AE623603F1475FFFB065EC07AF7A29",
"pin_ksn": "FFFF4357486333600002",
"reading_type": "ICC",
"tracks": {
  "enc_track2": "283587285CE10278E7FA50AD5C97CFFE87F472C9FE6406F8",
  "track_ksn": "FFFF4357486333600002"
}
},
"card": {
"card_holder_name": "John Doe"
},
"contact_details": {
"document_number": "",
"document_type": "-1",
"email": "",
"first_name": "",
"last_name": "",
"second_last_name": "",
"phone_number": ""
},
"pos_details": {
"brand": "SUNMI",
"model": "P2-EU",
"terminal_id": "PB04216R20537",
"version": "Kushki SunmiV1.1.26",
"has_print": true,
"location": {
  "latitude": -0.22480833333333333,
  "longitude": -78.487955
},
"user": "juan.perez",
"friendly_name": "Caja principal",
"serial": "SN123456",
"type": "COUNTERTOP",
"connectivity": "WIFI"
},
"country": "CHL",
"is_deferred": false,
"client_transaction_id": "6680eadc-6c8d-44aa-8ca0-18e061c1472a",
"merchant_id": "0987654321",
"transaction_type": "charge",
"transaction_mode": "Authorization",
"is_cashback": false,
"cvm_type": "none"
}

Cargos diferidos

Llama siempre primero al endpoint de consulta de BIN para confirmar que la tarjeta admite cuotas y obtener las opciones válidas para el BIN del tarjetahabiente.

Beta

Las Cuotas Comercio (Merchant Installments) están en fase Beta. Contacta al equipo de Kushki para habilitar esta funcionalidad en tu consola.

Cuotas Comercio (Merchant Installments) — de 2 a 12 meses

Envía credit_type: "03" dentro del objeto deferred.

{
  "transaction_type": "charge",
  "transaction_mode": "Authorization",
  "country": "CHL",
  "client_transaction_id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
  "is_deferred": true,
  "deferred": {
    "months": "6",
    "credit_type": "03"
  },
  "amount": {
    "currency": "CLP",
    "subtotal_iva": 0,
    "subtotal_iva0": 30000,
    "iva": 0,
    "tip": 0
  },
  "card_details": {
    "reading_type": "NFC",
    "enc_tlv": "<encrypted-tlv>",
    "pin_ksn": "<ksn-value>",
    "tracks": {
      "enc_track2": "<encrypted-track2>",
      "track_ksn": "<ksn-value>"
    }
  },
  "cvm_type": "none",
  "pos_details": {
    "brand": "SUNMI",
    "model": "P2-EU",
    "version": "Kushki SunmiV1.1.28",
    "has_print": true,
    "terminal_id": "PB04209860189"
  }
}

Cuotas Emisor (Issuer Installments) — de 2 a 48 meses

Omite credit_type: el emisor administra el plan de cuotas.

{
  "transaction_type": "charge",
  "transaction_mode": "Authorization",
  "country": "CHL",
  "client_transaction_id": "c3d4e5f6-a7b8-9012-cdef-34567890abcd",
  "is_deferred": true,
  "deferred": {
    "months": "12"
  },
  "amount": {
    "currency": "CLP",
    "subtotal_iva": 0,
    "subtotal_iva0": 50000,
    "iva": 0,
    "tip": 0
  },
  "card_details": {
    "reading_type": "ICC",
    "enc_tlv": "<encrypted-tlv>",
    "pin_ksn": "<ksn-value>",
    "tracks": {
      "enc_track2": "<encrypted-track2>",
      "track_ksn": "<ksn-value>"
    }
  },
  "cvm_type": "pin",
  "pos_details": {
    "brand": "SUNMI",
    "model": "P2-EU",
    "version": "Kushki SunmiV1.1.28",
    "has_print": true,
    "terminal_id": "PB04216R20537"
  }
}

Cashback

Chile admite cashback al momento del pago. Pon is_cashback: true e incluye cashback_amount.

{
  "transaction_type": "charge",
  "transaction_mode": "Authorization",
  "country": "CHL",
  "client_transaction_id": "d4e5f6a7-b8c9-0123-def0-456789abcdef",
  "is_cashback": true,
  "cashback_amount": 2000,
  "amount": {
    "currency": "CLP",
    "subtotal_iva": 0,
    "subtotal_iva0": 10000,
    "iva": 0,
    "tip": 0
  },
  "card_details": {
    "reading_type": "MCR",
    "tracks": {
      "enc_track1": "<encrypted-track1>",
      "enc_track2": "<encrypted-track2>"
    },
    "pin_ksn": "<ksn-value>"
  },
  "cvm_type": "pin",
  "pos_details": {
    "brand": "SUNMI",
    "model": "P2-EU",
    "version": "Kushki SunmiV1.1.28",
    "has_print": true,
    "terminal_id": "PB04209860189"
  }
}

WARNING

El cashback solo está disponible con tarjetas locales y no está soportado para transacciones NFC.

Modelo agregador

Para facilitadores de pago o marketplaces, incluye el objeto sub_merchant.

{
  "transaction_type": "charge",
  "transaction_mode": "Authorization",
  "country": "CHL",
  "client_transaction_id": "e5f6a7b8-c9d0-1234-ef01-567890abcdef",
  "amount": {
    "currency": "CLP",
    "subtotal_iva": 0,
    "subtotal_iva0": 15000,
    "iva": 0
  },
  "card_details": {
    "reading_type": "ICC",
    "enc_tlv": "<encrypted-tlv>",
    "pin_ksn": "<ksn-value>",
    "tracks": {
      "enc_track2": "<encrypted-track2>",
      "track_ksn": "<ksn-value>"
    }
  },
  "cvm_type": "pin",
  "sub_merchant": {
    "mcc": "5411",
    "id_affiliation": "987654321",
    "soft_descriptor": "Mi Comercio Chile",
    "city": "Santiago",
    "country_ans": "CHL",
    "zip_code": "7550000",
    "address": "Av. Apoquindo 4501",
    "social_reason": "Mi Comercio Chile SpA",
    "code": "SUB001CHL"
  },
  "pos_details": {
    "brand": "SUNMI",
    "model": "P2-EU",
    "version": "Kushki SunmiV1.1.28",
    "has_print": true,
    "terminal_id": "PB04209860189"
  }
}

Campos del request

Campos de primer nivel

Campo	Obligatorio	Descripción
`transaction_type`	Sí	`"charge"` para un pago único.
`transaction_mode`	Sí	`"Authorization"` para cobrar de inmediato.
`country`	Sí	ISO 3166-1 alpha-3. Debe ser `"CHL"`.
`client_transaction_id`	Sí	UUID v4 generado por el comercio. Debe ser único por transacción.
`is_deferred`	No	Ponlo en `true` para diferir el cargo.
`deferred`	No	Obligatorio cuando `is_deferred` es `true`.
`is_cashback`	No	Ponlo en `true` para incluir un monto de cashback.
`cashback_amount`	No	Obligatorio cuando `is_cashback` es `true`.
`cvm_type`	Sí	Método de verificación del tarjetahabiente: `"none"`, `"pin"` o `"signature"`.
`contact_details`	Sí	Datos de contacto del tarjetahabiente. Para Chile, envía `document_type: "-1"` (sin documento): los valores `"0"` y `"1"` de `document_type` aplican solo a Colombia.
`sub_merchant`	No	Modelo agregador: datos del subcomercio.
`metadata`	No	Objeto llave-valor con datos adicionales.

`amount`

Campo	Obligatorio	Descripción
`currency`	Sí	Debe ser `"CLP"`. CLP no tiene decimales: usa solo enteros.
`subtotal_iva`	Sí	Subtotal afecto a IVA. Ponlo en `0`: en Chile el IVA no se aplica a nivel de POS con este campo.
`subtotal_iva0`	Sí	Monto total de la transacción (sin impuestos).
`iva`	Sí	Monto del IVA. Ponlo en `0`.
`tip`	No	Monto de la propina en CLP.
`extra_taxes`	No	Impuestos adicionales: `airport_tax`, `iac`, `ice`, `travel_agency`.

`deferred`

Campo	Obligatorio	Descripción
`months`	Sí	Cantidad de meses de diferido. Cuotas Comercio: 2–12. Cuotas Emisor: 2–48.
`credit_type`	No	Envía `"03"` para Cuotas Comercio (Merchant Installments). Omítelo para Cuotas Emisor.

`card_details`

Campo	Obligatorio	Descripción
`reading_type`	Sí	`"ICC"`, `"MCR"` o `"NFC"`.
`enc_tlv`	No	Datos TLV cifrados (obligatorio para ICC y NFC).
`pin_block`	No	PIN block cifrado para transacciones con PIN en línea.
`pin_ksn`	No	Key serial number (KSN) del PIN o del TLV.
`tracks.enc_track1`	No	Track 1 cifrado (obligatorio solo para MCR).
`tracks.enc_track2`	No	Track 2 cifrado (obligatorio para ICC, MCR y NFC).
`tracks.track_ksn`	No	KSN del Track 2 (ICC y NFC).

`pos_details`

Campo	Obligatorio	Descripción
`terminal_id`	Sí	Identificador de la terminal asignado por Kushki.
`brand`	Sí	Marca de la terminal (por ejemplo, `"SUNMI"`).
`model`	No	Modelo de la terminal (por ejemplo, `"P2-EU"`).
`version`	No	Versión del software de la terminal.
`has_print`	No	`true` si la terminal tiene impresora (comprobante).
`location`	No	`{ "latitude": -33.4489, "longitude": -70.6693 }`: coordenadas GPS de la terminal.
`user`	No	Usuario operador del dispositivo.
`friendly_name`	No	Nombre visible asignado a la terminal (por ejemplo, `"Caja principal"`).
`serial`	No	Número de serie del dispositivo.
`type`	No	Tipo físico del dispositivo POS. Valores permitidos: `COUNTERTOP`, `MPOS`, `SELF_SERVICE`, `OTHER`, `SMARTPOS`.
`connectivity`	No	Tipo de conectividad de red del dispositivo. Valores permitidos: `GPRS`, `WIFI`, `ETHERNET`, `DIAL_UP`, `OTHER`.

Autenticación

Entornos

🟢 Producción

🧪 Sandbox (UAT)

https://api.kushkipagos.com/

Endpoints disponibles

Procesar un pago presencial

Envía una transacción única en POS — cargo estándar, Cuotas Comercio, Cuotas Emisor, cashback o propina — con lectura ICC, MCR o NFC.

¿Tienes una sugerencia sobre esta documentación? Escríbenos.

Pagos únicos

Tipos de cargo#

Canales de lectura#

Cargo único#

Cargos diferidos#

Cuotas Comercio (Merchant Installments) — de 2 a 12 meses#

Cuotas Emisor (Issuer Installments) — de 2 a 48 meses#

Cashback#

Modelo agregador#

Campos del request#

Campos de primer nivel#

amount#

deferred#

card_details#

pos_details#

Autenticación#

Entornos#

Endpoints disponibles#

Tipos de cargo

Canales de lectura

Cargo único

Cargos diferidos

Cuotas Comercio (Merchant Installments) — de 2 a 12 meses

Cuotas Emisor (Issuer Installments) — de 2 a 48 meses

Cashback

Modelo agregador

Campos del request

Campos de primer nivel

`amount`

`deferred`

`card_details`

`pos_details`

Autenticación

Entornos

Endpoints disponibles