Knowledge Base FAQs

+
Can my POS connect to TSYS's services using an IP address?

At TSYS, we use managed DNS services to provide global load balancing and data center redundancy. We publish our public IP addresses but we rely on DNS to make sure our customers are routed the to correct data centers at the correct times. Although it’s possible to use our public IP addresses directly, it would prevent us from managing uptime, balancing load, and supporting any network connectivity issues. Also, as we change ISPs (as we did in Q1 2017), ISVs and merchants may experience a loss of availability by circumventing DNS, as our IP addresses will change. We don’t recommend ISVs implement any custom load balancing or redundancy solutions but if you choose to, please be aware that we cannot assist or support you or your merchants in the design of such a system, nor in the operation thereof. Further, TSYS can make no guarantees around availability or uptime, as your solution would circumvent our global high availability system’s design.

TSYS is committed to providing the highest possible availability and best in class service. All of our systems are diverse, redundant, and highly available from our DNS providers to our ISPs, data centers, and every component and virtual machine within our data centers. We strongly believe that our mutual customers will benefit from your heeding the above guidance.

For more details on our High Availability strategy, please see our blog post on How TSYS helps protect merchants from costly downtime.

+
Can Transport Keys be used again?

The TransportKey used to access a Genius CED or Transport.Web is a one time use, time sensitive token.

When performing multiple activites using a TransportKey, or if a timeout is encountered when communicating with a Genius CED or Transport.Web a new TransportKey must be obtained.

+
Do e-Commerce merchants need a different MID for their online vs. storefront environments?

Merchants increasingly have both online and storefront environments. We are often asked whether merchants are required to have different MIDs for online vs. storefront, or if they can both use the same merchant account.

We recommend that merchants create separate MIDs for storefront vs. online transactions. The prevailing industry guidance is that merchants with an existing retail account can extend the merchant account to e-commerce, card not present transactions, within some limitations. Acquirers typically employ a "20% rule" where if a merchant has an existing Retail account - that is, the retailer should only process Card Not Present transactions up to 20% of their total sales. If a merchant exceeds the 20% rule, the account has a risk of downgrades and could possibly be shut down. When engaging with partners and merchants about unified commerce, it is best practice to consider this 20% rule to avoid these risks. When in doubt, opt to create distinct accounts for online vs. in store.

Even if merchants are using different MIDs online vs. in store, our Unified Commerce solution supports use cases like "buy online, return in store", allowing for a seamless customer and merchant experience across those two channels.

Please don’t hesitate to reach out to your relationship manager to further discuss risk management options.

+
Do you have a Bug Bounty Program?

Security first: Our bug bounty program

Our approach to security focuses on protecting merchants and their data. We monitor every transaction from swipes to payments, and are always innovating in fraud prevention. We protect businesses’ data as if our business depends on it­—because it does.
We follow industry-leading standards to:

  • Manage our network
  • Secure our web and client applications
  • Set policies across our organization

We take the security of our services very seriously and monitor their use for indications of a malicious attack.

How our bounty program works

We welcome the contributions of the security research community, and have implemented our bug bounty program to encourage coordinated reporting of security issues with our services.

We especially want to hear about problems with our payment flows or the protection of data at rest. You can receive a reward of at least $250 if we confirm these vulnerabilities.

Important: You must not use this program to access or obtain sensitive or protected data, for example, cardholder data or personal information.  

What is the scope of the program?

The bug bounty program applies to the following services:

  • genius.merchantware.net
  • transport.merchantware.net
  • portal.merchantware.net
  • ps1.merchantware.net
  • *.accessaccountdetails.com
Important: We review submissions that are associated with in-scope services only. For the purposes of this bug bounty program, *.tsys.com is not considered an in-scope service.

Note: We use Geo-IP Blocking to prevent connections from outside the US and Canada.

  1. If you are outside these regions, you need to use a proxy or originate your connection from the US or Canada.
  2. Our security team may block you during penetration testing, and terminate your connection. This is in line with our Incident Response Policy. To resume testing, change your IP address, ensuring that it originates in the US or Canada.
Note: At our sole discretion, we will provide test credentials and portal login credentials upon request to established members of our Hackerone program, subject to the terms of our Bug Bounty Program. These test accounts are configured to use our Test Processor, and will allow you to meaningfully exercise our portals and APIs, but will not allow you to perform any actual credit or debit card authorizations. The Test Processor is configured to return fake stand-in authorization codes, and does not communicate with any credit card networks or issuing banks.

Disclosure procedures

To help us identify legitimate security research as opposed to malicious attacks against our services, we promise not to take legal action against researchers who:

  • share the full details of any problems found with us;
  • do not share the issue with others until we have had reasonable time to address it;
  • do not intentionally harm the experience or usefulness of the service to others;
  • never attempt to view, modify, or damage other people’s data;
  • do not attempt a Denial-of-Service (DoS) attack, and;
  • do not carry out any research or testing which breaks the law.

Bounty value

Our security team determines the value of your bounty based on the severity of the vulnerability you report. Bounties start at $250. We award bounties entirely at our discretion; if you provide research that is more complete, with proof-of-concept code, and detailed write-ups you may receive a bonus percentage on top of the bounty we award. However, we may pay less for vulnerabilities which cannot be used as an attack vector, which require complex interactions, or if the impact of the security risk is minor.
In some cases, we may consolidate bounties into a single payout. For example, we may consolidate bounties into one payout, if you report a single vulnerability that:

  • compromises the security across several areas of one of our services; or
  • compromises the security across several of our services.

Note: Our services are genius.merchantware.net, transport.merchantware.net, ps1.merchantware.netportal.merchantware.net, and *accessaccountdetails.com.

We may reduce or decline bounties if there is evidence of abuse, such as data exfiltration or withholding reports in order to chain multiple issues together.

Eligibility and coordinated disclosure

You are eligible for a bounty only if you are the first person to disclose an unknown issue to us. Our security team and associated development teams have 30 days to respond to your report and up to 90 days to implement a fix based on the severity of the report. Please allow us to complete this process before you publicly disclose the vulnerability.

Note: You will forfeit any reward/bounty and risk immediate removal from this program if:

  • you post details or conversations about a report before we approve it for public release,
  • you post details that reflect badly on this program and the TSYS brand.

Important: The following people are not eligible for participation in the bounty program:

  • Current or former TSYS (or Cayan/Merchant Warehouse) employees
  • Vendors
  • Contractors
  • Immediate family members of current or former employees, vendors, and contractors

What type of vulnerabilities are we looking for?

We are looking for anything that could negatively affect the security of our merchants as described in this section.

OWASP Top 10

The following table contains the top ten risks as described by OWASP Top 10 Application Security Risks - 2013. The bounty program has an API only scope, not all of the risks shown in the following table are applicable, but they do provide a framework to identify and describe vulnerabilities, which you may uncover within our API.

