EMV Support in 4D Payments SDK

Requirements: 4D Payments SDK

Chapter Listing

  1. Overview
  2. EMV Transactions
  3. Downloading EMV Public Key and Other Parameters
  4. A Word on EMV Certification

Overview

4D Payments SDK supports the submission of EMV transaction data for the following processors:

  • FDMS Rapid Connect
  • TSYS (Terminal and Host Capture)
  • Paymentech (Terminal and Host Capture)
  • Global Payments

After obtaining the EMV data from the pin pad it may be passed to the component when performing the transaction. The EMV data is set via the EMVData property or configuration setting. For instance:

fdmsrcretail.EMVData = "9F4005F000F0A0019F02060000000...DF7906123456789012";

In addition to submitting EMV data for a transaction the EMVKeyMgr component provides a way to download EMV public key values for FDMS Rapid Connect and Paymentech.

EMV Transactions

The following sections detail how to submit EMV data for a transaction for the corresponding processor. EMV data must first be obtained from the EMV terminal which is outside the scope of this guide.

FDMS Rapid Connect – EMV Transactions

EMV transactions are supported in both FDMSRcRetail and FDMSRcDebit. Both signature and PIN based EMV are supported. EMV related settings:

  • EMVData – Specifies the EMV data.
  • EMVOnlinePIN – DUKPT DES encrypted PIN for EMV Online PIN transactions.
  • EMVOnlinePIN – Key Sequence Number for EMV Online PIN transactions.
  • Response.EMVData – The returned EMV data (if any).

Below is a basic EMV transaction for FDMS Rapid Connect. The EMVData property holds the EMV data obtained from the EMV terminal.

Fdmsrcretail fdmsrcretail = new Fdmsrcretail(); fdmsrcretail.IndustryType = FdmsrcretailIndustryTypes.fritRetail; fdmsrcretail.TPPID = "AAA000"; fdmsrcretail.MerchantTerminalNumber = "00000001"; fdmsrcretail.MerchantId = "1234"; fdmsrcretail.GroupId = "20001"; fdmsrcretail.DatawireId = "00011122233344455566"; fdmsrcretail.VisaIdentifier = "01000000000000"; fdmsrcretail.ApplicationId = "RAPIDCONNECTVXN"; fdmsrcretail.URL = "https://stg.dw.us.fdcnet.biz/rc"; fdmsrcretail.STAN = "112"; fdmsrcretail.TransactionNumber = "120013"; fdmsrcretail.ReferenceNumber = "123456"; fdmsrcretail.OrderNumber = "12000503"; fdmsrcretail.Card.MagneticStripe = "4761739001010010=15122011143804489"; fdmsrcretail.Card.EntryDataSource = EntryDataSources.edsTrack2; fdmsrcretail.TransactionAmount = "250"; fdmsrcretail.EMVData = "9F4005F000F0A0019F...F7906123456789012"; fdmsrcretail.Sale(); Console.WriteLine(fdmsrcretail.Response.Code + ": " + fdmsrcretail.Response.Text); Console.WriteLine("Response EMVData: " + fdmsrcretail.Response.EMVData);

Online PINs

To include online PIN information in FDMSRcRetail specify the EMVOnlinePin and EMVOnlineKSN configuration settings. For instance:

fdmsrcretail.Config("EMVOnlinePIN=83C33384650827F6"); fdmsrcretail.Config("EMVOnlineKSN=4A00310459400004"); fdmsrcretail.EMVData = "9F4005F000F0A0019F...F7906123456789012";

TSYS – EMV Transactions

EMV transactions are supported in both TSYSRetail and TSYSDebit. Both signature and PIN based EMV are supported.

Below is a basic EMV transaction with TSYS. TSYS offers additional configuration settings related to EMV accessed via the Config method. EMV related settings:

  • EMVData – Specifies the EMV data.
  • POSDataCode – Specifies the condition of the POS device used at the time.
  • EMVOnlinePIN – DUKPT DES encrypted PIN for EMV Online PIN transactions.
  • EMVOnlineKSN – Key Sequence Number for EMV Online PIN transactions.
  • ResponseEMVData – The returned EMV data (if any).
  • MessageReasonCode – Reversal reason code. Only used by TSYSReversal.

