Raw card-present API overview

October 16, 2024

Raw card-present API allows you to integrate a PCI PTS V6.0, EMV Contactless L1, EMV L1 and EMV L2 certified POS terminal to our payment network to process transactions quickly and securely. You can perform different operations with this integration.

Features

Terminals

Integrate POS terminals that are PCI PTS V6.0, EMV Contactless L1, EMV L1 and EMV L2 certified. Check with your account manager for compatibility of your terminals.

Operations

These are the operations available for integrations through Raw card-present API:

• Sale
• Cashback
• Tipping (pre and post)
• Deferred payments
• Pre-authorization and Capture
• Reauthorization
• Transaction search
• Voids and refunds

Supported card brands

The following card networks and brands are accepted through Raw card-present API integrations:

• Visa
• Mastercard
• Carnet
• Sodexo
• Sí Vale
• Edenred

Requirements

Before you can perform an integration, you must meet the following requirements:

• Complete your merchant’s affiliation process with Kushki.
• Have a test account.
• Have POS terminals certified with PCI PTS V6.0, EMV Contactless L1, EMV L1 and EMV L2.
• Receive the public keys and private keys with which you can authenticate, validate, and authorize transactions from your merchant.
• Sign a Non-Disclosure Agreement (NDA) for the HSM (Hardware Security Module) service, which will upload the shared cryptographic key information. This process will ensure key protection, allowing your merchant to access the MYHSM portal.
• Create and maintain Security Officer (SO) information, including contact details and appropriate SO groups within the portal. These people will be responsible for the security key exchange process.
• Have a Hardware Security Module for secure storage of encryption keys.

Environments

Make any adjustments to your system by testing in a dev development environment.

When ready, you can switch to the live environment to process real transactions.

Process a payment

Here is the general process of how card-present payments work:

INTEGRATION

The integration between Kushki and your merchant will be established through a REST API, which employs a cryptographic key system that allows the secure exchange of information by encrypting the sensitive information read from your customers’ cards to process their requests quickly and under strict security and confidentiality standards.

CUSTOMER PAYMENT PROCESS

Your customer presents their physical or digital credit card or debit card at your point of sale. Your merchant’s POS terminal, which may be connected via USB, bluetooth or other connection types, performs the following actions:

• Reads the data received from your customer by means of magnetic stripe, chip or contactless payment (NFC).
• Sends the read data in encrypted form to your backend so that it can send the data to Kushki via the REST API.
• Kushki’s API processes the request and returns a response to your backend with the approval or denial of the received request. In case of a successful transaction, Kushki debits the transaction amount from your customer’s account.

Encryption keys

A cryptographic key exchange ceremony is required between Kushki and your merchant via hardware security modules (HSM) to ensure the integrity and security of the information. You will need to encrypt the information read from the customers’ card using the DUKPT process using the keys received. Learn more about cryptographic key exchange and review the test data to cover the different scenarios.

Credentials

To send requests to the API, you will need to have valid credentials. To obtain your credentials, log in to the administration panel according to the environment (dev or live), select the Developers module in the side menu and select the Credentials option.

You can add a new credential or use a previously created one.

Accept a payment

Consume the Single payment endpoint by sending the information required to process a transaction. You must generate the payload according to the data read from the card through the POS terminal.

Example of a payment request:

{
  "card": {
    "card_holder_name": "John Doe"
  },
  "amount": {
    "iva": 0,
    "tip": 0,
    "currency": "MXN",
    "subtotal_iva": 0,
    "subtotal_iva0": 2000
  },
  "country": "MEX",
  "pos_details": {
    "brand": "SUNMI",
    "model": "P2-EU",
    "version": "Kushki SunmiV1.1.13",
    "location": {
      "latitude": -0.1842214,
      "longitude": -78.4212761
    },
    "has_print": true,
    "terminal_id": "PB04209860189"
  },
  "card_details": {
    "tracks": {
      "track_ksn": "FFFF4357486333600002",
      "enc_track2": "283587285CE10278E7FA50AD5C97CFFE87F472C9FE6406F8"
    },
    "enc_tlv": "CE447A062C49774934E42A7F826668C0A53CE9AF633A510E66C8031171AAFCF8CE29857B19101326ED67512533B86C51ED16C5E624DA97EDA72864A39763822418FCAC5439D2F1F72F6FC0BAA6EED37630767D9D161612654E49944FC435525C6C356177B1BD0A545C19FF5E47685E35B02B20B307BDE2A26FAD2F42D7CB00BE9C53FD05BECE71110919ADE3158398B8B02003F682374B942C4B6D7FD54DE2B65A9C66125DF28A80",
    "pin_ksn": "FFFF4357486333600002",
    "reading_type": "NFC"
  },
  "contact_details": {
    "email": "",
    "last_name": "",
    "first_name": "",
    "phone_number": "",
    "document_type": "0",
    "document_number": "123666",
    "second_last_name": ""
  },
  "transaction_mode": "Authorization",
  "transaction_type": "charge",
  "client_transaction_id": "ae6dd91a-9173-4ec7-8934-3178454ef341"
}

Please review Take Payments for more information.