Pagos únicos
Tipos de cargo
| Tipo | Cómo activarlo |
|---|---|
| Cargo único | transaction_type: "charge", transaction_mode: "Authorization" |
| MSI (Meses Sin Intereses) | Igual que el anterior + is_deferred: true + deferred.months |
| 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
{
"transaction_type": "charge",
"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",
"contact_details": {
"document_type": "-1",
"document_number": "",
"first_name": "",
"last_name": "",
"email": "",
"phone_number": ""
},
"pos_details": {
"brand": "SUNMI",
"model": "P2-EU",
"version": "Kushki SunmiV1.1.28",
"has_print": true,
"terminal_id": "PB04209860189",
"location": {
"latitude": 19.4326,
"longitude": -99.1332
}
}
}MSI (Meses Sin Intereses)
WARNING
| Meses | Monto mínimo |
|---|---|
| 3 | $300 MXN |
| 6 | $600 MXN |
| 9 | $900 MXN |
| 12 | $1,200 MXN |
| 18 | $1,800 MXN |
Envía el número de meses dentro del objeto deferred. months es su único campo. |
{
"transaction_type": "charge",
"transaction_mode": "Authorization",
"country": "MEX",
"client_transaction_id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
"is_deferred": true,
"deferred": {
"months": "6",
},
"amount": {
"currency": "MXN",
"subtotal_iva": 0,
"subtotal_iva0": 600,
"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"
}
}Modelo agregador
sub_merchant.{
"transaction_type": "charge",
"transaction_mode": "Authorization",
"country": "MEX",
"client_transaction_id": "e5f6a7b8-c9d0-1234-ef01-567890abcdef",
"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",
"sub_merchant": {
"mcc": "5411",
"id_affiliation": "987654321",
"soft_descriptor": "Mi Comercio México",
"city": "Ciudad de México",
"country_ans": "MEX",
"zip_code": "06600",
"address": "Av. Insurgentes Sur 1234",
"social_reason": "Mi Comercio México S.A. de C.V.",
"code": "SUB001MEX"
},
"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 "MEX". |
client_transaction_id | Sí | UUID v4 generado por el comercio. Debe ser único por transacción. |
is_deferred | No | Ponlo en true para crear un cargo a MSI. |
deferred | No | Obligatorio cuando is_deferred es true. |
cvm_type | Sí | Método de verificación del tarjetahabiente: "none", "pin" o "signature". |
sub_merchant | No | Modelo agregador: datos del subcomercio. |
metadata | No | Objeto llave-valor con datos adicionales. |
El objeto amount
| Campo | Obligatorio | Descripción |
|---|---|---|
currency | Sí | Debe ser "MXN". Admite dos decimales. |
subtotal_iva | Sí | Subtotal afecto a IVA. |
subtotal_iva0 | Sí | Subtotal exento de IVA. |
iva | Sí | Monto del IVA. |
tip | No | Monto de la propina en MXN. |
extra_taxes | No | Impuestos adicionales: airport_tax, iac, ice, travel_agency. |
El objeto deferred
| Campo | Obligatorio | Descripción |
|---|---|---|
months | Sí | Número de meses de MSI. Los valores disponibles dependen del BIN de la tarjeta. Valores comunes: 3, 6, 9, 12, 18. |
El objeto 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 para MCR). |
tracks.enc_track2 | No | Track 2 cifrado (MCR y NFC). |
tracks.track_ksn | No | KSN del Track 2 (ICC y NFC). |
El objeto pos_details
| Campo | Obligatorio | Descripción |
|---|---|---|
terminal_id | Sí | Identificador de la terminal asignado por Kushki. |
brand | No | 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": 19.4326, "longitude": -99.1332 } — coordenadas GPS de la terminal. |
Autenticación
| Cabecera | Valor |
|---|---|
Private-Merchant-Id | <your-private-key> |
Content-Type | application/json |
Entornos
🟢 Producción
🧪 Sandbox (UAT)
https://api.kushkipagos.com/Endpoints disponibles
¿Tienes una sugerencia sobre esta documentación? Escríbenos.
Modified at 2026-09-11 14:45:55