One-time payments

Integrate the Kushki services to accept one-time card-present 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.

In this guide, you will find a description of the card-present services enabled in your integration with Kushki.
Some of the available one-time payments you can perform are:

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

MCR = Magnetic Card reader

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 (it does not include tip). 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 (it does not include tip). 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	optional	✅	❌	✅
`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_deferred`	`boolean`	Alert to make a deferred payment	optional	✅	✅	✅
`deferred`	`object`	Required when `is_deferred` = `true`.	optional	✅	✅	✅
`deferred.months`	`string`	Number of months over which payment will be deferred	optional	✅	✅	✅
`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.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`	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.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	✅	✅	✅

Single charge

To make a charge, send charge in the transaction_type field and Authorization in the transaction_mode field as part of the body of your request.

ICC (Chip)

MCR (Magnetic Stripe)

NFC (Contactless)

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

Deferred charge

To defer a payment, if your customer requests to defer the charge of the transaction made at your store, you need to consume the endpoint https://api-uat.kushkipagos.com/pos/v1/transaction in the request body, include charge in the transaction_type field and Authorization in the transaction_mode field. Also, include the value of is_deferred in true, send the deferred object and in months, include the total number of months for which your customer’s payment will be deferred.

Send the deferred object along with the transaction details.

"deferred": {
    "months": "10"
}

Please see the full example below for more details:

{
  "card": {
    "card_holder_name": "Joe Doe"
  },
  "amount": {
    "iva": 0,
    "tip": 0,
    "currency": "PEN",
    "extra_taxes": {},
    "subtotal_iva": 0,
    "subtotal_iva0": 111
  },
  "country": "PER",
  "cvm_type": "none",
  "deferred": {
    "months": "10"
  },
  "is_cashback": false,
  "is_deferred": true,
  "pos_details": {
    "brand": "SUNMI",
    "model": "P2-EU",
    "version": "Kushki SunmiV1.1.28",
    "location": {
      "latitude": -1.2346533333333334,
      "longitude": -78.61959166666666
    },
    "has_print": true,
    "terminal_id": "PB04209860189"
  },
  "card_details": {
    "tracks": {
      "track_ksn": "FFFF4357486333600003",
      "enc_track2": "A5A26987202B4E8F3A595E0116A85E56D842005394315A18"
    },
    "enc_tlv": "8332743DB0D0FAA29CF0AA187558BE3EF056085299635BAD4147E5D50D70D6E01A396081D618BA3001AF8262CD8F52DC67C995D9E99E824EC7995FE20AD5E5FE850B29863A2E61D8BD6A2951A2F24CD0AEE4087020745EB48CC5B40E2AE2263D5BB47D4D508D8DC69E54C8ECC2AB6F471C299D1CAB1712CCD2E2D378A57D285E7139CCC6C98D57D8A6C30B1CE110DDE23C28C9C7FCAFEF2023AE4FC8B03BE86CA1B673D962D9E7EA",
    "pin_ksn": "FFFF4357486333600003",
    "reading_type": "NFC"
  },
  "transaction_mode": "Authorization",
  "transaction_type": "charge",
  "client_transaction_id": "dbdeb25b-b34a-4b6c-b664-085ea9552954"
}

Accepting payments with tips

You can accept payments with tips by adding an additional field with the tip information.

To accept this type of service, you need to consume the endpoint https://api-uat.kushkipagos.com/pos/v1/transaction and include the tip value in the tip field. Send Authorization in the transaction_mode field and charge in the transaction_type as part of the request body.

Check the example below:

{
  "card": {
    "card_holder_name": "CUST IMP MC 103"
  },
  "amount": {
    "iva": 0,
    "subtotal_iva": 0,
    "subtotal_iva0": 6000,
    "tip": 100,
    "currency": "PEN",
    "extra_taxes": {
      "iac": 0,
      "ice": 0,
      "airport_tax": 0,
      "travel_agency": 0
    }
  },
  "country": "PER",
  "cvm_type": "none",
  "is_cashback": false,
  "is_deferred": false,
  "merchant_id": "0987654321",
  "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": ""
  },
  "transaction_mode": "Authorization",
  "transaction_type": "charge",
  "client_transaction_id": "6680eadc-6c8d-44aa-8ca0-18e061c1472a"
}

Accepting payments with cashback (Perú 🇵🇪)

Kushki allows you to make a cashback at the time of a physical card payment. To accept this type of service, you need to consume the endpoint https://api-uat.kushkipagos.com/pos/v1/transaction and send the value of the is_cashback parameter in true and specify the cashback amount in cashback_amount.

Important

Please note that cashback only works with local cards.

Cashback is not supported for contactless transactions. Ensure the reading_type is not set to NFC.

Check the example below:

{
  "card": {
    "card_holder_name": "C92546CB8524197A17A1B960D5D09A01ABBE63E5478FD5155DBE2B18824771046EEA135D73B192236937AF33E781B81804098835D3A1AD81A863BAEA3BAA42E4"
  },
  "amount": {
    "iva": 0,
    "tip": 0,
    "currency": "PEN",
    "extra_taxes": {
      "iac": 0,
      "ice": 0,
      "airport_tax": 0,
      "travel_agency": 0
    },
    "subtotal_iva": 0,
    "subtotal_iva0": 2000
  },
  "country": "PER",
  "is_cashback": true,
  "pos_details": {
    "brand": "SUNMI",
    "model": "P2-EU",
    "version": "Kushki SunmiV1.1.13",
    "location": {
      "latitude": -0.1848534,
      "longitude": -78.4769761
    },
    "has_print": true,
    "terminal_id": "PB04209860189"
  },
  "card_details": {
    "tracks": {
      "track_ksn": "FFFF4357486333600002",
      "enc_track1": "06056D9EE9D77E4D846912F77C0B37C5FC6A95D1DF21DD502D3A08E8141CF82818F5DC4FA7637F400EA488D388F2B70F8A22EAEFBBEEDDE93A118BFB789BD8C0",
      "enc_track2": "FD580B3BBFCCB821EAB4AB64947C4632C0BE6C70AB4ECDE4"
    },
    "pin_ksn": "FFFF4357486333600002",
    "reading_type": "MCR"
  },
  "cashback_amount": 20,
  "transaction_mode": "Authorization",
  "transaction_type": "charge",
  "client_transaction_id": "ae6dd91a-9173-4ec7-8934-3178454ef341"
}

Supported Reading Channels#

Single charge#

Deferred charge#

Accepting payments with tips#

Accepting payments with cashback (Perú 🇵🇪)#

Supported Reading Channels

Single charge

Deferred charge

Accepting payments with tips

Accepting payments with cashback (Perú 🇵🇪)