API Raw Card Present Payments

The Card Present API lets you process face-to-face card payments directly from your POS terminals in Chile. A single, consistent set of endpoints covers the full payment lifecycle: one-time charges, two-step authorize-and-capture, voids, refunds, and transaction queries — across chip (ICC), magnetic stripe (MCR), and contactless (NFC) reading channels.

Beta

Card Present payments are in Beta phase for Chile 🇨🇱. Contact your account manager for access.

Available operations

One-Time Payments

Process immediate charges — single, deferred (Cuotas Comercio and Cuotas Emisor), cashback, or tip — in a single API call.

Two-Step Payments

Place a hold (pre-auth), then capture when ready. Supports reauthorization and cardless operations.

Voids & Refunds

Cancel an authorization (void), roll back a transaction (reverse), or refund a settled payment — full or partial, with or without card reading.

Card Information

Look up BIN data, check installment availability, and query Cuotas Comercio / Cuotas Emisor options before initiating a charge.

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 share a common request structure built around three main objects: the transaction intent, the card data, and the terminal details.

{
  "transaction_type": "charge",
  "transaction_mode": "Authorization",
  "country": "CHL",
  "client_transaction_id": "<uuid-v4>",
  "amount": {
    "currency": "CLP",
    "subtotal_iva": 0,
    "subtotal_iva0": 10000,
    "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": -33.4489,
      "longitude": -70.6693
    }
  }
}

Key concepts

Currency

Chile uses CLP (Chilean Peso). CLP has no decimal places — all amounts are integers.

"amount": {
  "currency": "CLP",
  "subtotal_iva": 0,
  "subtotal_iva0": 10000,
  "iva": 0
}

Reading channels

Set card_details.reading_type to indicate how the card was presented.

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 transactions, contactless)

Cardless operations

Chile has full support for cardless operations — no card read is required for voids, reverses, refunds, captures, and reauthorizations. Set omit_card: true to omit card_details and cvm_type.

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

Installments

Chile supports two types of deferred payments. Always call the BIN lookup first to confirm the card supports the desired installment type.

Type	How to trigger	Range
Cuotas Comercio (Merchant Installments)	`is_deferred: true` + `deferred.credit_type: "03"`	2–12 months
Cuotas Emisor (Issuer Installments)	`is_deferred: true` — no `credit_type`	2–48 months

Beta

Cuotas Comercio (Merchant Installments) are currently in Beta phase. Contact the Kushki team to enable this feature in your console.

Reversal, void, and refund cutoff

Operation	Cutoff
Reversal (same-day)	Before 23:59 Chile local time — used to check the outcome of a transaction affected by a timeout or communication issue
Void (same-day)	Before 23:59 Chile local time
Refund	Available after void cutoff, up to 120 days from the original transaction

Cashback

Chile supports cashback at the time of a card-present payment. Set is_cashback: true and include cashback_amount.

WARNING

Cashback is only available with local cards and is not supported for contactless (NFC) transactions.

Idempotency

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

Integration models

Chile supports both the Acquirer and Aggregator models.

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

Aggregator — `sub_merchant` object

"sub_merchant": {
  "mcc": "5411",
  "id_affiliation": "987654321",
  "soft_descriptor": "Mi Comercio Chile",
  "city": "Santiago",
  "country_ans": "CHL",
  "zip_code": "7550000",
  "address": "Av. Apoquindo 4501",
  "social_reason": "Mi Comercio Chile SpA",
  "code": "SUB001CHL"
}

Encryption

Card data (TLV, track data, PIN blocks) must be encrypted using the DUKPT (Derived Unique Key Per Transaction) protocol before being sent to the API. Kushki and the merchant exchange Base Derivation Keys (BDK) through a secure Key Encryption Key (KEK) ceremony prior to going live.

See Key Exchange Process for the full procedure.

Webhooks

Kushki sends webhook notifications for all Card Present events: charges, authorizations, captures, voids, reverses, and refunds. Configure your webhook endpoints from the Console (Developers > Webhooks).

WARNING

Card Present webhooks can only be configured through the Console. Webhook configuration via API is not supported.

Authentication

Operation	Header
Charges, voids, reverses, refunds, BIN lookup, query transactions (analytics)	`Private-Credential-Id: <your-private-credential>`
Deferred options	`Public-Merchant-Id: <your-public-key>`

Environments

🟢 Production

🧪 Sandbox (UAT)

🔬 Visa / MC Certification

https://api.kushkipagos.com/

Additional resources

Key Exchange Process

DUKPT/KEK ceremony required before processing live transactions.

Test Data

Amounts and scenarios for sandbox testing in Chile.

Error Catalog

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

Good Practices

Security and integration best practices for Card Present.

Got a suggestion on this documentation? Contact us.

Available operations#

How it works#

Key concepts#

Currency#

Reading channels#

Cardholder verification (cvm_type)#

Cardless operations#

Installments#

Reversal, void, and refund cutoff#

Cashback#

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`)

Cardless operations

Installments

Reversal, void, and refund cutoff

Cashback

Idempotency

Integration models

Aggregator — `sub_merchant` object

Encryption

Webhooks

Authentication

Environments

Additional resources