PTechDetailRecord Component

Properties   Methods   Events   Config Settings   Errors  

The PTechDetailRecord component is a tool used to create off-line Credit or Force transactions to be settled by the component. The PTDetailRecord component may also be used to modify the XML aggregates returned by the component's method.

Syntax

DPayments.DPaymentsSDK.Ptechdetailrecord

Remarks

Credit and voice-authorization Capture transactions are off-line transactions. This means that there is no authorization of funds using the PTechCharge component. Instead, you must manually add these transactions to the settlement batch. The PTDetailRecord component can be used to create these transactions, which can then be added to the PTechManualSettle component's DetailRecords property.

To create a Credit, first set the TransactionType to dttCredit, and then set the IndustryType and EntryDataSource Next, set the Card, SettlementAmount, and the current TransactionDate and TransactionTime.

Since this is an off-line transaction, the SequenceNumber may be any value (except 0), and need not reflect the next available sequence number used for authorizations. Finally, set the PTechManualSettle component's DetailRecords array property with the value returned by the GetDetailAggregate method. You've just added a Credit to the settlement.

Voice authorization Capture transactions are similar to credits, with the exception that it requires a Voice Authorization code obtained from your acquiring bank's call center. Generally, the purchase of large high-dollar items (cars, appliances, etc) will require the merchant to call and receive a voice authorization. Once this code is received, it should be set to the ApprovalCode property. The following example shows a Force transaction in a Retail environment.

In addition to creating Credit and Force transactions, the PTechDetailRecord component can be used to adjust the Detail Records returned from the PTechCharge component to reflect changes in the SettlementAmount. The most common reasons to modify these detail records are to add a GratuityAmount (tip) to a charge (itResturant IndustryType), or to add additional charges for the itHotel IndustryType. Note that when the SettlementAmount differs from the original authorized amount, the AmountStatus must be updated to asAmountChanged.

Property List

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

Method List

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

Event List

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

Config Settings

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

AmountStatus Property (PTechDetailRecord Component)

Indicates whether SettlementAmount has been modified from the original authorization.

Syntax

• C#
• VB.NET

public PtechdetailrecordAmountStatus AmountStatus { get; set; }

enum PtechdetailrecordAmountStatus {
  asActualAmount,
  asAmountChanged
}

Public Property AmountStatus As PtechdetailrecordAmountStatus

Enum PtechdetailrecordAmountStatus
  asActualAmount
  asAmountChanged
End Enum

Default Value

0

Remarks

Notes for the Hotel IndustryType:

To obtain the best interchange rate for Visa transactions in the Hotel IndustryType, the check out amount (SettlementAmount) must be within 15% of the original authorization amount. If the SettlementAmount is less than the original authorized amount by more than 15%, you must perform an authorization reversal using the PTechReversal component. This will immediately release funds from the cardholder's open to buy amount. The original transaction must then be settled for the new amount as usual. However, if the SettlementAmount exceeds the original authorized amount by more than 15%, you must submit an incremental authorization to make up the remaining amount. In this case even though there are two separate transactions, they are tied together with the same authorization code. Therefore, only the original authorization (with the newly updated SettlementAmount) is to be sent in the settlement.

Non-Visa transactions do not allow for Incrementals to tie transactions together, nor Reversals to release funds from the cardholder's open to buy amount. There are no restrictions on the difference between the SettlementAmount and the original authorization amount. However, if the merchant suspects that the final transaction amount will be substantially higher than the original authorization amount, the merchant should perform an additional authorization for the difference. This subsequent authorization must be sent to the host as a standard authorization-only transaction, and will not be tied in any way to the original transaction. Both transactions must be present in the settlement.

Notes for the Restaurant IndustryType:

For Visa transactions, to obtain the best interchange rate the SettlementAmount must be within 20% of the authorized amount. The initial authorization must be submitted for the actual transaction amount. It must not be altered to include an additional percentage that accounts for a tip being added before settlement.

The same rule applies to MasterCard transactions, with the exception that MasterCard allows the SettlementAmount to be within 25% of the authorized amount.

There are no rules concerning authorization and settlement amounts for other card types.

This information was accurate at the time this document was written. Please see the Processing and Interchange Guidelines (provided by Paymentech) for updates as well as additional information on interchange rate qualification.

ApprovalCode Property (PTechDetailRecord Component)

The Approval code returned in the response to the authorization linked to this transaction.

Syntax

• C#
• VB.NET

