Card Present Payments (API Raw)

The Card Present API lets you process face-to-face card payments directly from your POS terminals in Peru. 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. Contact your account manager for access.

Available operations

One-Time Payments

Process immediate charges — single, deferred, cashback, or tip — in a single API call.

Two-Step Payments

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

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 deferred availability, and query instalment 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.

POST /pos/v1/transaction
Private-Merchant-Id: <your-private-key>
Content-Type: application/json

{
  "transaction_type": "charge",
  "transaction_mode": "Authorization",
  "country": "PER",
  "client_transaction_id": "<uuid-v4>",
  "amount": {
    "currency": "PEN",
    "subtotal_iva": 0,
    "subtotal_iva0": 500,
    "iva": 0
  },
  "card_details": {
    "reading_type": "ICC",
    "enc_tlv": "<encrypted-tlv>",
    "pin_ksn": "<ksn-value>"
  },
  "cvm_type": "pin",
  "pos_details": {
    "brand": "SUNMI",
    "model": "P2-EU",
    "version": "1.1.13"
  }
}

Key concepts

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`
`MCR`	Magnetic stripe	`tracks.enc_track2`, `tracks.track_ksn`
`NFC`	Contactless	`enc_tlv` and/or `tracks` depending on card

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

For voids, reverses, refunds, captures, and reauthorizations where re-reading the card is not practical, set omit_card: true. The card_details and cvm_type fields are optional in this case.

Deferred charges

To process an instalment payment, set is_deferred: true and include the deferred object. Always call the BIN lookup endpoint first to confirm the card supports instalments.

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

Idempotency

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

Currencies

Currency	Code
Peruvian Sol	`PEN`
US Dollar	`USD`

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

See Introduction for signature verification and Card Payments / Refunds for the webhook body structure.

WARNING

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

Authentication

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

Using the API

🟢 Production

🧪 Sandbox (UAT)

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 Peru.

Error Catalog

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

Release Notes

Latest changes and version history for the Card Present API.

Got a suggestion on this documentation? Contact us.

Available operations#

How it works#

Key concepts#

Reading channels#

Cardholder verification (cvm_type)#

Cardless operations#

Deferred charges#

Idempotency#

Currencies#

Encryption#

Webhooks#

Authentication#

Using the API#

Additional resources#

Available operations

How it works

Key concepts

Reading channels

Cardholder verification (`cvm_type`)

Cardless operations

Deferred charges

Idempotency

Currencies

Encryption

Webhooks

Authentication

Using the API

Additional resources