Two-step-payments - Kushki Developer Portal

Los pagos en dos pasos separan la autorización (retención) de la captura (cobro). Úsalos cuando necesites confirmar la transacción antes de cobrar: por ejemplo, en check-in, estaciones de servicio u hotelería.

Flujo

1. POST /pos/v1/transaction  (transaction_type: "preAuth")        → hold funds
2. POST /pos/v1/transaction  (transaction_type: "reAuthorization") → extend hold (optional)
3. POST /pos/v1/transaction  (transaction_type: "capture")         → collect

También puedes anular una preautorización antes de la captura para liberar la retención.

Paso 1 — Preautorización

Pon transaction_type: "preAuth" y transaction_mode: "Authorization". Los campos varían un poco según el canal de lectura:

ICC (Chip)

MCR (Banda magnética)

NFC (Contactless)

{
"transaction_type": "preAuth",
"transaction_mode": "Authorization",
"country": "CHL",
"client_transaction_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"amount": {
"currency": "CLP",
"subtotal_iva": 0,
"subtotal_iva0": 20000,
"iva": 0,
"tip": 0,
"extra_taxes": {
  "airport_tax": 0,
  "iac": 0,
  "ice": 0,
  "travel_agency": 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.26",
"has_print": true,
"terminal_id": "PB04216R20537",
"location": {
  "latitude": -33.4489,
  "longitude": -70.6693
}
}
}

La respuesta devuelve un ticketNumber que necesitarás para el paso de la captura.

Paso 2 — Captura

Pon transaction_type: "capture" y envía el transaction_reference de la respuesta de la preautorización. Los campos varían un poco según el canal de lectura:

ICC (Chip)

MCR (Banda magnética)

NFC (Contactless)

