Take Payments

December 09, 2024

Accept payments with a certified POS terminal from your point of sale through the Raw card-present API. With the Raw card-present API you can use and manage your own terminals, connecting to our payment network to process transactions. You must securely generate and manage the cryptographic keys that will allow you to encrypt the information read from the card through the terminals. Send the required information in the request to perform a successful operation through our API.

Request data model

These are all the parameters you can configure when making a request.

Property	Type	Required	Description	Allowed values
amount	Object	Yes	Total transaction amount (including tip and taxes).
amount.currency	String	Yes	Transaction currency.	`MXN`, `COP`, `USD`, `CLP`, `PEN`
amount.iva	Number	Yes	Value Added Tax (IVA) amount.
amount.subtotal_iva	Number	Yes	Transaction amount excluding taxes.
amount.subtotal_iva0	Number	Yes	If the transaction does not have taxes, place the total amount in this property.
amount.tip	Number	No	Optional amount to add tip to the transaction.
amount.extra_taxes	Object	No	Object with additional tax properties.
amount.extra_taxes.airport_tax	Number	No	Airport tax.
amount.extra_taxes.iac	Number	No	Aggregate consumption tax.
amount.extra_taxes.ice	Number	No	Special consumption tax.
amount.extra_taxes.travel_agency	Number	No	Used in airlines
card	Object	No	Object with card information.
card.card_holder_name	String	No	Cardholder name.
card_details	Object	Yes	Object with card information.
card_details.enc_tlv	String	No	Only required for CHIP reading transactions. It is a field containing encrypted information that comes from the EMV chips of the cards.
card_details.pin_block	String	No	The pin block is a block of data that is used to encapsulate a personal identification number (PIN) during the process.
card_details.pin_ksn	String	No	Required if the `pin_block` field is sent. It is required in the DUKPT process to identify which initial key was used to encrypt the information.
card_details.pin_ksn_desc	String	No	Pin descriptor.
card_details.reading_type	String	Yes	Type of reading: `ICC` : Chip. `MCR`: Magnetic stripe. `NFC`: Contactless.	`ICC`, `MCR`, `NFC`
card_details.tracks	Object	Yes	Object with information read from the card.
card_details.tracks.enc_track1	String	No	Required when reading by magnetic stripe (MCR). Encrypted information contained within the card.
card_details.tracks.enc_track2	String	No	Required when reading by chip (ICC), magnetic stripe (MCR) or contactless (NFC). Encrypted information contained within the card.
card_details.tracks.track_ksn	String	Yes	Required when reading by chip (ICC) or contactless (NFC). Data encryption key.
card_details.tracks.track_ksn_desc	String	No	Required when sending the `track_ksn` property. KSN descriptor.
card_details.tracks.track2_length	String	No	Number in string format that represents the length of `enc_track2` but without the filler digits to complete the 16 positions.
client_transaction_id	String	Yes	IUUID v4 generated from the merchant side. It must be a unique ID per transaction.
country	String	Yes	Country (ISO 3166-1 alpha-3).	`COL`, `MEX`, `CHL`, `PER`
is_deferred	Boolean	No	Flag to set a transaction as deferred
deferred	Object	No	Required when the `is_deferred` property is set to `true`. Object with the transaction’s deferred settings.
deferred.months	String	No	Number of installments.
is_cashback	Boolean	No	Flag to perform a cashback operation.
cashback_amount	Number	No	Required when submitting the `is_cashback` property. Set the cashback amount.
pos_details	Object	Yes	Object containing information about the terminal.
pos_details.brand	String	Yes	Terminal brand.
pos_details.has_print	Boolean	No	Indicate whether the terminal has an integrated printer.
pos_details.location	Object	No	Object with location information.
pos_details.location.latitude	Number	No	Latitude from which the transaction originates.
pos_details.location.longitude	Number	No	Longitude from which the transaction originates.
pos_details.model	String	No	Terminal model.
pos_details.terminal_id	String	No	Terminal ID generated on your side.
pos_details.version	String	No	Terminal software version.
contact_details	Object	Yes	Object with customer information.
contact_details.document_number	String	No	Customer identification document number.
contact_details.document_type	String	Yes	Identification document type
contact_details.email	String	No	Customer email.
contact_details.first_name	String	No	Customer name.
contact_details.last_name	String	No	Customer last name.
contact_details.second_last_name	String	No	Second surname (applies only to Colombia).
contact_details.phone_number	String	No	Customer phone number.
transaction_mode	String	Yes	Transaction mode.	`Authorization`, `Reverse`, `Void`
transaction_type	String	Yes	Transaction type.	`capture`, `charge`, `preAuth`, `reAuthorization`, `tip`, `refund`
cvm_type	String	Yes	Cardholder Verification Methods.. `none` : No pin or signature verification method. `pin`: Pin verification method. `signature`: Signature verification method.	`none`, `pin`, `signature`
sub_merchant	Object	No	Object with merchant information.
sub_merchant.mcc	String	No	Merchant category code.
sub_merchant.id_affiliation	String	No	Merchant affiliation ID.
sub_merchant.soft_descriptor	String	No	Text that will appear on the cardholder’s statement. It is useful to help customers identify purchases and avoid unrecognized charges.
sub_merchant.city	String	No	City
sub_merchant.city_code	String	No	City code (ISO 3166-2). Required for Mexico only.
sub_merchant.country_ans	String	No	ISO 3166-1 alpha-3.
sub_merchant.zip_code	String	No	Zip code.
sub_merchant.address	String	No	Address.
sub_merchant.social_reason	String	No	Social reason. Applies only to Visa transactions.
sub_merchant.code	String	No	Submerchant ID.
merchant_id	String	No	Merchant ID.
omit_card	Boolean	No	Perform a cardless operation. Available only in Chile.
metadata	Object	No	Object with additional merchant information.

