Hosted Payments ID Tech Augusta KB EMV Overview

Document created by jeff.gross@vantiv.com on Mar 27, 2018Last modified by jeff.gross@vantiv.com on Nov 13, 2019
Version 7Show Document
  • View in full screen mode

Introduction

This document contains information on processing ID Tech Augusta KB device EMV transactions via the Hosted Payments solution on the Express payment platform.  Note that this device supports Credit Card transactions only (no PIN Debit).  The use of Cascading Style Sheets with Hosted Payments is also available, and details regarding this type of implementation are discussed later in this document.

 

The Augusta KB device can only be used with Express/Vantiv integrations at this time.  No other gateway processors are supported.

 

Hosted Payments Transaction Types Supported using ID Tech Augusta

 

Express Method

TransactionSetupMethod

CreditCardSale

1

CreditCardAuthorization

2

CreditCardForce

4

PaymentAccountCreate

7

PaymentAccountUpdate

8

 

Notes

    • Only Swiped and EMV Insert Credit Card transactions are supported.  Keyed and PIN Debit transactions are NOT supported.
    • Hosted Payments does not support unlinked refund transactions (i.e. CreditCardCredit) due to security risks involved with that transaction type.
    • Hosted Payments does not support Check/ACH processing because Check/ACH data does not fall under PCI scope.
    • The Hosted Payments page can be displayed in a number of different ways, including a full-page redirect, an iFrame, a popup, etc.
    • The Hosted Payments page can be displayed in an embedded or non-embedded format.  Refer to the TransactionSetup method in the interface specification for additional details.
    • If TransactionQuery (using the TransactionSetupID) is utilized to obtain additional transaction details immediately following a Hosted Payments transaction, please note that there may be more than one transaction associated with a single TransactionSetupID (such as both a Decline and Approval received during the single Hosted Payments session). Because of this, during the TransactionQuery, integrators should review the appropriate TransactionType and approval response to obtain transaction details regarding the successful Hosted Payments transaction.
    • Through the use of the Boolean AddressEditAllowed input parameter within the TransactionSetup method Address node (XML interface only), both the standard Hosted Payments page (Non-Embedded only) and the mobile Hosted Payments page (Non-Embedded only) can allow the individual entering the card information to edit the Billing Address details prior to submission to Express.  This is supported for card-present and card-not-present transactions, regardless of whether or not the Billing Address information is initially submitted in TransactionSetup.  Set AddressEditAllowed to “1” to allow users to edit the Billing Address details directly on the Hosted Payments page, and set AddressEditAllowed to “0” (or leave out entirely) if no Billing Address edits are allowed.
    • Because the Augusta KB device does not collect cardholder signatures, merchants should collect cardholder signatures (if applicable) in the same manner they are collected with any other non-signature capture device.

 

Helpful Links (basic Hosted Payments flow)

 

 

Hosted Payments ID Tech Augusta EMV Chip/Magstripe Reader Sample Flows

 

Single Sale Transaction using ID Tech Augusta EMV Chip/Magstripe Reader

  1. Your application collects the non-sensitive transaction details such as amount, transaction type, and address information where necessary, and submits a programmatic request using the TransactionSetup method in the interface specification (e.g. TransactionSetupMethod of 1/CreditCardSale for a single sale transaction).  When the Augusta reader is used, a TerminalCapabilityCode of 6 (ChipReader) should be included in the TransactionSetup request.  AutoReturn must be set to 1 (True) in all scenarios.
    • For EMV Insert, Swiped, or Keyed support in Hosted Payments:
      • Set TerminalCapabilityCode to 6 (ChipReader)
      • Set CardInputCode to 0 (UseDefault)
      • Set DeviceInputCode to 0 (NotUsed)
    • For only EMV Insert or Swiped support in Hosted Payments ("waiting for input" icon):
      • Set TerminalCapabilityCode to 6 (ChipReader)
      • Set CardInputCode to 0 (UseDefault)
      • Set DeviceInputCode to 2 (Terminal)
    • Note that Hosted Payments explicitly sets the CardInputCode value submitted to Express based on the entry mode used by the cardholder.
  2. Element responds with a TransactionSetupID (a GUID) if the request was successful.
  3. Your application performs a redirect (embedded browser control, full, popup, or iFrame, etc.) to our Hosted Payments URL and appends the TransactionSetupID to the end of that URL. For example, it might be: https://certtransaction.hostedpayments.com/?TransactionSetupID=INSERTHERE
  4. The end user inserts (if using an EMV chip card) or swipes (if using a non-EMV card) the card on the reader and the encrypted data output will flow into the Hosted Payments text box. If the EMV card cannot be read by the device, the Hosted Payments page will request the user to swipe the card. Once the insert or swipe data is parsed by Hosted Payments, the user can click the Submit button. Be aware that for any card-reader-in-progress timeout scenarios, the Augusta may take up to 30 seconds to provide a timeout response. When in a situation where the cardholder/merchant has unsuccessfully interacted with the reader, and they no longer wish to proceed, the Hosted Payments page should not be closed until the reader is back in an idle state.
  5. Element redirects the response details to the ReturnURL you originally provided in your initial TransactionSetup request from the first step (we append the response details in name/value pairs to the end of your ReturnURL). If using the embedded browser control, the Navigation URL in the object contains the response values that can be parsed. If the transaction was declined, pressing the Cancel Transaction button will redirect declined transaction details (and EMV tags) to the ReturnURL provided in the original TransactionSetup request.
  6. Your application receives the URL and parses out the response details, which you can then display on your own page/application. If processed as an EMV transaction, the EMV tags associated with the transaction will be included in the ReturnURL in a Tag/Length/Value (TLV) format to be parsed by the calling application for EMV receipt-printing purposes.

 

