Properties   Methods   Events   Configuration Settings  

The PTCanadianDebit component is used to authorize face-to-face Interac (Canadian) debit card transactions with the Paymentech NetConnect system on the Tampa platform. This component allows for simple, direct, secure communication to the Paymentech SSL gateway through a standard Internet connection. This component can be integrated into web pages or stand-alone Point Of Sale applications. Because all SSL communications are handled inside the component, any application or web page can be deployed without the need for expensive dedicated SSL servers.

NOTE: What follows is a very short description of the component interfaces. For more information, please consult the help files that come with the respective package.

Remarks

Canadian debit card processing on the Paymentech system is fundamentally different than authorizing US Debit cards. The US protocol requires an encrypted PIN block and Key Sequence Number (KSN), retrieved from a PIN Pad utilizing the DUKPT (DES/3DES) encryption protocols. However, Interac (Canadian) Debit uses Master/Session key authentication to retrieve an encrypted key from a PIN Pad. This is a much more complex procedure, and requires the use of a Chase Paymentech certified PIN pad. (we recommend the Ingenico i3070).

A unique key per device for both the PIN key and the MAC key is required. All PIN pads must have a unique key injected at the time of deployment. In order for Chase Paymentech to identify the Master Key being used by the device, the PIN pad serial number (PinPadSerialNumber) is required to be sent with every transaction.

Before you can send any debit card transactions, you must first load the PIN Pad with a current session key. This is retrieved from Paymentech via the RequestCurrentKeys method. Two keys will be returned in the response: Response (also known as TPK) and Response (also known as TAK). Both keys must be loaded into the PIN pad device. The PIN key is used by the PIN pad to encrypt the customer's PIN, and the MAC key is used to generate hash values used in requests and responses. These keys are updated after every transaction, and the PIN pad must be updated with the current keys each time a response is received.

Each transaction you send (excluding RequestCurrentKeys and MACReversals) requires an accompanying MACValue. This value is a hash of the contents of GetRequestDataToMAC, and is hashed by the PIN Pad device using the Response returned in response to the last transaction.

In each response there is also a Response. You must use the PIN Pad to calculate the hash of the value returned by GetResponseDataToMAC for each response, and make sure that calculated value matches the Response. If they do not match, you cannot accept the transaction, and you must send an MACReversal transaction. (For MACReversals you may send the MACValue used in the original request, or omit it entirely - do not calculate a new one)

The following code illustrates the steps necessary to initialize the PIN Pad and begin sending transactions:

First, set up the component with your merchant information.

' Set up the component component.MerchantNumber = "yourMerchantNumber" component.TerminalNumber = "100" component.ClientNumber = "0002" component.UserId = "yourUserId" component.Password = "yourPassword"

Then, retrieve the current PIN and MAC encryption keys with the RequestCurrentKeys method, as shown below. (The following code will also update the EncryptedKeyIndex).

component.SequenceNumber = 1 component.PinPadSerialNumber = "FFFFFFFFFFFFFFFF" ' retrieved from your PIN Pad component.RequestCurrentKeys()

After receiving a valid response to RequestCurrentKeys, it is essential that you update the PIN pad with the Response and Response. The Response is used by the PIN pad to encrypt the customer's pin, and the Response is used by the PIN pad's MAC function. Now we are able to send an actual customer sale transaction. First, set up the transaction details:

component.SequenceNumber = 2 component.InteracTransactionType = ittSale ' Set this before calling GetRequestDataToMAC component.TransactionAmount = "1.00"

Now, have the customer swipe his card, and pass the TransactionAmount, Card, and GetRequestDataToMAC to the PIN pad in a PURCHASE transaction. After the customer enters his PIN, use the response from the PIN pad to fill the following properties:

component.CardTrack2Data = "9999999800002773=05121015432112345678" ' retrieved from your card reader component.AccountType = acctChecking ' retrieved from your PIN pad component.EncryptedPIN = "FFFFFFFFFFFFFFFF" ' retrieved from your PIN pad component.MACValue = "FFFFFFFF" ' retrieved from your PIN pad

Once all the above properties are set, you can call the Authorize method to send the transaction to Paymentech for authorization.

component.Authorize()

If the transaction was successful, the Response property will contain "A" (for Approval). Before processing the response, you must first analyze the response with the PIN pad to verify that the Response is correct, load the newly returned keys, and print the transaction's success or failure on the PIN pad device for the customer to read. To do this, you send the Response, Response, and GetResponseDataToMAC to the PIN pad in a "Response Analysis" transaction. The PIN Pad response will indicate if the MAC value matches and the keys were successfully loaded.

If the MAC validated correctly, you're done with this transaction. However, if it did not validate, then you must send a MACReversal to abort the transaction, and then re-send it. If you are unable to verify the contents of the Response after another transaction attempt, refresh your keys via the RequestCurrentKeys method and try again. You must call RequestCurrentKeys any time the PIN pad loses sync with the Paymentech server, or whenever the Response property is True. (Or when initializing the PIN pad for the first time)

The status of any of the above transactions will be stored in the Response property, with human-readable text appearing in Response. Like the PTCHARGE component, there are several other Response fields which will contain data that should be logged. However, there are a few new properties specific to the PTCanadianDebit component that must be printed on each customer's receipt. These include Response, Response, and Response.

Once an authorization request is approved, one of two things happen. If your Paymentech account is setup with the Host Auto Close feature, you need take no further action. The host will close the current open batch at a designated time each day. This means that there is no end of day batch processing required from the merchant. In order for the merchant's batch to be included in the Paymentech Host Auto Close process, the merchant parameter file on the host must indicate that the merchant is Auto Close. Without this flag being set, the merchant's transactions must be settled with a Manual Batch Release.

If your account is not setup with Host Auto Close, then after an authorization is approved the transaction is added to the current batch on the Paymentech Server, and the money in the customer's account is blocked and tagged for the merchant. The transaction must go through the Manual Batch Release Settlement process in order for the blocked money to be transferred to the merchant's account. To release a batch for settlement, please see the PTSETTLE component.

Note that this component only supports the above two settlement methods, and does not support Terminal Capture processing.

Note: All PIN pads must be certified with Chase Paymentech and Interac prior to being used or deployed. All injection services must be approved and certified by Chase Paymentech.

Method List

Event List

Configuration Settings