TSYSHCRetail Class

Properties Methods Events Config Settings Errors

The TSYSHCRetail class is used to authorize credit cards in a Retail environment, where the customer is purchasing products or services in person. This class makes authorizing these types of transactions very easy.

Syntax

class dpaymentssdk.TSYSHCRetail

Remarks

This class allows for simple, direct, secure connection to the Vital/TSYS 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.

The TSYSHCRetail class makes authorizing Card-Present transactions (where the customer's card is swiped through a card reader) very easy by adding an additional layer of abstraction between the programmer and the protocol. There is no need to deal with raw sockets, TLS/SSL handshakes, or data packet formatting. The steps to setting up the class and authorizing a transaction are outlined below:

First, set the merchant and POS specific properties with setup information acquired from your member bank or processor. For instance:

TSYSHCRetail1.GenKey = "gen_key_value" TSYSHCRetail1.MerchantId = "merchant_id" TSYSHCRetail1.RoutingId = "routing_id"

Next, set properties that contain details about the transaction. At the minimum, you must set a transaction_amount and transaction_number. The transaction_number is a sequence number, and should be incremented for each transaction you send. transaction_amount is the amount of sale formatted with an implicit decimal place.

TSYSHCRetail1.TransactionAmount = "100" TSYSHCRetail1.TransactionNumber = 1

Now, set the credit card properties. If available, you should use Track1 data. Some cards may have a corrupt or missing track1, and for these cards you may use track2 data. If the card is not readable, you may also manually enter the card number and expiration date. The following example shows a transaction sent with track1 data.

TSYSHCRetail1.CardMagneticStripe = "%B4444333322221111^SMITH/JOHN J ^031210100000033301000000008000000?" TSYSHCRetail1.CardEntryDataSource = edsTrack1

Finally, submit the transaction by calling one of three authorization methods: sale, credit, or authenticate_card. The following code demonstrates a purchase: TSYSHCRetail1.Sale()

When the class receives a response from the Vital/TSYS servers, the result of the authorization will be displayed in several Response properties. The response_code indicates whether the transaction was approved, and the response_avs_result indicates whether the customer's billing address on file with his credit card company matches the information presented in the customer_address and customer_zip properties. The remaining properties provide additional information about the transaction.

Once a credit card sale or credit is approved and is added to the current batch. The transaction must go through the batch settlement process in order for the merchant to receive the funds in his merchant account. This is done automatically via a Scheduled Close Batch event that you have setup on your Host Capture Terminal Profile. Alternatively you can manually close a batch by using the TSYSHCBatchMgr class.

Property List

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


capture_mode	The capture mode to be used when performing an authorization or adjustment.
card_type	Type of credit card being used in this transaction.
card_cvv_data	Three digit security code on back of card (optional).
card_cvv_presence	Indicates the presence of the card verification value.
card_entry_data_source	This property contains a 1-character code identifying the source of the customer data.
card_exp_month	Expiration month of the credit card specified in Number .
card_exp_year	Expiration year of the credit card specified in Number .
card_is_encrypted	Determines whether data set to the Number or MagneticStripe properties is validated.
card_magnetic_stripe	Track data read off of the card's magnetic stripe.
card_number	Customer's credit card number for the transaction.
card_present	Indicates whether the current transaction is a card present transaction.
customer_address	The customer's billing address.
customer_zip	Customer's zip code (or postal code if outside of the USA).
gen_key	The unique GenKey value used to identify a POS device.
gratuity_amount	The gratuity (tip) amount of the transaction.
invoice_number	Invoice number for the purchase.
level_2_amex_charge_descriptor	Description of this transaction.
level_2_amex_charge_descriptor2	Description of this transaction.
level_2_amex_charge_descriptor3	Description of this transaction.
level_2_amex_charge_descriptor4	Description of this transaction.
level_2_amex_requester_name	The name of the requestor, if different than the cardholder.
level_2_amex_shipped_to_zip	The zip code to which the commodity was shipped.
level_2_is_tax_exempt	Identifies the characteristics of the amount appearing in TaxAmount and allows you to indicate whether the purchasing card qualifies for tax-exempt status.
level_2_purchase_order_number	Optional customer-specified purchase order number.
level_2_tax_amount	Sales tax charged in addition to the original TransactionAmount Any non-zero sales tax must have a minimum value of 0.
merchant_category_code	Classifies a merchant by the type of store.
merchant_id	The unique ID that associates the POS device with the merchant account.
repeat_indicator	Indicates whether a transaction is a repeat of a previous transaction attempt.
response_approval_code	Contains an authorization code when a transaction has been approved.
response_authorized_amount	The partial authorized amount.
response_avs_result	Contains the Address Verification System result code.
response_batch_number	Contains the incrementing ID assigned by TSYS to identify a merchant batch.
response_card_type	The type of card sent in the authorization request.
response_code	Indicates the status of the authorization request.
response_commercial_card_type	Response property that indicates whether the card is a commercial card.
response_cvv_result	Contains the returned CVV result code if it was requested.
response_installment_advice	Contains the Merchant Advice Code returned by MasterCard MIP.
response_retrieval_number	This number is to be used to identify transactions and should be submitted when making adjustments, reversals or at settlement.
response_returned_aci	Returned Authorization Characteristics Indicator contains CPS qualification status.
response_text	Text information that describes each response code.
response_transaction_date	Local transaction date returned from the server in MMddyy format.
response_transaction_id	Contains the Transaction Identifier or MasterCard Reference Number.
response_transaction_number	Check this property against the original Transaction Number.
response_transaction_time	Local transaction time returned from the server in HHmmss format.
routing_id	The Routing ID assigned to the merchant by TSYS.
ssl_accept_server_cert_encoded	This is the certificate (PEM/Base64 encoded).
ssl_cert_encoded	This is the certificate (PEM/Base64 encoded).
ssl_cert_store	This is the name of the certificate store for the client certificate.
ssl_cert_store_password	If the type of certificate store requires a password, this property is used to specify the password needed to open the certificate store.
ssl_cert_store_type	This is the type of certificate store for this certificate.
ssl_cert_subject	This is the subject of the certificate used for client authentication.
ssl_provider	This specifies the SSL/TLS implementation to use.
ssl_server_cert_encoded	This is the certificate (PEM/Base64 encoded).
timeout	A timeout for the class.
transaction_amount	Purchase amount to be authorized.
transaction_desc	Soft (Dynamic) Descriptor.
transaction_number	Sequence number of this transaction.

Method List

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


adjust_tip	Sends a tip adjustment request.
authenticate_card	Sends an authentication (authorization only) request which will not be captured.
bill_payment	Sends a bill payment request.
config	Sets or retrieves a configuration setting.
credit	Sends a credit request.
force	Performs an offline authorization request.
interrupt	Interrupts the current action.
reset	Clears all properties to their default values.
sale	Sends a sale/purchase request.
void_transaction	Sends a void request.

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.


on_error	Information about errors during data delivery.
on_ssl_server_authentication	Fired after the server presents its certificate to the client.
on_ssl_status	Fired when secure connection progress messages are available.

Config Settings

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


AllowPartialAuths	Indicates whether partial authorizations are to be supported.
AlternateMerchantName	Contains an alternate merchant/DBA name.
AuthorizationIndicator	The type of authorization request.
CashOverAmount	The Cash Over amount requested.
CashOverCurrency	The currency used when requesting a CashOver amount.
DomainServer	Remote domain server indicator.
ISOIdentifier	ISO (Independent Sales Organization) Identifier assigned by MasterCard or Discover.
Language	Indicates the language to be used in formatting the authorization response text message.
LocationDetailCity	Location Detail City.
LocationDetailCountry	The Payment Facilitator Sub-Merchant Country Code.
LocationDetailName	Location Detail Name.
LocationDetailPostalCode	The Payment Facilitator Sub-Merchant Postal Code.
LocationDetailState	The Payment Facilitator Sub-Merchant State/Province Code.
MobileDeviceType	Identifies the type of mobile device used by the cardholder to initiate the transaction.
PFForeignRetailerIndicator	The Payment Facilitator Foreign Retailer Indicator (Visa only).
PFIdentifier	The Payment Facilitator/Marketplace Identifier.
POSAcceptanceDeviceType	Identifies the type of device used to accept mobile Point of Sale (mPOS) transactions.
POSAuthEntity	The authentication entity to indicate the circumstances in which card data was entered at the POS.
POSCardCaptureCapability	Card capture capability data to indicate the circumstances in which card data was entered at the POS.
POSCardholderAuthCapability	Cardholder authentication capability data to indicate the circumstances in which card data was entered at the POS.
POSCardholderAuthMethod	Cardholder authentication method to indicate the circumstances in which card data was entered at the POS.
POSCardholderPresent	Cardholder present data to indicate the circumstances in which card data was entered at the POS.
POSCardInputCapability	Card input capability data to indicate the circumstances in which card data was entered at the POS.
POSCardInputMode	Card input mode to indicate the circumstances in which card data was entered at the POS.
POSCardOutputCapability	Card output capability data to indicate the circumstances in which card data was entered at the POS.
POSCardPresent	Card present data to indicate the circumstances in which card data was entered at the POS.
POSChipConditionCode	Chip condition code to indicate the circumstances in which card data was entered at the POS.
POSCITMITIndicator	CIT/MIT Indicator.
POSEnvironmentIndicator	Provides additional information about the transaction.
POSOperatingEnvironment	Operating environment data to indicate the circumstances in which card data was entered at the POS.
POSPINCaptureCapability	PIN capture capability data to indicate the circumstances in which card data was entered at the POS.
POSTerminalOutputCapability	Terminal output capability data to indicate the circumstances in which card data was entered at the POS.
POSTransactionStatus	A 1-character value used to indicate the purpose or status of the request.
RawRequest	Returns the request sent to the server for debugging purposes.
RawResponse	Returns the response received from the server for debugging purposes.
RequestToken	Indicates whether to request a token for the specified card data sent in an Authorize request.
ResponseCashOverAmount	The Cash Over amount approved.
RetrieveToken	Sends a Token Only request.
ServerURL	The server to which transactions are posted.
SubMerchantIdentifier	The Payment Facilitator Sub-Merchant Identifier.
SurchargeAmount	The transaction fee amount charged to the customer to account for acquirer-assessed surcharge.
Token	The token received from the TSYS host when a token request is sent.
TsysETB	The Encryption Transmission Block TSYS uses to decrypt encrypted data.
AcceptEncoding	Used to tell the server which types of content encodings the client supports.
AllowHTTPCompression	This property enables HTTP compression for receiving data.
AllowHTTPFallback	Whether HTTP/2 connections are permitted to fallback to HTTP/1.1.
Append	Whether to append data to LocalFile.
Authorization	The Authorization string to be sent to the server.
BytesTransferred	Contains the number of bytes transferred in the response data.
ChunkSize	Specifies the chunk size in bytes when using chunked encoding.
CompressHTTPRequest	Set to true to compress the body of a PUT or POST request.
EncodeURL	If set to True the URL will be encoded by the class.
FollowRedirects	Determines what happens when the server issues a redirect.
GetOn302Redirect	If set to True the class will perform a GET on the new location.
HTTP2HeadersWithoutIndexing	HTTP2 headers that should not update the dynamic header table with incremental indexing.
HTTPVersion	The version of HTTP used by the class.
IfModifiedSince	A date determining the maximum age of the desired document.
KeepAlive	Determines whether the HTTP connection is closed after completion of the request.
KerberosSPN	The Service Principal Name for the Kerberos Domain Controller.
LogLevel	The level of detail that is logged.
MaxRedirectAttempts	Limits the number of redirects that are followed in a request.
NegotiatedHTTPVersion	The negotiated HTTP version.
OtherHeaders	Other headers as determined by the user (optional).
ProxyAuthorization	The authorization string to be sent to the proxy server.
ProxyAuthScheme	The authorization scheme to be used for the proxy.
ProxyPassword	A password if authentication is to be used for the proxy.
ProxyPort	Port for the proxy server (default 80).
ProxyServer	Name or IP address of a proxy server (optional).
ProxyUser	A user name if authentication is to be used for the proxy.
SentHeaders	The full set of headers as sent by the client.
StatusCode	The status code of the last response from the server.
StatusLine	The first line of the last response from the server.
TransferredData	The contents of the last response from the server.
TransferredDataLimit	The maximum number of incoming bytes to be stored by the class.
TransferredHeaders	The full set of headers as received from the server.
TransferredRequest	The full request as sent by the client.
UseChunkedEncoding	Enables or Disables HTTP chunked encoding for transfers.
UseIDNs	Whether to encode hostnames to internationalized domain names.
UsePlatformHTTPClient	Whether or not to use the platform HTTP client.
UseProxyAutoConfigURL	Whether to use a Proxy auto-config file when attempting a connection.
UserAgent	Information about the user agent (browser).
ConnectionTimeout	Sets a separate timeout value for establishing a connection.
FirewallAutoDetect	Tells the class whether or not to automatically detect and use firewall system settings, if available.
FirewallHost	Name or IP address of firewall (optional).
FirewallPassword	Password to be used if authentication is to be used when connecting through the firewall.
FirewallPort	The TCP port for the FirewallHost;.
FirewallType	Determines the type of firewall to connect through.
FirewallUser	A user name if authentication is to be used connecting through a firewall.
KeepAliveInterval	The retry interval, in milliseconds, to be used when a TCP keep-alive packet is sent and no response is received.
KeepAliveTime	The inactivity time in milliseconds before a TCP keep-alive packet is sent.
Linger	When set to True, connections are terminated gracefully.
LingerTime	Time in seconds to have the connection linger.
LocalHost	The name of the local host through which connections are initiated or accepted.
LocalPort	The port in the local host where the class binds.
MaxLineLength	The maximum amount of data to accumulate when no EOL is found.
MaxTransferRate	The transfer rate limit in bytes per second.
ProxyExceptionsList	A semicolon separated list of hosts and IPs to bypass when using a proxy.
TCPKeepAlive	Determines whether or not the keep alive socket option is enabled.
TcpNoDelay	Whether or not to delay when sending packets.
UseIPv6	Whether to use IPv6.
LogSSLPackets	Controls whether SSL packets are logged when using the internal security API.
OpenSSLCADir	The path to a directory containing CA certificates.
OpenSSLCAFile	Name of the file containing the list of CA's trusted by your application.
OpenSSLCipherList	A string that controls the ciphers to be used by SSL.
OpenSSLPrngSeedData	The data to seed the pseudo random number generator (PRNG).
ReuseSSLSession	Determines if the SSL session is reused.
SSLCACertFilePaths	The paths to CA certificate files on Unix/Linux.
SSLCACerts	A newline separated list of CA certificate to use during SSL client authentication.
SSLCheckCRL	Whether to check the Certificate Revocation List for the server certificate.
SSLCheckOCSP	Whether to use OCSP to check the status of the server certificate.
SSLCipherStrength	The minimum cipher strength used for bulk encryption.
SSLEnabledCipherSuites	The cipher suite to be used in an SSL negotiation.
SSLEnabledProtocols	Used to enable/disable the supported security protocols.
SSLEnableRenegotiation	Whether the renegotiation_info SSL extension is supported.
SSLIncludeCertChain	Whether the entire certificate chain is included in the SSLServerAuthentication event.
SSLKeyLogFile	The location of a file where per-session secrets are written for debugging purposes.
SSLNegotiatedCipher	Returns the negotiated cipher suite.
SSLNegotiatedCipherStrength	Returns the negotiated cipher suite strength.
SSLNegotiatedCipherSuite	Returns the negotiated cipher suite.
SSLNegotiatedKeyExchange	Returns the negotiated key exchange algorithm.
SSLNegotiatedKeyExchangeStrength	Returns the negotiated key exchange algorithm strength.
SSLNegotiatedVersion	Returns the negotiated protocol version.
SSLSecurityFlags	Flags that control certificate verification.
SSLServerCACerts	A newline separated list of CA certificate to use during SSL server certificate validation.
TLS12SignatureAlgorithms	Defines the allowed TLS 1.2 signature algorithms when SSLProvider is set to Internal.
TLS12SupportedGroups	The supported groups for ECC.
TLS13KeyShareGroups	The groups for which to pregenerate key shares.
TLS13SignatureAlgorithms	The allowed certificate signature algorithms.
TLS13SupportedGroups	The supported groups for (EC)DHE key exchange.
AbsoluteTimeout	Determines whether timeouts are inactivity timeouts or absolute timeouts.
FirewallData	Used to send extra data to the firewall.
InBufferSize	The size in bytes of the incoming queue of the socket.
OutBufferSize	The size in bytes of the outgoing queue of the socket.
BuildInfo	Information about the product's build.
CodePage	The system code page used for Unicode to Multibyte translations.
LicenseInfo	Information about the current license.
MaskSensitive	Whether sensitive data is masked in log messages.
ProcessIdleEvents	Whether the class uses its internal event loop to process events when the main thread is idle.
SelectWaitMillis	The length of time in milliseconds the class will wait when DoEvents is called if there are no events to process.
UseInternalSecurityAPI	Whether or not to use the system security libraries or an internal implementation.

capture_mode Property

The capture mode to be used when performing an authorization or adjustment.

Syntax

def get_capture_mode() -> int: ...
def set_capture_mode(value: int) -> None: ...

capture_mode = property(get_capture_mode, set_capture_mode)

Default Value

Remarks

This property is used to specify the capture mode to be used when performing an authorization or an adjustment transaction.

Possible values are:


Normal (0)	The transaction will be added to the current batch, as specified by BatchNumber, if successfully authorized.
Delay (1)	Indicates that the transaction should not be captured in the current batch without adjustment. If the transaction is adjusted before the current batch closes, then the transaction will be captured in the current batch. If the transaction is not adjusted before the current batch closes, the transaction will be captured in the next batch with or without adjustment.
Hold (2)	When Hold is specified in an original authorization transaction, it will be excluded from batch closing processing.
Capture (3)	When Capture is specified in an adjustment transaction, the batch processing exclusion will be removed in which the transaction will be captured in the current batch.

If you wish to add Level 3 data, you will want to set capture_mode to Delay (1) when issuing the initial authorization. Then once the Level 3 request is successfully issued, the transaction will be captured in the next batch close event.

Note: To use the Hold and Capture modes, the merchant must be established as a Hold Capture participant.

Note: To use the Delay mode, the merchant must be established as a Delay Capture participant.

card_type Property

Type of credit card being used in this transaction.

Syntax

def get_card_type() -> int: ...
def set_card_type(value: int) -> None: ...

card_type = property(get_card_type, set_card_type)

Default Value

Remarks

Type of credit card being used in this transaction. This property contains the customer's credit card type. This is automatically computed after the card_number is set, but it can also be changed manually. A list of valid card types is included below.


ctUnknown (0)	Invalid or unknown prefix, card type not known.
ctVisa (1)	Visa or Delta Card.
ctMasterCard (2)	MasterCard.
ctAMEX (3)	American Express Card.
ctDiscover (4)	Discover Card.
ctDiners (5)	Diners Club or Carte Blanche Card.
ctJCB (6)	JCB Card.
ctVisaElectron (7)	Visa Electron Card (runs as a Visa for most gateways)
ctMaestro (8)	Maestro Card
ctLaser (10)	Laser Card (Ireland)

card_cvv_data Property

Three digit security code on back of card (optional).

Syntax

def get_card_cvv_data() -> str: ...
def set_card_cvv_data(value: str) -> None: ...

card_cvv_data = property(get_card_cvv_data, set_card_cvv_data)

Default Value

Remarks

Three digit security code on back of card (optional).

This alphanumeric property contains the three digit Visa "Card Verification Value" (CVV), MasterCard "Card Verification Code" (CVC), or four-digit American Express "Card Identification Number" (CID). This value appears as additional characters embossed on the card signature line following the credit card account number on the back of the credit card. This is an optional property which can be used to determine if the customer is actually in possession of the credit card.

Even if the card_cvv_data is incorrect, the transaction may still be authorized. It is up to the merchant to examine the ResponseCVVResult property and decide whether to honor the transaction or not.

Note: When set to a non-empty value, card_cvv_presence will be automatically set to cvpProvided. If set to empty string (""), card_cvv_presence will be automatically set to cvpNotProvided.

card_cvv_presence Property

Indicates the presence of the card verification value.

Syntax

def get_card_cvv_presence() -> int: ...
def set_card_cvv_presence(value: int) -> None: ...

card_cvv_presence = property(get_card_cvv_presence, set_card_cvv_presence)

Default Value

Remarks

Indicates the presence of the card verification value.

This property is used to indicate the presence of card_cvv_data.

The class will automatically set this value to cvpProvided when a card_cvv_data value is specified. You can explicitly specify the card_cvv_presence indicator by setting this property.

Available values are:

cvpNotProvided (0)
cvpProvided (1)
cvpIllegible (2)
cvpNotOnCard (3)

card_entry_data_source Property

This property contains a 1-character code identifying the source of the customer data.

Syntax

def get_card_entry_data_source() -> int: ...
def set_card_entry_data_source(value: int) -> None: ...

card_entry_data_source = property(get_card_entry_data_source, set_card_entry_data_source)

Default Value

Remarks

This property contains a 1-character code identifying the source of the customer data. The table below shows all supported values for this property.


edsTrack1 (0)	Full Magnetic stripe read and transmit, Track 1.
edsTrack2 (1)	Full magnetic stripe read and transmit, Track 2.
edsManualEntryTrack1Capable (2)	Manually keyed, Track 1 capable.
edsManualEntryTrack2Capable (3)	Manually keyed, Track 2 capable.
edsManualEntryNoCardReader (4)	Manually keyed, terminal has no card reading capability (use this for e-commerce and MOTO transactions).
edsTrack1Contactless (5)	Full magnetic stripe read (Track 1 only), Chip Card capable terminal (Visa, Mastercard, and JCB Transactions only).
edsTrack2Contactless (6)	Full magnetic stripe read (Track 2 only), Chip Card capable terminal (Visa, Mastercard, and JCB Transactions only).
edsManualEntryContactlessCapable (7)	Manually keyed, Chip Card read capable terminal (Visa, MasterCard, and JCB transactions only).
edsIVR (8)	Interactive Voice Response processing. This is applicable to Mail Order/Telephone Order (MOTO) transactions. (card_number, card_exp_month, and card_exp_year are sent).
edsKiosk (9)	Automated kiosk transaction. Track1 or Track2 data must be sent in card_magnetic_stripe, the transaction cannot be manually entered.

Below is a list of processors and their support EntryDataSource values:

FDMS - edsTrack1, edsTrack2, edsManualEntryTrack1Capable, edsManualEntryTrack2Capable, edsManualEntryNoCardReader, edsTrack1Contactless, edsTrack2Contactless, edsManualEntryContactlessCapable, edsIVR, edsKiosk

FDMSOmaha - All EntryDataSources applicable

FDMS Rapid Connect - All EntryDataSources applicable

Global - edsTrack1, edsTrack2, edsManualEntryTrack1Capable, edsManualEntryTrack2Capable, edsManualEntryNoCardReader, edsTrack1Contactless, edsTrack2Contactless, edsIVR, edsKiosk

PTech - edsTrack1, edsTrack2, edsManualEntryTrack1Capable, edsManualEntryTrack2Capable, edsManualEntryNoCardReader, edsTrack1Contactless, edsTrack2Contactless, edsManualEntryContactlessCapable

TSYS - edsTrack1, edsTrack2, edsManualEntryTrack1Capable, edsManualEntryTrack2Capable, edsManualEntryNoCardReader, edsTrack2Contactless, edsManualEntryContactlessCapable

TSYSHC - Values are based on Industry type.


TSYSHCBenefit	edsTrack2, edsManualEntryTrack1Capable, edsManualEntryTrack2Capable
TSYSHCECommerce	edsManualEntryNoCardReader
TSYSHCRetail	edsTrack1, edsTrack2, edsManualEntryTrack1Capable, edsManualEntryTrack2Capable, edsTrack1Contactless, edsTrack2Contactless, edsManualEntryContactlessCapable

card_exp_month Property

Expiration month of the credit card specified in Number .

Syntax

def get_card_exp_month() -> int: ...
def set_card_exp_month(value: int) -> None: ...

card_exp_month = property(get_card_exp_month, set_card_exp_month)

Default Value

Remarks

Expiration month of the credit card specified in card_number.

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

card_exp_year Property

Expiration year of the credit card specified in Number .

Syntax

def get_card_exp_year() -> int: ...
def set_card_exp_year(value: int) -> None: ...

card_exp_year = property(get_card_exp_year, set_card_exp_year)

Default Value

2000

Remarks

Expiration year of the credit card specified in card_number.

This property contains the expiration date of the customer's credit card. This property must be in the range 0 - 99, or 2000 - 2099. Any date before the year 2000 or after 2099 cannot be specified.

card_is_encrypted Property

Determines whether data set to the Number or MagneticStripe properties is validated.

Syntax

def get_card_is_encrypted() -> bool: ...
def set_card_is_encrypted(value: bool) -> None: ...

card_is_encrypted = property(get_card_is_encrypted, set_card_is_encrypted)

Default Value

FALSE

Remarks

Determines whether data set to the card_number or card_magnetic_stripe fields is validated.

By default, when the card_number or card_magnetic_stripe fields are set, the value will be validated and normalized. For instance, "4444-33332222 1111" will be normalized as "4444333322221111" and card_magnetic_stripe data will be parsed for the track specified by card_entry_data_source. However, any other non-numerical data entered will cause an exception to be thrown. It may be useful in some gateways to send other data in the card_number or card_magnetic_stripe fields, and this can be accomplished by setting IsEncrypted to true. However, please note that in doing so automatic calculation of the card_type may be affected, and the card number will not be verified.

card_magnetic_stripe Property

Track data read off of the card's magnetic stripe.

Syntax

def get_card_magnetic_stripe() -> str: ...
def set_card_magnetic_stripe(value: str) -> None: ...

card_magnetic_stripe = property(get_card_magnetic_stripe, set_card_magnetic_stripe)

Default Value

Remarks

Track data read off of the card's magnetic stripe.

If card_entry_data_source is not one of the manually entered enumerations, then this property must be set with the track1 or track2 data from the magnetic stripe on the back of the customer's credit card. This includes everything after but not including the start sentinel (% or ;) and up to but not including the end sentinel (?) and LRC check character. You may only set this property with track 1 or track 2 data, and may not pass both. Use the card_entry_data_source property to indicate which track you are sending.

The following example shows how to set the card_magnetic_stripe and card_entry_data_source properties if the data read off the card is "%B4788250000028291^TSYS^05121015432112345678?;4788250000028291=05121015432112345678?"

class.CardMagneticStripe = "B4788250000028291^TSYS^05121015432112345678" class.CardEntryDataSource = edsTrack1 or class.CardMagneticStripe = "4788250000028291=05121015432112345678" class.CardEntryDataSource = edsTrack2

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.

card_number Property

Customer's credit card number for the transaction.

Syntax

def get_card_number() -> str: ...
def set_card_number(value: str) -> None: ...

card_number = property(get_card_number, set_card_number)

Default Value

Remarks

Customer's credit card number for the transaction.

If you're sending the transaction with card_magnetic_stripe data, this property should be left empty.

card_present Property

Indicates whether the current transaction is a card present transaction.

Syntax

def get_card_present() -> bool: ...
def set_card_present(value: bool) -> None: ...

card_present = property(get_card_present, set_card_present)

Default Value

TRUE

Remarks

By default, this class handles only retail card-present transactions. However, there are times at which a retail merchant may need to make a card-not-present transaction. For instance, hotel reservations, pre-orders, and the like. By setting this property to False a merchant may submit a card-not-present transaction. However, merchants that deal primarily in card-not-present transactions (either over the Internet or over the telephone) should use the TSYSECommerce class instead.

customer_address Property

The customer's billing address.

Syntax

def get_customer_address() -> str: ...
def set_customer_address(value: str) -> None: ...

customer_address = property(get_customer_address, set_customer_address)

Default Value

Remarks

This field is used as part of the Address Verification Service (AVS) and contains the customer's street address as it appears on their monthly statement. Only the street number, street name, and apartment number are required in this field. City and state are not included, and the zip code is set in the customer_zip property.

This property is an alphanumeric field. Due to concerns with International addresses and changing specifications, the component does not do any processing on the address. The address will be included in the authorization request exactly as you set it.

Per TSYS specs, the following rules apply:

In the address, numbers are not spelled out. "First Street" becomes "1ST Street," "Second" becomes "2ND," and so on.
There must be a (space) between two consecutive data elements that are only numeric.

In order to maximize the address information included in the request, it is suggested that you strip out the spaces (when possible) and punctuations before setting the property.

Note the following examples:

"1234 56th Street" is equivalent to: "1234 56Street"
"1234 56th Street" is NOT equivalent to: "123456Street" //do not strip all spaces between two numbers
"1391 ELM STREET" is equivalent to: "1391ELMSTREET"
"P.O. BOX 24356" is equivalent to: "POBOX24356"

The length of this property is 19 characters, and any string longer than this fails with an error. If the customer's address is much greater than the length of this field, it is admissible to include only the street number in this field.

customer_zip Property

Customer's zip code (or postal code if outside of the USA).

Syntax

def get_customer_zip() -> str: ...
def set_customer_zip(value: str) -> None: ...

customer_zip = property(get_customer_zip, set_customer_zip)

Default Value

Remarks

This field is used as part of the Address Verification Service (AVS). If the customer resides within the United States, this field should contain the five or nine digit zip code as it appears on the customer's monthly statement. If the customer's billing address is outside of the United States, this field should contain the customer's postal code.

This field is an alphanumeric field with a maximum length of nine characters. Spaces and dashes are automatically stripped when the property is set.

gen_key Property

The unique GenKey value used to identify a POS device.

Syntax

def get_gen_key() -> str: ...
def set_gen_key(value: str) -> None: ...

gen_key = property(get_gen_key, set_gen_key)

Default Value

Remarks

This property is used to specify the unique GenKey value used to identify the POS device to the host capture system. This property is required to be specified in every transaction performed.

Your GenKey value is obtained from the host capture system when you successfully authenticate your POS device, which can be accomplished by calling authenticate_device. Once retrieved, your GenKey value must be stored in the POS device.

gratuity_amount Property

The gratuity (tip) amount of the transaction.

Syntax

def get_gratuity_amount() -> str: ...
def set_gratuity_amount(value: str) -> None: ...

gratuity_amount = property(get_gratuity_amount, set_gratuity_amount)

Default Value

Remarks

This property is used to specify the gratuity (tip) amount when performing an authorization via authorize.

If you wish to later adjust a tip amount, adjust_tip can be used after the initial authorization has been performed.

invoice_number Property

Invoice number for the purchase.

Syntax

def get_invoice_number() -> str: ...
def set_invoice_number(value: str) -> None: ...

invoice_number = property(get_invoice_number, set_invoice_number)

Default Value

Remarks

This property is used to specify the merchant assigned invoice number for the e-Commerce (card not present) purchase.

level_2_amex_charge_descriptor Property