public string ApprovalCode { get; set; }

Public Property ApprovalCode As String

Default Value

""

Remarks

If this is a Forced transaction, ApprovalCode should contain the voice auth code received from the call center. If this is a Credit (Refund) transaction it should remain empty or be space filled.

AuthSource Property (PTechDetailRecord Component)

Indicates the source of the authorization code stored in ApprovalCode .

Syntax

• C#
• VB.NET

public string AuthSource { get; set; }

Public Property AuthSource As String

Default Value

""

Remarks

This field contains a one character code indicating the source of the ApprovalCode. The received code must be stored and submitted in the batch settlement.

Valid source codes:

CardExpMonth Property (PTechDetailRecord Component)

Expiration month of the credit card specified by CardNumber .

Syntax

• C#
• VB.NET

public int CardExpMonth { get; set; }

Public Property CardExpMonth As Integer

Default Value

1

Remarks

This property contains the expiration date of the customer's credit card. This property must be in the range 1 - 12.

CardExpYear Property (PTechDetailRecord Component)

Expiration year of the credit card specified by CardNumber .

Syntax

• C#
• VB.NET

public int CardExpYear { get; set; }

Public Property CardExpYear As Integer

Default Value

1

Remarks

This property contains the expiration date of the customer's credit card. This property must be in the range 1 - 12.

CardNumber Property (PTechDetailRecord Component)

Customer's credit card number from the original authorization request.

Syntax

• C#
• VB.NET

public string CardNumber { get; set; }

Public Property CardNumber As String

Default Value

""

Remarks

This field contains the customer's credit card number used in the original authorization request. This alphanumeric field can be a maximum of 22 characters long, excluding whitespace and dashes which are stripped out when the property is set.

CardType Property (PTechDetailRecord Component)

Type of the credit card.

Syntax

• C#
• VB.NET

public string CardType { get; set; }

Public Property CardType As String

Default Value

""

Remarks

Paymentech determines the type of credit card used for each authorization, and returns that value to the merchant in the response. The following is a list of card mnemonics and their meanings.

CVVResult Property (PTechDetailRecord Component)

Contains the returned CVV result code if it was requested.

Syntax

• C#
• VB.NET

public string CVVResult { get; set; }

Public Property CVVResult As String

Default Value

""

Remarks

If a CVV value was sent in the authorization request, then this one character field will contain the host returned Card Verification Value result code.

ECI Property (PTechDetailRecord Component)

Electronic Commerce Indicator from the original authorization request.

Syntax

• C#
• VB.NET

public string ECI { get; set; }

Public Property ECI As String

Default Value

""

Remarks

This field should be identical to the ECI property from the original authorization request. This property is used only for eCommerce and Direct Marketing (card not present) transactions, and is ignored for all Card Present (Retail) transactions.

EntryDataSource Property (PTechDetailRecord Component)

Should reflect the Entry Data Source sent in the original authorization request.

Syntax

• C#
• VB.NET

public PtechdetailrecordEntryDataSources EntryDataSource { get; set; }

enum PtechdetailrecordEntryDataSources {
  edsTrack1,
  edsTrack2,
  edsManualEntryTrack1Capable,
  edsManualEntryTrack2Capable,
  edsManualEntryNoCardReader,
  edsTrack1Contactless,
  edsTrack2Contactless,
  edsManualEntryContactlessCapable,
  edsIVR,
  edsKiosk
}

Public Property EntryDataSource As PtechdetailrecordEntryDataSources

Enum PtechdetailrecordEntryDataSources
  edsTrack1
  edsTrack2
  edsManualEntryTrack1Capable
  edsManualEntryTrack2Capable
  edsManualEntryNoCardReader
  edsTrack1Contactless
  edsTrack2Contactless
  edsManualEntryContactlessCapable
  edsIVR
  edsKiosk
End Enum

Default Value

0

Remarks

If sending an off-line credit or capture this property should reflect the way in which the card was presented for the credit or capture.

The following data sources are supported - edsTrack1, edsTrack2, edsManualEntryTrack1Capable, edsManualEntryTrack2Capable, edsManualEntryNoCardReader, edsTrack1Contactless, edsTrack2Contactless, edsManualEntryContactlessCapable

This property is not available at design time.

GoodsIndicator Property (PTechDetailRecord Component)

Indicates the type of goods being sold by an e-Commerce merchant

Syntax

• C#
• VB.NET

public PtechdetailrecordGoodsIndicators GoodsIndicator { get; set; }