POSDataCode is required and specifies multiple details about the transaction. Please see the help file for additional details about these settings.

Tsysretail tsysretail = new Tsysretail(); tsysretail.Merchant.Zip = "27709"; tsysretail.Merchant.BankId = "999995"; tsysretail.Merchant.CategoryCode = "5999"; tsysretail.Merchant.Name = "TESTMERCHANT"; tsysretail.Merchant.Number = "888000002447"; tsysretail.Merchant.City = "800-1234567"; tsysretail.Merchant.State = "NC"; tsysretail.Merchant.StoreNumber = "5999"; tsysretail.Merchant.TerminalNumber = "1515"; tsysretail.Merchant.Zip = "27709"; tsysretail.IndustryType = DPayments.DPaymentsSDK.TsysretailIndustryTypes.sitRetail; tsysretail.TransactionNumber = tsysretail.TransactionNumber + 1; tsysretail.TransactionAmount = "100"; tsysretail.Card.MagneticStripe = "4761739001010010=15122011143804489"; tsysretail.Card.EntryDataSource = EntryDataSources.edsTrack2; tsysretail.Config("POSDataCode=CardInputCap=5;CardPresent=1;PINCaptureCap=4;CardholderAuthCap=1;TerminalOpEnv=1;CardholderPresent=0;CardInputMode=F;CardholderAuthMethod=1;CardholderAuthEntity=1;CardOutputCap=3;"); tsysretail.Config("EMVData=9F4005F000F0A0019F02...01234DF7906123456789012"); tsysretail.Authorize(); string emvData = tsysretail.Config("ResponseEMVData"); Console.WriteLine(tsysretail.Response.Code + ": " + tsysretail.Response.Text);

Online PINs

To include online PIN information in TSYSRetail specify the EMVOnlinePin and EMVOnlineKSN configuration settings. For instance:

tsysretail.Config("EMVOnlinePIN=83C33384650827F6"); tsysretail.Config("EMVOnlineKSN=4A00310459400004"); tsysretail.Config("POSDataCode=CardInputCap=5;CardPresent=1;PINCaptureCap=4;CardholderAuthCap=1;TerminalOpEnv=1;CardholderPresent=0;CardInputMode=F;CardholderAuthMethod=1;CardholderAuthEntity=1;CardOutputCap=3;"); tsysretail.Config("EMVData=9F4005F000F0A0019F02...01234DF7906123456789012");

Reversals

When performing a reversal of an EMV transaction with TSYSReversal the MessageReasonCode configuration setting must be set. Consult the help documentation for supported values.

Paymentech – EMV Transactions

EMV transactions are supported in PTechCharge, PTechRetail, PTechDebit, PTechHotel, and PTechCanadianDebit. Both signature and PIN based EMV are supported. EMV related settings:

  • EMVData – Specifies the EMV data.
  • EMVEntryDataSource – Specifies the EMV data entry source (DES).
  • EMVOnlinePIN – DUKPT DES encrypted PIN for EMV Online PIN transactions.
  • EMVOnlinePIN – Key Sequence Number for EMV Online PIN transactions.
  • ResponseEMVData – The returned EMV data (if any).
  • ResponseEMVCardAuthCode – The ChaseNet and Visa card authentication results code.
  • ResponseEMVDownloadIndicator – Whether EMV parameters should be updated.

Below is a basic EMV transaction with Paymentech.

