PTechCanadianDebit Class

Properties   Methods   Events   Config Settings   Errors  

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

Class Name

DPaymentsSDK_PTechCanadianDebit

Procedural Interface

 dpaymentssdk_ptechcanadiandebit_open();
 dpaymentssdk_ptechcanadiandebit_close($res);
 dpaymentssdk_ptechcanadiandebit_register_callback($res, $id, $function);
 dpaymentssdk_ptechcanadiandebit_get_last_error($res);
 dpaymentssdk_ptechcanadiandebit_get_last_error_code($res);
 dpaymentssdk_ptechcanadiandebit_set($res, $id, $index, $value);
 dpaymentssdk_ptechcanadiandebit_get($res, $id, $index);
 dpaymentssdk_ptechcanadiandebit_do_authorize($res);
 dpaymentssdk_ptechcanadiandebit_do_config($res, $configurationstring);
 dpaymentssdk_ptechcanadiandebit_do_getrequestdatatomac($res);
 dpaymentssdk_ptechcanadiandebit_do_getresponsedatatomac($res);
 dpaymentssdk_ptechcanadiandebit_do_interrupt($res);
 dpaymentssdk_ptechcanadiandebit_do_macreversal($res);
 dpaymentssdk_ptechcanadiandebit_do_requestcurrentkeys($res);
 dpaymentssdk_ptechcanadiandebit_do_reset($res);
 dpaymentssdk_ptechcanadiandebit_do_reversaladvice($res, $originaltransactiontype, $reasoncode);

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: ResponsePINKey (also known as TPK) and ResponseMACKey (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 ResponseMACKey returned in response to the last transaction.

In each response there is also a ResponseMACValue. 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 ResponseMACValue. If they do not match, you cannot accept the transaction, and you must send an MACReversal transaction (tor 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 class with your merchant information. ' Set up the class class.MerchantNumber = "yourMerchantNumber" class.TerminalNumber = "100" class.ClientNumber = "0002" class.UserId = "yourUserId" class.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). class.SequenceNumber = 1 class.PinPadSerialNumber = "FFFFFFFFFFFFFFFF" ' retrieved from your PIN Pad class.RequestCurrentKeys() After receiving a valid response to RequestCurrentKeys, it is essential that you update the PIN pad with the ResponsePINKey and ResponseMACKey. The ResponsePINKey is used by the PIN pad to encrypt the customer's pin, and the ResponseMACKey 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: class.SequenceNumber = 2 class.InteracTransactionType = ittSale ' Set this before calling GetRequestDataToMAC method class.TransactionAmount = "1.00" Now, have the customer swipe his card, and pass the TransactionAmount, CardNumber, 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: class.CardTrack2Data = "9999999800002773=05121015432112345678" ' retrieved from your card reader class.AccountType = acctChecking ' retrieved from your PIN pad class.EncryptedPIN = "FFFFFFFFFFFFFFFF" ' retrieved from your PIN pad class.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. class.Authorize() If the transaction was successful, the ResponseCode property will contain "A" (for Approval). Before processing the response, you must first analyze the response with the PIN pad to verify that the ResponseMACValue 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 ResponsePINKey, ResponseMACKey, 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 ResponseMACValue 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 ResponseForceKeyRequest 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 ResponseCode property, with human-readable text appearing in ResponseText. Like the PTechCharge class, there are several other Response fields which will contain data that should be logged. However, there are a few new properties specific to the PTechCanadianDebit class that must be printed on each customer's receipt. These include ResponseRetrievalNumber, ResponseTime, and ResponseTrace.

Debit card transactions are instant funds transfers. There is no block placed on the debit card, funds are immediately removed and sent to the merchant. Therefore, only the Host Capture settlement mode is supported. At the end of the day you should release the current batch using the PTechHostSettle class (the batch may contain other authorizations that were made using different classs from this product. See the documentation for the other classs you are using for more information).

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.

Property List

The following is the full list of the properties of the class with short descriptions. Click on the links for further details.

Method List

The following is the full list of the methods of the class with short descriptions. Click on the links for further details.

Event List

The following is the full list of the events fired by the class with short descriptions. Click on the links for further details.

Config Settings

The following is a list of config settings for the class with short descriptions. Click on the links for further details.

AccountType Property (DPaymentsSDK_PTechCanadianDebit Class)

Account type selected by the cardholder.

Object Oriented Interface

public function getAccountType();


public function setAccountType($value);

Procedural Interface

dpaymentssdk_ptechcanadiandebit_get($res, 1 );


dpaymentssdk_ptechcanadiandebit_set($res, 1, $value );

Default Value

0

Remarks

Canadian debit cards allow the customer to choose the account he or she wishes to pay with. Allowable account types are listed below:

Note that sending an Authorize transaction with AccountType set to acctNotSet will result in an error.

Data Type

Integer

CardNumber Property (DPaymentsSDK_PTechCanadianDebit Class)

The credit card number parsed from the CardTrack2Data .

Object Oriented Interface

public function getCardNumber();

Procedural Interface

dpaymentssdk_ptechcanadiandebit_get($res, 2 );

Default Value

''

Remarks

This read-only property will be computed by the class after the CardTrack2Data property is set.

This property is read-only.

Data Type

String

CardTrack2Data Property (DPaymentsSDK_PTechCanadianDebit Class)

The Track2 portion of the debit card's magnetic stripe.

Object Oriented Interface

public function getCardTrack2Data();


public function setCardTrack2Data($value);

Procedural Interface

dpaymentssdk_ptechcanadiandebit_get($res, 3 );


dpaymentssdk_ptechcanadiandebit_set($res, 3, $value );

Default Value

''

Remarks

This property should contain the track 2 data read from the debit card's magnetic stripe. This includes everything after but not including the start sentinel (;) and up to but not including the end sentinel (?) and LRC check character. You may only set this property with track 2 data, track 1 data will cause an error.

So if the full magnetic stripe read from the card is "%B4788250000028291^PAYMENTECH^05121015432112345678?;4788250000028291=05121015432112345678?", then this property should be set as follows:

class.CardTrack2Data = "4788250000028291=05121015432112345678"

Industry regulations do not allow merchants or processors to store track data in any form of persistent storage. Failure to abide by this regulation can result in significant fines and other penalties.

Data Type

String

ClientNumber Property (DPaymentsSDK_PTechCanadianDebit Class)

Merchant configuration property, assigned by Paymentech.

Object Oriented Interface

public function getClientNumber();


public function setClientNumber($value);

Procedural Interface

dpaymentssdk_ptechcanadiandebit_get($res, 4 );


dpaymentssdk_ptechcanadiandebit_set($res, 4, $value );

Default Value

''

Remarks

The ClientNumber will be supplied to you by Paymentech.

Data Type

String

DebitCashBack Property (DPaymentsSDK_PTechCanadianDebit Class)

Optional cash back amount for debit transactions.

Object Oriented Interface

public function getDebitCashBack();


public function setDebitCashBack($value);

Procedural Interface

dpaymentssdk_ptechcanadiandebit_get($res, 5 );


dpaymentssdk_ptechcanadiandebit_set($res, 5, $value );

Default Value

''

Remarks

This property may contain an optional cash back amount when authorizing a debit card transaction. The value of the TransactionAmount must reflect the cost of the goods or service purchased plus this DebitCashBack amount. This property is presented in CA Dollars with a decimal point in the proper position. The maximum value for this property is "999999.99". To send a transaction without cashback, set DebitCashBack to "".

This must be formatted as a dollar amount with a real decimal point, excluding the dollar sign. For instance "12.00"

Data Type

String

DebitSurcharge Property (DPaymentsSDK_PTechCanadianDebit Class)

Extra amount the merchant charges the customer for using a debit card.

Object Oriented Interface

public function getDebitSurcharge();


public function setDebitSurcharge($value);

Procedural Interface

dpaymentssdk_ptechcanadiandebit_get($res, 6 );


dpaymentssdk_ptechcanadiandebit_set($res, 6, $value );

Default Value

''

Remarks

Surcharging in Canada is optional at the point of sale terminal device. The amount of the surcharge is defined at the Point of Sale (POS) and must be accepted by the cardholder prior to the transaction being processed. If the DebitSurcharge property contains a value, the surcharge amount will be logged to the transaction record on the Host. The Surcharge Amount must be included as part of the transaction amount. Regulations require that this fee amount print on the receipt and be clearly labeled as "TERMINAL FEE" or "FRAIS D'OPER." For example:

In this case, the receipt would read: SALE $10.00 CASH BACK $ 5.00 TERMINAL FEE $ .50 TOTAL CHARGED $15.50

Data Type

String

EncryptedKeyIndex Property (DPaymentsSDK_PTechCanadianDebit Class)

Specifies the current keys that are in use in the PIN pad and by Paymentech.

Object Oriented Interface

public function getEncryptedKeyIndex();


public function setEncryptedKeyIndex($value);

Procedural Interface

dpaymentssdk_ptechcanadiandebit_get($res, 7 );


dpaymentssdk_ptechcanadiandebit_set($res, 7, $value );

Default Value

0

Remarks

The EncryptedKeyIndex specifies the current keys that are in use on the host (Paymentech) and in the PIN pad. This EncryptedKeyIndex is updated after every transaction, and is required to be sent in all transactions except a RequestCurrentKeys transaction. The normal range is from 1 through 9. The default is zero (0), and indicates that no encryption keys have been established. Transaction requests should never be sent with a value of zero (0). Note that MACReversals must be sent with the EncryptedKeyIndex from the original transaction to insure that the EncryptedPIN can be properly translated by the host.

Keys are required to be renewed every:

• 200 Transactions
• 24 Hours
• Each time a Batch is released for settlement
• Whenever the PIN pad loses sync with the server

If the ResponseForceKeyRequest property is True after any transaction, you must immediately perform a RequestCurrentKeys transaction before sending any more authorizations.

Data Type

Integer

EncryptedPIN Property (DPaymentsSDK_PTechCanadianDebit Class)

Customer's PIN, encrypted by a PIN pad under the current PINKey .

Object Oriented Interface

public function getEncryptedPIN();


public function setEncryptedPIN($value);

Procedural Interface

dpaymentssdk_ptechcanadiandebit_get($res, 8 );


dpaymentssdk_ptechcanadiandebit_set($res, 8, $value );

Default Value

''

Remarks

The EncryptedPIN block is required by all InteracTransactionTypes, as well as the MACReversal and ReversalAdvice methods. Only the RequestCurrentKeys method does not require this property. The maximum length for this property is 16 characters.

Data Type

String

InteracTransactionType Property (DPaymentsSDK_PTechCanadianDebit Class)

Indicates the type of transaction to authorize.

Object Oriented Interface

public function getInteracTransactionType();


public function setInteracTransactionType($value);

Procedural Interface

dpaymentssdk_ptechcanadiandebit_get($res, 9 );


dpaymentssdk_ptechcanadiandebit_set($res, 9, $value );

Default Value

27

Remarks

This property indicates the type of transaction that is to be sent in an Authorize request. The GetRequestDataToMAC method also uses this property when generating the data which must be MAC'ed by the PIN pad device. In addition to the transaction types listed below, this class also allows you to send MAC Reversals, Current Key Requests, and Reversal Advice transactions using the MACReversal, RequestCurrentKeys, and ReversalAdvice methods, respectively. Allowable transactions types include:

Data Type

Integer

LastRetrievalNumber Property (DPaymentsSDK_PTechCanadianDebit Class)

The last RetrievalNumber received from the host. Used for Void transactions.

Object Oriented Interface

public function getLastRetrievalNumber();


public function setLastRetrievalNumber($value);

Procedural Interface

dpaymentssdk_ptechcanadiandebit_get($res, 10 );


dpaymentssdk_ptechcanadiandebit_set($res, 10, $value );

Default Value

''

Remarks

When sending a transaction with the InteracTransactionType set to ittVoidSale or ittVoidReturn, this property must contain the ResponseRetrievalNumber from the very last transaction that you sent to the Paymentech Server. RetrievalNumberToVoid should be set with the ResponseRetrievalNumber of the transaction you wish to void.

Data Type

String

MACValue Property (DPaymentsSDK_PTechCanadianDebit Class)

Hash of transaction data used to verify message was not tampered with.

Object Oriented Interface

public function getMACValue();


public function setMACValue($value);

Procedural Interface

dpaymentssdk_ptechcanadiandebit_get($res, 11 );


dpaymentssdk_ptechcanadiandebit_set($res, 11, $value );

Default Value

''

Remarks

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 ResponseMACKey returned in response to the last transaction.

The GetRequestDataToMAC method returns a string containing the values of several transaction properties. This string must be MAC'ed by the PIN pad, so it is essential that the following properties be set before calling GetRequestDataToMAC:

• MerchantNumber
• TerminalNumber
• InteracTransactionType
• CardTrack2Data
• TransactionAmount
• SequenceNumber
• and optionally AccountType

Note that VeriFone pinpads support a PURCHASE transaction where the CardTrack2Data, EncryptedPIN, AccountType, and MACValue are returned in a single step. When using a VeriFone pad make sure AccountType is set to acctNotSet, otherwise the MACValue will not be calculated correctly. (AccountType must be set before calling GetRequestDataToMAC for Ingenico pads)

class.MerchantNumber = "yourMerchantNumber" class.TerminalNumber = "100" class.ClientNumber = "0002" class.UserId = "yourUserId" class.Password = "yourPassword" class.SequenceNumber = 2 class.TransactionAmount = "1.00" class.PinPadSerialNumber = "30700015P3600000" ' from label on back of PIN pad class.InteracTransactionType = ittSale class.AccountType = acctChecking class.CardTrack2Data = "9999999800002773=05121015432112345678" ' from card reader class.EncryptedPIN = "FFFFFFFFFFFFFFFF" ' from the PIN pad ' Now use the PIN pad to MAC the value returned from GetRequestDataToMAC ' and then set MACValue with the results class.MACValue = "FFFFFFFF" class.Authorize()

Data Type

String

MerchantNumber Property (DPaymentsSDK_PTechCanadianDebit Class)

A unique number used to identify the merchant, assigned by Paymentech.

Object Oriented Interface

public function getMerchantNumber();


public function setMerchantNumber($value);

Procedural Interface

dpaymentssdk_ptechcanadiandebit_get($res, 12 );


dpaymentssdk_ptechcanadiandebit_set($res, 12, $value );

Default Value

''

Remarks

This 12 digit field contains a unique number to identify the merchant to the host.

Data Type

String

Password Property (DPaymentsSDK_PTechCanadianDebit Class)

Password for authentication with the NetConnect Server .

Object Oriented Interface

public function getPassword();


public function setPassword($value);

Procedural Interface

dpaymentssdk_ptechcanadiandebit_get($res, 13 );


dpaymentssdk_ptechcanadiandebit_set($res, 13, $value );

Default Value

''

Remarks

The Password will be supplied to you by Paymentech.

Data Type

String

PinPadSerialNumber Property (DPaymentsSDK_PTechCanadianDebit Class)

The serial number retrieved from the PIN pad.

Object Oriented Interface

public function getPinPadSerialNumber();


public function setPinPadSerialNumber($value);

Procedural Interface

dpaymentssdk_ptechcanadiandebit_get($res, 14 );


dpaymentssdk_ptechcanadiandebit_set($res, 14, $value );

Default Value

''

Remarks

Your PIN pad will have a function that will return the PIN pad serial number. This number is used to identify the key being used by the PIN pad device to the Paymentech transaction sever, and is required to be sent in every transaction.

All PIN pad serial numbers MUST be unique. You must update the PinPadSerialNumbers property with a new value retrieved from the PIN pad device before each transaction.

All PIN Pad Serial Numbers can be variable in length, but must be a minimum of 9-bytes long, and a maximum of 16-bytes long.

The serial number of a PIN pad is usually printed on the label on the bottom of the unit. The PIN pad may also include the option of displaying the serial number on the screen or returning it through a COM interface. Please see the developer documentation for your specific PIN pad for more information.

Data Type

String

ProxyAuthScheme Property (DPaymentsSDK_PTechCanadianDebit Class)

This property is used to tell the class which type of authorization to perform when connecting to the proxy.

Object Oriented Interface

public function getProxyAuthScheme();


public function setProxyAuthScheme($value);

Procedural Interface

dpaymentssdk_ptechcanadiandebit_get($res, 15 );


dpaymentssdk_ptechcanadiandebit_set($res, 15, $value );

Default Value

0

Remarks

This property is used to tell the class which type of authorization to perform when connecting to the proxy. This is used only when the ProxyUser and ProxyPassword properties are set.

ProxyAuthScheme should be set to authNone (3) when no authentication is expected.

By default, ProxyAuthScheme is authBasic (0), and if the ProxyUser and ProxyPassword properties are set, the component will attempt basic authentication.

If ProxyAuthScheme is set to authDigest (1), digest authentication will be attempted instead.

If ProxyAuthScheme is set to authProprietary (2), then the authorization token will not be generated by the class. Look at the configuration file for the class being used to find more information about manually setting this token.

If ProxyAuthScheme is set to authNtlm (4), NTLM authentication will be used.

For security reasons, setting this property will clear the values of ProxyUser and ProxyPassword.

Data Type

Integer

ProxyAutoDetect Property (DPaymentsSDK_PTechCanadianDebit Class)

This property tells the class whether or not to automatically detect and use proxy system settings, if available.

Object Oriented Interface

public function getProxyAutoDetect();


public function setProxyAutoDetect($value);

Procedural Interface

dpaymentssdk_ptechcanadiandebit_get($res, 16 );


dpaymentssdk_ptechcanadiandebit_set($res, 16, $value );

Default Value

false

Remarks

This property tells the class whether or not to automatically detect and use proxy system settings, if available. The default value is false.

Data Type

Boolean

ProxyPassword Property (DPaymentsSDK_PTechCanadianDebit Class)

This property contains a password if authentication is to be used for the proxy.

Object Oriented Interface

public function getProxyPassword();


public function setProxyPassword($value);

Procedural Interface

dpaymentssdk_ptechcanadiandebit_get($res, 17 );


dpaymentssdk_ptechcanadiandebit_set($res, 17, $value );

Default Value

''

Remarks

This property contains a password if authentication is to be used for the proxy.

If ProxyAuthScheme is set to Basic Authentication, the ProxyUser and ProxyPassword are Base64 encoded and the proxy authentication token will be generated in the form Basic [encoded-user-password].

If ProxyAuthScheme is set to Digest Authentication, the ProxyUser and ProxyPassword properties are used to respond to the Digest Authentication challenge from the server.

If ProxyAuthScheme is set to NTLM Authentication, the ProxyUser and ProxyPassword properties are used to authenticate through NTLM negotiation.

Data Type

String

ProxyPort Property (DPaymentsSDK_PTechCanadianDebit Class)

This property contains the Transmission Control Protocol (TCP) port for the proxy Server (default 80).

Object Oriented Interface

public function getProxyPort();


public function setProxyPort($value);

Procedural Interface

dpaymentssdk_ptechcanadiandebit_get($res, 18 );


dpaymentssdk_ptechcanadiandebit_set($res, 18, $value );

Default Value

80

Remarks

This property contains the Transmission Control Protocol (TCP) port for the proxy ProxyServer (default 80). See the description of the ProxyServer property for details.

Data Type

Integer

ProxyServer Property (DPaymentsSDK_PTechCanadianDebit Class)

If a proxy Server is given, then the HTTP request is sent to the proxy instead of the server otherwise specified.

Object Oriented Interface

public function getProxyServer();


public function setProxyServer($value);

Procedural Interface

dpaymentssdk_ptechcanadiandebit_get($res, 19 );


dpaymentssdk_ptechcanadiandebit_set($res, 19, $value );

Default Value

''

Remarks

If a proxy ProxyServer is given, then the HTTP request is sent to the proxy instead of the server otherwise specified.

If the ProxyServer property is set to a domain name, a DNS request is initiated. Upon successful termination of the request, the ProxyServer property is set to the corresponding address. If the search is not successful, an error is returned.

Data Type

String

ProxySSL Property (DPaymentsSDK_PTechCanadianDebit Class)

This property determines when to use a Secure Sockets Layer (SSL) for the connection to the proxy.

Object Oriented Interface

public function getProxySSL();


public function setProxySSL($value);

Procedural Interface

dpaymentssdk_ptechcanadiandebit_get($res, 20 );


dpaymentssdk_ptechcanadiandebit_set($res, 20, $value );

Default Value

0

Remarks

This property determines when to use a Secure Sockets Layer (SSL) for the connection to the proxy. The applicable values are as follows:

Data Type

Integer

ProxyUser Property (DPaymentsSDK_PTechCanadianDebit Class)

This property contains a username if authentication is to be used for the proxy.

Object Oriented Interface

public function getProxyUser();


public function setProxyUser($value);

Procedural Interface

dpaymentssdk_ptechcanadiandebit_get($res, 21 );


dpaymentssdk_ptechcanadiandebit_set($res, 21, $value );

Default Value

''

Remarks

This property contains a username if authentication is to be used for the proxy.

If ProxyAuthScheme is set to Basic Authentication, the ProxyUser and ProxyPassword properties are Base64 encoded and the proxy authentication token will be generated in the form Basic [encoded-user-password].

If ProxyAuthScheme is set to Digest Authentication, the ProxyUser and ProxyPassword properties are used to respond to the Digest Authentication challenge from the server.

If ProxyAuthScheme is set to NTLM Authentication, the ProxyUser and ProxyPassword properties are used to authenticate through NTLM negotiation.

Data Type

String

ResponseApprovalCode Property (DPaymentsSDK_PTechCanadianDebit Class)

Contains an authorization code when a transaction has been approved, or an error code.

Object Oriented Interface

public function getResponseApprovalCode();

Procedural Interface

dpaymentssdk_ptechcanadiandebit_get($res, 22 );

Default Value

''

Remarks

Contains an authorization code when a transaction has been approved, or an error code. This six character field contains an authorization code when a transaction has been approved. If the ResponseCode returned indicates that the transaction has not been approved, then this field will contain an error code, and the ResponseText property will contain the description. Note that the host does not send back an actual authorization code for Credit Returns. Instead, the host sends back six blank spaces in the authorization code field. Credit VOIDS return the original authorization number.

See the list of errors for this class for more information.

This property is read-only.

Data Type

String

ResponseAuthSource Property (DPaymentsSDK_PTechCanadianDebit Class)

Indicates the source of the authorization code stored in ApprovalCode .

Object Oriented Interface

public function getResponseAuthSource();

Procedural Interface

dpaymentssdk_ptechcanadiandebit_get($res, 23 );

Default Value

''

Remarks

Indicates the source of the authorization code stored in ResponseApprovalCode. This field contains a one character code indicating the source of the ResponseApprovalCode. The received code must be stored and submitted in the batch settlement. Valid source codes:

This property is read-only and not available at design time.

Data Type

String

ResponseBatchNumber Property (DPaymentsSDK_PTechCanadianDebit Class)

Current open batch number This property is returned after sending a BatchInquiry or BatchRelease transaction with the PTECHHOSTSETTLE class, or after a SendSettlement sent using the PTECHMANUALSETTLE class.

Object Oriented Interface

public function getResponseBatchNumber();

Procedural Interface

dpaymentssdk_ptechcanadiandebit_get($res, 24 );

Default Value

''

Remarks

Current open batch number This property is returned after sending a BatchInquiry or BatchRelease transaction with the PTechHostSettle class, or after a SendSettlement sent using the PTechManualSettle class.

This property is read-only.

Data Type

String

ResponseCode Property (DPaymentsSDK_PTechCanadianDebit Class)

Indicates the status of the authorization request.

Object Oriented Interface

public function getResponseCode();

Procedural Interface

dpaymentssdk_ptechcanadiandebit_get($res, 25 );

Default Value

''

Remarks

Indicates the status of the authorization request. This is the property used to determine whether a transaction has been approved or not. Valid values for this property are:

See the list of errors for this class for more information.

This property is read-only.

Data Type

String

ResponseForceKeyRequest Property (DPaymentsSDK_PTechCanadianDebit Class)

Indicates the host requires the class to re-synchronize keys.

Object Oriented Interface

public function getResponseForceKeyRequest();

Procedural Interface

dpaymentssdk_ptechcanadiandebit_get($res, 26 );

Default Value

false

Remarks

Indicates the host requires the class to re-synchronize keys. If after any transaction the ForceKeyRequest is True, you must immediately perform a RequestCurrentKeys transaction to refresh the PIN and MAC keys on the PIN pad. If you do not call RequestCurrentKeys your PIN pad will be out of sync with Paymentech and further transactions may fail.

This property is read-only.

Data Type

Boolean

ResponseMACKey Property (DPaymentsSDK_PTechCanadianDebit Class)

MAC Encryption key to be loaded into the PIN pad device.

Object Oriented Interface

public function getResponseMACKey();

Procedural Interface

dpaymentssdk_ptechcanadiandebit_get($res, 27 );

Default Value

''

Remarks

MAC Encryption key to be loaded into the PIN pad device. MAC encryption key encrypted under the PIN pad master key. This key changes as required by Interac regulations, and should be loaded into the PIN pad device upon receipt. The developer should validate the MACValue returned in the host response using this key. Future transactions must contain a MACValue that was computed by the PIN pad using this key.

Keys are required to be renewed every:

• 200 Transactions
• 24 Hours
• Each time a Batch is released for settlement
• Whenever the PIN pad loses sync with the server

If the ResponseForceKeyRequest property is True after any transaction, you must immediately perform a RequestCurrentKeys transaction before sending any more authorizations.

This property is read-only.

Data Type

String

ResponseMACValue Property (DPaymentsSDK_PTechCanadianDebit Class)

Hash value that must be validated by the PIN pad after each response.

Object Oriented Interface

public function getResponseMACValue();

Procedural Interface

dpaymentssdk_ptechcanadiandebit_get($res, 28 );

Default Value

''

Remarks

Hash value that must be validated by the PIN pad after each response. Each successful response to a transaction will include a ResponseMACKey and a ResponseMACValue. The ResponseMACKey (and ResponsePINKey) should be loaded into the PIN pad device upon receipt. The ResponseMACValue is a string encrypted by the Paymentech server using the ResponseMACKey, and is included in every successful response message. The original unencrypted data is returned by the GetResponseDataToMAC method. After loading the ResponseMACKey into the PIN pad device, send both ResponseMACValue and GetResponseDataToMAC to the PIN pad device for validation. If the PIN pad indicates the MAC matches, you're done, and you can continue processing transactions. However, if the PIN pad indicates the MAC did not match, you must immediately perform a MACReversal transaction, and consider the request as not approved.

A mismatched MAC value may mean that something was corrupted in data transmission, the response packet was tampered with, or that the keys loaded into your PIN pad device are not synchronized with Paymentech. Try synchronizing your keys with the RequestCurrentKeys method and then re-submitting the transaction.

This property is read-only.

Data Type

String

ResponsePINKey Property (DPaymentsSDK_PTechCanadianDebit Class)

PIN Encryption key to be loaded into the PIN pad device.

Object Oriented Interface

public function getResponsePINKey();

Procedural Interface

dpaymentssdk_ptechcanadiandebit_get($res, 29 );

Default Value

''

Remarks

PIN Encryption key to be loaded into the PIN pad device. PIN encryption key encrypted under the PIN pad master key. This key changes as required by Interac regulations, and should be loaded into the PIN pad device upon receipt. Future transactions must contain an encrypted PIN block (EncryptedPIN) that was computed by the PIN pad using this key.

Keys are required to be renewed every:

• 200 Transactions
• 24 Hours
• Each time a Batch is released for settlement
• Whenever the PIN pad loses sync with the server

If the ResponseForceKeyRequest property is True after any transaction, you must immediately perform a RequestCurrentKeys transaction before sending any more authorizations.

This property is read-only.

Data Type

String

ResponseRetrievalNumber Property (DPaymentsSDK_PTechCanadianDebit Class)

Reference number returned from the Paymentech host.

Object Oriented Interface

public function getResponseRetrievalNumber();

Procedural Interface

dpaymentssdk_ptechcanadiandebit_get($res, 30 );

Default Value

''

Remarks

Reference number returned from the Paymentech host. This is the reference number of the transaction as assigned by the Paymentech host. This number must remain with the transaction for the duration of the transaction's life cycle. This information is sent as a parameter in the VoidTransaction method.

If the SettlementMode is set to manual this property will contain the POSRetrievalNumber submitted in the authorization. If no POSRetrievalNumber was sent, this property will contain all zeros, and you will not have a reference number for the transaction.

If the SettlementMode is set to host settle, this property will always contain the Paymentech-generated retrieval number returned by the transaction server, regardless of the value contained in the POSRetrievalNumber property.

In all cases, the ResponseRetrievalNumber will contain the number used to reference the transaction when issuing voids or reversals.

This property is read-only.

Data Type

String

ResponseSequenceNumber Property (DPaymentsSDK_PTechCanadianDebit Class)

SequenceNumber echoed from the authorization.

Object Oriented Interface

public function getResponseSequenceNumber();

Procedural Interface

dpaymentssdk_ptechcanadiandebit_get($res, 31 );

Default Value

''

Remarks

SequenceNumber echoed from the authorization. After any transaction this property will contain the same value sent in the SequenceNumber property.

This property is read-only.

Data Type

String

ResponseText Property (DPaymentsSDK_PTechCanadianDebit Class)

Approval/Decline/Error text message information This property contains a response or display text message, and is used by the terminal to display the authorization result.

Object Oriented Interface

public function getResponseText();

Procedural Interface

dpaymentssdk_ptechcanadiandebit_get($res, 32 );

Default Value

''

Remarks

Approval/Decline/Error text message information This field contains a response or display text message, and is used by the terminal to display the authorization result. This property will contain human-readable text indicating whether the transaction was approved or declined, or will contain a description of the error. The actual error code will be returned in the ResponseApprovalCode property. The ResponseText property is for informational use only, and should not be used in determining whether a transaction has been approved or not. Instead, use the ResponseCode property to determine this.

See the list of errors for this class for more information.

This property is read-only.

Data Type

String

ResponseTime Property (DPaymentsSDK_PTechCanadianDebit Class)

The server-normalized Date and Time of the transaction.

Object Oriented Interface

public function getResponseTime();

Procedural Interface

dpaymentssdk_ptechcanadiandebit_get($res, 33 );

Default Value

''

Remarks

The server-normalized Date and Time of the transaction. After a transaction completes (successful or not) this property will contain the date and time of the transaction, returned by the server. The format is "MMddyyyyHHmmss". For example, "01192008171543" indicates the date "January 19th, 2008 5:15:43 pm".

If the host-adjusted date/time is different than what the Point Of Sale has currently, the Point of Sale date/time should be updated to match.

This property is read-only.

Data Type

String

ResponseTrace Property (DPaymentsSDK_PTechCanadianDebit Class)

Trace number returned for Canadian Interac Debit transactions.

Object Oriented Interface

public function getResponseTrace();

Procedural Interface

dpaymentssdk_ptechcanadiandebit_get($res, 34 );

Default Value

''

Remarks

Trace number returned for Canadian Interac Debit transactions. This field is returned in the response to an Interac debit card transaction. The returned value is used for transaction tracking purposes, and must be printed on the customer's receipt.

This property is read-only.

Data Type

String

RetrievalNumberToVoid Property (DPaymentsSDK_PTechCanadianDebit Class)

Indicates the transaction to void.

Object Oriented Interface

public function getRetrievalNumberToVoid();


public function setRetrievalNumberToVoid($value);

Procedural Interface

dpaymentssdk_ptechcanadiandebit_get($res, 35 );


dpaymentssdk_ptechcanadiandebit_set($res, 35, $value );

Default Value

''

Remarks

When sending a transaction with the InteracTransactionType set to ittVoidSale or ittVoidReturn, this property must contain the ResponseRetrievalNumber from the transaction you wish to void. The LastRetrievalNumber is also required for void transactions, and must be set with the LAST ResponseRetrievalNumber received from the Paymentech Server. If LastRetrievalNumber is left blank, the current contents of the ResponseRetrievalNumber property will be used instead.

Data Type

String

SequenceNumber Property (DPaymentsSDK_PTechCanadianDebit Class)

Sequence number of the transaction.

Object Oriented Interface

public function getSequenceNumber();


public function setSequenceNumber($value);

Procedural Interface

dpaymentssdk_ptechcanadiandebit_get($res, 36 );


dpaymentssdk_ptechcanadiandebit_set($res, 36, $value );

Default Value

0

Remarks

This field is user definable and can be used at the users discretion. When submitting any type of transaction for approval, this sequence number may be any numeric value 0 to 2400. This is a purely optional field for the Host Capture SettlementMode, and you may choose to send a unique number or simply send every transaction with zeros. The host will echo the sequence number submitted from the authorization request back in the ResponseSequenceNumber property.

However, if you are processing with the Terminal Capture SettlementMode, SequenceNumber CANNOT remain zero, and must contain a number that is incremented for each transaction you authorized. When it reaches 2400, the SequenceNumber should then start over at 1 again.

Data Type

Integer

Server Property (DPaymentsSDK_PTechCanadianDebit Class)

The URL for the PaymenTech NetConnect server.

Object Oriented Interface

public function getServer();


public function setServer($value);

Procedural Interface

dpaymentssdk_ptechcanadiandebit_get($res, 37 );


dpaymentssdk_ptechcanadiandebit_set($res, 37, $value );

Default Value

'https://netconnect1.chasepaymentech.com/NetConnect/controller'

Remarks

This property contains the server to which all transactions are sent.

Data Type

String

SSLAcceptServerCertEncoded Property (DPaymentsSDK_PTechCanadianDebit Class)

This is the certificate (PEM/Base64 encoded).

Object Oriented Interface

public function getSSLAcceptServerCertEncoded();


public function setSSLAcceptServerCertEncoded($value);

Procedural Interface

dpaymentssdk_ptechcanadiandebit_get($res, 39 );


dpaymentssdk_ptechcanadiandebit_set($res, 39, $value );

Default Value

''

Remarks

This is the certificate (PEM/Base64 encoded). This property is used to assign a specific certificate. The SSLAcceptServerCertStore and SSLAcceptServerCertSubject properties also may be used to specify a certificate.

When SSLAcceptServerCertEncoded is set, a search is initiated in the current SSLAcceptServerCertStore for the private key of the certificate. If the key is found, SSLAcceptServerCertSubject is updated to reflect the full subject of the selected certificate; otherwise, SSLAcceptServerCertSubject is set to an empty string.

This property is not available at design time.

Data Type

Binary String

SSLCertEncoded Property (DPaymentsSDK_PTechCanadianDebit Class)

This is the certificate (PEM/Base64 encoded).

Object Oriented Interface

public function getSSLCertEncoded();


public function setSSLCertEncoded($value);

Procedural Interface

dpaymentssdk_ptechcanadiandebit_get($res, 67 );


dpaymentssdk_ptechcanadiandebit_set($res, 67, $value );

Default Value

''

Remarks

This is the certificate (PEM/Base64 encoded). This property is used to assign a specific certificate. The SSLCertStore and SSLCertSubject properties also may be used to specify a certificate.

When SSLCertEncoded is set, a search is initiated in the current SSLCertStore for the private key of the certificate. If the key is found, SSLCertSubject is updated to reflect the full subject of the selected certificate; otherwise, SSLCertSubject is set to an empty string.

This property is not available at design time.

Data Type

Binary String

SSLCertStore Property (DPaymentsSDK_PTechCanadianDebit Class)

This is the name of the certificate store for the client certificate.

Object Oriented Interface

public function getSSLCertStore();


public function setSSLCertStore($value);

Procedural Interface

dpaymentssdk_ptechcanadiandebit_get($res, 83 );


dpaymentssdk_ptechcanadiandebit_set($res, 83, $value );

Default Value

'MY'

Remarks

This is the name of the certificate store for the client certificate.

The SSLCertStoreType property denotes the type of the certificate store specified by SSLCertStore. If the store is password protected, specify the password in SSLCertStorePassword.

SSLCertStore is used in conjunction with the SSLCertSubject property to specify client certificates. If SSLCertStore has a value, and SSLCertSubject or SSLCertEncoded is set, a search for a certificate is initiated. Please see the SSLCertSubject property for details.

Designations of certificate stores are platform dependent.

The following designations are the most common User and Machine certificate stores in Windows:

When the certificate store type is PFXFile, this property must be set to the name of the file. When the type is PFXBlob, the property must be set to the binary contents of a PFX file (i.e., PKCS#12 certificate store).

Data Type

Binary String

SSLCertStorePassword Property (DPaymentsSDK_PTechCanadianDebit Class)

If the type of certificate store requires a password, this property is used to specify the password needed to open the certificate store.

Object Oriented Interface

public function getSSLCertStorePassword();


public function setSSLCertStorePassword($value);

Procedural Interface

dpaymentssdk_ptechcanadiandebit_get($res, 84 );


dpaymentssdk_ptechcanadiandebit_set($res, 84, $value );

Default Value

''

Remarks

If the type of certificate store requires a password, this property is used to specify the password needed to open the certificate store.

Data Type

String

SSLCertStoreType Property (DPaymentsSDK_PTechCanadianDebit Class)

This is the type of certificate store for this certificate.

Object Oriented Interface

public function getSSLCertStoreType();


public function setSSLCertStoreType($value);

Procedural Interface

dpaymentssdk_ptechcanadiandebit_get($res, 85 );


dpaymentssdk_ptechcanadiandebit_set($res, 85, $value );

Default Value

0

Remarks

This is the type of certificate store for this certificate.

The class supports both public and private keys in a variety of formats. When the cstAuto value is used, the class will automatically determine the type. This property can take one of the following values:

Data Type

Integer

SSLCertSubject Property (DPaymentsSDK_PTechCanadianDebit Class)

This is the subject of the certificate used for client authentication.

Object Oriented Interface

public function getSSLCertSubject();


public function setSSLCertSubject($value);

Procedural Interface

dpaymentssdk_ptechcanadiandebit_get($res, 86 );


dpaymentssdk_ptechcanadiandebit_set($res, 86, $value );

Default Value

''

Remarks

This is the subject of the certificate used for client authentication.

This property must be set after all other certificate properties are set. When this property is set, a search is performed in the current certificate store to locate a certificate with a matching subject.

If a matching certificate is found, the property is set to the full subject of the matching certificate.

If an exact match is not found, the store is searched for subjects containing the value of the property.

If a match is still not found, the property is set to an empty string, and no certificate is selected.

The special value "*" picks a random certificate in the certificate store.

The certificate subject is a comma-separated list of distinguished name fields and values. For instance, "CN=www.server.com, OU=test, C=US, E=support@nsoftware.com". Common fields and their meanings are as follows:

If a field value contains a comma, it must be quoted.

Data Type

String

SSLProvider Property (DPaymentsSDK_PTechCanadianDebit Class)

This specifies the SSL/TLS implementation to use.

Object Oriented Interface

public function getSSLProvider();


public function setSSLProvider($value);

Procedural Interface

dpaymentssdk_ptechcanadiandebit_get($res, 94 );


dpaymentssdk_ptechcanadiandebit_set($res, 94, $value );

Default Value

0

Remarks

This property specifies the SSL/TLS implementation to use. In most cases the default value of 0 (Automatic) is recommended and should not be changed. When set to 0 (Automatic) the class will select whether to use the platform implementation or the internal implementation depending on the operating system as well as the TLS version being used.

Possible values are:

In most cases using the default value (Automatic) is recommended. The class will select a provider depending on the current platform.

When Automatic is selected, on Windows the class will use the platform implementation. On Linux/macOS the class will use the internal implementation. When TLS 1.3 is enabled via SSLEnabledProtocols the internal implementation is used on all platforms.

Data Type

Integer

SSLServerCertEncoded Property (DPaymentsSDK_PTechCanadianDebit Class)

This is the certificate (PEM/Base64 encoded).

Object Oriented Interface

public function getSSLServerCertEncoded();

Procedural Interface

dpaymentssdk_ptechcanadiandebit_get($res, 96 );

Default Value

''

Remarks

This is the certificate (PEM/Base64 encoded). This property is used to assign a specific certificate. The SSLServerCertStore and SSLServerCertSubject properties also may be used to specify a certificate.

When SSLServerCertEncoded is set, a search is initiated in the current SSLServerCertStore for the private key of the certificate. If the key is found, SSLServerCertSubject is updated to reflect the full subject of the selected certificate; otherwise, SSLServerCertSubject is set to an empty string.

This property is read-only and not available at design time.

Data Type

Binary String

TerminalNumber Property (DPaymentsSDK_PTechCanadianDebit Class)

Terminal number assigned by Paymentech.

Object Oriented Interface

public function getTerminalNumber();


public function setTerminalNumber($value);

Procedural Interface

dpaymentssdk_ptechcanadiandebit_get($res, 123 );


dpaymentssdk_ptechcanadiandebit_set($res, 123, $value );

Default Value

''

Remarks

3-digit field assigned by Paymentech, which identifies the terminal to the host.

Data Type

String

Timeout Property (DPaymentsSDK_PTechCanadianDebit Class)

A timeout for the class.

Object Oriented Interface

public function getTimeout();


public function setTimeout($value);

Procedural Interface

dpaymentssdk_ptechcanadiandebit_get($res, 124 );


dpaymentssdk_ptechcanadiandebit_set($res, 124, $value );

Default Value

60

Remarks

If the Timeout property is set to 0, all operations will run uninterrupted until successful completion or an error condition is encountered.

If Timeout is set to a positive value, the class will wait for the operation to complete before returning control.

The class will use DoEvents to enter an efficient wait loop during any potential waiting period, making sure that all system events are processed immediately as they arrive. This ensures that the host application does not "freeze" and remains responsive.

If Timeout expires, and the operation is not yet complete, the class fails with an error.

Please note that by default, all timeouts are inactivity timeouts, i.e. the timeout period is extended by Timeout seconds when any amount of data is successfully sent or received.

The default value for the Timeout property is 60 seconds.

Data Type

Integer

TransactionAmount Property (DPaymentsSDK_PTechCanadianDebit Class)

Purchase amount for an authorization.

Object Oriented Interface

public function getTransactionAmount();


public function setTransactionAmount($value);

Procedural Interface

dpaymentssdk_ptechcanadiandebit_get($res, 125 );


dpaymentssdk_ptechcanadiandebit_set($res, 125, $value );

Default Value

''

Remarks

This field contains the transaction amount to be authorized. The transaction amount is presented in CA Dollars with a decimal point in the proper position. If sending a Debit transaction and the customer requests cash back, the TransactionAmount must include the total cost of the purchase, PLUS the DebitCashBack amount.

This must be formatted as a dollar amount with a real decimal point, excluding the dollar sign. For instance "12.00"

Data Type

String

UserId Property (DPaymentsSDK_PTechCanadianDebit Class)

UserId for authentication with the NetConnect Server .

Object Oriented Interface

public function getUserId();


public function setUserId($value);

Procedural Interface

dpaymentssdk_ptechcanadiandebit_get($res, 126 );


dpaymentssdk_ptechcanadiandebit_set($res, 126, $value );

Default Value

''

Remarks

The UserId will be supplied to you by PaymenTech.

Data Type

String

Authorize Method (DPaymentsSDK_PTechCanadianDebit Class)

Authorizes a Canadian debit card transaction.

Object Oriented Interface

public function doAuthorize();

Procedural Interface

dpaymentssdk_ptechcanadiandebit_do_authorize($res);

Remarks

This method sends a Canadian (Interac) debit card transaction to the Paymentech Server The transaction sent is based on the InteracTransactionType. Authorize can only be used to send customer-initiated transactions that require that the customer physically enter his PIN on the PIN pad device - meaning Sales, Returns, and Voids. Administrative transactions are handled via the RequestCurrentKeys, ReversalAdvice, and MACReversal methods.

An example sale is shown below:

class.MerchantNumber = "yourMerchantNumber" class.TerminalNumber = "100" class.ClientNumber = "0002" class.UserId = "yourUserId" class.Password = "yourPassword" class.SequenceNumber = 2 class.TransactionAmount = "1.00" class.PinPadSerialNumber = "30700015P3600000" ' from label on back of PIN pad class.InteracTransactionType = ittSale class.AccountType = acctChecking class.CardTrack2Data = "9999999800002773=05121015432112345678" ' from card reader class.EncryptedPIN = "FFFFFFFFFFFFFFFF" ' from the PIN pad ' Now use the PIN pad to MAC the value returned from GetRequestDataToMAC ' and then set MACValue with the results class.MACValue = "FFFFFFFF" class.Authorize() If the ResponseCode is "A", load the PIN pad device with the ResponsePINKey and ResponseMACKey, and then validate the ResponseMACValue against the value returned by GetResponseDataToMAC using the PIN pad. If the MAC does not validate, call MACReversal to reverse the transaction.

Config Method (DPaymentsSDK_PTechCanadianDebit Class)

Sets or retrieves a configuration setting.

Object Oriented Interface

public function doConfig($configurationstring);

Procedural Interface

dpaymentssdk_ptechcanadiandebit_do_config($res, $configurationstring);

Remarks

Config is a generic method available in every class. It is used to set and retrieve configuration settings for the class.

These settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the class, access to these internal properties is provided through the Config method.

To set a configuration setting named PROPERTY, you must call Config("PROPERTY=VALUE"), where VALUE is the value of the setting expressed as a string. For boolean values, use the strings "True", "False", "0", "1", "Yes", or "No" (case does not matter).

To read (query) the value of a configuration setting, you must call Config("PROPERTY"). The value will be returned as a string.

GetRequestDataToMAC Method (DPaymentsSDK_PTechCanadianDebit Class)

Returns a string of data for the PIN pad to hash with the MAC algorithm.

Object Oriented Interface

public function doGetRequestDataToMAC();

Procedural Interface

dpaymentssdk_ptechcanadiandebit_do_getrequestdatatomac($res);

Remarks

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 ResponseMACKey returned in response to the last transaction.

The GetRequestDataToMAC method returns a string containing the values of several transaction properties. This string must be MAC'ed by the PIN pad, so it is essential that the following properties be set before calling GetRequestDataToMAC:

• MerchantNumber
• TerminalNumber
• InteracTransactionType
• CardTrack2Data
• TransactionAmount
• SequenceNumber
• and optionally AccountType

Note that VeriFone pinpads support a PURCHASE transaction where the CardTrack2Data, EncryptedPIN, AccountType, and MACValue are returned in a single step. When using a VeriFone pad make sure AccountType is set to acctNotSet, otherwise the MACValue will not be calculated correctly. (AccountType must be set before calling GetRequestDataToMAC for Ingenico pads)

class.MerchantNumber = "yourMerchantNumber" class.TerminalNumber = "100" class.ClientNumber = "0002" class.UserId = "yourUserId" class.Password = "yourPassword" class.SequenceNumber = 2 class.TransactionAmount = "1.00" class.PinPadSerialNumber = "30700015P3600000" ' from label on back of PIN pad class.InteracTransactionType = ittSale class.AccountType = acctChecking class.CardTrack2Data = "9999999800002773=05121015432112345678" ' from card reader class.EncryptedPIN = "FFFFFFFFFFFFFFFF" ' from the PIN pad ' Now use the PIN pad to MAC the value returned from GetRequestDataToMAC ' and then set MACValue with the results class.MACValue = "FFFFFFFF" class.Authorize()

GetResponseDataToMAC Method (DPaymentsSDK_PTechCanadianDebit Class)

Returns a string containing data to validate against the MACValue using a PIN pad device.

Object Oriented Interface

public function doGetResponseDataToMAC();

Procedural Interface

dpaymentssdk_ptechcanadiandebit_do_getresponsedatatomac($res);

Remarks

Each successful response to a transaction will include a ResponseMACKey and a ResponseMACValue. The ResponseMACKey (and ResponsePINKey) should be loaded into the PIN pad device upon receipt. The ResponseMACValue is a string encrypted by the Paymentech server using the ResponseMACKey, and is included in every successful response message. The original unencrypted data is returned by the GetResponseDataToMAC method. After loading the ResponseMACKey into the PIN pad device, send both ResponseMACValue and GetResponseDataToMAC to the PIN pad device for validation. If the PIN pad indicates the MAC matches, you're done, and you can continue processing transactions. However, if the PIN pad indicates the MAC did not match, you must immediately perform a MACReversal transaction, and consider the request as not approved.

A mismatched MAC value may mean that something was corrupted in data transmission, the response packet was tampered with, or that the keys loaded into your PIN pad device are not synchronized with Paymentech. Try synchronizing your keys with the RequestCurrentKeys method and then re-submitting the transaction.

Interrupt Method (DPaymentsSDK_PTechCanadianDebit Class)

Interrupt the current method.

Object Oriented Interface

public function doInterrupt();

Procedural Interface

dpaymentssdk_ptechcanadiandebit_do_interrupt($res);

Remarks

If there is no method in progress, Interrupt simply returns, doing nothing.

MACReversal Method (DPaymentsSDK_PTechCanadianDebit Class)

Reverses a transaction when MAC validation fails.

Object Oriented Interface

public function doMACReversal();

Procedural Interface

dpaymentssdk_ptechcanadiandebit_do_macreversal($res);

Remarks

After sending a transaction with the Authorize method, the ResponseMACValue must be validated against the GetResponseDataToMAC using the PIN pad device's MAC functionality. It must be validated under the latest ResponseMACKey returned from Paymentech. If the ResponseMACValue cannot be validated, you should immediately send a MACReversal to void the authorization. Note that you do not need to calculate a new MACValue for a MACReversal. You may simply send the MACValue from the original authorization request (the Paymentech server will not validate the MACValue). All other properties must match the properties sent during the original authorization, including the EncryptedPIN, CardTrack2Data, and EncryptedKeyIndex.

RequestCurrentKeys Method (DPaymentsSDK_PTechCanadianDebit Class)

Used to retrieve the current encryption keys from Paymentech.

Object Oriented Interface

public function doRequestCurrentKeys();

Procedural Interface

dpaymentssdk_ptechcanadiandebit_do_requestcurrentkeys($res);

Remarks

This method retrieves the current encryption keys from Paymentech, and stores them in the ResponsePINKey and ResponseMACKey properties. These keys are used by the PIN pad device to encrypt customer PINs and to create and validate MAC hash values, and are normally updated after every Authorize transaction. But when the PIN pad is first initialized (or when the PIN pad becomes out of sync with the Paymentech Server) you must retrieve the current keys using this method.

Keys are required to be renewed every:

• 200 Transactions
• 24 Hours
• Each time a Batch is released for settlement
• Whenever the PIN pad loses sync with the server

If the ResponseForceKeyRequest property is True after any transaction, you must immediately perform a RequestCurrentKeys transaction before sending any more authorizations.

For example: class.MerchantNumber = "yourMerchantNumber" class.TerminalNumber = "100" class.ClientNumber = "0002" class.UserId = "yourUserId" class.Password = "yourPassword" class.SequenceNumber = 1 class.PinPadSerialNumber = "FFFFFFFFFFFFFFFF" ' retrieved from your PIN Pad class.RequestCurrentKeys() Now load the ResponsePINKey and ResponseMACKey into the PIN Pad device.

Reset Method (DPaymentsSDK_PTechCanadianDebit Class)

Clears all properties to their default values.

Object Oriented Interface

public function doReset();

Procedural Interface

dpaymentssdk_ptechcanadiandebit_do_reset($res);

Remarks

This method clears all properties to their default values.

ReversalAdvice Method (DPaymentsSDK_PTechCanadianDebit Class)

Used if no response is received from the Server to void the authorization.

Object Oriented Interface

public function doReversalAdvice($originaltransactiontype, $reasoncode);

Procedural Interface

dpaymentssdk_ptechcanadiandebit_do_reversaladvice($res, $originaltransactiontype, $reasoncode);

Remarks

If no response is returned after sending an authorization with the Authorize method, and the status of the response is unknown, you must send a ReversalAdvice transaction. This will advise the Paymentech Server that you did not receive a response to your authorization request, and that the original request is to be voided. If no request is found (meaning your original authorization request never made it to Paymentech) or if the authorization is successfully reversed (ResponseCode is "A"), you may try to resubmit the transaction.

This method takes two parameters, OriginalTransactionType and Reason Code. The former indicates the InteracTransactionType of the original authorization, and the latter indicates the reason for the reversal. Allowable values for these parameters are listed below:

Allowable OriginalTransactionType values:

Reason Code values:

DataPacketIn Event (DPaymentsSDK_PTechCanadianDebit Class)

Fired when receiving a data packet from the transaction server.

Object Oriented Interface

public function fireDataPacketIn($param);

Procedural Interface

dpaymentssdk_ptechcanadiandebit_register_callback($res, 1, array($this, 'fireDataPacketIn'));

Parameter List

 'datapacket'

Remarks

This event fires when a packet is received. The entire data packet (including all framing and error detection characters) is contained in the parameter "DataPacket". This parameter may be inspected for advanced troubleshooting, or to extract additional response properties beyond the scope of this class.

DataPacketOut Event (DPaymentsSDK_PTechCanadianDebit Class)

Fired when sending a data packet to the transaction server.

Object Oriented Interface

public function fireDataPacketOut($param);

Procedural Interface

dpaymentssdk_ptechcanadiandebit_register_callback($res, 2, array($this, 'fireDataPacketOut'));

Parameter List

 'datapacket'

Remarks

This event fires right before each data packet is sent. The entire data packet (including all framing and error detection characters) is contained in the parameter "DataPacket". This parameter may be inspected for advanced troubleshooting.

Error Event (DPaymentsSDK_PTechCanadianDebit Class)

Information about errors during data delivery.

Object Oriented Interface

public function fireError($param);

Procedural Interface

dpaymentssdk_ptechcanadiandebit_register_callback($res, 3, array($this, 'fireError'));

Parameter List

 'errorcode'
 'description'

Remarks

The Error event is fired in case of exceptional conditions during message processing.

ErrorCode contains an error code and Description contains a textual description of the error. For a list of valid error codes and their descriptions, please refer to the Error Codes section.

SSLServerAuthentication Event (DPaymentsSDK_PTechCanadianDebit Class)

Fired after the server presents its certificate to the client.

Object Oriented Interface

public function fireSSLServerAuthentication($param);

Procedural Interface

dpaymentssdk_ptechcanadiandebit_register_callback($res, 4, array($this, 'fireSSLServerAuthentication'));

Parameter List

 'certencoded'
 'certsubject'
 'certissuer'
 'status'
 'accept'

Remarks

During this event, the client can decide whether or not to continue with the connection process. The Accept parameter is a recommendation on whether to continue or close the connection. This is just a suggestion: application software must use its own logic to determine whether or not to continue.

When Accept is False, Status shows why the verification failed (otherwise, Status contains the string OK). If it is decided to continue, you can override and accept the certificate by setting the Accept parameter to True.

SSLStatus Event (DPaymentsSDK_PTechCanadianDebit Class)

Fired when secure connection progress messages are available.

Object Oriented Interface

public function fireSSLStatus($param);

Procedural Interface

dpaymentssdk_ptechcanadiandebit_register_callback($res, 5, array($this, 'fireSSLStatus'));

Parameter List

 'message'

Remarks

The event is fired for informational and logging purposes only. This event tracks the progress of the connection.

Config Settings (PTechCanadianDebit Class)

PTechCanadianDebit Config Settings

HTTP Config Settings

TCPClient Config Settings

SSL Config Settings

-----BEGIN CERTIFICATE-----
MIIEKzCCAxOgAwIBAgIRANTET4LIkxdH6P+CFIiHvTowDQYJKoZIhvcNAQELBQAw
...
eWHV5OW1K53o/atv59sOiW5K3crjFhsBOd5Q+cJJnU+SWinPKtANXMht+EDvYY2w
F0I1XhM+pKj7FjDr+XNj
-----END CERTIFICATE-----
\r \n
-----BEGIN CERTIFICATE-----
MIIEFjCCAv6gAwIBAgIQetu1SMxpnENAnnOz1P+PtTANBgkqhkiG9w0BAQUFADBp
..
d8q23djXZbVYiIfE9ebr4g3152BlVCHZ2GyPdjhIuLeH21VbT/dyEHHA
-----END CERTIFICATE-----

-----BEGIN CERTIFICATE-----
MIIEKzCCAxOgAwIBAgIRANTET4LIkxdH6P+CFIiHvTowDQYJKoZIhvcNAQELBQAw
...
eWHV5OW1K53o/atv59sOiW5K3crjFhsBOd5Q+cJJnU+SWinPKtANXMht+EDvYY2w
F0I1XhM+pKj7FjDr+XNj
-----END CERTIFICATE-----
\r \n
-----BEGIN CERTIFICATE-----
MIIEFjCCAv6gAwIBAgIQetu1SMxpnENAnnOz1P+PtTANBgkqhkiG9w0BAQUFADBp
..
d8q23djXZbVYiIfE9ebr4g3152BlVCHZ2GyPdjhIuLeH21VbT/dyEHHA
-----END CERTIFICATE-----

Socket Config Settings

Base Config Settings

Trappable Errors (PTechCanadianDebit Class)

PTechCanadianDebit Errors

Paymentech Server Errors:

The following is a list of error codes which may be returned by the Paymentech Server. In the case of a server-side error condition, the ResponseCode property will contain "E", the error code will be contained in the ResponseApprovalCode property, and the description in ResponseText

Paymentech Issuer Errors

Paymentech Format Errors

Paymentech Host / Setup Errors

Paymentech Debit / EBT Specific Errors

Paymentech Batch Management Errors (use the ErrorCode configuration setting to retrieve this information from the PTechHostSettle class.

The class may also return one of the following error codes, which are inherited from other classes.

HTTP Errors

The class may also return one of the following error codes, which are inherited from other classes.

TCPClient Errors

SSL Errors

TCP/IP Errors