Integrate the Kushki services to accept card-present two-step payments in your existing flow or create a new flow with the services we offer.

Important

Remember that it is necessary to make the requests through HTTPS using the credentials we provided. It is important that you do not share sensitive data in public places.

Processing preauthorizations, captures, and reauthorizations

If you need to reserve an amount from your customer’s card, you can use the preauthorization service. For example, when your business needs to request a deposit to ensure that the total cost will be financed at the end of the service, you can hold a specific amount from your customer’s bank account.

Preauthorize a payment

Capture a payment

Cardless capture

Process Reauthorizations

Cardless Reauthorization

Void an preauthorization or reauthorization

Supported Reading Channels

We support the following reading channels. The fields you send to us to process a charge may differ depending on the reading type.

ICC = Integrated Circuit Card (Chip)

MCR = Magnetic Card reader (Stripe)

NFC = Near Field Communication (Contactless)

Here we tell you about the description of each of the fields that are part of the request to accept transactions and the differences of these fields according to the reading channel of the POS terminal of your business.

Field	Type	Description	Required	ICC (Chip)	MCR (Stripe)	NFC (Contactless)
`amount`	`object`	Transaction total amount	required	✅	✅	✅
`amount.currency`	`string`	Type of currency in which the transaction is being processed	required	✅	✅	✅
`amount.extra_taxes`	`object`	Additional taxes to be taken into account in the collection of taxes	optional	✅	✅	✅
`amount.extra_taxes.airport_tax`	`number`	Airport tax	optional	✅	✅	✅
`amount.extra_taxes.iac`	`number`	Aggregate Consumption Tax	optional	✅	✅	✅
`amount.extra_taxes.ice`	`number`	Special Excise Tax. It must be set to `0` in case the transaction does not have this tax	optional	✅	✅	✅
`amount.extra_taxes.travel_agency`	`number`	Travel agency surcharge. Used in airlines	optional	✅	✅	✅
`amount.iva`	`number`	Value Added Tax. Should be set to `0` in case the transaction has no VAT tax	required	✅	✅	✅
`amount.subtotal_iva`	`number`	Value Added Tax subtotal. Should be set to `0` in case the transaction has no VAT tax.	required	✅	✅	✅
`amount.subtotal_iva0`	`number`	Total amount of the transaction in case it is not taxed. The total amount of the transaction should be set here if the transaction is not taxed. Otherwise, it should be set to `0`.	required	✅	✅	✅
`amount.tip`	`number`	Tip	optional	✅	✅	✅
`card`	`object`	Card information of the card with which the customer is making the transaction	optional	✅	✅	✅
`card.card_holder_name`	`string`	Name of cardholder	optional	✅	✅	✅
`card_details`	`object`	Card information details. Depends on the input mode	required	✅	✅	✅
`card_details.enc_tlv`	`string`	Not required when the card is read with magnetic stripes	required	✅	❌	✅
`card_details.pin_block`	`string`	The PIN block is a data block that is used to encapsulate a personal identification number (PIN) during the process. It must be sent if the transaction is an online PIN transaction and must be encrypted with the BDK PIN key shared by Kushki	optional	✅	✅	✅
`card_details.pin_ksn`	`string`	Required if the `pin_block` field is sent. Allowed values: `16 characters` `20 characters`	optional	✅	✅	✅
`card_details.pin_ksn_desc`	`string`	Required if the `pin_block` field is sent. Allowed values: `655` `A55`	optional	✅	✅	✅
`card_details.reading_type`	`string`	Indicates the reader type. Allowed values: `ICC`, `MCR`, `NFC`	required	✅	✅	✅
`card_details.tracks`	`object`	Track information	required	✅	✅	✅
`card_details.tracks.enc_track1`	`string`	Required when reading is done by magnetic stripe.	optional	❌	✅	❌
`card_details.tracks.enc_track2`	`string`	Required when reading by chip, magnetic stripe or NFC.	required	✅	✅	✅
`card_details.tracks.track_ksn`	`string`	Required when reading is done by chip or NFC. Data encryption key.	required	✅	❌	✅
`card_details.tracks.track_ksn_desc`	`string`	Required if the `track_ksn` field is sent.	optional	✅	✅	✅
`card_details.tracks.track2_length`	`string`	Number in string format representing the length of track 2.	optional	✅	✅	✅
`client_transaction_id`	`string`	UUID v4 generated from the trade side. A unique ID must be created per transaction.	required	✅	✅	✅
`country`	`string`	ISO 3166-1 alpha-3 Allowed values: `PER`	required	✅	✅	✅
`is_cashback`	`boolean`	Cashback or refund alerts	optional	✅	✅	✅
`cashback_amount`	`number`	Required when `is_cashback` = `true`	optional	✅	✅	✅
`pos_details`	`object`	POS terminal information	required	✅	✅	✅
`pos_details.brand`	`string`	Terminal reference.	required	✅	✅	✅
`pos_details.has_print`	`boolean`	Indicates whether the POS terminal has hardware for voucher printing.	optional	✅	✅	✅
`pos_details.location`	`object`	The longitude and latitude where the POS terminal is located.	optional	✅	✅	✅
`pos_details.location.latitude`	`number`	The latitude where the POS terminal is located.	optional	✅	✅	✅
`pos_details.location.longitude`	`number`	The length where the POS terminal is located.	optional	✅	✅	✅
`pos_details.model`	`string`	POS terminal model.	optional	✅	✅	✅
`pos_details.terminal_id`	`string`	Identification generated by Kushki. Applies a per-terminal identification	required	✅	✅	✅
`pos_details.version`	`string`	Terminal software version	optional	✅	✅	✅
`contact_details`	`object`	Contact details	required	✅	✅	✅
`contact_details.document_number`	`string`	Document number. Optional when `document_type` = `-1`	required	✅	✅	✅
`contact_details.document_type`	`string`	`-1`: No document will be sent. `0`: DNI `1`: Passport	required	✅	✅	✅
`contact_details.email`	`string`	Cardholder's email address	optional	✅	✅	✅
`contact_details.first_name`	`string`	Cardholder's first name	optional	✅	✅	✅
`contact_details.last_name`	`string`	Cardholder's last name	optional	✅	✅	✅
`contact_details.second_last_name`	`string`	Cardholder's second last name	optional	✅	✅	✅
`contact_details.phone_number`	`string`	Cardholder's cell phone number. EE.164 standard	optional	✅	✅	✅
`transaction_mode`	`string`	Transaction mode Allowed values: `Authorization`, `Reverse`, `Void`	required	✅	✅	✅
`transaction_type`	`string`	Transaction type. Allowed values: `capture`, `charge`, `preAuth`, `reAuthorization`, `refund`, `posTip`	required	✅	✅	✅
`cvm_type`	`string`	Cardholder verification methods. Allowed values: `none`, `pin`, `signature`	required	✅	✅	✅
`sub_merchant`	`object`	Submerchant information	optional	✅	✅	✅
`sub_merchant.mcc`	`string`	MCC- Merchant Category Code	required	✅	✅	✅
`sub_merchant.id_affiliation`	`string`	Merchant Affiliation Id	required	✅	✅	✅
`sub_merchant.soft_descriptor`	`string`	Text that will appear on the cardholder's statement.	required	✅	✅	✅
`sub_merchant.city`	`string`	City where the submerchant is located	required	✅	✅	✅
`sub_merchant.city_code`	`string`	City code according to ISO 3166-2 (3 characters).	required	✅	✅	✅
`sub_merchant.country_ans`	`string`	ISO 3166-1 alpha-3	required	✅	✅	✅
`sub_merchant.zip_code`	`string`	`<= 10 characters`	required	✅	✅	✅
`sub_merchant.address`	`string`	Submerchant address	required	✅	✅	✅
`sub_merchant.social_reason`	`string`	Submerchant's business name. Applies to Visa transactions only.	required	✅	✅	✅
`sub_merchant.code`	`string`	Submerchant identifier	required	✅	✅	✅
`merchant_id`	`string`	Identifier generated by the merchant. It must contain 9 digits.	optional	✅	✅	✅
`metadata`	`object`	Additional information of the transaction	optional	✅	✅	✅

