Raw card-present API overview

June 26, 2025

Raw card-present API allows you to integrate a certified POS terminal to our payment network to process transactions quickly and securely. You can perform different operations with this integration.

Features

Operations

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

• Sale
• 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.

Brand Certification (Visa and Mastercard)

Certification with Visa and Mastercard brands is required in the following cases:

1. When a new integration with Kushki is performed due to the incorporation of a new acquirer or card network (Visa, Mastercard, Amex, Diners).
2. Before launching a new terminal model or updating its firmware.
3. If the EMV kernel or transaction logic that impacts the payment flow is modified.
4. If required by any of the brand schemes (Visa, Mastercard, etc.).

Types of Certification

Each brand has a specific process:

• Visa: Requires certification with the ADVT (Acquirer Device Validation Toolkit) and CDET (Contactless Device Evaluation Toolkit) protocols.
• Mastercard: Requires passing M-TIP (Mastercard Terminal Integration Process) certification.

These certifications validate that the hardware and software involved comply with the technical and security standards required by each brand.

Support During Certification

Kushki accompanies merchants in this process with the support of its Engineering and Integrations teams, ensuring that the covered scenarios reflect the merchant’s real operations.

There are also certifying houses authorized by the brands that can provide direct assistance in the validation and execution of the process. The merchant can decide which entity to contract for this support.

Certification Environment

Certification is not carried out in the traditional testing environment, but in a dedicated environment:

https://api-qa-acq.orizaba.kushki.dev

This environment is specifically enabled to execute the test cases required by Visa and Mastercard.

What Scenarios Must Be Certified?

Only the real scenarios that will be operated with Kushki need to be certified. It is not mandatory to validate cases that will not be used.

Some examples of scenarios that may be part of the certification include:

• Debit or credit card payments.
• Contactless transactions.
• Payments for low amounts (below the floor limit) or high amounts.
• Transactions with installments option.
• Combinations of the above for each brand.

The exact number and nature of the cases to be certified will depend on the merchant’s operating model and needs.

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.