Risk
Description
API Example
A1 - Injection Injection flaws, such as SQL, OS, and LDAP injection occur when untrusted data is sent to an interpreter as part of a command or query. The attacker’s hostile data can trick the interpreter into executing unintended commands or accessing data without proper authorization. SQL, LDAP Injection
A2 - Broken Authentication and Session Management Application functions related to authentication and session management are often not implemented correctly, allowing attackers to compromise passwords, keys, or session tokens, or to exploit other implementation flaws to assume other users’ identities. Authentication Bypass, Escalated Privilege, Session Replay, Exposure of administrative functions to unauthorized callers
A3 - Cross-Site Scripting (XSS) XSS flaws occur whenever an application takes untrusted data and sends it to a web browser without proper validation or escaping. XSS allows attackers to execute scripts in the victim’s browser which can hijack user sessions, deface web sites, or redirect the user to malicious sites.  
A4 - Insecure Direct Object References A direct object reference occurs when a developer exposes a reference to an internal implementation object, such as a file, directory, or database key. Without an access control check or other protection, attackers can manipulate these references to access unauthorized data.  
A5 - Security Misconfiguration Good security requires having a secure configuration defined and deployed for the application, frameworks, application server, web server, database server, and platform. Secure settings should be defined, implemented, and maintained, as defaults are often insecure. Additionally, software should be kept up to date.  
A6 - Sensitive Data Exposure Many web applications do not properly protect sensitive data, such as credit cards, tax IDs, and authentication credentials. Attackers may steal or modify such weakly protected data to conduct credit card fraud, identity theft, or other crimes. Sensitive data deserves extra protection such as encryption at rest or in transit, as well as special precautions when exchanged with the browser.  
A7 - Missing Function Level Access Control Most web applications verify function level access rights before making that functionality visible in the UI. However, applications need to perform the same access control checks on the server when each function is accessed. If requests are not verified, attackers will be able to forge requests in order to access functionality without proper authorization.  
A8 - Cross-Site Request Forgery (CSRF) A CSRF attack forces a logged-on victim’s browser to send a forged HTTP request, including the victim’s session cookie and any other automatically included authentication information, to a vulnerable web application. This allows the attacker to force the victim’s browser to generate requests the vulnerable application thinks are legitimate requests from the victim.  
A9 - Using Components with Known Vulnerabilitites Components, such as libraries, frameworks, and other software modules, almost always run with full privileges. If a vulnerable component is exploited, such an attack can facilitate serious data loss or server takeover. Applications using components with known  

Additional vulnerabilities

The following table contains additional vulnerabilities we are especially interested in identifying and fixing:

Risk
Description
API Example
B1 - Server-Side Request Forgery (SSRF) SSRF occurs when attackers can influence a network connection made by the application server. The network connection will originate from the application server internal IP, attackers are able to use this connection to bypass network controls and scan or attack internal resources that are not otherwise exposed.  
B2 - XML External Entity Attacks (XXE) XXE attacks enable attackers to reveal normally protected files from a server or connected network. An attack occurs when a weakly configured XML parser processes an XML input containing a reference to an external entity. The attack can lead to the disclosure of confidential data, DoS, SSRF, port scanning from the perspective of the machine where the parser is located, etc.  
B3 - Open Redirect Vulnerabilities An open redirect is an application that takes a parameter and redirects a user to the parameter value without any validation. Phishing attacks use open redirects to get users to visit malicious sites without realizing it.  
B4 - Remote Code Execution (RCE) Attacker executes their choice of arbitrary code on a target machine or target process.  

Capture the flag (file)

We will pay a bounty if you can find the hackerone-flag.txt. Please note the following:

  • The hackerone-flag.txt file contains a 32 character UUID
  • The SHA256 digest of the flag is: a35eb8614dc3afa714107b09796f22146104bf046d718ed8b2beb0b28af08c40

Important: To claim the bounty, you must tell us how you found the file.

Computing the SHA256 message digest

We are publishing the digest of the flag to allow you to confirm you have found the right file. To view the digest of the flag, we ran the following command:

    echo [32 characters] | sha256sum 

You can run the same command on your terminal. You may need to install sha256sum or use an alternative method.
For example, if the value of the token was:

    fb3f8fe63cc107c1977855c95633fb13

Then you would get the following response:

    ~ echo -n fb3f8fe63cc107c1977855c95633fb13 | sha256sum
    
    d4c039c506f3666f205aaa811f9c6c7b82433769c1aee98549f486d0a4944896 *- 

Note: The values listed above are not genuine and are for example only.

What type of vulnerabilities are we not looking for?

We do not consider the following severe enough for reward as part of our bug bounty program:

  • Vulnerabilities affecting users of outdated browsers or platforms:
    • Internet Explorer prior to version 9
    • Chrome prior to version 40
    • Firefox prior to version 35
    • Safari prior to version 7
    • Opera prior to version 13
  • Concerns about best practices
  • Highly speculative reports about theoretical damage
  • Self-XSS that cannot be used to exploit other users (this includes having a user paste JavaScript into the browser console)
  • Vulnerabilities reported by automated tools or scans without additional analysis as to how they are an issue
  • DoS Attacks
  • Reflected File Download (RFD)
  • Issues related to Window.opener
  • Social engineering attempts (this includes phishing attacks against our employees)
  • Content injection issues
  • Non-validated reports from automated web vulnerability scanners (Acunetix, Vega, etc.)
  • Cross-site Request Forgery (CSRF) with minimal security implications (Logout CSRF, etc.)
  • Missing cookie flags on non-security sensitive cookies
  • Issues which require physical access to a victim’s computer
  • Fraud issues
  • Banner grabbing issues (figuring out what web server we use, etc.)
  • Brute force attacks without proof that TSYS failed to lock out or otherwise disable a valid account after a number of unsuccessful login attempts
  • Open ports without an accompanying proof-of-concept demonstrating vulnerability
  • Issues related to software that is not under our control
  • Any physical attempts against our property or our data centers
  • The presence of autocomplete attribute on web forms
  • Missing HTTP security headers (unless you deliver a proof-of-concept that takes advantage of their absence)
  • Clickjacking on widgets intended to be embedded in other pages
  • Reports of insecure SSL/TLS ciphers (unless you have a working proof-of-concept, and not just a report from a scanner such as SSL labs)
  • An oracle that discloses whether a given username, email address, or phone number is associated with an actual account. (However, please do submit anything that allows you to recover usernames as a whole.)
  • Bugs that we are already fixing or that someone else has previously reported
  • Underspecified reports, where the information provided is insufficient to reproduce the vulnerability
  • Functionality bugs which do not compromise the security of our users’ accounts or personal information
  • Bugs that have been disclosed publicly or to third parties (brokers) by you or others
  • Vulnerabilities on sites that are not owned or operated by us
  • Testing a suspected vulnerability in a way that violates any law or compromises data that is not your own
  • Informational-based or reconnaissance-based reports that:
    • are best practices
    • do not lead to real-world threat vectors
    • could not be used to exploit the target systems 

Attack pivoting

  • We want to limit the security testing to the scope provided above, for more information see What is the scope of the program?
  • We do not allow any pivoting from the initial point of compromise; this is to ensure we protect external systems and third parties.
  • Do not extend the scope of the testing from the scope.

Submitting a bug report

If you think you have found a security vulnerability, you can submit your report via Hackerone. Please email <bounty AT cayan.com> to request access to our Hackerone program.  Please include the email address linked to your Hackerone account in your request

Attributes of a good report

You should include the following information when reporting a vulnerability to us:

  • Detailed steps on how to reproduce the bug, please include the following:
    • Screenshots
    • Any links you clicked
    • Any pages you visited, etc.
  • Description of the versions of all relevant components of the attack, for example, browser, OS, mobile app version, etc.
  • Provide context, describe the specific scenario, and how the bug/vulnerability will affect us.

Encrypting email communications

You can encrypt email communications to <bounty AT cayan.com> using our PGP key below.