enum PtechdetailrecordGoodsIndicators {
  giPhysicalGoods,
  giDigitalGoods
}

Public Property GoodsIndicator As PtechdetailrecordGoodsIndicators

Enum PtechdetailrecordGoodsIndicators
  giPhysicalGoods
  giDigitalGoods
End Enum

Default Value

0

Remarks

If the merchant is selling physical goods (goods that are shipped or are otherwise tangible) this property must be set to giPhysicalGoods. If the merchant is selling Digital goods, such a membership, or any software or file that is delivered electronically, this field must be set to giDigitalGoods. This property is only valid when the IndustryType is set to itECommerce.

GratuityAmount Property (PTechDetailRecord Component)

Gratuity amount for settling restaurant industry transactions.

Syntax

• C#
• VB.NET

public string GratuityAmount { get; set; }

Public Property GratuityAmount As String

Default Value

""

Remarks

This field contains the gratuity (tip) amount of the transaction being settled. This amount is only sent when the PTechCharge component's IndustryType is set to "itRestaurant". If a transaction includes a GratuityAmount amount, the SettlementAmount must reflect the total of the original Authorized Amount plus the GratuityAmount.

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

Hotel Property (PTechDetailRecord Component)

Contains additional information required for the Hotel/Lodging industry.

Syntax

• C#
• VB.NET

public PTechHotelInfo Hotel { get; set; }

Public Property Hotel As PTechHotelInfo

Remarks

This property will be sent in both authorizations and detail records when the IndustryType is set to Hotel. At minimum, you should pass the expected Duration, ArrivalDate, expected DepartureDate, and SaleCode. You may pass the ExtraChargeAmount and ExtraChargesCode in the authorization, but those are normally not known until settlement. To process a reservation or any other transaction where the customer and his card are not physically present, set the PreferredCustomer field to True;. This will indicate to Paymentech that the transaction is a card-not-present authorization (PreferredCustomer must be set to False for normal card-present transaction processing).

IndustryType Property (PTechDetailRecord Component)

Determines the merchant's industry type.

Syntax

• C#
• VB.NET

public PtechdetailrecordIndustryTypes IndustryType { get; set; }

enum PtechdetailrecordIndustryTypes {
  pitRetail,
  pitDirectMarketing,
  pitECommerce,
  pitRestaurant,
  pitHotel
}

Public Property IndustryType As PtechdetailrecordIndustryTypes

Enum PtechdetailrecordIndustryTypes
  pitRetail
  pitDirectMarketing
  pitECommerce
  pitRestaurant
  pitHotel
End Enum

Default Value

0

Remarks

This property sets the merchant's industry type. Valid values are shown in the table below:

* Restaurant orders taken over the phone should be processed as itDirectMarketing transactions. Hotel transactions should always be processed in the itHotel IndustryType. Setting the PTechHotelInfo.PreferredCustomer field to True.

InvoiceNumber Property (PTechDetailRecord Component)

Invoice Number from the original authorization request.

Syntax

• C#
• VB.NET

public string InvoiceNumber { get; set; }

Public Property InvoiceNumber As String

Default Value

""

Remarks

This property should be identical to the InvoiceNumber from the original authorization request.

Level2Data Property (PTechDetailRecord Component)

Supplies extra information for Commercial or Purchasing cards.

Syntax

• C#
• VB.NET

public PTechLevel2 Level2Data { get; set; }

Public Property Level2Data As PTechLevel2

Remarks

This property can be used to send additional Level II data that may qualify the merchant for a lower Interchange rate for this transaction. However, it is only valid for use with business or government Purchasing or Commercial Cards. This property is only valid for Sale and AuthOnly transactions. The PTechLevel2 type contains the following fields:

NetworkId Property (PTechDetailRecord Component)

The Authorizing network Id from the original authorization response.

Syntax

• C#
• VB.NET

public string NetworkId { get; set; }

Public Property NetworkId As String

Default Value

""

Remarks

This property should be identical to the NetworkId returned from Paymentech in the authorization response.

SequenceNumber Property (PTechDetailRecord Component)

Sequence number of the transaction.

Syntax

• C#
• VB.NET

public int SequenceNumber { get; set; }

Public Property SequenceNumber As Integer

Default Value

1

Remarks

This should be identical to the sequence number sent in the original authorization.

ServerNumber Property (PTechDetailRecord Component)

Used for restaurant transactions: Id number of the server (waiter/waitress) making the transaction.

