API Raw Card Present Payments - 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 Colombia. 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 and a single main endpoint cover the whole payment lifecycle: one-time charges, two-step authorize-and-capture, reversals, voids, refunds, and transaction queries — across chip (ICC), magnetic stripe (MCR), and contactless (NFC) reading channels.

Available operations

One-Time Payments

Immediate charges — single, deferred, with cashback, or with tip — in a single API call.

Two-Step Payments

Place a hold (pre-authorization), then capture when ready. Supports reauthorization.

Voids & Refunds

Reverse a transaction with an unknown outcome, void it the same day, or refund a settled payment — full or partial.

Query Transactions

Search and paginate through POS terminal transactions with filters by date, BIN, card digits, or reference.

How it works

All Card Present operations are sent to the same endpoint and share a common request structure built around four objects: the transaction intent, the amount, the card data, and the terminal details.

{
  "transaction_type": "charge",
  "transaction_mode": "Authorization",
  "country": "COL",
  "client_transaction_id": "6680eadc-6c8d-44aa-8ca0-18e061c1472a",
  "amount": {
    "currency": "COP",
    "subtotal_iva": 0,
    "subtotal_iva0": 50000,
    "iva": 0,
    "tip": 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": "0",
    "document_number": "1234567890",
    "first_name": "Andrés",
    "last_name": "Martínez",
    "second_last_name": "Rojas",
    "email": "user@example.com",
    "phone_number": "+573912345678"
  },
  "pos_details": {
    "brand": "SUNMI",
    "model": "P2-EU",
    "version": "Kushki SunmiV1.1.28",
    "has_print": true,
    "terminal_id": "PB04209860189",
    "location": {
      "latitude": 4.7110,
      "longitude": -74.0721
    }
  }
}

Required at the root: amount, card_details, client_transaction_id, country, pos_details, contact_details, transaction_type, and cvm_type.

Key concepts

Currency

Colombia uses COP (Colombian Peso). Amounts are sent in whole pesos — no decimals.

"amount": {
  "currency": "COP",
  "subtotal_iva": 0,
  "subtotal_iva0": 50000,
  "iva": 0
}

Keep in mind!

Do not pad amounts with 00 to simulate cents — 50000 is fifty thousand pesos, not five hundred. Padding would charge your customer 100× the intended amount.

Taxes travel inside amount: iva, subtotal_iva, subtotal_iva0, and the optional extra_taxes object (iac, ice, airport_tax, travel_agency). Set to 0 any tax that does not apply to the transaction.

Reading channels

Set card_details.reading_type to indicate 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 sent in `card_details.pin_block`
`signature`	Signature at the terminal
`none`	No CVM (e.g., low-value or contactless transactions)

Cardholder identification (`contact_details`)

contact_details is required in Colombia, and document_type is the only mandatory field inside it.

`document_type`	Meaning
`-1`	No document is sent — `document_number` is not required
`0`	DNI — `document_number` is required (Colombia only)
`1`	Passport — `document_number` is required (Colombia only)

document_number accepts up to 11 characters. second_last_name applies only in Colombia. phone_number follows the E.164 standard (+573912345678).

Transaction types and modes

Field	Allowed values
`transaction_type`	`charge`, `preAuth`, `capture`, `reAuthorization`, `refund`
`transaction_mode`	`Authorization`, `Reverse`, `Void`

Deferred charges

To defer a payment, send is_deferred: true and the deferred object with the number of installments agreed with the cardholder:

"is_deferred": true,
"deferred": {
  "months": "10"
}

WARNING

Colombia does not use credit_type or graceMonths — those belong to Cuotas Comercio in Chile and MSI in Mexico. Sending only months is enough.

Cashback

Colombia supports cashback at the time of a card-present payment. Send is_cashback: true and the amount in cashback_amount.

Important

Cashback works only with local cards.

Cashback is not supported for contactless transactions — make sure reading_type is not NFC.

Tips