Preauthorize a payment

To make authorizations, send preAuth in the transaction_type field and authorization in the transaction_mode field as part of the body of your request.

Check the examples below:

ICC (Chip)

MCR (Magnetic Stripe)

NFC (Contactless)

{
  "card": {
    "card_holder_name": "John Doe"
  },
  "amount": {
    "iva": 0,
    "tip": 0,
    "currency": "PEN",
    "extra_taxes": {
      "iac": 0,
      "ice": 0,
      "airport_tax": 0,
      "travel_agency": 0
    },
    "subtotal_iva": 0,
    "subtotal_iva0": 600
  },
  "country": "PER",
  "cvm_type": "none",
  "is_cashback": false,
  "is_deferred": false,
  "pos_details": {
    "brand": "SUNMI",
    "model": "P2-EU",
    "version": "Kushki SunmiV1.1.26",
    "location": {
      "latitude": -0.22480833333333333,
      "longitude": -78.487955
    },
    "has_print": true,
    "terminal_id": "PB04216R20537"
  },
  "card_details": {
    "tracks": {
      "track_ksn": "FFFF4357486333600002",
      "enc_track2": "283587285CE10278E7FA50AD5C97CFFE87F472C9FE6406F8"
    },
    "enc_tlv": "CE447A062C49774934E42A7F826668C0C478E38402C158062EE794C0E471B43EA8CE49C256C2C8B157526B0B2BE74FC23F65E18D4F52B99A1A0910E6CCD9B11A32D6D537E2B6E2B011C89569DE6A3D53318080BC77E0E70B398ED3083FD7366CCF8FB4DBF34A116E6D52CFBEF26371878D842034E5029EF62DF235D2C427F04102E451773D9E8975978917E3BC531327702967052E239F8C592734AE14688E603C52B858FC1D97B763AE623603F1475FFFB065EC07AF7A29",
    "pin_ksn": "FFFF4357486333600002",
    "reading_type": "ICC"
  },
  "contact_details": {
    "email": "",
    "last_name": "",
    "first_name": "",
    "phone_number": "",
    "document_type": "-1",
    "document_number": "",
    "second_last_name": ""
  },
  "transaction_mode": "Authorization",
  "transaction_type": "preAuth",
  "client_transaction_id": "6680eadc-6c8d-44aa-8ca0-18e061c1472a"
}