Syntax

• C#
• VB.NET

public string ServerNumber { get; set; }

Public Property ServerNumber As String

Default Value

""

Remarks

Each server should have his or her own unique Id number.

SettlementAmount Property (PTechDetailRecord Component)

The amount that the customer will be charged.

Syntax

• C#
• VB.NET

public string SettlementAmount { get; set; }

Public Property SettlementAmount As String

Default Value

"0.00"

Remarks

This field contains the final settlement amount of the transaction. In most cases, this is the TransactionAmount from the original authorization request. However, you may settle a lesser amount (ie: Partial shipment or backordered stock). This field must always be greater than zero.

Note: If a transaction includes a GratuityAmount amount, the SettlementAmount must reflect the total of the original authorized amount plus the GratuityAmount (this is only applicable to the itResturant IndustryType).

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

Notes for the Hotel IndustryType:

To obtain the best interchange rate for Visa transactions in the Hotel IndustryType, the check out amount (SettlementAmount) must be within 15% of the original authorization amount. If the SettlementAmount is less than the original authorized amount by more than 15%, you must perform an authorization reversal using the PTechReversal component. This will immediately release funds from the cardholder's open to buy amount. The original transaction must then be settled for the new amount as usual. However, if the SettlementAmount exceeds the original authorized amount by more than 15%, you must submit an incremental authorization to make up the remaining amount. In this case even though there are two separate transactions, they are tied together with the same authorization code. Therefore, only the original authorization (with the newly updated SettlementAmount) is to be sent in the settlement.

Non-Visa transactions do not allow for Incrementals to tie transactions together, nor Reversals to release funds from the cardholder's open to buy amount. There are no restrictions on the difference between the SettlementAmount and the original authorization amount. However, if the merchant suspects that the final transaction amount will be substantially higher than the original authorization amount, the merchant should perform an additional authorization for the difference. This subsequent authorization must be sent to the host as a standard authorization-only transaction, and will not be tied in any way to the original transaction. Both transactions must be present in the settlement.

Notes for the Restaurant IndustryType:

For Visa transactions, to obtain the best interchange rate the SettlementAmount must be within 20% of the authorized amount. The initial authorization must be submitted for the actual transaction amount. It must not be altered to include an additional percentage that accounts for a tip being added before settlement.

The same rule applies to MasterCard transactions, with the exception that MasterCard allows the SettlementAmount to be within 25% of the authorized amount.

There are no rules concerning authorization and settlement amounts for other card types.

This information was accurate at the time this document was written. Please see the Processing and Interchange Guidelines (provided by Paymentech) for updates as well as additional information on interchange rate qualification.

TransactionDate Property (PTechDetailRecord Component)

Local Transaction Date from the original authorization response.

Syntax

• C#
• VB.NET

public string TransactionDate { get; set; }

Public Property TransactionDate As String

Default Value

"010101"

Remarks

This six digit field contains a local transaction date associated with the transaction being settled. If the transaction was authorized on-line, this field must contain the value returned in the original authorization response message. If the transaction was processed off-line, this field must contain a Point of Sale (POS) device generated date. This field must appear in MMDDYY format.

TransactionTime Property (PTechDetailRecord Component)

Local transaction time from the original authorization response.

Syntax

• C#
• VB.NET

public string TransactionTime { get; set; }

Public Property TransactionTime As String

Default Value

"000000"

Remarks

This six digit field contains a local transaction time associated with the transaction being settled. If the transaction was authorized on-line, this field must contain the value returned in the original authorization response message. If the transaction was processed off-line, this field must contain a Point of Sale (POS) device generated time. This field must appear in HHMMSS format.

TransactionType Property (PTechDetailRecord Component)

Indicates transaction type for this detail record

Syntax

• C#
• VB.NET

public PtechdetailrecordTransactionTypes TransactionType { get; set; }

enum PtechdetailrecordTransactionTypes {
  dttSale,
  dttCapture,
  dttHotelNoShow,
  dttCredit
}

Public Property TransactionType As PtechdetailrecordTransactionTypes

Enum PtechdetailrecordTransactionTypes
  dttSale
  dttCapture
  dttHotelNoShow
  dttCredit
End Enum

Default Value

1

Remarks

This property indicates the type of transaction that is being settled.

Note that only credit card transactions are supported here. EBT, Stored Value, Debit, and Canadian Debit cards must be processed with the Host Capture System, and cannot be manually settled.