Tips are charged inline with the payment: include the value in amount.tip on the original charge. There is no separate post-tip operation in Colombia.

Reversal, void, and refund

Which operation applies depends on the day and time the original transaction and the cancellation request are processed.

Operation	When it applies
Reversal	The processing time was exceeded and the outcome of the charge is unknown (e.g., a timeout). Same day only, before 23:59 — wait at least 1 minute after the transaction before reversing. Send `transaction_mode: "Reverse"` and the original `client_transaction_id`.
Void	The transaction is known to be approved and is cancelled the same day, before 23:59 (approximate) — the exact cutoff depends on the processor. Up to 3 attempts are made; once approved, the charge disappears from the cardholder's statement. Send `transaction_mode: "Void"` and the original `transaction_reference`.
Refund	Requested after the void cutoff, on a different day, or after the 3 void attempts were exhausted. Maximum 120 days from the original transaction. Partial refunds are supported by including the `amount` object.

Refunds are the only operation sent to a different path:

WARNING

Cardless operations (omit_card: true) are not available in Colombia. They are generally available in Chile and in Beta in Mexico and Peru. Every void, reversal, refund, capture, and reauthorization in Colombia requires reading the card.

Idempotency

Every request must include a unique client_transaction_id (UUID v4). Reusing the same ID on a retry is safe — Kushki returns the result of the original transaction instead of creating a duplicate.

Integration models

Model	Description	Required fields
Acquirer	Direct integration — the merchant is registered with Kushki	Standard request body
Aggregator	Marketplace / payment facilitator — sub-merchants transact under your umbrella	Add the `sub_merchant` object to the request

Aggregator — `sub_merchant` object

"sub_merchant": {
  "mcc": "5411",
  "id_affiliation": "987654321",
  "soft_descriptor": "Mi Comercio Colombia",
  "city": "Bogotá",
  "country_ans": "COL",
  "zip_code": "110221",
  "address": "Cra. 7 #71-52",
  "social_reason": "Mi Comercio Colombia S.A.S.",
  "code": "SUB001COL"
}

mcc is a 4-character Merchant Category Code, country_ans follows ISO 3166-1 alpha-3, and social_reason applies only to Visa transactions.

Encryption

Card data — TLV, track data, and PIN blocks — must be encrypted with the DUKPT (Derived Unique Key Per Transaction) protocol before being sent to the API. Track data must be encrypted in hexadecimal format, replacing = with a capital D. 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-authorizations, captures, reversals, voids, and refunds.

WARNING

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

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

Authentication

Every request must include your merchant credential in the header:

Operation	Header
Charges, pre-authorizations, captures, reversals, voids, refunds	`Private-Credential-Id: <your-private-credential>`
Query transactions (analytics)	`Private-Credential-Id: <your-private-credential>`

Environments

🟢 Production

🧪 Sandbox (UAT)

🔬 Visa / MC Certification

https://api.kushkipagos.com/

Additional resources

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

Amounts and card scenarios for sandbox testing in Colombia.

Error Catalog

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

Good Practices

Security and integration best practices for Card Present.

Release Notes

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

Got a suggestion on this documentation? Contact us.

API Raw Card Present

Available operations#

How it works#

Key concepts#

Currency#

Reading channels#

Cardholder verification (cvm_type)#

Cardholder identification (contact_details)#

Transaction types and modes#

Deferred charges#

Cashback#

Tips#

Reversal, void, and refund#

Idempotency#

Integration models#

Aggregator — sub_merchant object#

Encryption#

Webhooks#

Authentication#

Environments#

Additional resources#

Available operations

How it works

Key concepts

Currency

Reading channels

Cardholder verification (`cvm_type`)

Cardholder identification (`contact_details`)

Transaction types and modes

Deferred charges

Cashback

Tips

Reversal, void, and refund

Idempotency

Integration models

Aggregator — `sub_merchant` object

Encryption

Webhooks

Authentication

Environments

Additional resources