Overview

The Smart Card API will allow to every functionality related to a smart card. It means that every task which involves a card reader, such as NFC, magnetic band, SAM ... This API provides all the necessary functionalities for working with smart cards and card readers.

It supports transport, EMV, or both environments. Nowadays, this API gives support to the following devices:

Verifone: UX410

A general outline of the Smart Card Manager API can be observed in the following figure:

Smart Card Manager API

Functionalities

The Smart Card Manager API provides the following functionalities:

Device operations
- Asynchronous operations:
  - Get devices: Get devices connected to the equipment.
  - Get reader: Get readers connected to a specific device.
  - Get version: Get the software information of a reader
  - Add keys: Add keys to a specific device, those keys can be loaded from json file or C++ structure.
  - Get keys: Get keys from specific device.
  - Remove keys: Remove keys from specific device.
  - Play media profile: Play a specific profile (sounds and lights).
  - Add media profile: Add a new media profile.
  - Get media profile: Get a specific media profile.
  - Remove all media profiles: Remove all media profiles.
  - Get PCI DSS reboot time: Get the reboot time for PCI DSS.
  - Set PCI DSS reboot time: Set a new reboot time for PCI DSS.
  - Set network properties: Allows to change the network configuration.DHCP under revision.
  - Get network properties: Allows to get the current network configuration.
- Synchronous operations:
  - Get PCI DSS reboot time: Get the reboot time for PCI DSS.
  - Set PCI DSS reboot time: Set a new reboot time for PCI DSS.
- Subscription functionalities:
  - Device status change: Device status change (new o remove device).
  - PCI DSS reboot time events: Every status change related to PCI DSS reboot time.
  - Upgrade status: Every upgrade status change.
Card operations
- Asynchronous operations:
  - Card operation: Send any type of operation to a smart card.
  - Payment request: Start an EMV transaction
  - Payment confirmation: Confirm/cancel a EMV transaction
  - Set Payment Application status: Set a configuration for the Payment Application responsible of EMV transaction.
  - Get Payment Application information: Get the current status of the Payment Application.
  - Get Payment Application configuration: Get the current configuration of the Payment Application.
  - Set Payment Application configuration: Set the current configuration of the Payment Application.
  - Pass through: Send any command to smart cards.
  - Ultralight counter value: Get the current ultralight counter value.
  - Ultralight counter increment: Increment the a ultralight counter.
- Synchronous operations:
  - Read: Read blocks or pages of Mifare Classic or Ultralight smart cards.
  - Write: Write blocks or pages of Mifare Classic or Ultralight smart cards.
  - APDU Exchange: Exchange APDUs to smart cards.
  - Pass through: Send any command to smart cards.
  - Ultralight counter value: Get the current ultralight counter value.
  - Ultralight counter increment: Increment the a ultralight counter.
- Subscription functionalities:
  - New card events: Subscribe to new card events, available or removed smart cards.
  - Payment request result: The result of a payment EMV request.

What should you know before starting your application development?

How can I know which devices are connected?

The Smart Card Service is able to work with multiple smart card readers regardless the type. The service knows when a reader is connected or disconnected in run time, and it publishes at the moment, if there is any status change. In order to get this functionality, you have to subscribe to new device list event functionality.
Synchronous operations:
- Read: Synchronous operation for reading blocks or pages of Mifare Classic or Ultralight smart cards.
- Write: Synchronous operation for writing blocks or pages of Mifare Classic or Ultralight smart cards.
- APDU Exchange: Synchronous operation for exchanging APDUs to smart cards.
Subscription functionalities:
- New card events: Subscribe to new card events, available or removed smart cards.
- Payment request result: The result of a payment EMV request.

Once you know the devices which are connected, you, for sure, need which readers are available for use. In many cases, one device may have several readers, such as few SAM slots and one contactless reader, for instance. You can get this information by requesting the available readers for a specific device and it returns a list of the available readers and its type.

But.... How can I know when there is a card in the field?

Well, you can subscribe to every card event triggered by the reader. For example, if a smart card has been approached or removed to the field, it is immediately received the UID and the card event type.

I have received an event, now, how can I interact with the card?

The API provide all the functionalities for smart cards, such as reading or writing blocks/pages or exchange APDUs. Moreover, it has been provide a multipurpose method for any kind of operation that it is wanted to take in any type of smart card, just using the card operation functionality. Knowing the development software complexity, in this case, it has been provided synchronous and asynchronous methods. Because, sometimes the card transactions demand synchronous operations, because the next operation depends on the result of the previous one. Furthermore, it is possible to give more efficiency to our software implementing the asynchronous methods, giving the possibility to launch a request and continue with other task meanwhile it is been dealing with that request.

What can I do if my smart card requires authentication?

Ok, the smart cards need authentication, for those cases it is possible to add, get and remove keys. Moreover, it is possible to load those keys from the source code or json file. Giving the chance to the final costumer. Once the keys are set, the service will automatically authenticate for each request.

Well, I know how to develop a transport application, but.... if I want EMV capabilities?