Note that transactions Voided with the PTechCharge component must be removed from the batch. Voided transactions must not be settled.

Config Method (PTechDetailRecord Component)

Sets or retrieves a configuration setting.

Syntax

• C#
• VB.NET

public string Config(string configurationString);

Public Function Config(ByVal ConfigurationString As String) As String

Remarks

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

These settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the component, 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.

GetDetailAggregate Method (PTechDetailRecord Component)

Returns an aggregate containing details of this transaction, which is then used for settlement.

Syntax

• C#
• VB.NET

public string GetDetailAggregate();

Public Function GetDetailAggregate() As String

Remarks

This method returns an aggregate containing all of the required data to send a transaction to settlement. This aggregate must be passed to the PTechManualSettle component's DetailAggregate array property in order to settle the transaction. If you wish to view or change any part of the aggregate (such as adding a gratuity or additional info for an Installment payment), you may use the PTechDetailRecord component to do so.

Note: This method may only be called after a successful authorization. If the authorization was not successful the method throws an exception.

An example of how this method is used is shown below:

PTechCharge.Sale(); PTechManualSettle.DetailRecord[0] = PTechCharge.GetDetailAggregate();

ParseAggregate Method (PTechDetailRecord Component)

Parses the aggregate returned from another component's GetDetailAggregate method.

Syntax

• C#
• VB.NET

public void ParseAggregate(string aggregate);

Public Sub ParseAggregate(ByVal Aggregate As String)

Remarks

This method takes the XML aggregate returned from the PTechCharge component, parses it, and then fills all the properties of the PTechDetailRecord component. While normally you can pass the results of the GetDetailAggregate method call directly to the PTechManualSettle component, sometimes it is necessary to adjust the contents of the XML aggregate first.

Reset Method (PTechDetailRecord Component)

Clears all properties to their default values.

Syntax

• C#
• VB.NET

public void Reset();

Public Sub Reset()

Remarks

This method clears all properties to their default values.

Error Event (PTechDetailRecord Component)

Information about errors during data delivery.

Syntax

• C#
• VB.NET

public event OnErrorHandler OnError;

public delegate void OnErrorHandler(object sender, PtechdetailrecordErrorEventArgs e);

public class PtechdetailrecordErrorEventArgs : EventArgs {
  public int ErrorCode { get; }
  public string Description { get; }
}

Public Event OnError As OnErrorHandler

Public Delegate Sub OnErrorHandler(sender As Object, e As PtechdetailrecordErrorEventArgs)

Public Class PtechdetailrecordErrorEventArgs Inherits EventArgs
  Public ReadOnly Property ErrorCode As Integer
  Public ReadOnly Property Description As String
End Class

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.

PTechHotelInfo Type

Contains additional information required for the Hotel/Lodging industry.

Remarks

This type is used in both authorizations and detail records when processing transactions in the hotel/lodging industry type. At minimum, you should pass the expected Duration of stay, ArrivalDate, expected DepartureDate, and SaleCode. You may pass the ExtraChargeAmount and ExtraChargesCode in the authorization, but those are normally not known until settlement. To process a reservation or any other transaction where the customer and his card are not physically present, set the PreferredCustomer field to True;. This will indicate to Paymentech that the transaction is a card-not-present authorization (PreferredCustomer must be set to False for normal card-present transaction processing).

Fields

Constructors

• C#
• VB.NET

public PTechHotelInfo();

Public PTechHotelInfo()

PTechLevel2 Type

Level II Purchase or Commercial Card information.

Remarks

This type allows the merchant to specify additional fields for Commercial Cards or Purchasing Cards for business or government transaction. Supplying the PurchaseId, SalesTax, and ShipToZip for these credit cards can qualify the merchant for a lower Interchange rate.

Fields

Constructors

• C#
• VB.NET

public PTechLevel2(string purchaseId, string salesTax, string shipToZip);

Public PTechLevel2(ByVal PurchaseId As String, ByVal SalesTax As String, ByVal ShipToZip As String)

• C#
• VB.NET

public PTechLevel2();

Public PTechLevel2()

Config Settings (PTechDetailRecord Component)

PTechDetailRecord Config Settings

Base Config Settings

Trappable Errors (PTechDetailRecord Component)

PTechDetailRecord 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 Code field will contain "E", the error code will be contained in the ApprovalCode field, and the description in Text

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 component.

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

HTTP Errors

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

TCPClient Errors

SSL Errors

TCP/IP Errors