Capture a payment (optional)

Once your business is requested to charge your customer’s card, you can capture the amount of the purchased product or service.

The requested capture corresponds to the sum of the authorization and all reauthorizations made that have not been canceled.

By receiving payments under the authorization and capture scheme, your business can ensure the availability of the amount on your customer’s card for a maximum of 28 days for credit cards and 7 days for debit cards. If the transaction payment is not captured during the mentioned times, the held funds will be released by the issuing bank back to the cardholder.

To capture a payment, you need to consume the endpoint /pos/v1/transaction and send capture in the transaction_type field and Authorization in the transaction_mode field as part of the request body.

Important

Please note that the transaction_reference field must come from an authorization and not from a reauthorization.

Check the examples below:

ICC (Chip)

MCR (Magnetic Stripe)

NFC (Contactless)

{
  "card": {
    "card_holder_name": "John Doe"
  },
  "amount": {
    "iva": 0,
    "tip": 0,
    "currency": "PEN",
    "extra_taxes": {
      "iac": 0,
      "ice": 0,
      "airport_tax": 0,
      "travel_agency": 0
    },
    "subtotal_iva": 0,
    "subtotal_iva0": 60000
  },
  "country": "PER",
  "cvm_type": "none",
  "is_cashback": false,
  "is_deferred": false,
  "pos_details": {
    "brand": "SUNMI",
    "model": "P2-EU",
    "version": "Kushki SunmiV1.1.26",
    "location": {
      "latitude": -0.22480833333333333,
      "longitude": -78.487955
    },
    "has_print": true,
    "terminal_id": "PB04216R20537"
  },
  "card_details": {
    "tracks": {
      "track_ksn": "FFFF4357486333600002",
      "enc_track2": "283587285CE10278E7FA50AD5C97CFFE87F472C9FE6406F8"
    },
    "enc_tlv": "CE447A062C49774934E42A7F826668C0C478E38402C158062EE794C0E471B43EA8CE49C256C2C8B157526B0B2BE74FC23F65E18D4F52B99A1A0910E6CCD9B11A32D6D537E2B6E2B011C89569DE6A3D53318080BC77E0E70B398ED3083FD7366CCF8FB4DBF34A116E6D52CFBEF26371878D842034E5029EF62DF235D2C427F04102E451773D9E8975978917E3BC531327702967052E239F8C592734AE14688E603C52B858FC1D97B763AE623603F1475FFFB065EC07AF7A29",
    "pin_ksn": "FFFF4357486333600002",
    "reading_type": "ICC"
  },
  "contact_details": {
    "email": "",
    "last_name": "",
    "first_name": "",
    "phone_number": "",
    "document_type": "-1",
    "document_number": "",
    "second_last_name": ""
  },
  "transaction_mode": "Authorization",
  "transaction_type": "capture",
  "client_transaction_id": "6680eadc-6c8d-44aa-8ca0-18e061c1472a",
  "transaction_reference": "f2f29080-0214-42c0-95a5-77ecf3434cd7"
}

Cardless capture

Note

This functionality is currently in Beta phase in Peru.

To perform a cardless capture, send the omit_card field with the value of true and then the other non-required fields are omitted:

{
    "amount": {
        "currency": "PEN",
        "iva": 0.0,
        "subtotal_iva": 0.0,
        "subtotal_iva0": 600
    },
    "transaction_mode": "Authorization",
    "transaction_type": "capture",
    "client_transaction_id": "6680eadc-6c8d-44aa-8ca0-18e061c1472a",
    "transaction_reference": "f2f29080-0214-42c0-95a5-77ecf3434cd7",
    "omit_card": true
}

Process Reauthorizations

With this service, you can perform the following actions to modify a transaction that was previously approved:

Increase the payment amount or make an adjustment to the authorization.

Tip

Sending an amount of 0 in the reauthorization is a common practice to extend the capture date without actually capturing any funds from the cardholder’s account.