If you want to include the EMV functionality in your project, you must know few things before starting. As you well know, there is a Payment Application which is responsible of the EMV transactions. This application needs some previous configuration, for example, if it is a equipment installed into a bus, you must configure the ticket price, the operator ID, the route, if you support online, offline mode or both ... In order to configure the Payment Application, it is crucial do it during the start up. Also, the Payment Gateway of the project is.

If there is an EMV transaction, you should sent a payment request specifying the ticket price. Afterwards, it will be published the transaction result with all the information related to that transaction. By this way, it is given the responsibility to the user to confirm or cancel that transaction in the following message.

CAUTION! According to PCI Security Standards, the ux410 Verifone terminal must reboot every 24h, therefore it is strongly recommended to configure this PCI time.

Constraint: The SAM cards are detected during the start up of the terminal. Threfore, if any SAM is changed when the application is running, it will not be detected. And the system will report the last SAM read.

It is highly recommend to read carefully all the documentation about the SCM and study the system before starting the development. Furthermore, it is crucial to know which device is going to be connected, it does not have the same behaviours a Verifone than Ingenico device.

EMV Configuration and requests

Payment Application configuration

Note: The typical transport fields are highlighted.

Field	Description	Length (Bytes / string)
*Access point code*	Access point code	less-than 20
*Access point type*	Access point type. Available values: "input", "output"	string
*Transport operator ID*	Transport operator identifier	6
Online mode	It indicates which pricing plan is configured. Available values: "variable-kft", "fix-kft", "pinpad", "0-mtt", "1-mtt"	string
Offline mode	The terminal shall work in offline mode. Available values: "on", "off"	string
Offline backup	The terminal shall work in offline mode the online mode fails. Available values: "on", "off"	string
*Price*	Ticket price	10
Transaction mode configuration	Transaction mode configuration	6
End of day time	At which time it is made the shift change	4
Blacklist	Enable/disable blacklist. Available values: "on", "off"	string
Black list update timer	Timer in minutes for updating the black list in the payment terminal	2
Black list update retries	How much updating retries can be done before refusing bank cards	2
Black list time without updates	Number of hours without updating the black list	2
White list	Enable/disable white list. Available values: "on", "off"	string
ODA Card	Enable/disable ODA cards. Available values: "on", "off"	string
Passback timer	Timer for counting the consecutive logins	2
Passback number	Maximum number of attempts that can be done with bank card	3
Language	Terminal language. Available languages: "spanish", "catalan", "english", "french", "german", "italian", "portuguese", "galician", "basque", "valencian"	string
Destination mode	Destination mode configuration	4
*Route*	It indicates the route which is done in the vehicle where is installed the payment terminal	less-than 10
*Transport zone*	It indicates the zone where is the transport vehicle which has installed the payment terminal	less-than 10
*Stop*	It indicates the stop where is the transport vehicle which has installed the payment terminal	less-than 60
*Employee ID*	It indicates the employee id	less-than 60
*Vehicle*	Vehicle id	less-than 60
*Extra*	Extra information, such us expedition	less-than 256

Payment Application status

Field	Options
Work mode indicator	Gateway disable: The payment terminal has not communication with Redsys
	Redsys: The payment terminal has communications with Redsys
Functionality indicator	Idle: The payment terminal is operational
	Not available: The payment terminal is not operational.
	Not initialised: The payment terminal has not been initialised
	No keys: The payment terminal has no keys
	Terminal broken: The payment terminal has some failure
	No communications: The payment terminal has no GPRS signal or connectivity
Protocol version	Version protocol: library version which enables the communication between the Transport and Payment application

Payment Requests

Field	Options
Ticket mode	Disable ticket: The payment terminal must not generate operation ticket
	Client ticket: The payment terminal shall generate the client ticket
	Both tickets: The payment terminal shall generate the trade and client ticket
Error code	Specific transaction code result.
Request type	Sale: Sale
	Full overview: Query for grand total
	Countable closing: Query for countable closing
	General operation detail: Query for detailing general operations
	Particular operation detail: Query for detailing single operations
	Print local copy: Query for printing a local copy
	Print last online copy: Query for printing the last online copy
	Trade allocation: Query for assigning the trade allocation
	ECO query: ECO query
Product type	Debit: Debit card
	Credit: Credit card
	Commercial: Commercial card
	Prepaid: Prepaid card
	Private: Some private card
	Unknown product: No known product
Technology type	Contactless EMV card
	Contactless EMV NFC device (e.g smartphone, smartwatch, smartband...)
	Contactless band card
	Contactless band NFC device.
	Contact EMV
	Magnetic band
	Unknown technology
Application ID	Application identifier, it indicates the smart card brand of the operation
Country ID	The issuing country of the smart card
Cancellation	Confirm or cancel the charge request

Specific Error codes

This service also provides a concret set of SCM errors, which specify the result of a Smart Card transaction. It is also given the global DPY error. Those erros could be found here:

Dpy SCM Error Smart Card Manager Errors Library