{
"transaction_type": "capture",
"transaction_mode": "Authorization",
"country": "CHL",
"client_transaction_id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
"transaction_reference": "f2f29080-0214-42c0-95a5-77ecf3434cd7",
"amount": {
"currency": "CLP",
"subtotal_iva": 0,
"subtotal_iva0": 20000,
"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",
"pos_details": {
"brand": "SUNMI",
"model": "P2-EU",
"version": "Kushki SunmiV1.1.26",
"has_print": true,
"terminal_id": "PB04216R20537"
}
}

INFO

El transaction_reference de la captura debe venir de la autorización, no de una reautorización.

Reautorización

Para extender o aumentar una retención existente, usa transaction_type: "reAuthorization". Envía el transaction_reference de la preautorización original. Los campos varían un poco según el canal de lectura:

ICC (Chip)

MCR (Banda magnética)

NFC (Contactless)

{
"transaction_type": "reAuthorization",
"transaction_mode": "Authorization",
"country": "CHL",
"client_transaction_id": "c3d4e5f6-a7b8-9012-cdef-34567890abcd",
"transaction_reference": "f2f29080-0214-42c0-95a5-77ecf3434cd7",
"amount": {
"currency": "CLP",
"subtotal_iva": 0,
"subtotal_iva0": 5000,
"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": "none",
"pos_details": {
"brand": "SUNMI",
"model": "P2-EU",
"version": "Kushki SunmiV1.1.26",
"has_print": true,
"terminal_id": "PB04209860189"
}
}

INFO

Envía un monto de 0 en la reautorización para extender la fecha de captura sin aumentar el monto retenido.

Operaciones sin tarjeta

Chile tiene soporte completo para operaciones sin tarjeta: no hace falta leer la tarjeta al momento de la captura, la reautorización o la anulación. Pon omit_card: true y omite card_details, cvm_type, contact_details y pos_details.

INFO

Las operaciones sin tarjeta están disponibles para tarjetas de crédito y débito Visa y Mastercard en Chile.

Captura sin tarjeta

{
  "transaction_type": "capture",
  "transaction_mode": "Authorization",
  "client_transaction_id": "d4e5f6a7-b8c9-0123-def0-456789abcdef",
  "transaction_reference": "f2f29080-0214-42c0-95a5-77ecf3434cd7",
  "omit_card": true,
  "amount": {
    "currency": "CLP",
    "subtotal_iva": 0,
    "subtotal_iva0": 30000,
    "iva": 0
  }
}

Reautorización sin tarjeta

{
  "transaction_type": "reAuthorization",
  "transaction_mode": "Authorization",
  "client_transaction_id": "e5f6a7b8-c9d0-1234-ef01-567890abcdef",
  "transaction_reference": "f2f29080-0214-42c0-95a5-77ecf3434cd7",
  "omit_card": true,
  "amount": {
    "currency": "CLP",
    "subtotal_iva": 0,
    "subtotal_iva0": 0,
    "iva": 0
  }
}

Anulación de preautorización sin tarjeta

{
  "transaction_type": "preAuth",
  "transaction_mode": "Void",
  "client_transaction_id": "f6a7b8c9-d0e1-2345-f012-6789abcdef01",
  "transaction_reference": "f2f29080-0214-42c0-95a5-77ecf3434cd7",
  "omit_card": true,
  "amount": {
    "currency": "CLP",
    "subtotal_iva": 0,
    "subtotal_iva0": 20000,
    "iva": 0
  }
}

Límites de la retención

Tipo de tarjeta	Duración máxima de la retención
Tarjeta de crédito	28 días
Tarjeta de débito	7 días

Si la transacción no se captura dentro del plazo permitido, el banco emisor libera los fondos retenidos.

Campos del request

Campo	Obligatorio	Descripción
`transaction_type`	Sí	`"preAuth"` para retener, `"capture"` para cobrar, `"reAuthorization"` para extender.
`transaction_mode`	Sí	`"Authorization"` para continuar; `"Void"` para anular una preautorización.
`country`	Sí	ISO 3166-1 alpha-3. Debe ser `"CHL"` (opcional en operaciones sin tarjeta).
`client_transaction_id`	Sí	UUID v4 generado por el comercio. Debe ser único por transacción.
`transaction_reference`	No	Obligatorio para la captura, la reautorización y la anulación (no se necesita en preAuth).
`cvm_type`	Sí	`"none"`, `"pin"` o `"signature"`. Opcional para operaciones sin tarjeta.
`omit_card`	No	`true` para hacer una operación sin tarjeta.
`metadata`	No	Objeto llave-valor con datos adicionales.

`amount`

Campo	Obligatorio	Descripción
`currency`	Sí	Debe ser `"CLP"`. Usa enteros: sin decimales.
`subtotal_iva`	Sí	Ponlo en `0`.
`subtotal_iva0`	Sí	Monto de la transacción en CLP.
`iva`	Sí	Ponlo en `0`.
`tip`	No	Monto de la propina.

`card_details`

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

Autenticación

Entornos

🟢 Producción

🧪 Sandbox (UAT)

https://api.kushkipagos.com/

Endpoints disponibles

Preautorización, captura, reautorización y anulación

Retén el saldo de una tarjeta (preAuth), cobra los fondos (capture), extiende una retención (reAuthorization) o anula una preautorización: todo con un solo endpoint. Soporte completo sin tarjeta.

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

Pagos en dos pasos

Flujo#

Paso 1 — Preautorización#

Paso 2 — Captura#

Reautorización#

Operaciones sin tarjeta#

Captura sin tarjeta#

Reautorización sin tarjeta#

Anulación de preautorización sin tarjeta#

Límites de la retención#

Campos del request#

amount#

card_details#

Autenticación#

Entornos#

Endpoints disponibles#

Flujo

Paso 1 — Preautorización

Paso 2 — Captura

Reautorización

Operaciones sin tarjeta

Captura sin tarjeta

Reautorización sin tarjeta

Anulación de preautorización sin tarjeta

Límites de la retención

Campos del request

`amount`

`card_details`

Autenticación

Entornos

Endpoints disponibles