Handler Details - File Format - Processing Methods

3. Processing Methods

3.8 File Format

3.8.14 Handler Details

Throughout the Developer‟s Guide, references have been made to “listeners” (or handlers), which are responsible for processing merchant orders and requests. This section lists the available handlers and describes what they do, as well as when and how they are used.

An HTTP Handler (also referred to as Listener) in the SENTRY world is essentially a web page. When loaded, it will read all the data contained in the HTTP request that it received, and will process the particular request as per the logic programmed into it.

The SENTRY PG handlers expect HTTP requests to be POSTed to them. The incoming requests have to include the various order fields as form fields.

The following fields are mandatory for all Handlers:

Name Value

Version 1.0.0

MerID Merchant Id (As given by your provider)

AcqID Acquirer Id (As given by your provider)

PurchaseAmt Purchase Amount

PurchaseCurrency Currency of the purchase amount. (ISO Numeric Value) PurchaseCurrencyExponent Purchase currency decimal digits.

OrderID Order Id that uniquely identifies the transaction is the Merchant System.

Signature Hashed Signature

Supported handlers are described below, along with usage scenarios and the extra fields that they expect.

3.8.14.1 DirectAuthLink

The DirectAuthLink can be used to process authorization requests without 3-D Secure. Being a Direct Link handler, it expects to receive all the necessary transaction information and card details (card number, expiry date, CVV2 if required). When it completes processing, it returns the basic response fields such as

CONFIDENTIAL AND PROPRIETARY © 2013, Total System Services, Inc. All rights reserved worldwide. Total System Services, Inc.® and TSYS are federally registered service marks of Total System Services, Inc., in the United States. Total System Services, Inc., owns a number of service marks that are registered in the United States and in other countries. All other products and company names are trademarks or registered trademarks of their respective companies.

Page 46 of 72 the response code, the auth. Code, among others. In order to process transactions through this Handler,

merchants need to include the following fields in addition to the mandatory Direct Link fields:

Name Value

CardNo The Card Number

CardExpDate The Card Expiry Date in MMYY format

CardCVV2 The card verification value is optional if allowed by your provider, or mandatory if required by your provider

3.8.14.2 DirectAuthztpLink

The DirectAuthztpLink can be used to process 3-D Secure authorization requests with 3-D Secure data collected outside of SENTRY PG before the order request is submitted, with a 3^rd party MPI. It works just like the DirectAuthLink but it expects the extra 3-D Secure data to be passed to it as well.

Name Value

CardNo The Card Number

CardExpDate The Card Expiry Date in MMYY format

CardCVV2 * The presence of card verification value is conditional, depending on the SENTRY provider‟s requirements

CAVVValue The CAVVValue is the Card Authentication and Verification Value generated by the cardholder‟s Issuer to prove that Authentication (or Attempt Authentication) occurred.

Depending on the status of the messages that MPI sends during the Authentication phase, the values in the table above might not exist. Also there are only a few combinations of the fields allowed since the rest are not valid. The following table explains the different possible combinations:

VISA ECI Mastercard ECI

AuthenticationResult Explanation

05 02 Y This means that the Authentication was

completed successfully since the card holder entered the correct password on the Issuer.

The CAVV and XID should be present in the order request.

06 01 A This means that the card was set up for

Attempt Authentication on the Issuer and no card holder‟s interaction was required. The CAVV and XID should be present in the order

Page 47 of 72

Secure Authentication but the card holder or the Issuer was not participating in the program (card or bin not enrolled). Since no PaReq was ever send then there is no CAVV

or XID available, and they should not be present in the request.

07 00 U This means that there was a problem

somewhere in the Authentication cycle and the MPI received an ECI value of 07/00. The CAVV and XID can be included depending on

where in the cycle the process failed and whether the MPI returned these values.

3.8.14.3 DirectAVSLink

Address Verification Service is used mainly in the US to verify the address information of the card holder as an additional verification measure before proceeding to the authorization. This handler can be used to perform AVS-only checks and depending on the response, a merchant can choose whether or not to proceed with authorization or not.

The DirectAVSLink is very similar to the DirectAuthLink handler, but instead of authorization it performs an Address Verification check. The main difference in the order request is that the merchant has to set the PurchaseAmt to 000000000000 and also include the Billing Address information (see Appendix A).

Please note that the Acquirer/Processor authorization host must support AVS functionality, otherwise this handler cannot be used.

Name Value

CardNo The Card Number

CardExpDate The Card Expiry Date in MMYY format

CardCVV2 * The presence of card verification value is conditional, depending on the SENTRY provider‟s requirements

3.8.14.4 DirectAuthzLink

The DirectAuthzLink can be used to process authorization requests with 3-D Secure Authentication using the SENTRY MPI. The handler can also be used to carry out only the 3-D Secure Authentication cycle (set AuthenticationOnly order field to “Y”). This Handler expects to receive the card‟s details, and unlike the Direct Authorization-Only handler, this handler expects to receive the MerRespURL value.

Name Value

CardNo The Card Number

CardExpDate The Card Expiry Date in MMYY format

Page 48 of 72

Name Value

CardCVV2 * The presence of card verification value is conditional, depending on the SENTRY provider‟s requirements

MerRespURL The merchant‟s response page where the SENTRY Payment Gateway will redirect the card holder after the transaction is completed.

3.8.14.5 RedirectLink

The Redirect Link can be used to process non-3DSecure Authorization requests, Authentication requests (3-D Secure) or a combination of both (full 3D-Secure Authorization), by using the SENTRY Checkout Page instead of the merchant‟s own checkout system. The merchant is not required to submit the card details in the order request; the card details will be supplied by the cardholder.

Name Value

MerRespURL The merchant‟s response page where the SENTRY Payment Gateway will redirect the card holder after the transaction is completed.

3.8.14.6 FinancialLink

The FinancialLink is a special Handler that can Capture, Refund or Reverse already submitted transactions. It was intended as an interface for merchants wishing to integrate with a pure HTTP-based API instead of the Store Front Web Services.

To choose between the actions to be performed on the transaction, merchants set the value of the

“Action” field. The Action field can be set to “Capture”, “Refund” or “Reverse”. There is also an extra field called “Amount” which is the amount of the action to be performed. Decimals are implicit for this field.

For example if a merchant wishes to refund $20 for a particular transaction, they can set the request‟s Action field equal to “Refund”, and the Amount field to “000000002000”.

Name Value

Action This is the action to perform on the transaction. Allowed values are

“Capture”, “Reverse” or “Refund”.

Amount This is the amount of the action to be performed on the transaction. It has the same 12 digit format as the Purchase Currency. Decimals are implicit

In document SENTRY Payment Gateway (Page 45-48)