SHA256 (HEX) Fingerprint: A0753D2CC520F41B9404E354550C339DB8F7619A3495B91059D868637552DCD3
 

    -----BEGIN PGP PUBLIC KEY BLOCK-----
    
    Version: BCPG C# v1.6.1.0
    
    
    
    mQENBFcU1RwBCACLfGRjEaHnMtSd1UWss0ZYh1qvPHI3uBcdCpnYcc82BN1QZxKj
    
    5oRs1bVHYubvj9KaX/xynO+G1oeknzPiC10hCci7CXhry+JWoRW++N29TSByzDYE
    
    uZ+H422uQl5z5e7qeLTSrIiWem/HvD17KOpod82FjC1c8ec0NPa3yVKmDlsRxnd0
    
    boHMuBwxDMll2ZVdn9aK1awfIjbdDpJdSgUCWDmLTAsrZi8tEUPopaYWOautS1eN
    
    EUJ7nB0jmNDy0I2T6oSPgGi6fdssre2jDIXe7dtu9UplK/v8X4NDLPOMF8A5scaV
    
    iKP1z3oWZSPiG80/RZPOmPqpZ+RKTSRFKLo/ABEBAAG0EWNtY2dpbGxAY2F5YW4u
    
    Y29tiQEcBBABAgAGBQJXFNUcAAoJEJNOgFWE+avjfuUH/jhfYiPNyS3lttFCO6lV
    
    fnFWcczNGCRqaGFNsrK/OlNZOttWMq+b3bHqqc1JbSKUO4/Qde7sMt1mD28BjMnh
    
    mEKX13ssD3OXHR+n56Z5h33ONXUBvCDd958TrsIeJylac4SbMZYZu6aGO/ag38OL
    
    i9r2PBKrf8vxkqLjDuG9WwHP9sNaI7OZiy/nrudXPiTfvBYfdz8BC1zVCCkFbj2x
    
    SJA2u6KIKTRHfv9Fq0xZjBovV8HuL57sTOMfRbobbaajegHS61H/kSNEMPetTtmx
    
    OT60uD6S4Vtw/NEq1btyBxSzfQrfWoT9pi44xw/IclvEPoZR/1p+d8f76dN6tXQa
    
    cys=
    
    =Wjzm
    
    -----END PGP PUBLIC KEY BLOCK-----

Terms and Conditions

  • Participants are responsible for paying any taxes associated with rewards.
  • Please use your own account for testing or research purposes. Do not attempt to gain access to another user’s account or confidential information. Your testing must not violate any law, or disrupt or compromise any data that is not your own.
  • We reserve the right to modify the terms of this program or terminate this program at any time.
  • By participating in this program, you agree to be bound by these rules.
+
Do you have any cURL examples?

Our Certification Engineering team will occasionally receive inquiries relating to the use of cURL for staging a Genius transaction. We have put together a few common examples that you may use as a reference for debugging purposes.

Stage Transaction

  • Command Line Format: curl.exe https://transport.merchantware.net/v4/transportService.asmx -H "Content-Type:text/xml" -X POST -d @"StageTransaction.txt"
  • Request Format
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
    <CreateTransaction xmlns="http://transport.merchantware.net/v4/">
    <merchantName>Zero Inc</merchantName>
    <merchantSiteId>00000000</merchantSiteId>
    <merchantKey>00000-00000-00000-00000-00000</merchantKey>
    <request>
        <TransactionType>SALE</TransactionType>
        <Amount>1.23</Amount>
        <ClerkId>ABC123</ClerkId>
        <OrderNumber>ABC123</OrderNumber>
        <Dba>ZERO BRANDS</Dba>
        <SoftwareName>ABC SOFTWARE</SoftwareName>
        <SoftwareVersion>1.0.0.0</SoftwareVersion>
        <Cardholder>VISA TEST CARD</Cardholder>
        <TransactionId>ABC123</TransactionId>
        <ForceDuplicate>false</ForceDuplicate>
        <CustomerCode>ABC123</CustomerCode>
        <PoNumber>ABC123</PoNumber>
        <TaxAmount>0.10</TaxAmount>
        <TerminalId>01</TerminalId>
        <HealthCareAmountDetails>
            <HealthCareTotalAmount>0.00</HealthCareTotalAmount>
            <ClinicalAmount>0.00</ClinicalAmount>
            <CopayAmount>0.00</CopayAmount>
            <DentalAmount>0.00</DentalAmount>
            <PrescriptionAmount>0.00</PrescriptionAmount>
            <VisionAmount>0.00</VisionAmount>
        </HealthCareAmountDetails>
        <TipDetails>
            <EligibleAmount>0.00</EligibleAmount>
        </TipDetails>
    </request>
</CreateTransaction>
</soap:Body>
</soap:Envelope>

Initiate Transaction

  • Command Line Format: curl.exe "http://[CED IP Address]:8080/v2/pos?TransportKey=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&Format=XML"

Retrieve Transaction Details

  • Command Line Format: curl.exe https://genius.merchantware.net/v1/Reporting.asmx -H "Content-Type:text/xml" -X POST -d@"Details.txt"
  • Request Format
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <DetailsByTransportKey xmlns="http://schemas.merchantwarehouse.com/genius/10/Reporting">
    	<merchantName>Zero Inc</merchantName>
    	<merchantSiteId>00000000</merchantSiteId>
    	<merchantKey>00000-00000-00000-00000-00000</merchantKey>
    	<TransportKey>xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx</TransportKey>
    </DetailsByTransportKey>
  </soap:Body>
</soap:Envelope>
+
Does Genius support multicast DNS?

Genius versions 5.0 and later support Multicast DNS (mDNS) and DNS Service Discovery (DNS-SD). What does this mean for a POS developer? If your operating system supports mDNS (sometimes also referred to as Bonjour or Zeroconf), you can:

  1. Address a Genius terminal using a friendly name based on its serial number, instead of its IP address. This is particularly useful if your merchant's network uses dynamically assigned IP addresses (DHCP) rather than static IP addresses.
  2. Discover all Genius terminals on your network. This can be used to do a "quick setup" of a Genius terminal by browsing all of the terminals available on the network.