To perform reauthorizations, you need to consume the endpoint /pos/v1/transaction and send reAuthorization in the transaction_type field and Authorization in the transaction_mode field as part of the request body.

Check the examples below:

ICC (Chip)

MCR (Magnetic Stripe)

NFC (Contactless)

{
  "card": {
    "card_holder_name": "John Doe"
  },
  "amount": {
    "iva": 0,
    "tip": 0,
    "currency": "PEN",
    "extra_taxes": {
      "iac": 0,
      "ice": 0,
      "airport_tax": 0,
      "travel_agency": 0
    },
    "subtotal_iva": 0,
    "subtotal_iva0": 6000
  },
  "country": "PER",
  "cvm_type": "none",
  "is_cashback": false,
  "is_deferred": false,
  "pos_details": {
    "brand": "SUNMI",
    "model": "P2-EU",
    "version": "Kushki SunmiV1.1.26",
    "location": {
      "latitude": -0.22480833333333333,
      "longitude": -78.487955
    },
    "has_print": true,
    "terminal_id": "PB04216R20537"
  },
  "card_details": {
    "tracks": {
      "track_ksn": "FFFF4357486333600002",
      "enc_track2": "283587285CE10278E7FA50AD5C97CFFE87F472C9FE6406F8"
    },
    "enc_tlv": "CE447A062C49774934E42A7F826668C0C478E38402C158062EE794C0E471B43EA8CE49C256C2C8B157526B0B2BE74FC23F65E18D4F52B99A1A0910E6CCD9B11A32D6D537E2B6E2B011C89569DE6A3D53318080BC77E0E70B398ED3083FD7366CCF8FB4DBF34A116E6D52CFBEF26371878D842034E5029EF62DF235D2C427F04102E451773D9E8975978917E3BC531327702967052E239F8C592734AE14688E603C52B858FC1D97B763AE623603F1475FFFB065EC07AF7A29",
    "pin_ksn": "FFFF4357486333600002",
    "reading_type": "ICC"
  },
  "contact_details": {
    "email": "",
    "last_name": "",
    "first_name": "",
    "phone_number": "",
    "document_type": "-1",
    "document_number": "",
    "second_last_name": ""
  },
  "transaction_mode": "Authorization",
  "transaction_type": "reAuthorization",
  "client_transaction_id": "6680eadc-6c8d-44aa-8ca0-18e061c1472a",
  "transaction_reference": "f2f29080-0214-42c0-95a5-77ecf3434cd7"
}

Cardless Reauthorization

Note

This functionality is currently in Beta phase in Peru.

To perform a cardless reauthorization, send the omit_card field with the value of true and then the other non-required fields are omitted:

{
    "amount": {
        "currency": "PEN",
        "iva": 0.0,
        "subtotal_iva": 0.0,
        "subtotal_iva0": 600
    },
    "transaction_mode": "Authorization",
    "transaction_type": "reAuthorization",
    "client_transaction_id": "6680eadc-6c8d-44aa-8ca0-18e061c1472a",
    "transaction_reference": "f2f29080-0214-42c0-95a5-77ecf3434cd7",
    "omit_card": true
}

Void a preauthorization or reauthorization

If you need to void an authorization or reauthorization to release the funds to the cardholder, you can do so by performing a void, using the transaction_reference obtained in the authorization.

To void an authorization or reauthorization, send Void in the transaction_mode field, preAuth or reAuthorization in the transaction_type and the client_transaction_id (an ID for the void transaction) as part of the body of your request along with the transaction_reference of the preauthorization or reauthorization to cancel.

Note

How to cancel a preauthorization with associated reauthorizations?
You only need to void the last generated reauthorization.

Cardless void

Note

This functionality is currently in Beta phase in Peru.

To perform a cardless operation, send the omit_card field with the value of true and then the other non-required fields are omitted:

{
  "amount": {
    "iva": 0,
    "currency": "PEN",
    "subtotal_iva": 0,
    "subtotal_iva0": 600
  },
  "omit_card": true,
  "transaction_mode": "Void",
  "transaction_type": "preAuth",
  "client_transaction_id": "6680eadc-6c8d-44aa-8ca0-18e061c1472a",
  "transaction_reference": "f2f29080-0214-42c0-95a5-77ecf3434cd7"
}

Two-step-payments

Processing preauthorizations, captures, and reauthorizations#

Supported Reading Channels#

Preauthorize a payment#

Capture a payment (optional)#

Cardless capture#

Process Reauthorizations#

Cardless Reauthorization#

Void a preauthorization or reauthorization#

Cardless void#

Processing preauthorizations, captures, and reauthorizations

Supported Reading Channels

Preauthorize a payment

Capture a payment (optional)

Cardless capture

Process Reauthorizations

Cardless Reauthorization

Void a preauthorization or reauthorization

Cardless void