One-time payments
Charge types
| Type | How to trigger |
|---|---|
| Single charge | transaction_type: "charge", transaction_mode: "Authorization" |
| MSI (Meses Sin Intereses) | Same as above + is_deferred: true + deferred.credit_type: "03" + deferred.months |
| Tip | Same as single charge + amount.tip |
Reading channels
| Value | Channel |
|---|---|
ICC | Chip (Integrated Circuit Card) |
MCR | Magnetic stripe |
NFC | Contactless |
Single charge
{
"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
credit_type: "03" and the number of months inside the deferred object.{
"transaction_type": "charge",
"transaction_mode": "Authorization",
"country": "MEX",
"client_transaction_id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
"is_deferred": true,
"deferred": {
"months": "6",
"credit_type": "03",
"graceMonths": "00"
},
"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"
}
}Aggregator model
sub_merchant object.{
"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"
}
}Request fields
Top-level fields
| Field | Required | Description |
|---|---|---|
transaction_type | Yes | "charge" for a one-time payment. |
transaction_mode | Yes | "Authorization" to charge immediately. |
country | Yes | ISO 3166-1 alpha-3. Must be "MEX". |
client_transaction_id | Yes | UUID v4 generated by the merchant. Must be unique per transaction. |
is_deferred | No | Set to true to create an MSI charge. |
deferred | No | Required when is_deferred is true. |
cvm_type | Yes | Cardholder verification method: "none", "pin", or "signature". |
sub_merchant | No | Aggregator model: sub-merchant details. |
metadata | No | Key-value object with extra data. |
amount
| Field | Required | Description |
|---|---|---|
currency | Yes | Must be "MXN". Supports two decimal places. |
subtotal_iva | Yes | Subtotal subject to VAT. |
subtotal_iva0 | Yes | Subtotal exempt from VAT. |
iva | Yes | VAT amount. |
tip | No | Tip amount in MXN. |
extra_taxes | No | Additional taxes: airport_tax, iac, ice, travel_agency. |
deferred
| Field | Required | Description |
|---|---|---|
months | Yes | Number of MSI months. Available values depend on the card BIN. Common values: 3, 6, 9, 12, 18. |
credit_type | Yes | Always "03" for MSI (Meses Sin Intereses). |
graceMonths | Yes | Must be "00" for Mexico. |
card_details
| Field | Required | Description |
|---|---|---|
reading_type | Yes | "ICC", "MCR", or "NFC". |
enc_tlv | No | Encrypted TLV data (required for ICC and NFC). |
pin_block | No | Encrypted PIN block for online-PIN transactions. |
pin_ksn | No | Key serial number (KSN) for the PIN/TLV. |
tracks.enc_track1 | No | Encrypted Track 1 (required for MCR). |
tracks.enc_track2 | No | Encrypted Track 2 (MCR and NFC). |
tracks.track_ksn | No | KSN for Track 2 (ICC and NFC). |
pos_details
| Field | Required | Description |
|---|---|---|
terminal_id | Yes | Terminal identifier assigned by Kushki. |
brand | No | Terminal brand (e.g., "SUNMI"). |
model | No | Terminal model (e.g., "P2-EU"). |
version | No | Terminal software version. |
has_print | No | true if the terminal has a printer (voucher). |
location | No | { "latitude": 19.4326, "longitude": -99.1332 } — terminal GPS coordinates. |
Authentication
Environments
🟢 Production
🧪 Sandbox (UAT)
https://api.kushkipagos.com/Available Endpoints
Got a suggestion on this documentation? Contact us.
Modified at 2026-07-11 00:04:23