Operations

Discover all the operations available through Raw card-present API integrations.

Sale

Take present payment with physical or digital cards at your local store via a terminal. The terminal allows you to read your customer’s card and perform operations involved in the DUKPT process. The responsibility of your POS system is to send the data read from the terminal to Kushki for processing.

To make a sale, consume the Single payment endpoint, set the transaction mode (transaction_mode) to Authorization, the transaction type (transaction_type) to charge, and send the rest of the required information.

Request example:

{
  "card": {
    "card_holder_name": "John Doe"
  },
  "amount": {
    "iva": 0,
    "currency": "MXN",
    "subtotal_iva": 0,
    "subtotal_iva0": 60000
  },
  "country": "MEX",
  "cvm_type": "none",
  "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": "",
    "second_last_name": ""
  },
  "transaction_mode": "Authorization",
  "transaction_type": "charge",
  "client_transaction_id": "6680eadc-6c8d-44aa-8ca0-18e061c1472a"
}

Cashback

To perform a cashback transaction, consume the Single payment endpoint, set the transaction mode and transaction type the same as in a sale, set the is_cashback property to true, and set the amount of cash to withdraw during the transaction in the cashback_amount property.

Request example:

{
  "is_cashback": true,
  "cashback_amount": 1000,  
  "card": {
    "card_holder_name": "John Doe"
  },
  "amount": {
    "iva": 0,
    "currency": "MXN",
    "subtotal_iva": 0,
    "subtotal_iva0": 60000
  },
  "country": "MEX",
  "cvm_type": "none",
  "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": "",
    "second_last_name": ""
  },
  "transaction_mode": "Authorization",
  "transaction_type": "charge",
  "client_transaction_id": "6680eadc-6c8d-44aa-8ca0-18e061c1472a"
}

Tipping

To add tip during a transaction, consume the Single payment endpoint, set the transaction mode and transaction type the same as in a sale, and set the tip amount in the tip property inside the amount object.

Request example:

{ 
  "card": {
    "card_holder_name": "John Doe"
  },
  "amount": {
    "tip": 100,
    "iva": 0,
    "currency": "MXN",
    "subtotal_iva": 0,
    "subtotal_iva0": 60000
  },
  "country": "MEX",
  "cvm_type": "none",
  "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": "",
    "second_last_name": ""
  },
  "transaction_mode": "Authorization",
  "transaction_type": "charge",
  "client_transaction_id": "6680eadc-6c8d-44aa-8ca0-18e061c1472a"
}

For more information on how to add tip in a transaction, please see our FAQ section.

Post-tipping

Make a separate transaction to collect the tip amount after checkout in case it was omitted during the sale.

To make a post-tip sale, consume the Single payment endpoint, set the transaction mode (transaction_mode) to Authorization, the transaction type (transaction_type) to posTip, and set the tip amount in the subtotal_iva0 property inside the amount object.

Request example:

{ 
  "card": {
    "card_holder_name": "John Doe"
  },
  "amount": {
    "iva": 0,
    "currency": "MXN",
    "subtotal_iva": 0,
    "subtotal_iva0": 100
  },
  "country": "MEX",
  "cvm_type": "none",
  "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": "",
    "second_last_name": ""
  },
  "transaction_mode": "Authorization",
  "transaction_type": "charge",
  "client_transaction_id": "6680eadc-6c8d-44aa-8ca0-18e061c1472a"
}

Deferred payments

To make a deferred payment, consume the Single payment endpoint, set the transaction mode and transaction type the same as in a sale, set the is_deferred property to true, and set the number of installments to defer a payment in the months property within the deferred object.