An example of discovering music sharing devices on your LAN. •	Example taken from the Apple Bonjour Overview. •	https://developer.apple.com/library/ios/documentation/Cocoa/Conceptual/NetServices/Articles/NetServicesArchitecture.html
(Example image taken from the Apple Bonjour Overview. https://developer.apple.com/library/ios/documentation/Cocoa/Conceptual/NetServices/Articles/NetServicesArchitecture.html)

This is the same technology that allows your iPhone to discover playback devices within your home network, or your laptop to discover printers on your office's LAN.

This feature works well with Genius's HTTPs feature, also supported in version 5.0 and later.

Addressing a Genius Terminal

Using this feature, you can address a Genius terminal by its serial number rather than its IP address. As mentioned below, your POS must be utilizing an Operating System or library that supports mDNS. Additionally, you must update your POS's configuration to use this addressing scheme:

http://<serial_number>-geniusced.local (eg. http://288-250-247-geniusced.local:8080)

This feature also works using the HTTPs protocol scheme (eg. https://288-250-247-geniusced.local:8443).

Discovering all Genius Terminals on your Network

Genius terminals can be discovered on your local area network using DNS-SD. Genius terminals advertise themselves on the pseudo ".local" domain as follows:

Service Type
Description
_geniusced_http Genius on http port 8080
_geniusced_https Genius over https port 8443

Below is an example of browsing all Genius terminals using the DNS-SD Service Browser, a Java application that's part of the Bonjour SDK.

Operating System Support

To take advantage of this feature, you'll need an Operating System that supports mDNS, install a helper application like Bonjour or Avahi, or else you'll need to use a library that supports mDNS. Information for several popular platforms is included below:

OS/Platform Recommendation
Mac OSX Supports mDNS natively via Bonjour
iOS (iPad, iPhone) Supports mDNS natively via Bonjour
Windows Can be supported by installing Bonjour
Linux Supported on distributions running Avahi
Java Supported via one of many Java libraries (eg. JmDNS, mdnsjava)
Android As per Java. Newer versions of Android support Network Service Discovery.

If your POS is running on Mac OSX, iOS, Windows with Bonjour installed, or Linux with Avahi installed, mDNS should be seamlessly integrated into your Operating System's network stack. This means that your OS, libraries, and frameworks should know how to handle HTTP requests for the geniusced.local pseudo TLD without you having to make any specific changes to your POS.

mDNS Repeaters

By design, Multicast DNS only can discover and communicate with devices on your local area network (more specifically, within the same subnet). If your merchant's storefront uses multiple virtual lans/subnets - eg. the merchant is employing network segmentation such that the POSes are on subnet #1 and the terminals are on subnet #2 - you will need to take advantage of an mDNS repeater. An mDNS repeater will forward mDNS requests from one subnet to another. Many common commercial and home routers support this feature, sometimes dubbed as "Wide Area Bonjour". If yours doesn't, there are options, such as mdns-repeater.

+
Does Genius support the MasterCard 2-Series BIN Range?
MasterCard has announced that they have received an additional range of 2-series (222100-272099) BIN numbers and card issuing banks may be assigned the new BIN ranges starting January 2017. The new BIN series will be processed in the same way as their existing 5-series (510000-559999) BIN ranges.
 
What is a BIN?
 
A BIN (bank identification number) is a six digit number that identifies the card issuing institution and is the first part of a credit card number. The remainder of the card number is the account number that is assigned by the card issuing bank.
 
Do you support the new MasterCard BIN Range?
 
Yes, we have updated our solutions and APIs to support the new MasterCard BIN range. All of our integrated POS partners will automatically get support for the new BIN range without making changes to their POS integration, ultimately, providing support for the new BIN range to their respective merchants.
+
Does my POS require supporting Stored Value (Gift) Cards?
Does my POS require supporting Stored Value (Gift) Cards?
Stored Value (Gift) cards are great for attracting consumers and driving incremental bottom line revenue. Gift card sales have increased steadily over recent years, and demand remains incredibly strong.

Many ISV’s have a target audience for which their point of sale system will cater to, and depending on the payment types the merchant wishes to accept, support for Gift transactions may not be an immediate option. Often, merchants who are using an integrated point of sale system will inquire about accepting Gift transactions upon signing with TSYS.

To reduce potential costly development work at a later point, and reduce downtime for merchants, TSYS requires that new or existing ISV’s integrating to our Genius API include support for Gift processing. Gift card functionality will be reviewed during the implementation process and is a requirement aimed at providing a seamless integration for both developers as well as mutual merchants across all forms of the Genius API.

Please reach out to your Sales Engineer or the Certification Engineering team for any questions you may have with regards to your Genius integration.
+
How can I connect to a Genius device?

DNS Hostname

Locating the DNS Hostname

  • From the Idle screen, press "0 0 0" (zero-zero-zero) on the keypad
  • Enter the Admin password: 9416557
  • Press the green Enter button
  • The Hostname will be displayed on the screen
  • Pressing the red Cancel button will return you back to the Idle screen

IP Address

Locating the IP Address

  • From the Idle screen, press "0 0 0" (zero-zero-zero) on the keypad
  • Enter the Admin password: 9416557
  • Press the green Enter button
  • The IP Address will be the first item displayed
  • Pressing the red Cancel button will return you back to the Idle screen
 

Configuring Static IP Address

  • From the Idle screen, press "0 0 0" (zero-zero-zero) on the keypad
  • Enter the Admin password: 9416557
  • Press the green Enter button
  • Tap Network
  • Tap Configure
  • Select Static as the IP Mode
  • Enter the IP Address you wish to assign to the Genius device
    • For an IP Address such as 10.0.0.1, enter the values as 010.000.000.001
    • For an IP Address such as 192.168.0.1, enter the values as 192.168.000.001
  • Continue entering the Netmask, Gateway, DNS 1 & DNS 2 values according to your network configuration
    • If you make a mistake while keying this information, use the yellow Back button
  • Tap Save once all the values have been entered
  • Pressing the red Cancel button will return you back to the Idle screen
+
How do I install the Genius root certificate?

Genius version 5.0 and later supports a HTTPs interface in addition to its traditional HTTP interface. Only the protocol scheme (https vs. http) and port (8443 vs 8080) differ from traditional Genius implementations. All other details regarding how your POS communicates with the terminal are unchanged - all API calls, URIs, messages, and request/response payloads are identical, excepting the protocol scheme and port. For more details, please see Alternate Device Communication Methods in our Genius documentation.

Genius supports a HTTPS interface so users can communicate with the CED using TLS to secure the connection. Combined with Genius's CORS support, this feature is especially useful for partners who have developed browser based Points of Sale. The terminal will generate appropriate certificates as required in order to serve the TLS connection, and all certificates generated by the CED will be signed by the Cayan CA.

This means that if merchants install the Cayan CA, then their client machines will trust the certificates that are served by the terminal.

Installing the Cayan CA

The Root Certificate can be downloaded from https://docs.cayan.com/Site/Media/Docs/Site-Content/Cayan_1.crt. Instructions differ between Operating Systems and Browsers, but installation is generally straight forward. Generally, you just need to download the certificate, double click it, and follow the prompts on your screen.

Installation instructions are provided below for some major Windows-based browsers. Firefox appears to use its own local certificate store, while Internet Explorer and Chrome appear to use the standard Windows certificate store. This means that if your POS is a desktop application, you will probably need to follow the Internet Explorer / Chrome installation instructions.

firefox

Go to https://docs.cayan.com/Site/Media/Docs/Site-Content/Cayan_1.crt

If you see:

Certificate-Alert.png

Then you've already got the Cayan CA installed and you don't have anything further to do. Otherwise, you'll see:

Certificate-Installation-(1).png

Ensure that "Trust this CA to identify websites" is checked, then click "OK", and you're done.

Internet Explorer / Chrome

Go to https://docs.cayan.com/Site/Media/Docs/Site-Content/Cayan_1.crt and you'll be offered to download the Cayan.crt file, download it and save it somewhere on your hard drive.

Locate the file on your hard drive and right-click on it and choose "Install Certificate".

Select to install the certificate on the local machine and click next.



When asked "Windows can automatically select a certificate store, or you can specify a location for the certificate", choose "Place all certificates in the following store" and hit "Browse":

Certificate-IE-Install-(1).png

When prompted, choose "Trusted Root Certification Authorities" and click "OK":

Certificate-Trust.png

Then click "Next" on the following screen.



Finally click "Finish" to complete the installation.

Certificate-Success.png

 

+
How should my network be configured to work with TSYS's services?

As a security measure, many merchants restrict outbound communications from their networks - whitelisting traffic to just a handful of sites, such as their payment processor.

Below are all the necessary details for how a Network Administrator should configure his/her networks and firewalls to inter-operate with TSYS's services.

Data / Transaction Flow Diagram

The below diagram, excerpted from our Genius PA-DSS Eligibility Assessment, illustrates a common workflow between the Genius credit card terminal ("PED"), our Gateway, and the ISV's Point of Sale.

Genius-Data-Flow-Diagram.png
  1. The user initiates a transaction, and the third-party software sends a payment request with the amount and other information (but no cardholder data) to the Gateway.
  2. The gateway responds with a transport key.
  3. The third-party software sends the transport key to the PED using HTTP.
  4. The PED uses the transport key to retrieve the purchase amount from the Gateway.
  5. Cardholder data is collected by the PED and encrypted.
  6. The PED sends the encrypted data to the Gateway protected with HTTPS.
  7. The transaction response (e.g., authorized, declined) and other information is sent to the PED.
  8. The transaction response and other information is passed back to the third-party software.


Hosts:

  • transport.merchantware.net
  • genius.merchantware.net
  • ps1.merchantware.net
  • s01.merchantware.net
  • logupload.merchantware.net

Production IP Addresses

TSYS employs BGP in its data centers, which means that each of our data centers is served by multiple ISPs that advertize the same IP address ranges. By employing multiple ISPs in its data centers, TSYS can better protect its services from internet outages and traffic disruptions and provide higher uptimes and faster transactions for our customers. If you whitelist outbound traffic, you may want to whitelist the below IP ranges as a precautionary measure:
  • Chicago: 209.133.97.0 /24
  • Boston:   209.119.131.0 /24

Ports

Public internet:

  • 443: SSL
  • 7622: SFTP (via SSH)

Local area network:

  • 8080: POS (or Store & Forward) communication to a Genius terminal (HTTP)
  • 8443: POS communication to a Genius terminal (HTTPS)
  • 7500: default Store & Forward for all traffic represented by transport.merchantware.net
  • 7501: default Store & Forward for all traffic represented by ps1.merchantware.net
  • 7502: default Store & Forward for all traffic represented by genius.merchantware.net
  • 7503: default Store & Forward for Rest API that can be used to communicate with Store and Forward
  • 7504: default Store & Forward that services the Administration Website

Third Parties

Genius will reach out to our Certificate Authority (Digicert) in order to perform certificate revocation checks, and otherwise validate certificates, to prevent against "man in the middle" attacks. If you see traffic on your network to "*.digicert.com", that's what this is, and you may want to whitelist those domains.

If your POS uses Genius over HTTPs and you do not have GlobalSign's root and intermediate certificates in your certificate store, you may need to install those. See GlobalSign's site for more details.

Troubleshooting

As you lock down your network, you may run into issues, and prevent your Point of Sale from being able to communicate with our gateway, thus preventing your merchants from processing credit card transactions. We recommend that network engineers read this document, as well as ours Service Availability Monitoring Best Practices guide, for how to test that their networks can communicate with TSYS.

We recommend that network engineers confirm that they can load the health check pages mentioned in the Service Availability Monitoring guide. Please confirm that your network can communicate with both of our data centers. We recommend that you run sequential tests, statically configuring DNS (eg. by modifying your hosts file) to point at our Boston and then Chicago data centers. Alter your DNS to force traffic to our Boston Data Center. Using a web browser running on your POS, confirm that you can load our health check pages. Then, modify your DNS to use our Chicago IP addresses, and re-confirm that you can load our health check pages.

If you encounter troubles connecting to TSYS's environment, please try repeating your test, using some neutral 3rd party site (eg. Google, Facebook, LinkedIn, ...). Once that is working, compare & contrast those settings with those you've implemented for TSYS's network.

We also suggest repeating any failed tests from an unrestricted network (eg. connected to a 4G LTE network) to help determine if the root cause is more likely to be with your network configuration than TSYS's. If you can connect from an unrestricted network, please examine your restricted network's configuration to ensure that all of NAT rules and ACLs are set up properly.

We also suggest using various common network troubleshooting tools & procedures to help diagnose any issues:

  • nslookup & ping - to ensure that you've resolved our FQDNs properly
  • traceroute - to ensure that your packets are making it to our data centers
  • telnet - to make a quick connection to our IP addresses
  • WireShark - to spy on your Point of Sale's traffic, and ensure that all TCP & SSL/TLS handshakes are occurring as expected

Warning: statically configuring DNS is only acceptable in a test/lab environment. TSYS manages its availablity using a DNS load balancing algorithm, with a low TTL. TSYS requires its merchants and ISVs to use public DNS to.resolve our FQDNs. Not doing so will void any SLAs that may be in place, and will likely lead to downtime outside of TSYS's control.

Chicago IPs

209.133.97.100 ps1.merchantware.net
209.133.97.107 genius.merchantware.net
209.133.97.108 transport.merchantware.net
209.133.97.60 s01.merchantware.net
209.133.97.110 logupload.merchantware.net

Boston IPs

209.119.131.100 ps1.merchantware.net
209.119.131.107 genius.merchantware.net
209.119.131.108 transport.merchantware.net
209.119.131.110 logupload.merchantware.net
209.119.131.60 s01.merchantware.net

Overseas Data Centers

TSYS's products are presently only available in the North Amercian marketplace. As a security measure, we've restricted inbound traffic to IP addresses in the USA and Canada. If you attempt to access our services outside of these countries - or from known public VPNs - your traffic may be blocked. We understand many of our partners have overseas development and testing teams who will need need access to our payment gateway. In these cases, we request that you reach out to your Sales Engineer or Business Development Manager to whitelist your IP addresses.

+
What are the different types of tokens?

Tokens are a way to work with cards and transactions without actually having the card number. They can allow you to void transactions, repeat a sale, look up info, or save a card for later use.
However, there are a few different types of tokens you may encounter. Below are a list of the different kinds of tokens and what you can do with them.

Transaction Reference Number (Transaction Token)

This is the token that is returned with any transaction. You may also see this refered to as the PN Reference Number (PNRef). These tokens open up a range of functionality such as voiding, refunding, and capturing.
Gateway accounts can also be grouped together for Reference Number sharing. This will allow a call from one account to utilize tokens from the other. For instance, if a customer bought something from Store A but went to return them item at Store B, Store B would be able to use the original sale token to run a refund, so long as the two locations were "grouped" with each other. This allows a business to provide a customer with a unified commerce experience between different store locations and any online stores they may have.

Reference Number Use: Merchantware 4.5

To make use of a Reference Number in the MerchantWare 4.5 API, you need to define the Source tag as PREVIOUSTRANSACTION and the Token tag as the Reference Number you want to use inside the PaymentData object of your transaction request.

Example Previous Transaction SOAP Request

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
   <soap:Body>
      <Refund xmlns="http://schemas.merchantwarehouse.com/merchantware/v45/">
         <Credentials>
            <MerchantName>Zero Inc</MerchantName>
            <MerchantSiteId>00000000</MerchantSiteId>
            <MerchantKey>00000-00000-00000-00000-00000</MerchantKey>
         </Credentials>
         <PaymentData>
            <Source>PreviousTransaction</Source>
            
            <!--Previous Transaction Field-->
            <Token>608957</Token>
         </PaymentData>
         <Request>
            <InvoiceNumber>1703</InvoiceNumber>
            <RegisterNumber>35</RegisterNumber>
            <MerchantTransactionId>165902</MerchantTransactionId>
            <CardAcceptorTerminalId>3</CardAcceptorTerminalId>
         </Request>
      </Refund>
   </soap:Body>
</soap:Envelope>

Below are the calls that use a Reference Number.
Method Description
 Capture Captures on a previous Authorization.
 Void Voids out a previous transaction. This is used when the transaction in question is still in the open batch.
 Refund Refunds the transaction.
 TransactionsByReference Retrieves transaction information for the token used.
 DetailedTransactionByReference  Retrieves detailed transaction information for the token used.
 VaultBoardCredit Uses a Reference Number to create a Vault Token.
For more information, see the MerchantWare 4.5 documentation.

Vault Token

The Vault is a way to store a card so it can be later used through the Vault Token generated, unlocking Card on File functionality for a business.

Vault Token Use: Merchantware 4.5

To make use of a Reference Number in the MerchantWare 4.5 API, you need to define the Source tag as VAULT and the Token tag as the Vault Token you want to use inside the PaymentData object of your transaction request.

Example Vault SOAP Request

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
   <soap:Body>
      <Sale xmlns="http://schemas.merchantwarehouse.com/merchantware/v45/">
         <Credentials>
            <MerchantName>Zero Inc</MerchantName>
            <MerchantSiteId>00000000</MerchantSiteId>
            <MerchantKey>00000-00000-00000-00000-00000</MerchantKey>
         </Credentials>
         <PaymentData>
            <Source>Vault</Source>
            
            <!--Vault Fields-->
            <VaultToken>1000000000002AVGMM7Z</VaultToken>
         </PaymentData>
         <Request>
            <Amount>1.83</Amount>
            <CashbackAmount>0.00</CashbackAmount>
            <SurchargeAmount>0.00</SurchargeAmount>
            <TaxAmount>0.00</TaxAmount>
            <InvoiceNumber>1559</InvoiceNumber>
            <PurchaseOrderNumber>17809</PurchaseOrderNumber>
            <CustomerCode>23</CustomerCode>
            <RegisterNumber>35</RegisterNumber>
            <MerchantTransactionId>166909</MerchantTransactionId>
            <CardAcceptorTerminalId>3</CardAcceptorTerminalId>
            <EnablePartialAuthorization>False</EnablePartialAuthorization>
            <ForceDuplicate>False</ForceDuplicate>
         </Request>
      </Sale>
   </soap:Body>
</soap:Envelope>

Below are the calls that use a Vault Token.
Feature Description
 BoardCredit Saves a swiped card into the Vault and returns a Vault Token to be used in future transactions.

 UpdateBoardedCard 

Updates the expiration date of a card stored in the Vault.
 Sale Uses a Vault Token to run a Sale.
 Refund Uses a Vault Token to run a Refund.
 Authorize Uses a Vault Token to run an Authorization.
 FindBoardedCard Returns the card info that is tied to a Vault Token.
 UnboardCard Removes a Vault Token and the associated card from the Vault.
For more information, see the MerchantWare 4.5 documentation.

One Time Use Genius Checkout Token

The Genius Checkout Single Use Token functions a bit differently from the other token types. This token is not tied to a card number or a completed transaction, this token is tied to a transaction that has yet to be run. It is meant to be used only once to run the transaction it was created for, much like a Transport Key, and will expire in two minutes. While the format of a Checkout token will be the same as a Vault token, know that they are separate and will only function as per their actual source.

For more information, https://docs.cayan.com/e-commerce

+
What are the Genius Countertop's power requirements?
The Genius Countertop terminals can be powered either via AC current or via Power Over Ethernet (PoE). Included in the table below are representative power requirements that TSYS observed in its lab for Verifone V4 hardware models, as would be deployed in a P2PE environment. The power requirements measured between AC and PoE tended to be within 1W of each other. The MX925 series was observed to have higher Wattage requirements, as it has a larger screen than a MX915. Please note that using PoE with your Genius terminal requires a specialized I/O block, available from TSYS and Verifone. Please reach out to your Sales Engineer to ensure that you receive the necessary equipment.
 
Terminal model boot  idle transactions
mx915 2-3W 2-3W 4-7W
mx925 3-4W 3-4W 6-9W

Power over Ethernet or PoE describes any of several standardized or ad-hoc systems which pass electric power along with data on twisted pair Ethernet cabling. This allows a single cable to provide both data connection and electric power to devices such as wireless access points, IP cameras, and VoIP phones.
 
The original IEEE 802.3af-2003 PoE standard provides up to 15.4 W of DC power (minimum 44 V DC and 350 mA) on each port. Only 12.95 W is assured to be available at the powered device as some power dissipates in the cable. The updated IEEE 802.3at-2009 PoE standard also known as PoE+ or PoE plus, provides up to 25.5 W of power for "Type 2" devices. The 2009 standard prohibits a powered device from using all four pairs for power. Both of these amendments have since been incorporated into the IEEE 802.3-2012 publication.
 
Employing Power over Ethernet brings several advantages to an installation:
  • Time and cost savings - by reducing the time and expense of having electrical power cabling installed.  Network cables do not require a qualified electrician to fit them, and can be located anywhere.
  • Flexibility - without being tethered to an electrical outlet, devices such as IP cameras and wireless access points can be located wherever they are needed most, and repositioned easily if required.
  • Safety - POE delivery is intelligent, and designed to protect network equipment from overload, underpowering, or incorrect installation.
  • Reliability - POE power comes from a central and universally compatible source, rather than a collection of distributed wall adapters.  It can be backed-up by an uninterruptible power supply, or controlled to easily disable or reset devices.
  • Scalability - having power available on the network means that installation and distribution of network connections is simple and effective.
If your environment provides insufficient power to the payment terminals, you may notice anomalous behavior, such as the terminals unexpectedly rebooting. TSYS recommends that all network engineers employ the following best practices when deploying payment terminals in a PoE environment:
  • Provide sufficient power to the remote powered device. This may sound simple, but in practice, it is difficult. The IEEE 802.3af standard identifies four possible power classifications. At maximum, the powered remote device can draw up to 12.95 watts of power. Factoring loss through the length of the cable, this means that, at maximum, the power-sourcing equipment must have the ability to provide 15.4 watts of power to each port. In a 24-port Ethernet switch or midspan device, this means that approximately 370 watts of power must be available to supply the necessary power to each port. For the Ethernet switches, additional power above and beyond that required for PoE must be available for its switching functions.
  • Provide sufficient power to the remote powered device – by ensuring that they’re plugged into the right ports. Many switches will offer several “tiers” of power to PoE devices – for example, they may offer both 4W ports and 15.4W ports. Many smaller devices (eg. web cameras or microphones/speakers) have lower power requirements than payment terminals. Ensure that your payment terminals are plugged into ports that support the power requirements outlined above.
  • Connect the power source to uninterruptible and redundant power. The remote devices fed by PoE typically are mission-critical devices. For instance, an IP phone that loses power is a lost voice circuit. Think about that for a moment. Regardless of whether it is a traditional circuit-switched analog phone or an IP phone, it is a lifeline circuit. It has to work. You must consider how you are going to design your network to ensure that consistent and reliable data transfer and power are maintained to this critical device. Connect the critical power-sourcing devices to an uninterruptible power supply, and use devices with dual redundant power supplies to ensure that your critical devices never lose power.
  • Pay attention to cabling-performance specifications. What Category rating does your cabling infrastructure have? Most likely, this is Category 5e or 6.
  • Pay attention to cabling length. PoE will only power the unit so long as there is enough voltage to power the unit at the end of the cable run. The maximum distance you can power a device will vary depending on the access point and its voltage required, as well as the voltage provided by the power supply, and the quality of the cable. Cat6 cable is recommended for long POE runs. For passive POE you should use a 24V power supply. 24V passive POE will power an OM series AP up to about 50 meters or 100-150 feet. 48V 802.3af standard POE can usually go about 100 meters/300 feet.       
+
What are the Genius status call possible responses?

Status Check Possible Responses

Code Screen Screen Reference
00 Idle screen 01-Idle.png
01 Validating TransportKey 01-Validating-TransportKey.png
02 Main payment collection  Please-Remove-Card.png EMV-Card-Removed-Too-Early.png EMV-Problem-Reading-Card.png
03 Custom payment collection 03-Custom-Payment-Swipe.png   
04 Looking up card BIN Processing-(1).png
05 Waiting for amount confirmation  
06 Waiting for PIN entry 06-Waiting-for-PIN-Entry.png
07 Processing payment Processing.png EMV-processing-2.gif
08 Waiting for signature
09 Processing signature capture  
10 Transaction result  10-Transaction-Result-Declined.png
11 Cancel confirmation
12 Run as credit confirmation 12-Run-as-Credit-Cofirmation.png
13 SKU display 13-SKU-Display.png
14 Cashback selection screen 14-Cashback-Selection.png
15 Cashback custom screen 15-Cashback-Custom.png
16 Tip selection screen 16-Tip-Selection.png
17 Tip custom screen 17-Tip-Custom.png
18 Donation selection screen 18-Donation-Selection.png
19 Donation custom screen 19-Donation-Custom.png
20 Confirmation screen 20-Confirmation.png
24 Error screen  
26 SKU amount confirmation screen 26-SKU-Confirm-Transaction-Amount.png
27 PAN entry screen 27-PAN-Entry.png
28 Expiration entry screen 28-Expiration-Entry-Screen.png
29 CVV entry screen 29-CVV-Entry.png
30 Zip entry screen 30-Zip-Entry.png
31 Agreement screen 31-Agreement.png
32 Agreement signature screen 32-Agreement-Signature.png
33 EMV application selection screen 33-EMV-Application-Selection.png
35 Get customer input screen 35-Get-Customer-Input.png
36 Gift card capture screen 36-Gift-Card-Capture.png
38 Network details screen 38-Admin-Network-Details.png
39 Network configuration screen 39-admin-network-configuration.png
+
What causes the invalid serial number error on Genius?
As a security mechanism Genius CED devices are paired to merchant credentials using the device serial number. Because of this, production merchants will have devices configured to their account prior to shipment to the merchant location. Test devices used for integration will also be paired to your specific Genius test account.

If you are integrating to a physical device and receiving this error verify the credentials being used to perform the test transactions. If you are still experiencing difficulty contact the Certification Engineering team at the developer@cayan.com email address. 

If a device needs to be moved from one merchant account to another, please contact us at the partnersupport@cayan.com email address. 
+
What is PCI?
The PCI Security Standards Council is a global forum for the ongoing development, enhancement, storage, dissemination and implementation of security standards for account data protection.

PCI Security Standards are technical and operational requirements set by the PCI Security Standards Council (PCI SSC) to protect cardholder data. The standards apply to all entities that store, process or transmit cardholder data – with requirements for software developers and manufacturers of applications and devices used in those transactions. The Council is responsible for managing the security standards, while compliance with the PCI set of standards is enforced by the founding members of the Council, American Express, Discover Financial Services, JCB, MasterCard and Visa Inc.

The Payment Card Industry Data Security Standard (PCI DSS) is a set of security standards designed to ensure that ALL entities that accept, process, store or transmit credit card information maintain a secure environment. It covers technical and operational system components included in or connected to cardholder data. If you accept or process payment cards, PCI DSS applies to you.

For more information on PCI, the PCI SSC, and PCI DSS, please see:

  1. https://www.pcicomplianceguide.org/pci-faqs-2/
  2. https://www.pcisecuritystandards.org/
+
What is track data?

Financial cards

There are up to three tracks on magnetic cards known as tracks 1, 2, and 3. Track 3 is virtually unused by the major worldwide networks, and often isn't even physically present on the card by virtue of a narrower magnetic stripe. Point-of-sale card readers almost always read track 1, or track 2, and sometimes both, in case one track is unreadable. The minimum cardholder account information needed to complete a transaction is present on both tracks. Track 1 has a higher bit density (210 bits per inch vs. 75), is the only track that may contain alphabetic text, and hence is the only track that contains the cardholder's name.

Track 1 is written with code known as DEC SIXBIT plus odd parity. The information on track 1 on financial cards is contained in several formats: A, which is reserved for proprietary use of the card issuer, B, which is described below, C-M, which are reserved for use by ANSI Subcommittee X3B10 and N-Z, which are available for use by individual card issuers:

Track 1, Format B:

  • Start sentinel — one character (generally '%')
  • Format code="B" — one character (alpha only)
  • Primary account number (PAN) — up to 19 characters. Usually, but not always, matches the credit card number printed on the front of the card.
  • Field Separator — one character (generally '^')
  • Name — two to 26 characters
  • Field Separator — one character (generally '^')
  • Expiration date — four characters in the form YYMM.
  • Service code — three characters
  • Discretionary data — may include Pin Verification Key Indicator (PVKI, 1 character), PIN Verification Value (PVV, 4 characters), Card Verification Value or Card Verification Code (CVV or CVC, 3 characters)
  • End sentinel — one character (generally '?')
  • Longitudinal redundancy check (LRC) — it is one character and a validity character calculated from other data on the track.

Track 2: This format was developed by the banking industry (ABA). This track is written with a 5-bit scheme (4 data bits + 1 parity), which allows for sixteen possible characters, which are the numbers 0-9, plus the six characters  : ; < = > ? . The selection of six punctuation symbols may seem odd, but in fact the sixteen codes simply map to the ASCII range 0x30 through 0x3f, which defines ten digit characters plus those six symbols. The data format is as follows:

  • Start sentinel — one character (generally ';')
  • Primary account number (PAN) — up to 19 characters. Usually, but not always, matches the credit card number printed on the front of the card.
  • Separator — one char (generally '=')
  • Expiration date — four characters in the form YYMM.
  • Service code — three digits. The first digit specifies the interchange rules, the second specifies authorisation processing and the third specifies the range of services
  • Discretionary data — as in track one
  • End sentinel — one character (generally '?')
  • Longitudinal redundancy check (LRC) — it is one character and a validity character calculated from other data on the track. Most reader devices do not return this value when the card is swiped to the presentation layer, and use it only to verify the input internally to the reader.

Service code values common in financial cards:

First digit

1: International interchange OK

2: International interchange, use IC (chip) where feasible

5: National interchange only except under bilateral agreement

6: National interchange only except under bilateral agreement, use IC (chip) where feasible

7: No interchange except under bilateral agreement (closed loop)

9: Test

 

Second digit

0: Normal

2: Contact issuer via online means

4: Contact issuer via online means except under bilateral agreement

 

Third digit

0: No restrictions, PIN required

1: No restrictions

2: Goods and services only (no cash)

3: ATM only, PIN required

4: Cash only

5: Goods and services only (no cash), PIN required

6: No restrictions, use PIN where feasible

7: Goods and services only (no cash), use PIN where feasible

+
What requirements exist for printing receipts?

Knowing what to print on a merchant & customer receipt isn't a simple task - navigating the varying different requirements of the different card brands and issuing banks requires a lot of effort and detailed analysis. By following our best practice guide which collates the different requirements from the various card brands and issuing banks into an easy to follow matrix, you'll ensure that your merchants' receipts can be used as evidence in any chargeback process.

 

Magnetic Stripe & Keyed Transaction Receipt Requirements

Merchant DBA Name REQUIRED REQUIRED Uniquely identifies the merchant location TSYS
Merchant location REQUIRED REQUIRED Uniquely identifies the merchant location; Provide as much specificity as possible to distinguish the store (eg. city, state, zip, phone, store #, ...)

1 Federal Street, 2nd Floor

Boston, MA 02110

1.800.749.2173

Merchant ID REQUIRED REQUIRED Uniquely identifies the merchant location 123456789
Merchant Website REQUIRED REQUIRED Required for online & card not present transactions; optional otherwise www.tsys.com
Transaction date & time REQUIRED REQUIRED Time that the transaction happened Date: May 29, 2015 Time: 10:00 PM
Transaction Type REQUIRED REQUIRED retail sale, credit, debit, cash disbursement, refund, ... SALE
Description of products/services sold REQUIRED REQUIRED

A description and the price of each product and service purchased or returned, including applicable taxes, in detail sufficient to identify the Transaction.

If for whatever this is not possible, please consider including the Invoice Number and/or Purchase Order.

  • 1 x Genius Terminal: $4.00
  • 1 x Merchant Agreement: $6.00
Invoice Number RECOMMENDED RECOMMENDED Helps provide a description of products/services sold; identifies the transaction 00020091
Purchase Order OPTIONAL OPTIONAL Helps provide a description of products/services sold; identifies the transaction  
Transaction amounts REQUIRED REQUIRED

The total Transaction amount and Transaction currency. If no currency is identified on the Transaction receipt, the Transaction is deemed to have taken place in the currency that is legal tender at the POI.

Please include subtotal, taxes, and currency used.

Subtotal: $10.00

MA Sales Tax (6%): $0.60

Total: $10.60

Authorization/approval code REQUIRED REQUIRED The authorization number, if obtained from the Issuer 09926C
Card brand REQUIRED REQUIRED VISA, MASTERCARD, AMEX, DISCOVER, CHINA UNION PAY, ... VISA
PAN REQUIRED REQUIRED Masked - only show last 4 digits XXXXXXXXXXXX8887
Register Number RECOMMENDED RECOMMENDED   Register #1
Transaction ID RECOMMENDED RECOMMENDED   252994899
Entry Mode OPTIONAL OPTIONAL Keyed vs. Swiped vs. Proximity/NFC SWIPED
Cardholder's signature OPTIONAL REQUIRED

On at least the merchant copy, space for the Cardholder’s signatureunless:

  • No CVM was used - eg. a card not present transaction
  • A non-signature CVM is used - eg. PIN Debit
Cardholder signature: x_______________
Is this a merchant v/ cardholder copy REQUIRED REQUIRED Must appear near signature Cardholder Copy
Retain this copy... REQUIRED OPTIONAL On the Cardholder copy, the words (in English, local language, or both): “IMPORTANT— retain this copy for your records,” or words to similar effect  
Wording to the effect that "I agree to pay the above total..." OPTIONAL OPTIONAL Must appear near signature I agree to pay above total amount according to card issuer agreement (merchant agreement if credit voucher)
Refund/Return Policy (must appear near signature) REQUIRED RECOMMENDED Must appear near signature All sales are final. No refunds or exchanges.
Cardholder name REQUIRED REQUIRED Should appear near signature John Doe
PIN FORBIDDEN FORBIDDEN    
CVV/CVV2/CSC/CVM/CVC (card security codes/card validation methods) FORBIDDEN FORBIDDEN    
Expiration Date FORBIDDEN FORBIDDEN    
Requirement
Cardholder Receipt
Merchant Receipt
Comments
Example

Example MSR Receipts

Below are VISA's Transaction Receipt Requirements for Card-Present and Card-Absent Merchants.

 

EMV Receipt Requirements

The below receipt requirements for EMV transactions are in addition to the general MSR credit card receipt requirements outlined above. Importantly, EMV also requires that you print a receipt for a declined transaction.

Field Visa Master Card Discover American Express EMVCo
AID MUST INCLUDE MUST INCLUDE MUST INCLUDE MUST INCLUDE MUST INCLUDE
Application Label MUST INCLUDE (IF AVAILABLE) MUST INCLUDE (IF AVAILABLE) MUST INCLUDE (IF AVAILABLE) MUST INCLUDE (IF AVAILABLE) OPTIONAL
Application Expiry Date OPTIONAL OPTIONAL OPTIONAL OPTIONAL OPTIONAL
Application Effective Date OPTIONAL OPTIONAL OPTIONAL OPTIONAL OPTIONAL
Application Interchange Profile OPTIONAL OPTIONAL OPTIONAL OPTIONAL OPTIONAL
Application Version Number OPTIONAL OPTIONAL OPTIONAL OPTIONAL OPTIONAL
Application Transaction Counter OPTIONAL OPTIONAL OPTIONAL OPTIONAL OPTIONAL
Masked Pan OPTIONAL OPTIONAL OPTIONAL OPTIONAL OPTIONAL
Pan Squence Number OPTIONAL OPTIONAL OPTIONAL OPTIONAL OPTIONAL
Card Expiry Date MUST NOT INCLUDE MUST NOT INCLUDE MUST NOT INCLUDE MUST NOT INCLUDE MUST NOT INCLUDE
Cryptogram Type OPTIONAL OPTIONAL OPTIONAL RECOMENDED OPTIONAL
Cryptogram OPTIONAL OPTIONAL OPTIONAL RECOMENDED OPTIONAL
CVM Results OPTIONAL OPTIONAL OPTIONAL OPTIONAL OPTIONAL
Issuer Application Data OPTIONAL OPTIONAL OPTIONAL OPTIONAL OPTIONAL
Terminal Verification Results OPTIONAL OPTIONAL OPTIONAL OPTIONAL OPTIONAL
Unpredictable Number OPTIONAL OPTIONAL OPTIONAL OPTIONAL OPTIONAL
Amount Authorized OPTIONAL OPTIONAL OPTIONAL OPTIONAL OPTIONAL
Amount Other OPTIONAL OPTIONAL OPTIONAL OPTIONAL OPTIONAL
POS Entry Mode OPTIONAL OPTIONAL OPTIONAL OPTIONAL OPTIONAL
Termina Type OPTIONAL OPTIONAL OPTIONAL OPTIONAL OPTIONAL
Ifd Serial Number OPTIONAL OPTIONAL OPTIONAL OPTIONAL OPTIONAL
Terminal Country Code OPTIONAL OPTIONAL OPTIONAL OPTIONAL OPTIONAL
Transaction Type OPTIONAL OPTIONAL OPTIONAL OPTIONAL OPTIONAL
Transaction Currency Code OPTIONAL OPTIONAL OPTIONAL OPTIONAL OPTIONAL
Cryptogram Information Data OPTIONAL OPTIONAL OPTIONAL OPTIONAL OPTIONAL
PIN Statement MUST INCLUDE (IF AVAILABLE) MUST INCLUDE (IF AVAILABLE) MUST INCLUDE (IF AVAILABLE) MUST INCLUDE (IF AVAILABLE) MUST INCLUDE (IF AVAILABLE)
Cvm Method OPTIONAL OPTIONAL OPTIONAL OPTIONAL OPTIONAL

 


Example EMV Receipt

Demo-EMV-Receipt.JPG

What About TSYS's Electronic Receipts?

TSYS's Virtual Terminal portal provides electronic receipts that can be used to dispute a chargeback. These receipts meet the card brands' requirements for both MSR and EMV transactions. In the case of merchants using TSYS's Genius CED, these receipts contain a electronic signature and are retained for a period of 18 months. While TSYS provides an electronic copy of the receipt available to merchants, partners' points of sale are required to produce a compliant receipt for your merchants' cardholders.

For merchants who perform card-present transactions but do not use Genius and whose Point of Sale does not transmit a digitally captured signature to TSYS, these receipts will not have a digital signature, which is often used as part of the chargeback dispute & resolution process. TSYS recommends that these merchants retain a signed physical paper copy of their merchant receipt in their records for a period of 18 months.

Please reach out to the Certification Engineering team for any questions/comments related to upgrading your integration by contacting developer@cayan.com.

+
Which Windows POS Operating Systems are supported by PCI?
PCI requires that all systems used by parties processing Cardholder Data be patched and supported by their respective vendors. Merchants not using a supported Operating System will not be PCI compliant, and must update to a supported Operating System.

Below is a table of common POS Operating Systems released by Microsoft, and their respective support dates.
 
Operating System Support Status
Windows XP Support ended on April 8, 2014
Windows Server 2003 Support ended on July 14, 2015
Windows Embedded for Point of Service (WEPOS) Mainstream support ended on April 12, 2011
Extended support ended on April 12, 2016
Windows Vista Support ended on April 11, 2017
Windows Embedded POSReady 2009 Mainstream support ended on April 8, 2014
Extended support ends on April 9, 2019
Windows Server 2008 SP2 Support ends January 14, 2020
Windows 7 Extended support ends on January 14, 2020
Windows Embedded POSReady 7 Extended support ends on October 12, 2021
Windows Embedded 8 Industry Support ended on January 12, 2016; must install Windows Embedded 8.1 Industry in order to continue receiving updates and support
Windows Embedded 8.1 Industry Mainstream support ends on July 10, 2018
Extended support ends on July 11, 2023
Windows Server 2012 Support ends October 10, 2023
Windows 10 (IoT & Enterprise) Under Embedded name: Variable (some versions out of support), up to 2019 (mainstream) and 2023 (extended)
Under new IoT name: Mainstream support to at least 2020 and extended 2025
Windows Server 2016 Support ends January 11, 2027