Use of Embedded and AutoReturn parameters with ID Tech Augusta

  • Integrators may use the Embedded (1) or Non-Embedded (0) option during the XML TransactionSetup request.
  • Integrators can ONLY use the AutoReturn option set to True (1) during the XML TransactionSetup request. An AutoReturn value set to False (0) will not support the return of EMV data.

 

ID Tech Augusta EMV Chip/Card Reader Troubleshooting

 

Input/Behavior

Insert LED

Small LED

Sound

Description/Meaning

N/A

N/A

Solid Blue

N/A

Device is idle and waiting for insert or swipe.

Insert Valid Chip Card

Solid Blue, then flashing Blue (success and remove card)

Solid Blue, then flashes Green, then flashing Blue (success and remove card)

2 short beeps, then continuous long beeps indicating card can be removed

EMV insert was successful.

Insert Invalid Chip Card

Flashing Blue

Flashing Red

Continuous short beeps

Device cannot read the inserted card.  Hosted Payments will display fallback message of “Unable to read input. Insert card again or swipe.”  Retry or fall back to swipe (within 30 seconds or timeout).

N/A

N/A

Flashing Green

N/A

Device is in EMV fallback mode.  Swipe card.

Insert Valid Chip Card

Solid Blue

Solid Blue

N/A

Chip card may have been removed too early.  Insert chip card again.  If the reader beeps twice and returns an error, retry the transaction.

Swipe

N/A

Flashes Red 3 times

1 beep

Device could not read the swipe attempt.  Retry.

Swipe Chip Card

Flashing Blue

Flashing Red

No beep

Chip card was swiped.  Please insert card instead (within 30 seconds or timeout).

Insert Invalid Chip Card

Flashing Blue back to N/A

Flashing Red back to Solid Blue

Long beep

Device cannot read chip card after 4 attempts.  Transaction is cancelled.  Retry using another card or fall back to swipe.

 

ID Tech Augusta EMV/Chip Card Reader ReturnURL Response Parameters

When the ID Tech Augusta reader is used to process an EMV transaction, the EMV tag information used for the transaction is returned in a Tag-Length-Value (TLV) format in the EmvData response field. To view an example of the parsing of TLV EMV tags, integrators can visit http://www.emvlab.org/tlvutils/. A full list of EMV tags is available at http://www.emvlab.org/emvtags/all/. Integrators must be able to parse this TLV format for the purpose of printing the necessary EMV tags on the cardholder transaction receipt (for both approvals and declines). Refer to EMV Tags-Augusta Receipt Printing Purposes.xlsx from Developer Integrations team for EMV tags to display on receipts.

 

Below is an example of a raw ReturnURL containing EMV tag data (with EMV Data parameter and tag data in red).

 

