API Raw Card Present - Kushki Developer Portal

The Card Present Raw API gives you direct, low-level access to Kushki's payment infrastructure for processing face-to-face card transactions in Mexico. You own the full integration stack — terminal firmware, DUKPT encryption, card reading, and request construction — and get maximum flexibility in return.

A single base URL covers every operation in the payment lifecycle: charges, two-step authorizations, voids, refunds, cardless flows, BIN lookups, MSI installment options, and transaction queries.

Base URLs

🟢 Production

🧪 Sandbox (UAT)

https://api.kushkipagos.com/

API sections

One-Time Payments

Single charge, MSI installments (Meses Sin Intereses), and tip — all in a single API call

Two-Step Payments

Pre-authorization → capture flow. Supports reauthorization and cardless operations.

Voids & Refunds

Same-day voids, same-day reversals, and post-settlement refunds — with or without card read.

Card Information

BIN lookup and MSI option queries. Always call before initiating a deferred charge.

Query Transactions

Paginated transaction search with filters by date, BIN, last digits, or reference.

Authentication

Every request must include your merchant key in the appropriate header depending on the operation:

Operation	Header
Charges, voids, refunds	`Private-Merchant-Id: <your-private-key>`
BIN lookup, transaction list	`Private-Credential-Id: <your-private-credential>`
MSI deferred options	`Public-Merchant-Id: <your-public-key>`
Query transactions (analytics)	`Private-Credential-Id: <your-private-credential>`

Request anatomy

All write operations share the same base structure:

{
  "transaction_type": "charge",
  "transaction_mode": "Authorization",
  "country": "MEX",
  "client_transaction_id": "ae6dd41a-9173-4ec7-8734-3178454ef341",
  "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": "1.1.28",
    "has_print": true,
    "terminal_id": "PB04209860189",
    "location": {
      "latitude": 19.4326,
      "longitude": -99.1332
    }
  }
}

Key concepts

Currency

Mexico uses MXN (Mexican Peso). MXN supports two decimal places.

"amount": {
  "currency": "MXN",
  "subtotal_iva": 580,
  "subtotal_iva0": 0,
  "iva": 80
}

See The Amount Object for the full field reference and IVA calculation examples.

Card reading channels

Set card_details.reading_type to match how the card was presented at the terminal:

Value	Channel	Required card data
`ICC`	Chip (EMV)	`enc_tlv`, `pin_ksn`, `tracks.enc_track2`, `tracks.track_ksn`
`MCR`	Magnetic stripe	`tracks.enc_track1`, `tracks.enc_track2`
`NFC`	Contactless	`enc_tlv`, `tracks.enc_track2`, `tracks.track_ksn`

Cardholder verification (`cvm_type`)

Value	Meaning
`pin`	Online PIN — encrypted PIN block in `card_details.pin_block`
`signature`	Signature at the terminal
`none`	No CVM (low-value or contactless transactions)

MSI — Meses Sin Intereses

Mexico supports MSI installments. Always call the BIN lookup first to confirm eligibility and retrieve valid month options for the card.

To trigger an MSI charge, add the deferred object with credit_type: "03" and graceMonths: "00":

{
  "is_deferred": true,
  "deferred": {
    "months": "6",
    "credit_type": "03",
    "graceMonths": "00"
  }
}

WARNING

Minimum amounts for MSI in Mexico:

Months	Minimum amount
3	$300 MXN
6	$600 MXN
9	$900 MXN
12	$1,200 MXN
18	$1,800 MXN

Cardless operations

Beta

Cardless operations are currently in Beta phase in México. Contact the Kushki team to enable this feature.

Set omit_card: true to skip card_details and cvm_type. Supported for captures, reauthorizations, voids, reverses, and refunds.

{
  "transaction_type": "capture",
  "transaction_mode": "Authorization",
  "omit_card": true,
  "transaction_reference": "f2f29080-0214-42c0-95a5-77ecf3434cd7",
  "amount": {
    "currency": "MXN",
    "subtotal_iva": 0,
    "subtotal_iva0": 500,
    "iva": 0
  }
}

Void and refund cutoff

Operation	Window
Void	Same day, before 22:00 México local time
Cardless reversal	Same day, before 22:00 México local time — uses `client_transaction_id`
Refund	After void cutoff, up to 120 days from the original transaction

Idempotency

Every request must include a unique client_transaction_id (UUID v4). If you retry the same request with the same ID, Kushki returns the original result — no duplicate transaction is created.

Integration models

Model	Description	Required
Acquirer	The merchant is directly registered with Kushki	Standard request body
Aggregator	Marketplace or payment facilitator — sub-merchants operate under your umbrella	Add `sub_merchant` to the request

Aggregator — `sub_merchant` object

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

Encryption

All card data — TLV, track data, and PIN blocks — must be encrypted with the DUKPT protocol before sending to the API. Kushki and your organization exchange Base Derivation Keys (BDK) through a secure Key Encryption Key (KEK) ceremony before going live.

See Key Exchange Process for the step-by-step procedure.

Webhooks

Kushki sends POST notifications to your configured endpoint for every Card Present event: charges, pre-auths, captures, voids, reverses, and refunds.

WARNING

Card Present webhooks can only be configured through the Console (Developers > Webhooks). Webhook setup via API is not supported.

Event	Webhook body reference
Charge, preAuth, capture, void, reverse	Card Payments
Refund	Refunds

See Webhooks — Introduction for authentication headers, signature verification, and static IPs.

Reference docs

Amount Object

Full field reference for the amount object — IVA, subtotals, tip, and extra taxes.

Key Exchange Process

DUKPT/KEK ceremony required before processing live transactions.

Test Data

Sandbox amounts and card scenarios for testing in Mexico.

Error Catalog

HTTP status codes and ISO error codes for Visa and Mastercard.

Webhooks

Receive payment notifications.

Release Notes

Version history and changelog for the Card Present API in Mexico.

Got a suggestion on this documentation? Contact us.

API RAW CARD PRESENT PAYMENTS 🇲🇽

Base URLs#

API sections#

Authentication#

Request anatomy#

Key concepts#

Currency#

Card reading channels#

Cardholder verification (cvm_type)#

MSI — Meses Sin Intereses#

Cardless operations#

Void and refund cutoff#

Idempotency#

Integration models#

Aggregator — sub_merchant object#

Encryption#

Webhooks#

Reference docs#

Base URLs

API sections

Authentication

Request anatomy

Key concepts

Currency

Card reading channels

Cardholder verification (`cvm_type`)

MSI — Meses Sin Intereses

Cardless operations

Void and refund cutoff

Idempotency

Integration models

Aggregator — `sub_merchant` object

Encryption

Webhooks

Reference docs