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".

{
  "transaction_type": "preAuth",
  "transaction_mode": "Authorization",
  "country": "MEX",
  "client_transaction_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "amount": {
    "currency": "MXN",
    "subtotal_iva": 0,
    "subtotal_iva0": 500,
    "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": 19.4326,
      "longitude": -99.1332
    }
  }
}

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.

{
  "transaction_type": "capture",
  "transaction_mode": "Authorization",
  "country": "MEX",
  "client_transaction_id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
  "transaction_reference": "f2f29080-0214-42c0-95a5-77ecf3434cd7",
  "amount": {
    "currency": "MXN",
    "subtotal_iva": 0,
    "subtotal_iva0": 500,
    "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.

{
  "transaction_type": "reAuthorization",
  "transaction_mode": "Authorization",
  "country": "MEX",
  "client_transaction_id": "c3d4e5f6-a7b8-9012-cdef-34567890abcd",
  "transaction_reference": "f2f29080-0214-42c0-95a5-77ecf3434cd7",
  "amount": {
    "currency": "MXN",
    "subtotal_iva": 0,
    "subtotal_iva0": 100,
    "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

La captura, la reautorización y la anulación sin tarjeta están en fase Beta en México. 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 México.

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": "MXN",
    "subtotal_iva": 0,
    "subtotal_iva0": 500,
    "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": "MXN",
    "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": "MXN",
    "subtotal_iva": 0,
    "subtotal_iva0": 500,
    "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 `"MEX"` (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`	No	`"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 `"MXN"`. Admite dos decimales.
`subtotal_iva`	Sí	Ponlo en `0`.
`subtotal_iva0`	Sí	Monto de la transacción en MXN.
`iva`	Sí	Ponlo en `0`.
`tip`	No	Monto de la propina.

`card_details`

Campo	Obligatorio	Descripción
`reading_type`	No	`"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 (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.

¿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