Two-step Payments

Two-step payments let you separate authorization (hold) from capture (collect). Use this when you need to confirm the transaction before charging — for example, at check-in, fuel stations, or hospitality.

Beta

Card Present payments are in Beta phase.

Flow

1. POST /pos/v1/transaction  (transaction_type: "preAuth")   → hold funds
2. POST /pos/v1/transaction  (transaction_type: "capture")   → collect

You can also reauthorize — extend an existing hold — or void it before capture.

Step 1 — Pre-authorization

Set transaction_type: "preAuth" and transaction_mode: "Authorization".

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

The response returns a ticketNumber you will need for the capture step.

Step 2 — Capture

Set transaction_type: "capture" and pass the ticketNumber from the pre-auth.

{
  "transaction_type": "capture",
  "transaction_mode": "Authorization",
  "country": "PER",
  "client_transaction_id": "b1f2c3d4-e5f6-7890-bcde-f01234567890",
  "amount": {
    "currency": "PEN",
    "subtotal_iva": 0,
    "subtotal_iva0": 250,
    "iva": 0,
    "tip": 0
  },
  "card_details": {
    "reading_type": "ICC"
  },
  "pos_details": {
    "brand": "SUNMI",
    "model": "P2-EU",
    "version": "1.1.13",
    "has_print": true
  }
}

Reauthorization

To extend an existing hold, use transaction_type: "reAuthorization". Pass the original ticketNumber.

Cardless capture / reauthorization

For cardless operations (no physical card read required at capture time), set omit_card: true. The card_details and cvm_type fields are optional in this case.

Request fields

Field	Required	Description
`transaction_type`	Yes	`"preAuth"` to hold, `"capture"` to collect, `"reAuthorization"` to extend.
`transaction_mode`	Yes	`"Authorization"` to proceed; `"Void"` to cancel a pre-auth.
`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.
`cvm_type`	No	Cardholder verification method: `"none"`, `"pin"`, or `"signature"`. Optional for cardless.
`omit_card`	No	`true` to perform a cardless capture or reauthorization.
`is_cashback`	No	`true` to include a cashback amount at capture.
`cashback_amount`	No	Required when `is_cashback` is `true`.
`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`	No	`"ICC"`, `"MCR"`, or `"NFC"`.
`enc_tlv`	No	Encrypted TLV data (ICC and NFC).
`pin_block`	No	Encrypted PIN block for online-PIN transactions.
`pin_ksn`	No	KSN for the PIN block.
`tracks.enc_track2`	No	Encrypted Track 2 data (MCR and NFC).
`tracks.track_ksn`	No	KSN for Track 2.

`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.
`location`	No	`{ "latitude": ..., "longitude": ... }` — terminal GPS coordinates.

Authentication

Using the API

🟢 Production

🧪 Sandbox (UAT)

https://api.kushkipagos.com/

Available Endpoints

Pre-auth, Capture & Reauthorization

Place a hold on a card (preAuth), collect funds (capture), extend a hold (reAuthorization), or void a pre-auth — all through the same endpoint.

Got a suggestion on this documentation? Contact us.

Flow#

Step 1 — Pre-authorization#

Step 2 — Capture#

Reauthorization#

Cardless capture / reauthorization#

Request fields#

amount#

card_details#

pos_details#

Authentication#

Using the API#

Available Endpoints#

Flow

Step 1 — Pre-authorization

Step 2 — Capture

Reauthorization

Cardless capture / reauthorization

Request fields

`amount`

`card_details`

`pos_details`

Authentication

Using the API

Available Endpoints