Two-step-payments

Two-step payments 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.

Flow

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

You can also void a pre-authorization before capture to release the hold.

Step 1 — Pre-authorization

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

{
  "transaction_type": "preAuth",
  "transaction_mode": "Authorization",
  "country": "MEX",
  "client_transaction_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "amount": {
    "currency": "MXN",
    "subtotal_iva": 0,
    "subtotal_iva0": 500,
    "iva": 0,
    "tip": 0,
    "extra_taxes": {
      "airport_tax": 0,
      "iac": 0,
      "ice": 0,
      "travel_agency": 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": "Kushki SunmiV1.1.26",
    "has_print": true,
    "terminal_id": "PB04216R20537",
    "location": {
      "latitude": 19.4326,
      "longitude": -99.1332
    }
  }
}

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

Step 2 — Capture

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

{
  "transaction_type": "capture",
  "transaction_mode": "Authorization",
  "country": "MEX",
  "client_transaction_id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
  "transaction_reference": "f2f29080-0214-42c0-95a5-77ecf3434cd7",
  "amount": {
    "currency": "MXN",
    "subtotal_iva": 0,
    "subtotal_iva0": 500,
    "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": "Kushki SunmiV1.1.26",
    "has_print": true,
    "terminal_id": "PB04216R20537"
  }
}

INFO

The transaction_reference for capture must come from the authorization, not from a reauthorization.

Reauthorization

To extend or increase an existing hold, use transaction_type: "reAuthorization". Pass the transaction_reference from the original pre-auth.

{
  "transaction_type": "reAuthorization",
  "transaction_mode": "Authorization",
  "country": "MEX",
  "client_transaction_id": "c3d4e5f6-a7b8-9012-cdef-34567890abcd",
  "transaction_reference": "f2f29080-0214-42c0-95a5-77ecf3434cd7",
  "amount": {
    "currency": "MXN",
    "subtotal_iva": 0,
    "subtotal_iva0": 100,
    "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": "none",
  "pos_details": {
    "brand": "SUNMI",
    "model": "P2-EU",
    "version": "Kushki SunmiV1.1.26",
    "has_print": true,
    "terminal_id": "PB04209860189"
  }
}

INFO

Send an amount of 0 in the reauthorization to extend the capture date without increasing the hold amount.

Cardless operations

Cardless capture, reauthorization, and void are in Beta phase in México. Set omit_card: true and omit card_details, cvm_type, contact_details, and pos_details.

INFO

Cardless operations are available for Visa and Mastercard credit and debit cards in México.

Cardless capture

{
  "transaction_type": "capture",
  "transaction_mode": "Authorization",
  "client_transaction_id": "d4e5f6a7-b8c9-0123-def0-456789abcdef",
  "transaction_reference": "f2f29080-0214-42c0-95a5-77ecf3434cd7",
  "omit_card": true,
  "amount": {
    "currency": "MXN",
    "subtotal_iva": 0,
    "subtotal_iva0": 500,
    "iva": 0
  }
}

Cardless reauthorization

{
  "transaction_type": "reAuthorization",
  "transaction_mode": "Authorization",
  "client_transaction_id": "e5f6a7b8-c9d0-1234-ef01-567890abcdef",
  "transaction_reference": "f2f29080-0214-42c0-95a5-77ecf3434cd7",
  "omit_card": true,
  "amount": {
    "currency": "MXN",
    "subtotal_iva": 0,
    "subtotal_iva0": 0,
    "iva": 0
  }
}

Cardless void of pre-auth

{
  "transaction_type": "preAuth",
  "transaction_mode": "Void",
  "client_transaction_id": "f6a7b8c9-d0e1-2345-f012-6789abcdef01",
  "transaction_reference": "f2f29080-0214-42c0-95a5-77ecf3434cd7",
  "omit_card": true,
  "amount": {
    "currency": "MXN",
    "subtotal_iva": 0,
    "subtotal_iva0": 500,
    "iva": 0
  }
}

Hold limits

Card type	Maximum hold duration
Credit card	28 days
Debit card	7 days

If the transaction is not captured within the allowed period, the held funds are released by the issuing bank.

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 `"MEX"` (optional for cardless).
`client_transaction_id`	Yes	UUID v4 generated by the merchant. Must be unique per transaction.
`transaction_reference`	No	Required for capture, reauthorization, and void (not needed for preAuth).
`cvm_type`	No	`"none"`, `"pin"`, or `"signature"`. Optional for cardless operations.
`omit_card`	No	`true` to perform a cardless operation.
`metadata`	No	Key-value object with extra data.

`amount`

Field	Required	Description
`currency`	Yes	Must be `"MXN"`. Supports two decimal places.
`subtotal_iva`	Yes	Set to `0`.
`subtotal_iva0`	Yes	Transaction amount in MXN.
`iva`	Yes	Set to `0`.
`tip`	No	Tip amount.

`card_details`

Field	Required	Description
`reading_type`	No	`"ICC"`, `"MCR"`, or `"NFC"`. Optional for cardless.
`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 or TLV.
`tracks.enc_track2`	No	Encrypted Track 2 data (MCR and NFC).
`tracks.track_ksn`	No	KSN for Track 2 (ICC and NFC).

Authentication

Environments

🟢 Production

🧪 Sandbox (UAT)

https://api.kushkipagos.com/

Available Endpoints

Pre-auth, Capture, Reauthorization & Void

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

Got a suggestion on this documentation? Contact us.

Flow#

Step 1 — Pre-authorization#

Step 2 — Capture#

Reauthorization#

Cardless operations#

Cardless capture#

Cardless reauthorization#

Cardless void of pre-auth#

Hold limits#

Request fields#

amount#

card_details#

Authentication#

Environments#

Available Endpoints#

Flow

Step 1 — Pre-authorization

Step 2 — Capture

Reauthorization

Cardless operations

Cardless capture

Cardless reauthorization

Cardless void of pre-auth

Hold limits

Request fields

`amount`

`card_details`

Authentication

Environments

Available Endpoints