One-time Payments

The One-Time Payments endpoint lets you process card-present transactions directly from your POS terminal. A single endpoint handles all reading channels and charge types — basic charges, deferred instalments, cashback, and tip.

Beta

Card Present payments are in Beta phase for Peru 🇵🇪.

Charge types

Type	How to trigger
Single charge	`transaction_type: "charge"`, `transaction_mode: "Authorization"`
Deferred charge	Same as above, plus `is_deferred: true` and the `deferred` object
Cashback	Same as single charge, plus `is_cashback: true` and `cashback_amount`
Tip	Same as single charge, plus `amount.tip`

Reading channels

Send card_details.reading_type to indicate how the card was read.

Value	Channel
`ICC`	Chip (Integrated Circuit Card)
`MCR`	Magnetic stripe
`NFC`	Contactless

Depending on the channel, different card_details sub-fields apply (enc_tlv for ICC/NFC; tracks for MCR/NFC).

Single charge

{
  "transaction_type": "charge",
  "transaction_mode": "Authorization",
  "country": "PER",
  "client_transaction_id": "a0e1b2c3-d4e5-6789-abcd-ef0123456789",
  "amount": {
    "currency": "PEN",
    "subtotal_iva": 0,
    "subtotal_iva0": 150,
    "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": "-1",
    "document_number": "",
    "first_name": "Carlos",
    "last_name": "Ramirez"
  },
  "pos_details": {
    "brand": "SUNMI",
    "model": "P2-EU",
    "version": "1.1.13",
    "has_print": true
  }
}

Deferred charge

Set is_deferred: true and include the deferred object with the number of instalments.

{
  "transaction_type": "charge",
  "transaction_mode": "Authorization",
  "country": "PER",
  "client_transaction_id": "a0e1b2c3-d4e5-6789-abcd-ef0123456789",
  "is_deferred": true,
  "deferred": {
    "months": "6"
  },
  "amount": {
    "currency": "PEN",
    "subtotal_iva": 0,
    "subtotal_iva0": 500,
    "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": "1.1.13",
    "has_print": true
  }
}

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 `"PER"`.
`client_transaction_id`	Yes	UUID v4 generated by the merchant. Must be unique per transaction.
`is_deferred`	No	Set to `true` to defer the charge.
`deferred`	No	Required when `is_deferred` is `true`.
`is_cashback`	No	Set to `true` to include a cashback amount.
`cashback_amount`	No	Required when `is_cashback` is `true`.
`cvm_type`	Yes	Cardholder verification method: `"none"`, `"pin"`, or `"signature"`.
`omit_card`	No	Set to `true` for cardless operations.
`metadata`	No	Key-value object with extra data.

`amount`

Field	Required	Description
`currency`	Yes	`"PEN"` or `"USD"`.
`subtotal_iva`	Yes	Subtotal subject to VAT. Set to `0` if no VAT applies.
`subtotal_iva0`	Yes	Subtotal not subject to VAT (total amount when untaxed).
`iva`	Yes	VAT amount. Set to `0` if no VAT applies.
`tip`	No	Tip amount.
`extra_taxes`	No	Additional taxes: `airport_tax`, `iac`, `ice`, `travel_agency`.

`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 block.
`tracks.enc_track2`	No	Encrypted Track 2 data (MCR and NFC).
`tracks.track_ksn`	No	KSN for Track 2.

`deferred`

Field	Required	Description
`months`	Yes	Number of instalment months.

`contact_details`

Field	Required	Description
`document_type`	No	`-1` — no document sent.
`document_number`	No	Required when `document_type` is not `-1`.
`first_name`	No	Cardholder first name.
`last_name`	No	Cardholder last name.
`email`	No	Cardholder email address.
`phone_number`	No	Cardholder phone (E.164 format).

`pos_details`

Field	Required	Description
`brand`	No	Terminal brand (e.g., `"SUNMI"`).
`model`	No	Terminal model.
`version`	No	Terminal software version.
`has_print`	No	`true` if the terminal has a printer.
`terminal_id`	No	Up to 15-character terminal ID.
`connectivity`	No	Network connectivity type.
`serial`	No	Device serial number.
`type`	No	Physical POS device type.
`friendly_name`	No	Display name assigned to the terminal.
`user`	No	Operator user of the device.
`location`	No	`{ "latitude": ..., "longitude": ... }` — terminal GPS coordinates.

Authentication

Using the API

🟢 Production

🧪 Sandbox (UAT)

https://api.kushkipagos.com/

Available Endpoints

Process Card-Present Payment

Submit a one-time POS transaction — basic charge, deferred, cashback, or tip — using ICC, MCR, or NFC reading.

Got a suggestion on this documentation? Contact us.

Charge types#

Reading channels#

Single charge#

Deferred charge#

Request fields#

Top-level fields#

amount#

card_details#

deferred#

contact_details#

pos_details#

Authentication#

Using the API#

Available Endpoints#

Charge types

Reading channels

Single charge

Deferred charge

Request fields

Top-level fields

`amount`

`card_details`

`deferred`

`contact_details`

`pos_details`

Authentication

Using the API

Available Endpoints