Ptechretail ptechretail = new Ptechretail(); ptechretail.Server = "https://netconnectvar.paymentech.net/NetConnect/controller"; ptechretail.MerchantNumber = "700000000125"; ptechretail.TerminalNumber = "100"; ptechretail.ClientNumber = "0002"; ptechretail.UserId = "dpayments01"; ptechretail.Password = "dpaymentspw01"; ptechretail.InvoiceNumber = "inv123"; ptechretail.IndustryType = PtechretailIndustryTypes.pitRetail; ptechretail.SequenceNumber = 1; ptechretail.TransactionAmount = "11.00"; ptechretail.Card.MagneticStripe = "B4788250000028291^PAYMENTECH^09121015432112345678"; ptechretail.Card.EntryDataSource = EntryDataSources.edsTrack1; ptechretail.Config("EMVEntryDataSource=52"); // Chip (but not Contactless) Capable - Track 1 from swiped ptechretail.Config("EMVData=9F4005F000F0A0019F02060000000020...234DF7906123456789012"); ptechretail.Sale(); Console.WriteLine(ptechretail.Config("ResponseEMVData"));

Online PINs

To include online PIN information in PTechRetail specify the EMVOnlinePin and EMVOnlineKSN configuration settings. For instance:

ptechretail.Config("EMVOnlinePIN=1837AE06B216B6D7"); ptechretail.Config("EMVOnlineKSN=000000008F00002B");

Global Payments – EMV Transactions

EMV transactions are supported in GlobalCharge, and GlobalDebit. (Note: Global Payments does not currently support EMV Debit transactions). Both signature and PIN based EMV are supported. EMV related settings:

  • EMVCapable – Indicates whether the POS is EMV enabled.
  • EMVData – Specifies the EMV data.
  • EMVEntryDataSource – Specifies the EMV data entry source (DES).
  • EMVOnlinePIN – DUKPT DES encrypted PIN for EMV Online PIN transactions.
  • EMVOnlinePIN – Key Sequence Number for EMV Online PIN transactions.
  • ResponseEMVData – The returned EMV data (if any).

Below is a basic EMV transaction with Global Payments.

GlobalCharge1 = new Globalcharge(); //This is your Global UserName GlobalCharge1.UserId = "UserId"; //This is your Global Password GlobalCharge1.Password = "Password"; GlobalCharge1.Server = "https://certapia.globalpay.com"; GlobalCharge1.Card.MagneticStripe = "5499990123456781=18125025432198712345"; GlobalCharge1.Card.ExpMonth = 12; GlobalCharge1.Card.ExpYear = 18; GlobalCharge1.CustomerName = "John Doe"; GlobalCharge1.TransactionAmount = "7.77"; GlobalCharge1.InvoiceNumber = "12345"; GlobalCharge1.Config("EMVCapable=True"); GlobalCharge1.Config("EMVData=9F40056000F0A00.....125F24032512319F1E08324B393435343737"); GlobalCharge1.Config("EMVEntryDataSource=0"); // EMV GlobalCharge1.Sale(); Console.WriteLine(GlobalCharge1.Config("ResponseEMVData"));

Online PINs

To include online PIN information in GlobalCharge specify the EMVOnlinePin and EMVOnlineKSN configuration settings. For instance:

GlobalCharge1.Config("EMVOnlinePIN=83C33384650827F6"); GlobalCharge1.Config("EMVOnlineKSN=FFFF4A00310459400004");

Downloading EMV Public Key and Other Parameters

The EMVKeyMgr component provides a way to download EMV public key information and other EMV parameters from the respective processor as applicable. The EMV public key information includes the RID (Registered Application Provider Identifier), Index, Modulus, Exponent, CheckSum, and optional ExpDate.

In general, the following information can be obtained with this component.

Platform Available Information
FDMS Rapid Connect EMV Public Key information
TSYS None. Must be downloaded from the TSYS developer portal
Paymentech EMV Public Key information and Fallback information
Global Payments None. Must be downloaded from the Global Payments developer portal

Please refer to the help file for details about the individual properties and methods.

FDMS Rapid Connect – EMV Public Keys

FDMS Rapid Connect allows for EMV public key information to be periodically retrieved. In addition you can check for updates since the last time you downloaded the EMV public key information to see if any new information is available. Below is an example of this process.