https://www.MerchantURLHere.com/?HostedPaymentStatus=Complete&TransactionSetupID=1E60AF21-7DCA-456C-BA86-6F5B2ED33A1F&TransactionID=2837242&ExpressResponseCode=0&ExpressResponseMessage=Approved&ApprovalNumber=607077&LastFour=1006&ValidationCode=A790D15C2D8F4C91&CardLogo=Amex&ApprovedAmount=1.00&Bin=374245&Entry=Chip&EmvData=4F08A0000000250108015004414D45589F12009F2608E9C92D9A31FB97CB8A025A339F0702FFC05F2A020840820254009F3602001B9F34033F00019F2701808408A0000000250108019F0D05FC50AC88009F0E0500000000009F0F05FC70BC98009F100706020103A081009F1A020840950542008080009A031801169B02E8009F21031436529C01009F3704E9E68F55

 

Additional Parsing Option (to be used only if ReturnURL data is corrupt/unavailable)

In the event that the EMV tag data returned in the ReturnURL query string value from Hosted Payments, the Express platform supports the ability to utilize the programmatic XML TransactionQuery method with the ReceiptEMVData input field set to 1 in the request (example request/response below).  Please note, though, that the ReceiptEMVData returned may not contain all necessary approval and/or decline EMV tags to be printed/displayed on cardholder receipts.

 

<TransactionQuery xmlns="https://reporting.elementexpress.com">
<Credentials>
<AccountID>INSERT</AccountID>
<AccountToken>INSERT</AccountToken>
<AcceptorID>INSERT</AcceptorID>
</Credentials>
<Application>
<ApplicationID>INSERT</ApplicationID>
<ApplicationName>INSERT</ApplicationName>
<ApplicationVersion>INSERT</ApplicationVersion>
</Application>
<Parameters>
<TransactionID>3976625</TransactionID>
</Parameters>
<ReceiptEMVData>1</ReceiptEMVData>
</TransactionQuery>

 

- <TransactionQueryResponse xmlns="https://reporting.elementexpress.com">
- <Response>
<ExpressResponseCode>0</ExpressResponseCode>
<ExpressResponseMessage>Success</ExpressResponseMessage>
<ExpressTransactionDate>20180326</ExpressTransactionDate>
<ExpressTransactionTime>130828</ExpressTransactionTime>
<ExpressTransactionTimezone>UTC-05:00:00</ExpressTransactionTimezone>
- <ReportingData>
- <Items>
- <Item>
<TransactionID>3976625</TransactionID>
<AcceptorID>123</AcceptorID>
<AccountID>1001182</AccountID>
<Name>Merchant Name</Name>
<TerminalID>01</TerminalID>
<ApplicationID>2</ApplicationID>
<ApprovalNumber>50365A</ApprovalNumber>
<ApprovedAmount>4.00</ApprovedAmount>
<ExpirationMonth>12</ExpirationMonth>
<ExpirationYear>22</ExpirationYear>
<ExpressResponseCode>0</ExpressResponseCode>
<ExpressResponseMessage>Approved</ExpressResponseMessage>
<HostBatchID>7118</HostBatchID>
<HostItemID>3</HostItemID>
<HostResponseCode>00</HostResponseCode>
<OriginalAuthorizedAmount>4.00</OriginalAuthorizedAmount>
<ReferenceNumber>A001</ReferenceNumber>
<TrackingID>D13BC5F4BC514B6B8D40E0D8651C03A3</TrackingID>
<TransactionAmount>4.00</TransactionAmount>
<TransactionStatus>Approved</TransactionStatus>
<TransactionStatusCode>1</TransactionStatusCode>
<TransactionType>CreditCardSale</TransactionType>
<CardNumberMasked>xxxx-xxxx-xxxx-0076</CardNumberMasked>
<CardLogo>Visa</CardLogo>
<CardType>Credit</CardType>
<TrackDataPresent>TRUE</TrackDataPresent>
<HostTransactionID>976625</HostTransactionID>
<ExpressTransactionDate>20180326</ExpressTransactionDate>
<ExpressTransactionTime>103222</ExpressTransactionTime>
<TimeStamp>2018-03-26T10:32:22.970</TimeStamp>
<IntegrationTypeID>1</IntegrationTypeID>
<BatchStatusCode>1</BatchStatusCode>
</Item>
</Items>
</ReportingData>
<ReportingID>21931362</ReportingID>
<ReceiptEMVData>4F08A0000000031010019F2608192D8377FA66F8DE9F2701809F34031E0300</ReceiptEMVData>
</Response>
</TransactionQueryResponse>

Attachments

    Outcomes