Request example:

{
  "is_deferred": true,
  "deferred": {
    "months": "12"
  },
  "card": {
    "card_holder_name": "John Doe"
  },
  "amount": {
    "iva": 0,
    "currency": "MXN",
    "subtotal_iva": 0,
    "subtotal_iva0": 60000
  },
  "country": "MEX",
  "cvm_type": "none",
  "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": "",
    "second_last_name": ""
  },
  "transaction_mode": "Authorization",
  "transaction_type": "charge",
  "client_transaction_id": "6680eadc-6c8d-44aa-8ca0-18e061c1472a"
}

Pre-authorization

In case you need to reserve an amount from your client’s bank account, you can use the pre-authorization service. For example, when your merchant needs to request a deposit to guarantee that the total cost will be financed at the end of the service, you can retain a specific amount from your client’s bank account.

To perform a pre-authorization, consume the Authorization and capture endpoint, set the transaction mode (transaction_mode) to Authorization, the transaction type (transaction_type) to preAuth, and send the rest of the required information.

Request example:

{
  "card": {
    "card_holder_name": "John Doe"
  },
  "amount": {
    "iva": 0,
    "currency": "MXN",
    "subtotal_iva": 0,
    "subtotal_iva0": 60000
  },
  "country": "MEX",
  "cvm_type": "none",
  "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": "",
    "second_last_name": ""
  },
  "transaction_mode": "Authorization",
  "transaction_type": "preAuth",
  "client_transaction_id": "6680eadc-6c8d-44aa-8ca0-18e061c1472a"
}

Reauthorization

If you need to modify the amount of a previously pre-authorization or extend the date of the capture, you can use the reauthorization service. Send an amount equal to $0 in a reauthorization to extend the capture period or send an amount in the reauthorization to extend the pre-authorization.

To perform a reauthorization, consume the Authorization and capture endpoint, set the transaction mode (transaction_mode) to Authorization, the transaction type (transaction_type) to reAuthorization, and send the rest of the required information.

Request example:

{
  "card": {
    "card_holder_name": "John Doe"
  },
  "amount": {
    "iva": 0,
    "currency": "MXN",
    "subtotal_iva": 0,
    "subtotal_iva0": 60000
  },
  "country": "MEX",
  "cvm_type": "none",
  "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": "",
    "second_last_name": ""
  },
  "transaction_mode": "Authorization",
  "transaction_type": "reAuthorization",
  "client_transaction_id": "6680eadc-6c8d-44aa-8ca0-18e061c1472a"
}

Capture

Once you are required to collect the funds from your customer’s bank account, capture the amount for only the products or services used.

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 Authorization and capture endpoint, set the transaction mode (transaction_mode) to Authorization, the transaction type (transaction_type) to capture and add the transaction_reference property with the value of the reference returned at the time of performing a pre-authorization

Request example:

{
  "transaction_reference": "d5979f96-0449-414b-9ece-b0b3681089d6"
  "card": {
    "card_holder_name": "John Doe"
  },
  "amount": {
    "iva": 0,
    "currency": "MXN",
    "subtotal_iva": 0,
    "subtotal_iva0": 60000
  },
  "country": "MEX",
  "cvm_type": "none",
  "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": "",
    "second_last_name": ""
  },
  "transaction_mode": "Authorization",
  "transaction_type": "capture",
  "client_transaction_id": "6680eadc-6c8d-44aa-8ca0-18e061c1472a"
}

Response

If the information submitted is correct, you will receive a response similar to the following with the information of the processed transaction.

{
  "F11": "101619",
  "cvm_type": "none",
  "franchise": "MASTERCARD",
  "message_fields": {
    "F38": "121866",
    "F39": "00"
  },
  "kushki_response": {
    "code": "000",
    "message": "Transacción Aprobada."
  },
  "transaction_type": "charge",
  "authorized_amount": 611,
  "additional_amounts": {
    "amount": 0,
    "card_type": "",
    "amount_type": "",
    "account_type": "",
    "currency_code": ""
  },
  "transaction_status": "APPROVAL",
  "transaction_reference": "fb1d8f34-31fc-4d9d-ab7e-375d7f0801a5"
}

In case of error, you can get a response with a structure similar to the following:

{
  "code": "E001",
  "details": {
    "Origin": "Process Generic Transaction | validateRequest",
    "Message": "document_number: cannot be blank; document_type: cannot be blank."
  },
  "message": "Cuerpo de la petición inválido."
}

See the full list of error codes.

Please review the Raw card-present API reference for more information.

Test data

Make any necessary adjustments to your system using the test data.

Transactions

Get the list of transactions with information relevant to your operations.