emvkeymgr.TPPID = "AAA000"; emvkeymgr.MerchantTerminalNumber = "00000001"; emvkeymgr.MerchantId = "1234"; emvkeymgr.GroupId = "20001"; emvkeymgr.DatawireId = "00011122233344455566"; emvkeymgr.ApplicationId = "RAPIDCONNECTVXN"; emvkeymgr.URL = "https://stg.dw.us.fdcnet.biz/rc"; emvkeymgr.STAN = "112"; emvkeymgr.TransactionNumber = "120013"; emvkeymgr.KeyFileDate = "03262014120000"; emvkeymgr.KeyFileSize = 123; emvkeymgr.KeyFileCRC = "0000"; //Check if an update is available emvkeymgr.CheckForUpdate(); if (emvkeymgr.UpdateAvailable) { emvkeymgr.GetKeyInfo(); //Save these values to provide in the next CheckForUpdate call string origKeyCRC = emvkeymgr.KeyFileCRC; int origKeySize = emvkeymgr.KeyFileSize; string origKeyDate = emvkeymgr.KeyFileDate; //Iterate over the key details for (int i = 0; i < emvkeymgr.KeyDetails.Count; i++) { Console.WriteLine("RID: " + emvkeymgr.KeyDetails[i].RID); Console.WriteLine("ExpDate: " + emvkeymgr.KeyDetails[i].ExpDate); Console.WriteLine("Index: " + emvkeymgr.KeyDetails[i].Index); Console.WriteLine("Checksum: " + emvkeymgr.KeyDetails[i].CheckSum); Console.WriteLine("Modulus: " + emvkeymgr.KeyDetails[i].Modulus); Console.WriteLine("Exponent: " + emvkeymgr.KeyDetails[i].Exponent); Console.WriteLine("********************************"); } }

TSYS – EMV Public Keys

TSYS does not currently provide a way to obtain EMV parameters programmatically. Instead the EMV public key parameters must be downloaded manually from the TSYS Partner Portal. As such, there is no functionality within the EMVKeyMgr component to obtain EMV parameters from TSYS.

Paymentech – EMV Public Keys

Paymentech allows EMV public key information to be retrieved, and also includes an expiration date to know when that key information is expired and new information should be retrieved. In addition Paymentech also includes an indicator for each RID to indicate whether fallback to regular magnetic stripe transactions when the chip is unreadable is allowed. Below is an example of this process:

emvkeymgr.Platform = EmvkeymgrPlatforms.kpPaymentech; emvkeymgr.URL = "https://netconnectvar.paymentech.net/NetConnect/controller"; emvkeymgr.UserId = "userid"; emvkeymgr.Password = "password"; emvkeymgr.MerchantId = "700000000125"; emvkeymgr.MerchantTerminalNumber = "001"; emvkeymgr.ClientNumber = "0002"; emvkeymgr.GetKeyInfo(); //Iterate over the key details for (int i = 0; i < emvkeymgr.KeyDetails.Count; i++) { Console.WriteLine("RID: " + emvkeymgr.KeyDetails[i].RID); Console.WriteLine("Index: " + emvkeymgr.KeyDetails[i].Index); Console.WriteLine("Checksum: " + emvkeymgr.KeyDetails[i].CheckSum); Console.WriteLine("Modulus: " + emvkeymgr.KeyDetails[i].Modulus); Console.WriteLine("Exponent: " + emvkeymgr.KeyDetails[i].Exponent); Console.WriteLine("Fallback Allowed: " + emvkeymgr.KeyDetails[i].FallbackAllowed); Console.WriteLine("********************************"); }

Global Payments – EMV Public Keys

Global Payments does not currently provide a way to obtain EMV parameters programmatically. Instead the EMV public key parameters must be downloaded manually from the Global Payments Developer Portal. As such, there is no functionality within the EMVKeyMgr component to obtain EMV parameters from Global Payments.

A Word on EMV Certification

Since EMV certification is an end-to-end certification, you must perform your own EMV certification. The component cannot be certified since it is only one part of a larger solution. Contact your chosen processor for more details about certification.

If you are using TSYS contact acq-partnerprogram@tsys.com for help getting started.

We appreciate your feedback. If you have any questions, comments, or suggestions about this entry please contact our support team at support@4dpayments.com.