Merchant e-solutions Payment Gateway. Merchant e-solutions October 2013 Version 4.10

Transcription

1 Merchant e-solutions Payment Gateway Merchant e-solutions October 2013 Version 4.10

2 This publication is for information purposes only and its content does not represent a contract in any form. Furthermore, this publication shall not be deemed to be a warranty of any kind, either express or implied. Merchant e-solutions expressly disclaims, and you expressly waive, any and all warranties, including without limitation those of merchantability and fitness for a particular purpose. Merchant e-solutions reserves the right to alter product specifications without notice. No part of this publication may be reproduced or transmitted in any form or by any means, electronic or mechanical, including photocopy, recording, or any information storage or retrieval system, without Merchant e-solutions permission. MeS Payment Systems Merchant e-solutions 2013 MasterCard is a federally registered trademark of MasterCard International, Inc. Visa is a federally registered trademark of Visa, U.S.A., Inc. Discover Card is a federally registered trademark of Discover Financial Services Inc. American Express is a federally registered trademark of American Express Company. ZIP code and ZIP + 4 are federally registered trademarks of the United States Postal Service.

3 Table of Contents Chapter 1 Related Documentation... 4 Applicable documents Related documents Document revisions... 4 Chapter 2 Overview Introduction Settlement to Bank... 6 Chapter 3 Credit Card Processing Introduction Transaction Method Risk Management Tools Address Verification Service Cardholder Validation Commercial and Purchase Card Extended Data Dynamic Descriptors Store Card FraudDeflector Settlement Card Security Obligation Chapter 4 Back Office Chapter 5 Testing and Certification Roadmap Testing Certification Test Card Numbers Address Verification Testing CVV, CVC, CID Testing D Secure (Verified by Visa, MC Secure Code) Testing Amount Driven Response Testing PINNED Debit Testing American Express AAV (Cardholder , Name and Phone Number Verification) Partial Authorization and Balance Inquiry Testing Chapter 6 - Processing Interface Communication Protocol Batch Processing Security Chapter 7 - Request Field Definitions Request Fields FraudDeflector Recommended Required Fields FraudDeflector Field Definitions (Digital Goods) FraudDeflector Field Definitions (Physical Goods) Non-Card-Present Data Field Definitions Commercial and Purchase Card Extended Data Field Definitions Dynamic DBA Information Field Definitions Verified by Visa (when using a third party for verification) MasterCard Secure Code (when using a third party for verification) International Currency Field Definitions Recurring Payments-Installment PINNED Debit (online only) American Express Enhanced Address and Cardholder Verification Service American Express Enhanced Data Fields Hotel, Cruise, Auto Rental Enhance Data Fields Basic Request Sample Chapter 8 - Response Field Definitions Required Fields Payment Gateway Error Codes Merchant e-solutions, Inc. 1

4 8.3 Payvision International Error Codes Adyen International Error Codes Authorization Responses (as defined by Visa and MC) Merchant e-solutions Authorization Switch Error Codes AVS Response Codes CVV Response Codes Multi-Currency Code Table Chapter 9 Request/Response Samples Sales, Pre-Authorizations, Capture Transactions Sale Pre-Authorization Successful Capture Multi-Settle Re-Auth Refund, Credit, and Void Transactions Refund Resulting in a Credit Transaction Refund Resulting in a Voided Transaction Partial Refund Resulting in an Adjustment Partial Refund Resulting in a Credit Credit Void Store card Transactions Store card Immediate Sale Using Stored Card ID from Store card Sample Above Batch Close Batch Close Verification Only Verification Only Inquiry Inquiry Transaction Partial Authorization Sale with Partial Authorization Chapter 10 - Echo Fields Echo Field Examples Chapter 11 - Response Control Interface Usage Response Control Fields Response Field Values Chapter 12 FraudDeflector Introduction Transaction Flow FraudDeflector Request Fields Fingerprint Integration FraudDeflector Response Fields FraudDeflector Error Codes FraudDeflector Examples Sale with ACCEPT response Sale with DENY response Pre-Authorization with MANUAL_REVIEW response Chapter 13 Batch Processing Submitting a Request File Upload via MeS Web Portal Upload via API Requesting a Response File Retrieval via MeS Web Portal Retrieval via API Error Codes Merchant e-solutions, Inc. 2

5 13.4 Confirmation Chapter 14 Corporate Card Line Item Detail Processing Introduction Request Fields for Visa and MasterCard Level III Visa Line Item Subfields MasterCard Line Item Subfields Request Fields American Express American Express Line Item Subfields Level III Error Codes Sale (D) Source Code Example Settle (S) Source Code Example Merchant e-solutions, Inc. 3

6 Chapter 1 Related Documentation Applicable documents This document describes the request and response record formats for authorization devices using Merchant e-solutions (MES) Payment Gateway Application Programming Interface (API). The following documents provide additional definition and background information. Please refer to the related documents listed for applicable information. 1.2 Related documents Documentation and SDK libraries are located at: Document revisions Chapter Action Data 7 Add 8 Update 11 Update Added the Hotel, Cruise, Auto Rental addendum data, section 7.13 Added new gateway error codes for Hotel, Cruise, Auto Rental transactions table 8.2 Added response control fields to table 11.2 and commented on field for product level result code Merchant e-solutions, Inc. 4

7 Chapter 2 Overview 2.1 Introduction The Merchant e-solutions (MeS) Payment Gateway Application Programming Interface (API) utilizes the Internet to provide a simple and secure method of processing credit card payments. By sending an HTTPS POST with minimal transaction information to the payment gateway, a merchant can avoid the complex transmission protocols and message formats unique to the credit card payment industry networks. MeS not only simplifies the procedure, but manages the ongoing process of change resulting from credit card association requirement updates. Figure 2.1 The following graphic illustrates the process: Figure 2.1 Settlement to bank. Merchant s order entry system, online storefront, etc. uest. MeS Payment Gateway Credit Card Association Networks Settlement to Bank Merchant Bank 2013 Merchant e-solutions, Inc. 5

8 2.2 Settlement to Bank The MeS Payment Gateway accepts a request and returns a response, allowing a limited set of administrative actions. Each day, at a time chosen by the merchant, all transactions that have been approved are marked for capture and automatically settled. The settlement process results in funding to the merchant s bank account. The client is responsible for all development and security required to post the request and handle the response. This includes maintaining compliance with all PCI regulations. This document is intended to: Offer an overview of credit card processing, including transaction types and payment components that address risk management, Interchange qualification, and other information necessary to the payment process. Provide the specific technical information needed to submit a successful request and receive and interpret the resulting response. Outline the steps required to implement the MeS Payment Gateway API including testing and certification Merchant e-solutions, Inc. 6

9 Chapter 3 Credit Card Processing 3.1 Introduction A successful payment transaction consists of two elements: authorization and capture. The issuer of the credit card provides the authorization based on a number of factors including availability of credit and status of the account (card not reported stolen, for example). The response provided by the issuer includes an approval acknowledgement or a decline code, along with additional information such as billing address verification and/or cardholder validation value match results. When an approval is issued on a credit card transaction, that dollar amount is removed from the amount of available credit on that account for a given timeframe (determined by the issuing bank). Capturing a transaction, or marking an authorized transaction for capture, is required for that transaction to be settled, or submitted for final processing that results in a charge to the cardholder and a credit to the merchant. The distinction between authorization and capture exists to accommodate differing processing requirements. For example, some merchants may only need to do a single sale transaction in which an authorized transaction is automatically marked for capture. Another merchant may need to obtain an approval but, because an item might not be available for shipment that day, or the final billing amount might differ from the authorized amount, may not want the payment to be included with the next settlement. This latter merchant would want to handle the authorization and the capture in two steps. Best Practice: There should be a 1 to 1 relationship between an authorization and a settlement (capture). To settle an amount larger than the authorization a new authorization for the full amount should be requested, then void the original authorization to reverse the hold on funds. The only exception are industries that allow for a gratuity and are listed below. Best Practice: A settlement should occur within 7 calendar days of the authorization. If the delay is more than 7 days, the merchant should obtain a new authorization and void the original. Whether a transaction is authorized and captured all-at-once, or in sequential steps, is the result of the Transaction Type submitted in the authorization request. The MeS Payment Gateway API accepts the following Transaction Types: Transaction Type Description Comments Sale If the transaction receives an approval, it will be automatically marked for settlement at the same time. Pre-Authorization The transaction will be authorized but not marked for capture. To complete a Pre- Authorization, a Settle Pre-Authorization transaction must be performed to mark the transaction for capture. Once marked for capture, a transaction will be included in the next scheduled settlement batch. Settling a transaction seven days or more from the approval date will result in a downgrade to the Interchange levels, resulting in higher processing costs. Settling a transaction beyond seven days from the date of approval also increases the risk of a chargeback. No transaction should be settled more than twenty-eight days after the 2013 Merchant e-solutions, Inc. 7

10 Transaction Type Description Comments approval date. Settle Pre- Authorization Multi-Settle Re-Auth (of a declined transaction) Void A Settle Pre-Authorization marks the matching Pre-Authorization transaction for capture. Best Practice: There should be at least 15 seconds between a Pre-Authorization and a Settle Pre-Authorization request. This function is used by merchants that initially process a transaction but settle for less, want to process another sale but no longer have the card credentials. This is most typically used in a scenario where items are on back order. This function should NOT be used as a way to facilitate recurring billing. The store card function should be used for recurring. Multi-Settle transactions may not be submitted for transactions older than 30 days. Multi-Settle requires initial authorization and settlement to be written to the database to function properly. It is not intended for the user to send concurrent settlement requests. This transaction is typically used when a transaction is declined and the merchant no longer has the card account information (particularly the full account number) in order to resubmit the transaction. Declines older than 30 days may not be re-authorized. A Void request should only be processed for a Pre-Authorization transaction. Voiding a Sale should be done with a Refund transaction. Voiding a Pre- Authorization will initiate an auth-reversal. Best Practice: A Void transaction should be restricted to Pre-Authorization transactions. Once a Settlement has been If the settled amount is less than the original request a partial auth-reversal will be issued. Requests to settle amounts greater than the authorization will be ignored unless the merchant MCC allows for tip processing. These are: Restaurants Bars and Taverns Fast Food Restaurants Taxicabs & Limousines Hair Salons Health & Beauty Spas. Each new request is considered a new sale, therefore there is no cap on the amount of sale. All transactions are submitted with the transaction type S and the original transaction ID. Each new request will receive a new Transaction ID. This function is available for both USD and International, but not available for FX transactions. This function is not intended and should not be used for repeated authorization attempts. It is recommended that after a decline, the merchant either contact the customer for a recommended day to re-submit, or wait a few days prior to resubmission. This function is available for USD transactions only, full card numbers are not stored in MeS database when declined. A Void will generate an authreversal, which, depending on the bank, may release the amount held by the authorization Merchant e-solutions, Inc. 8

11 Transaction Type Description Comments performed on a Pre-Authorization it is best handled with a Refund transaction. Refund Credit Store card Delete Store card Offline Verification Only A Refund request looks for the Transaction ID of the originating transaction. If that transaction has not yet been settled, it will void the transaction from the batch. If that transaction has been settled, it will issue a credit transaction. Partial Refunds: To issue a partial refund, provide the transaction amount parameter in the request. Partial refund amount must be less than or equal to the original transaction amount. A refund to the cardholder. Best Practice: Whenever possible a refund should be processed rather than a credit. A refund is a safer transaction because it references a prior transaction and cannot exceed the amount of the original sale. Store card number. The transaction_id returned by the store request can be used in subsequent requests via the card_id parameter. The function will delete a transaction from the Gateway that was previously stored using the store card feature These transactions will be settled using the authorization code provided by the merchant in the request. This transaction is non-monetary in nature and is used to verify the card number and billing address of a cardholder. This service is most fully supported by Visa For American Express and Discover this service will validate address and zip only, The word "Void", "Adjustment" or "Credit" will be included in the response message to indicate the result of the action. Transactions may be refunded only once if submitted for the full amount of the original transaction. Multiple refunds are permitted for a single sale transaction up to but not over the original sale amount. A credit transaction does not attempt to match to a prior settled or unsettled transaction. A credit is a stand-alone transaction. The ability to do a credit must be enabled in the Merchant e- Solutions MeS profile. Enables user to safely store cardholder card number on MeS secured servers for processing future transactions. This can be performed independently or in conjunction with a pre-auth or sale transaction. Offline transactions typically result when an authorization attempt results in a Call response, or when authorization codes are obtained by phone because of a technical problem. Transactions submitted using this transaction code will be downgraded to lower Interchange levels. Offline transactions are not permitted for International transactions. For this transaction to be successful and reach the issuer for true validation both street address and zip code must be submitted. If no address information or zip only is submitted the response will 2013 Merchant e-solutions, Inc. 9

12 Transaction Type Description Comments it will not provide any status on the account (open, closed, etc). In addition, the card verification value is not validated. Inquiry Batch Close MasterCard supports an AVS only transaction with a zero amount and will verify only address match and not the status of the card. This function may be used to inquire about a previously submitted transaction. Typically used if the system times out and does not provide a response back to the originator. If found all original response fields will be returned, if the transaction is not located a message will be returned indicating it was not found. In addition, a retry_count will be included to indicate the number of inquiries on a particular transaction. Allows a user to initiate a batch close via the API. not be successfully processed. In addition, an amount of $0.00 should be submitted. Verification Only is not permitted for International transactions. This request is only valid within 48 hours of the original request. In order to use this function, a retry ID must be submitted with every transaction, this is the identifier used to perform this function. Primarily designed for POS applications that typically have a close function built in. Typically these will be POS terminals. In addition to transaction types, there are transaction elements that may need to be considered when processing transactions. 3.2 Transaction Method Transactions can be accepted in the following ways: Card-Present Non-Card-Present Mail/Telephone Order (MOTO) E-Commerce Transaction Recurring Billing The credit card associations require that a transaction be identified by the method of acceptance. This is done primarily through the moto_ecommerce_ind field, although there are additional field and security requirements that correspond with each acceptance method. A card-present transaction is one where the magnetic card stripe is read by an electronic device and sent with the authorization request. The cardholder is presented with a paper receipt to sign which the merchant retains, and is provided with a copy for their records. In the event that the card stripe is damaged and cannot be read, the transaction can be hand-keyed at the point-of-sale. A higher transaction fee may be incurred when a card-present transaction is hand-keyed. Card track data (data from the magnetic stripe read) can never be stored by a merchant Merchant e-solutions, Inc. 10

13 Non card-present MOTO indicators include: a onetime mail/telephone order (MOTO), a recurring transaction, and an installment payment. A recurring charge has no defined number of payments; an installment charge has a set number of charges, such as 7 payments of $ An e-commerce transaction is a sale that is conducted on the Internet. A secure transaction uses Secure Socket Layers (SSL) with encryption strength of at least 128-bit. No e-commerce transaction should ever be processed in a non-secure manner. Note: The MeS API defaults transactions with an e-commerce indicator of 7. Only transactions that fall into a different category need to include this indicator. 3.3 Risk Management Tools There are many tools available at the transaction level to help merchants manage risk and reduce fraud when accepting non face-to-face credit card transactions. These include standard tools such as Address Verification Service (AVS) and Cardholder Validation Code. In addition, use of optional fields like Dynamic Descriptors may reduce cardholder disputes that while not fraud related may improve overall processing. MeS also offers a comprehensive risk and fraud management system called FraudDeflector Address Verification Service Address Verification Service (AVS) is a tool to help merchants manage risk and reduce fraud when accepting non face-to-face credit card transactions. By submitting the cardholder s billing address and zip code at the time of authorization, a comparison is done against the billing information on file at the bank. A response is returned indicating a full (address and zip) match, an address-only partial match, a zip code-only partial match, or a response indicating AVS Results are not available (this could result from a number of factors including an AVS system outage, the issuing bank not participating, etc.). Best Practice: When initially accepting a card for payment, it is recommended to perform a verification only transaction to verify the billing address and zip. This is a non-monetary transaction that will not impact a customer s open to buy on their card. Performing AVS is a requirement with card-not-present transactions in order to qualify for the optimal Interchange rate. Authorization requests that do not include the cardholder s billing address and zip will cost more to process. While the credit card associations have mandated AVS be performed on non cardpresent transactions, there is no requirement based on result at this time. Deciding how to handle transactions that receive responses other than a full match is based on a merchant s own risk tolerance. The AVS result will not affect the transaction itself; if a transaction has received an approval, it will process accordingly regardless of the AVS result. Merchants who may not want to accept transactions with certain AVS results must take the appropriate action depending on the type of transaction: a Pre-Authorization transaction should not be converted to a Settle Pre-Authorization transaction until a merchant is comfortable with the AVS discrepancy; a Sale transaction may need to be Voided before the next scheduled settlement if the AVS result is deemed a significant risk Merchant e-solutions, Inc. 11

14 3.3.2 Cardholder Validation Card Validation Codes is another tool to help merchants manage risk and reduce fraud when accepting non face-to-face credit card transactions. Under the generic Card Validation Code, each card type has a unique name for the feature: Visa: Card Verification Value 2 (CVV2) MasterCard: Card Verification Code 2 (CVC2) American Express: Card Identification Data (CID) Discover: Card Identification Data (CID) The Validation Code is a three-digit number that appears on the signature panel of Visa, MasterCard and Discover cards. It usually appears on the back of the credit card, after the account number printed on the signature panel. With America Express cards, it is a four-digit number that appears above and at the end of the embossed card number on the front of the card. Submitting the Card Verification Code is not required by the credit card associations at this time. Deciding whether or not to submit the Card Verification Code should be a decision made by the merchant based on their own risk tolerance. The Card Verification Code result, in most cases, will not affect the transaction itself; if a transaction has received an approval, it will process accordingly regardless of the Card Verification Code result. There are a few card issuing banks that will decline a transaction based on a No Match Validation Code response. Merchants who may not want to accept transactions with certain Card Verification Code results must take the appropriate action depending on the type of transaction: a Pre- Authorization transaction should not be converted to a Settle Pre-Authorization transaction until a merchant is comfortable with the Card Verification Code discrepancy; a Sale transaction may need to be Voided before the next scheduled settlement if the Card Verification Code result is deemed a significant risk. Card Verification Codes can never be saved by a merchant after a transaction has been authorized Commercial and Purchase Card Extended Data Commercial Cards and Level 2 Purchase Cards require additional or extended data as a part of the transaction. This data is included when the transaction is settled, and is used by the card issuing bank to provide enhanced reporting to their cardholders. Commercial and Level 2 Purchase Cards that are submitted do not include the additional required fields may result in a processing fee that is higher than the normal cost for that card category. These fields may vary based on category and card type, but usually consist of one or more of the following: Purchase Order Number (sometimes called Customer Code), Tax Amount, and/or Tax Indicator. If the appropriate extended data is not provided for these specific cards, the MeS Payment Gateway will add those fields at the time of settlement. MeS will not overwrite any data submitted by the merchant in the authorization request Merchant e-solutions, Inc. 12

15 3.3.4 Dynamic Descriptors In the event that a merchant needs to process some transactions with Doing Business As (DBA) information different than the information on their merchant account, this information can be included in the request message. Data in these fields will override the profile DBA data. Users of this feature must comply with association regulations. The first 3, 7, or 12 digits must be static followed by an *. The remaining available characters may be unique. In order to use this feature Payment Gateway Certification for Dynamic DBA must be completed. The merchant profile will need to be enabled for this feature, and the static prefix for the descriptor will be preset in the merchant profile. An example of a full Dynamic Descriptor is provided in section Store Card A request can be made to store cardholder data. This allows a merchant to process transactions with the cardholder information at a later time by using an assigned transaction ID, eliminating the need to store sensitive cardholder data. Store card may be requested as an independent transaction or performed during a pre-authorization or sale request FraudDeflector The MeS FraudDeflector is an additional service offered to merchant s using the MeS Payment Gateway for processing. In addition to basic velocity checks, white and black lists, the MeS FraudDeflector offers many external checks such as IP addresses and country of issue. Merchants that required detailed fraud analysis are encouraged to sign up for this integrated service Settlement Settlement happens automatically. If a transaction has been approved and marked for capture, it will be included in the next settlement batch. Once a batch has settled, nothing else (such as a void) can be done to that specific transaction. The cut off time should be considered in regard to: Completion of necessary actions such as corrections (Credits, Voids) or follow-up actions (submitting an Offline transaction, converting a Pre-Authorization transaction to a Settle Pre-Authorization transaction) that needs to be included in the current batch. Reconciliation of bank deposits. The default batch close time is set to 09:00 pm PT but is configurable via the Payment Gateway Back Office Administration. Batch close times set between 09:00 pm PT and 12:00 am PT are not guaranteed to process in that same day s cycle Card Security Obligation Compliance with Payment Card Industry (PCI) Data Security Standards (DSS) is required of all merchants and service providers. This applies to all payment channels, including retail (brick-and-mortar), mail/telephone order, and e-commerce. Merchants 2013 Merchant e-solutions, Inc. 13

16 Merchants that are not yet PCI certified will receive follow up from the Merchant e- Solutions PCI support team and will be provided tools and the assistance needed to comply with PCI requirements. All merchants should visit one or both of the following websites for comprehensive information on the responsibilities and requirements for PCI compliance. Third Party Resellers Resellers must be PA-DSS certified prior to issuance of a certification letter by Merchant e-solutions. If the reseller operates as both merchant and reseller they must comply with both PCI and PA-DSS requirements. Because a merchant must be compliant with PCI requirements, it is in their best interest to use software applications that follow best practices to facilitate this compliance, the PA-DSS guide will provide the guidance necessary to ensure applications and hardware meet these guidelines. Resellers may visit the following website for additional information: Merchant e-solutions, Inc. 14

17 Chapter 4 Back Office The Payment Gateway Back Office provides the following functionality to supplement the integrated processing: Home provides a snapshot of transactions pending settlement, total pre-authorizations, and one click access to the last settled batch. The back office home page also provides important updates and industry new bulletins. Administration allows the client to set the settlement time and designate transaction acceptance based on AVS and Cardholder Verification responses. Transaction processing is available for processing exception transactions manually when the integrated processing is not an option. The client may process all transaction types using a virtual terminal. Batch Management allows for the management of unsettled transactions (marking as settled or voiding), as well as the ability to view and print settled batches Merchant e-solutions, Inc. 15

18 5.1 Testing Chapter 5 Testing and Certification Roadmap In order to obtain an ID for testing, the certification request form must be submitted online at Upon receipt of a completed form, the test ID will be ed within 24 hours. The certification request form is located at: on=1 Merchant e-solutions will a document which contains important configuration information, including Profile ID, merchant key and URL. These ID s are set up for the test/certification environment only. Best Practice: It is important to use the test profile for testing to prevent billing for authorizations obtained during testing. MeS will bill for all authorizations obtained using a production profile even if the transactions are part of the testing cycle. The MeS Certification Servers are available 24 x 7 for unattended testing. The certification server is a replication of the Payment Gateway production servers and will support testing for all available functionality. These transactions will all be processed as test so there is no need to worry about live authorizations or potential settlement to a cardholder account. Test ID configuration will contain the following: TPG Development PID for (Client Name) PROPRIETARY SOFTWARE MERCHANT CONFIGURATION INFORMATION Certification DBA MeS PG Development TEST # Profile ID (unique profile id value) Merchant Key (unique key value) API Development URL Certification Once testing has been completed, a script will be provided that will test both record formats and interchange qualification. These scripts will be customized for the client based upon the record types identified on the Certification Request form. Once the certification scripts have been reviewed and approved by the MeS Certification team, a certification letter will be issued the Development Profile ID will be disabled. The Production Configuration will be provided after the certification letter has been issued and the client s merchant number has been configured for the MeS Payment Gateway. All transactions under this configuration will be live. It is important to remember when installing the production ID s that you ensure the URL is updated to route all requests to the MeS Production Servers Merchant e-solutions, Inc. 16

19 5.3 Test Card Numbers The authorization process in the test environment is simulated. Any card may be used without impacting the cardholder s account as all responses are from a simulated authorization system. MeS also suggests use of the test card numbers provided in the table below: Card Type Length Card Number Visa Visa MasterCard American Express Discover JCB The table below will generate as listed the commercial card response indicator for testing Business to Business transaction: Card Type Card Number Commercial Card Response Indicator Visa B - Business Card MasterCard B - Business Card MasterCard S - Purchasing Card Visa R - Corporate Card MasterCard R - Corporate Card 5.4 Address Verification Testing The card associations have developed Address Verification as a tool to assist a merchant in processing a transaction based on information submitted that is compared to the credit card billing address. In order to test the variety of possible responses, the table below can be used. Defined input values will result in responses as described: Street Address Zip Code AVS Result Code Y street and postal code match Y street and postal code match (Visa) X street and postal code match (MasterCard) 123 EH8 9ST D - exact match, international 123 Other Zip A - address match, zip mismatch 234 Any Zip U - address unavailable 345 Any Zip G - verification unavailable due to international issuer nonparticipation (Visa and MasterCard only) 456 Any Zip R - issuer system unavailable, retry 235 Any Zip S AVS not supported Other Address Z - address mismatch, 5-digit zip match Other Address EH8 9ST Z - address mismatch, international zip match 2013 Merchant e-solutions, Inc. 17

20 Street Address Zip Code AVS Result Code Z- address mismatch, zip match (Visa) Other Address W- address mismatch, zip match (MasterCard) Other Address Other Zip N - address and zip mismatch 5.5 CVV, CVC, CID Testing This table will test CVV, CVC, and CID which is the 3 or 4 digit code printed on the back of a card. This security feature assists merchants processing in a Card Not Present environment and receiving a positive response ensures the likely hood that the cardholder making the purchase is in physical possession of the card. Visa, MC, and Discover encode a 3 digit value on the cards and American Express encodes either a 3 or 4 digit value. Defined input values will result in responses as described: CVV / CVC Value Result Code 123 M-Match 234 P-Not Processed 345 U-Issuer is not certified else N-No Match This table will test American Express CID: CID Value Result Code 1234 M-match (this response is generated when the CID flag is enabled on the MeS Profile ID) 2345 P-not processed (this response is generated when the CID flag is enabled on the MeS Profile ID) **** (any value other than 1234 or 2345) N-no match (with a response code of 000) (this response is generated when the CID flag is enabled on the MeS Profile ID) 5.6 3D Secure (Verified by Visa, MC Secure Code) Testing This table provides the values and the respective response used in our Certification environment for testing Verified by Visa, the test system will not edit the XID field so we recommend for testing that you submit the same value in XID that is submitted in the CAVV field (note: when in production Visa will return unique values for each field). MOTO Indicator CAVV Result 5 ERERERERERERERERERERERERERE= Error code = MjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMg== Error code = 000 not 5 any value Error code = 000 This table provides the values and the respective response used in our Certification environment for testing MasterCard Secure Code, the test system will not edit the ucaf_auth_data field so we recommend for testing that you submit: ERERERERERERERERERERERERERE= MOTO Indicator UCAF Collection Indicator Result 5 2 Error code = Error code = Merchant e-solutions, Inc. 18

21 5.7 Amount Driven Response Testing In addition to testing for approval codes, this table will allow testing for a wide variety of potential response codes: Amount Response Code Auth response text Reason/Description Card OK For card verification testing, submit a transaction code=a "Call" refer to issuer "Call" refer to issuer - special condition "Hold-call" pick up card (no fraud) "Decline" do not honor "Hold-call" pick up card (fraud) "Card No. Error" invalid card number No Such Issuer Invalid card number "RE Enter" re-enter transaction "Hold-call" pick up card (fraud: lost card) "Hold-call" pick up card (fraud: stolen card) "Decline" insufficient funds "Expired Card" issuer indicates card is expired "Serv Not Allowed" Suspected Fraud transaction not permitted to cardholder Do not honor card Invalid Auth Invalid Authorization Life Cycle TA Can t Verify PIN "CT NOT ALLOWED" System is unable to validate the Pin # Merchant does not accept this type of card 5.8 PINNED Debit Testing Note: Pinned Debit will only work with PIN Pads that have been injected to work with the MeS Keys. Send PIN=1234 for an approved transaction. Any other PIN will be declined with response code '55' (Wrong PIN). The simulator also supports the following trigger inputs: Note: These will work with any card number 2013 Merchant e-solutions, Inc. 19

22 Encrypted PIN Block KSN Response Code 706E3CADE53F11CA Approval DDD Wrong PIN CCCCCCCCCCCCCCCC Encryption Error 5.9 American Express AAV (Cardholder , Name and Phone Number Verification) The following AAV or ITD values will cause the simulator to return a 'Y' response in the appropriate response field. Field Name Group Value Billing Street Address AAV 123 (only numeric part matters) Billing Postal Code AAV or Billing First Name AAV CHRIS Billing Last Name AAV FROST Billing Phone Number AAV Customer ITD CFFROST@ ADDRESS.COM Any other value will cause the simulator to return a 'N' response in the appropriate response field. If a given data element is not supplied the simulator will return a space Partial Authorization and Balance Inquiry Testing To obtain a partial authorization, submit any valid amount that will generate an approval and the simulator will return 1/3 of the requested amount. Balance Inquiry testing is not available for testing on the simulator but if requested and if the issuer provides a balance it will be returned in production. In order to validate the transaction processes include the balance inquiry request, the system will accept the request but a value will not be returned Merchant e-solutions, Inc. 20

23 Chapter 6 - Processing Interface 6.1 Communication Protocol The MeS TPG API supports Hypertext Transfer Protocol using Secure Sockets Layer (HTTPS). This provides a single-threaded process in which the originating server makes an HTTPS request to the TPG and waits for MeS to return an HTTPS response. Although HTTP is single-threaded, a single originating server can make multiple requests at once. 6.2 Batch Processing Large batches may be processed using the Payment Gateway. Sale transactions processed with a single Profile ID will run at a rate of approximately 7 transactions per second (420 per minute or 25,200 per hour). 6.3 Security HTTPS requests must be encrypted at 128-bit cipher strength. Upon receiving the HTTPS request, the MeS API identifies and authenticates the request through two required fields: the profile ID, which is a unique identifier assigned to each merchant, and a profile key, which is a password linked to that profile ID. Once authenticated, the MeS Gateway handles the transportation and storage of all cardholder data in accordance with Payment Card Industry (PCI) requirements Merchant e-solutions, Inc. 21

24 Chapter 7 - Request Field Definitions 7.1 Request Fields profile_id profile_key card_number Field Name Description Required Length Format Comments Identifies the source of the incoming request. Specifies the API password assigned to the specified profile identifier. Cardholder account number Yes 20 N Yes 32 A/N Yes 5-22 N Card number should be submitted with only numbers no dashes or spaces? card_exp_date Card expiration date Yes 4 N Submit as MMYY; if the month is single digit precede with a leading zero. If the card has expired and the expired date is submitted, and the moto_ecommerce_ind is set to a 2 or 3 (recurring), the Payment Gateway will submit 0000 as the expiration date in the authorization request. If processing International transactions in the cardholders native currency, submission of 0000 is not supported. card_swipe Contents of card track read by card-swipe device and passed to payment gateway. Yes (if processing cardpresent, card-swiped transaction). card_id Card Identifier Yes (if processing a transaction with stored cardholder data) The card_number, card_swipe and card_id parameters are mutually exclusive. Providing more than one in a single request will result in an error. The card_swipe parameter overrides moto_ecommerce_ind values. Swiped transactions are assumed to be cardholder present transactions. AVS and CVV2 data are not needed on card_swipe transactions; if provided, they will be ignored during the authorization request. The payment gateway supports full mag-stripe reads, track 1 and track 2 reads both with and without sentinels. If you are using the GET method, be sure to properly URL encode all track data character ID assigned during a previous store card request. The card_number, card_swipe and card_id parameters are mutually exclusive. Providing more than one in a single request will result in an error. transaction_amount Transaction amount Yes 12 N If processing via MeS International gateway, this amount should be in the foreign currency desired Merchant e-solutions, Inc. 22

25 Field Name Description Required Length Format Comments transaction_id Transaction Identifier Yes, for some Tran Types. See comments 32 A/N 32-character transaction id returned in the original authorization request. Required only for tran type=v,s,u Note:the same tran ID is returned when processing a settle from a pre-auth, otherwise the tran ID will be unique transaction_type Transaction type Yes 1 A D=Sale C=Credit (Domestic only) P=Pre-Auth J=Re-Auth (of a declined transaction) O=Offline (Domestic only) V-Void S=Settle Pre-Auth U=Refund (no multiples for International) T= Store card data. X=Delete Store card data A=Verification Only (Domestic only) I=Inquiry Z=Batch Close moto_ecommerce_ind Indicates the type of transaction. No, default is 7. 1 N Z=Not a Mail/Telephone Order Transaction. 1=One Time Mail/Telephone Order Transaction. 2=Recurring Mail/Telephone Order Transaction. 3=Installment Payment of a Mail/Telephone Order Transaction. 5=Secure Electronic Commerce Transaction (3D Authenticated) 6= Non-Authenticated Security Transaction at a 3-D Securecapable merchant, and merchant attempted to authenticate the cardholder using 3-D secure 7 =e-commerce Transaction. Third Party 3D Users: Verified By Visa EciFlag maps directly to this field. reference_number client_reference_number auth_code Reference number is assigned by the Payment Gateway Merchant defined number Authorization code obtained by means outside of the MeS API. This field should only be included when transaction type = Is assigned by the MeS Payment Gateway MC Secure Code, set value to 5 when the EciFlag is 2, set value to 6 when EciFlag=1 11 N This field is no longer available for a client to populate with data, however remains an option for merchants that implemented this field in prior versions. No 96 A/N Merchant defined reference number that may be used for cross reference and internal tracking. (the & sign and the = sign are not valid characters) Yes, only for Offline transactions. 6 A/N 2013 Merchant e-solutions, Inc. 23

26 Field Name Description Required Length Format Comments batch_number retry_id store_card cvv2 Offline. Used to specify the batch number to close Used to look up an Inquiry transaction Used to store (tokenize) a card during a pre-auth or sale CVV2/CID value from card. When present a CVV2/CID match request is made. Yes, only if using batch close feature Yes, only if implementin g the Inquiry transaction type 3 N Valid values are System edits for duplicate batches and will reject a batch submitted with the same batch number within 5 calendar days 16 A/N This is only required if the Inquiry transaction type is being deployed. Number must be unique per transaction within a 48 hour time period. No Boolean Boolean (Y, y, True) This field is used to store (tokenize) a card concurrent with a pre-authorization or sale transaction. The tokenized card ID will be returned in the response string in the card_id field. No 3-4 N This does require enablement on the MeS Payment Gateway to work properly. 7.2 FraudDeflector Recommended Required Fields Gathering additional data on all transaction requests is recommended in order to accumulate a processing history that will enable MeS to assist with fraud detection and management. A full list of all fraud fields and responses is available in Chapter FraudDeflector Field Definitions (Digital Goods) Field Name Description Required Length Format Comments cardholder_first_name cardholder_last_name ip_address cardholder_ cardholder_phone device_id Cardholders first name Cardholders last name Customer s Internet IP address Cardholders billing Cardholders billing phone number Device id generated by BlueCava or other vendor No 15 A No No 30 A 15 A/N/+ No Ex: customerabc@order.com 60 A/N/+ Special characters require URL encoding No Submit as: N 10 nnnnnnnnnn No Unlimited A/N See section 12.4 for details on acquiring the device_id FraudDeflector Field Definitions (Physical Goods) Field Name Description Required Length Format Comments cardholder_first_name cardholder_last_name Cardholders first name Cardholders last name No 15 A No 30 A 2013 Merchant e-solutions, Inc. 24

27 Field Name Description Required Length Format Comments ip_address cardholder_ cardholder_phone ship_to_first_name ship_to_last_name ship_to_address ship_to_zip device_id Customer s Internet IP address Cardholders billing Cardholders billing phone number First name where goods will be shipped Last name where goods will be shipped Address where goods will be shipped Postal Code where goods will be shipped Device id generated by BlueCava or other vendor No No No No No No No 15 A/N/+ 60 A/N/+ 10 N 15 A 30 A 50 A/N 9 A/N Ex: customerabc@order.com Special characters require URL encoding Submit as: nnnnnnnnnn No Unlimited A/N See section 12.4 for details on acquiring the device_id 7.3 Non-Card-Present Data Field Definitions Field Name Description Required Length Format Comments invoice_number cardholder_street_address cardholder_zip Cardholder address data. When present an AVS request is issued. Example: 123 Main St. Cardholder zip or postal code. When present an AVS request is issued. Example: or Yes, for preferred Interchange 17 A/N Defined by Visa as 0-9, a-z, A-Z or spaces. No special characters permitted. No Unlimited A/N/+ Special characters require URL encoding. Addresses longer than 19 characters will be truncated during authorization request. Yes, for preferred Interchange 5 or 9 AN Note: cardholder_zip is also a field used for card-present transactions when the magnetic strip fails to be read. Alpha Permitted for International Transactions, AVS currently supported internationally in Canada and UK only 7.4 Commercial and Purchase Card Extended Data Field Definitions Required to qualify for Commercial and Purchase Card interchange categories. Field Name Description Required Length Format Comments invoice_number tax_amount ship_to_zip Sales/Local Tax Amount Ship to zip or postal code. Yes, for preferred Interchange Yes, for preferred Interchange Yes, for preferred Interchange for level III processing 17 A/N Defined by Visa as 0-9, a-z, A-Z or spaces. No special characters permitted. 12 Decimal required. 5 or 9 A/N This field is only used when implementing Level III processing Merchant e-solutions, Inc. 25

28 7.5 Dynamic DBA Information Field Definitions Data in these fields will override the profile DBA data. The client must complete Payment Gateway Certification for this feature and provide a static prefix value of 3, 7, or 12 characters to be set in the merchant profile. If the merchant profile is not flagged to include this prefix the Merchant DBA value will be used. Field Name Description Required Length Format Comments merchant_name merchant_phone Dm_contact_info merchant_category_code DBA Name to appear on the cardholder statement. Customer Service phone number to be using in direct marketing extension data. URL or contact information that is not a phone number Merchant Category Code (SIC) to be used when settling this transaction. No 25 A/N/+ The only allowed special character is the * symbol. Must comply with Association regulations. First 3, 7, or 12 digits must be static followed by an *, then remaining 25 characters of the field may be unique (ex: HarleyD* Parts) No 10 N No dashes, special characters, etc. EX: No 13 AN No 4 N Consult Merchant e- Solutions for valid MCC code. 7.6 Verified by Visa (when using a third party for verification) Field Name Description Required Length Format Comments xid Verified By Visa Transaction ID Yes varies Base 64 This value comes from the XID field in the 3D response. cavv Verified By Visa CAVV Yes varies Base 64 This value comes from the CAVV field in the 3D response. 7.7 MasterCard Secure Code (when using a third party for verification) Field Name Description Required Length Format Comments ucaf_collection_ind MasterCard Secure Code Collection Indicator. Yes varies A/N Valid Values: 1 = Supported by the merchant, but UCAF data was not present. 2 = Both merchant and issuer are UCAF enabled ucaf_auth_data MasterCard Secure Code cardholder authentication data. 7.8 International Currency Field Definitions Cardinal Centinel Users: Use the value returned in the ECI Flag. Yes varies Base 64 Cardinal Centinel Users: Use the value returned in the CAVV. Field Name Description Required Length Format Comments currency_code 3-digit ISO 4217 currency code. For example, to process a request in Euros, the currency_code would No, default is N By default the API sets the currency code to 840 (US Dollars). This field is needed when using either 2013 Merchant e-solutions, Inc. 26

29 be submitted as 978. In this example, a transaction_amount of would be 36 Foreign Currency Exchange (FX) or International processing options. Refer to the Currency Code Table on the MeS resources site. Click on MeS FX Currency Code Table in the Reference Materials section. 7.9 Recurring Payments-Installment Field Name Description Required Length Format Comments recurring_pmt_num recurring_pmt_count The payment number of the current transaction. The total number of payments. Optional 2 N Modifies the cardholder statement message (see recurring_pmt_count) Note: moto_ecommerce_ind should be set to a 3 when using Installment Payment option Optional 2 N Modified cardholder statement by appending thestring"xx OF YY" to the DBA name. XX is the recurring_pmt_num and YY is the recurring_pmt_count. Note: moto_ecommerce_ind should be set to a 3 when using Installment Payment option 7.10 PINNED Debit (online only) Field Name Description Required Length Format Comments debit_pin_block debit_ksn Contains the DUKPT encrypted pin block from the pin pad device Contains the Key Serial Number (KSN). Yes A/N Only transaction type permitted for PINNED Debit is a Sale (D). To issue funds back to a cardholder a Credit as a credit card transaction may be issued, or issue cash or check Yes A/N Only transaction type permitted for PINNED Debit is a Sale (D). To issue funds back to a cardholder a Credit as a credit card transaction may be issued, or issue cash or check 7.11 American Express Enhanced Address and Cardholder Verification Service Enhanced cardholder verification should be paired with use of the Response Control Interface (RCT) in chapter 11. Use of the RCT to receive detailed validations for each field will further validate the cardholder is who they say they are. Enhanced authorization is not required and if just address and zip are submitted, the AVS response will be returned in the core response string. Field Name Description Required Length Format Comments cardholder_first_name Cardholders first name No 15 A cardholder_last_name Cardholders last name No 30 A cardholder_ Cardholders billing (on file with American Express) No 60 A/N/+ Ex: customerabc@order.com 2013 Merchant e-solutions, Inc. 27

30 cardholder_phone cardholder_street_address cardholder_zip Cardholders billing phone number First 20 characters of the cardholders billing address. No leading, trailing zeros permitted Cardholders billing postal code No 10 N No 19 A/N Yes 9 A/N Submit as: nnnnnnnnnn 5 or 9 digit zip for US addresses, International may be any format and A/N 7.12 American Express Enhanced Data Fields American Express enhanced data is OPTIONAL, and will be used by American Express to determine if the transaction will be approved or declined. Fields are optional and you may send all or just some fields. While these fields are designed to ensure the transaction is valid, it may also increase the number of declines from American Express. Field Name Description Required Length Format Comments ship_to_first_name First name where goods will be shipped No 15 A ship_to_last_name Ship_to_phone ship_to_address ship_to_zip dest_country_code ip_address Last name where goods will be shipped Phone number where goods will be shipped Address where goods will be shipped Postal Code where goods will be shipped 3 digit numeric country code where goods will be shipped Customer s Internet IP address No 30 A No 10 N No 50 A/N No 9 A/N No 3 N No 15 A/N/+ Cust_host_name Customer Hostname No 1-60 http_browser_type HTTP Browser Type A/N/+ No 1-60 A/N/+ Customer Ani Customer ANI No 15 A/N/+ Customer2Digits Customer II Digits No 2 A/N Format is nnnnnnnnnn; no special characters or extension numbers. Per Amex requirements, for international phone numbers, the furthest right 10 numeric digits will be sent 5 or 9 digit zip for US addresses, International may be any format and A/N Example: 840 (USA) or 124 (Canada), etc. Format is nnn.nnn.nnn.nnn Example: Name of the server that the customer is connected to. Example: PPD.QWEST.COM Customer s HTTP browser type. Example: EXPLORER/6.0~WINDO WS~VISTA note: ~ = character space ANI (Automatic Number Identification) specified phone number that customer used to place order with merchant. Example: Telephone companyprovide ANI ii (Information Identifier) coding digits associated with Customer 2013 Merchant e-solutions, Inc. 28

31 Field Name Description Required Length Format Comments Prod_sku ship_method Unique SKU (Stock Keeping Unit) inventory reference number of product Method goods were shipped No 15 A/N No 2 A/N ANI phone number that corresponds to call-type; e.g., cellular, government institution, etc. Example: 00 DIGITAL GIFTCARD or PHYSICALGIFTCARD or SKU of the highest valued item if purchase is not a gift card. If SKU exceeds 15 digits, send last 15 digits. Two-byte, shipment-type code: 01 = Same Day 02 = Overnight/Next Day 03 = Priority, 2-3 days 04 = Ground, 4 or more days 05 = Electronic Delivery 06-ZZ = Reserved for future use 7.13 Hotel, Cruise, Auto Rental Enhance Data Fields The following fields are required in addition to the basic transaction data to qualify transactions at preferred Interchange, and to send meaningful data to card issuers. Travel fields are only used if a transaction contains both a statement begin and a statement end date Field Name Description Required Length Format Comments statement_date_begin Date of hotel check in, cruise departure, start date for auto rental Yes 10 Date mm/dd/yyyy mm/dd/yyyy statement_date_end Requester_name name_of_place rate_daily no_show_ind Date of hotel check out, cruise end date, return date for auto rental Name of individual checking in/picking up Name of Hotel location, name of Cruise Ship, or name of Rental Agency Amount of daily rate for room, auto rental, or cruise. For cruise may be total amount of cruise if a daily rate does not apply A value of Y indicates a customer did not check in and the charge is for a no show Yes 10 Date Yes 38 A/N Yes 25 A/N Yes 12 N Yes 1 Y/N industry_code Identifies type of industry Yes 1 A/N Please note, if statement begin date and statement end date exceed 99 days the default calculated and sent to the card associations will be 99. This is due to field length limitations with the card assocations. Supported values: A (auto rental), D (direct marketing) Merchant e-solutions, Inc. 29

32 Field Name Description Required Length Format Comments H (hotel/cruise). Default is D. invoice_number Identifies folio for hotel, rental agreement number for auto, and primary tracking number for cruise Yes 17 A/N Defined by Visa as 0-9, a- z, A-Z or spaces. No special characters permitted Basic Request Sample Sale Request URL: POST /mes-api/tridentapi HTTP/1.1 Content-Type: application/x-www-form-urlencoded Cache-Control: no-cache Pragma: no-cache User-Agent: Java/1.7.0_21 Host: cert.merchante-solutions.com Accept: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2 Connection: keep-alive Content-Length: 578 profile_id= &profile_key=a7b8c9a7a7b8c9a7a7b8c9a7a7b8 C9A7&transaction_type=D&card_number= &card_exp_date=0409&tr ansaction_amount=.15&cardholder_street_address=920&cardholder_zip=99212&invoice _number=12345&tax_amount=0.01 Note: an extended set of request and response samples are available in Chapter 9 of this document Merchant e-solutions, Inc. 30

33 Chapter 8 - Response Field Definitions 8.1 Required Fields Field Name Description Required Length Format Comments transaction_id error_code auth_response_text Auth_code avs_result cvv2_result retry_count 3-character error code providing additional detail. Text message showing auth response. 6 digit approval code or response from issuer Result code for the AVS response. Only provided if AVS data was provided in the request. Result code for the CVV2/CID request. Only provided if the CVV2/CID value was provided in the request. Number of times a single transaction has been Inquired upon Yes for some Tran Types. See comments 32 A/N 32-character transaction id returned in the original authorization request. Required only for trantype=v,s,u Note:the same tran ID is returned when processing a settle from a pre-auth, otherwise the tran ID will be unique YES 3 or 4 A/N See error code table below. 4 digit codes for Payvision International Only. YES 64 A/N Special characters require URL encoding. YES 6 A/N YES 1 A/N YES 1 A/N YES 2 N Only returned if retry ID is sent with a transaction and is only returned with an Inquiry transaction. 8.2 Payment Gateway Error Codes Response Code 000 0xx Error Description No errors - Transaction Approved. (approved Verification Only will return a code of 085) Authorization request failed. xx = Authorization Response Code. Required Action Action determined by authorization host response code see MeS Authorization Responses. 101 Invalid Profile ID or Profile Key. Correct the profile ID and profile key, then resubmit. 102 Incomplete Request. Provide all required data. 103 Invoice Number Length Error. Reduce the invoice number length. 104 Reference Number Length Error. Reduce the reference number length. 105 AVS Address Length Error. Correct the AVS Address. 106 AVS Zip Length Error. Correct the AVS Zip. 107 Merchant Name Length Error. Reduce the merchant name length. 108 Merchant City Length Error. Reduce the city name length. 109 Merchant State Length Error. Provide a valid state. 110 Merchant Zip Length Error. Provide a valid 5 or 9 digit zip Merchant e-solutions, Inc. 31

34 Response Code 111 Error Description Merchant Category Code Length Error. Required Action Provide a valid MCC. 112 Merchant Phone Length Error. Provide a valid phone number. 113 Reference Number Must Be Numeric. Provide a valid number. 114 Missing Card Holder Account Data. Provide valid card data. 115 Invalid Card Number. Provide a valid card number. 116 Credits Not Allowed. Contact Merchant e-solutions to have credits enabled. 117 Card Type Not Accepted. Contact Merchant e-solutions to add the card type. 118 Currency Type Not Accepted. Contact Merchant e-solutions to add the currency type Retry ID length error. Must be 16 characters or less An invoice number is required for a 3D enrollment check MOTO/e-Commerce indicator length error. Non-USD offline transactions are not supported Retry request with a valid retry ID. Retry request with a purchase ID. Retry request with a valid indicator. Do not submit any International transactions with the Offline transaction code. 123 Client Reference Number length error Resubmit with appropriate length, maximum is Batch Number Required A batch number is required when submitted a transaction_type of Z 125 Invalid Batch Number Batch number must be between Invalid Industry Code Industry Code submitted conflicts with transaction data submitted. Example: D for direct marketing with hotel check in and check out data 201 Invalid Transaction ID. Correct the transaction ID, then resubmit. 202 Invalid Transaction Amount. Correct settlement amount to be less than or equal to the original authorization amount. 203 Void Failed. Failed to void transaction, retry void or issue credit. 204 Transaction Already Settled. Void failed because transaction has already settled, submit credit. 205 Transaction Already Voided. Void failed because transaction is already voided. 206 Transaction Already refunded. A refund has already been performed on the transaction. 207 Refund failed. Internal error. Retry refund. 208 Failed to receive a response from auth host. Retry request. 209 Invalid tax amount. Correct tax amount and retry request. 210 AVS result is declined by user. Correct AVS data and retry request. 211 CVV2 result is declined by user. Correct CVV2 data retry request Refund amount must be between zero and the original amount. Only sale transactions can be refunded. Only one type of card data allowed per request. Correct amount and retry request. Provide a valid transaction ID. Only use one of the following: * card_number * card_swipe * card_id. 215 Invalid Card ID. Provide a valid card ID Failed to load card data, retry request. Failed to store card data, retry request. Card ID parameter cannot be included in this type of transaction. Offline transactions requires an authorization code Retry request. Retry request. Remove the card_id parameter and resubmit. Provide authorization code 2013 Merchant e-solutions, Inc. 32

35 Response Code 220 Error Description Failed to delete card data, retry request Required Action Retry request 221 Invalid Card ID Provide a valid card ID 222 Card ID required Provide a valid card ID 223 Retry Request ID Lookup Failed Retry request 224 FX rate ID invalid. Provide a valid FX rate table ID 225 FX rate has expired. Update rate tables and retry request 226 FX rate lookup failed, retry request. Retry request with valid rate ID 227 FX rate ID required for foreign currency transactions. Provide a valid rate ID 228 Base and consumer amounts are inconsistent with the FX rate. Correct provided amounts 229 Failed to find currency code for the requested country code. Check country code and retry request 230 Failed to post transaction the FX service. Internal Only 231 FX amount in base currency is required. Provide the base amount 232 FX transactions not accepted for this account. Contact Merchant e-solutions 233 Request currency code must match Retry request with a currency code that matches the FX FX rate currency code currency code. 234 Pin debit transactions require track 2 swipe data. Verify track 2 data is sent with the request 235 Invalid pin debit transaction type. Only a sale (D) is supported 236 Non-USD pin debit transactions are PINNED Debit for USD transactions only not supported. 237 Batch Close Failed Please verify parameters are correct and re-submit 238 Quit Duplicate Batch The same batch number was submitted within 5 calendar days of another closed batch. Verify batch is not a duplicate and resubmit with a new batch number 239 Returned when an Inquiry message is sent and there is no transaction matching the submitted retry ID within 48 hours of the original transaction Failed to load declined auth data Failed to capture International transaction. Failed to void International transaction. Failed to refund International transaction. Validate the retry ID and resubmit if valid and within 48 hours of original request. If valid then code 239 means that transaction does not exist. System was unable to successfully locate data needed for a new authorization request (only when submitting re-auth or multisettle requests) Retry request. Retry request. Retry request. 303 Card Verify not supported. Retry request. 304 Failed to reverse International authorization. Retry request. 350 Adyen request refused Adyen is declining the transaction; refer to text response for details. Should indicated Refused details for decline Adyen threw an exception; refer to the text response for details. 351 Adyen request failed Should also contain a three digit Adyen error code listed in section Failed to capture Adyen transaction Retry request 353 Failed to refund Adyen transaction Retry request Transaction type not supported by Retry request 354 Adyen 355 Adyen credit failed Retry request 356 Adyen request failed Retry request 2013 Merchant e-solutions, Inc. 33

36 Response Code Error Description Required Action 357 Adyen void failed Retry request 400 VBV/MSC Enrollment Check Retry request. 401 VBV/MSC Verification Failed. Retry request Failed to load captured transaction data Multiple captures are not supported on FX transactions Statement begin date must be the same or before statement end date Duration between statement dates must be 99 days or less Retry request FX not supported for re-auth of declines 999 Internal Error. Retry request. Level III Error Codes Fraud Deflector Error Codes 8.3 Payvision International Error Codes Response Code Error Description 0 No errors Groups all errors related to the parameters sent. Groups all errors related to International. Groups all responses related to declines. Groups all responses related to referral transactions. Groups all errors related to the acquiring bank. Groups all errors regarding security issues Groups all unexpected errors Groups all codes different than 0 given by the business rules applied to the execution of an operation. (i.e. A rule preventing the execution of a refund because a manual refund is required will produce a result 6000.) 8.4 Adyen International Error Codes Required Action Text portion of response will contain a 2 digit error code that provides additional data to assist with resolution Text portion of response will contain a 2 digit error code that provides additional data to assist with resolution Text portion of response will contain a 2 digit error code that provides additional data to assist with resolution Text portion of response will contain a 2 digit error code that provides additional data to assist with resolution Text portion of response will contain a 2 digit error code that provides additional data to assist with resolution Text portion of response will contain a 2 digit error code that provides additional data to assist with resolution Text portion of response will contain a 2 digit error code that provides additional data to assist with resolution Text portion of response will contain a 2 digit error code that provides additional data to assist with resolution Adyen responses will be one of 4 types: Approval, Refused, Error, and Exception: Approvals will indicate Authorised in the text and include an approval code. Refused will contain in the approval field and Refused detail in the text field. MeS will return a 350 Payment Gateway error code for refused transactions. Ex: (Refused Refused). If the acquirer returns a numeric refusal code, MeS will send that code instead of a 350. Adyen uses several acquirers and they do not all use the same set of refusal messages so an accurate table cannot be provided. Generally a 000 response should be treated as an approval and any other value as a decline. Error and Exception transactions will indicate the error code in the table below and fault in the text of the response and MeS will return a 351 Payment Gateway error code. Ex: (validation 140 Invalid expirymonth[1..12]/expiryyear[>2000], or before now) 2013 Merchant e-solutions, Inc. 34

37 Error Code Fault Description 000 Unknown An unknown error occurred 010 Not allowed You are not allowed to perform this action 100 No amount specified There is no amount specified in the request 101 Invalid card number The specified card number is not valid 102 Unable to determine variant The system was not able to determine the variant of the card number 103 CVC is not the right length The length of the CVC code is not correct for the given card number 104 Billing address problem There was an error in the specified billing address fields 105 Invalid pares from issuer The specified pares from the issuer in the 3D secure authorisation request is not correct 107 Recurring is not enabled You are trying to use recurring, but it is not (yet) enabled for your account 108 Invalid bankaccount number The specified bankaccount number is not valid 109 Invalid variant The determined variant of the card is not valid 110 BankDetails missing No bank details specified 111 Invalid BankCountryCode specified The specified bankcountrycode is not valid (bank payment) 112 This bank country is not supported The specified bankcountrycode is not supported (bank payment) 117 Invalid billing addresss The specified billing address is not valid 125 Invalid recurring contract specified The specified recurring contract value is not valid 126 Bank Account or Bank Location Id The specified bank account or bank location Id is not valid or not valid or missing missing (elv payment) 127 Account holder missing No account holder specified 128 Card Holder Missing No card holder specified 129 Expiry Date Invalid The specified expiry data is not a valid date 137 Invalid amount specified The specified amount is invalid, or above the equivalent of 50, EUR. 138 Unsupported currency specified The specified currency is not supported 139 Recurring requires shopper and No shopper or shopperreference specified shopperreference 140 Invalid expirymonth[1..12] / The specified expiry month/year is not valid or in the past expiryyear[>2000], or before now 141 Invalid expirymonth[1..12] / The specified expiry month/year is not valid expiryyear[>2000] 142 Bank Name or Bank Location not valid or missing The specified bank name or bank location Id is not valid or missing (elv payment) 144 Invalid startmonth[1..12] / The specified start month/year is not valid or in the future startyear[>2000], or in the future 800 Contract not found The specified recurring contract could not be found 802 Invalid contract The specified recurring contract is not valid 803 PaymentDetail not found The specified paymentdetails could not be found 804 Failed to disable Unable to disable the specified recurring details 805 RecurringDetailReference not available for provided recurringcontract The specified recurringdetailreferece is not available for the specified recurring contract 901 Invalid Merchant Account The specified merchant account is not valid 902 Shouldn't have gotten here without a No request specified, or invalid namespace request! 903 Internal error An internal error occurred while processing the request 904 Unable To Process The request could not be processed 905 Payment details are not supported The specified payment details are not availble for the specified action 2013 Merchant e-solutions, Inc. 35

38 8.5 Authorization Responses (as defined by Visa and MC) Note: All American Express responses are mapped to Visa Response Codes. Discover requests/responses are routed via the Visa network. The Payment Gateway will always return a 3 digit response code, all responses below will be preceded by a zero. Visa Authorization Response Codes MasterCard Authorization Response Codes Code Definition Code Definition 00 Successful approval/completion or that V.I.P. PIN 00 Approved or completed successfully verification is valid 01 Refer to card issuer 01 Refer to card issuer 02 Refer to card issuer, special condition 03 Invalid merchant 03 Invalid merchant or service provider 04 Capture card 04 Pickup card 05 Do not honor 05 Do not honor 08 Honor with ID 06 Error 10 Partial Approval 07 Pickup card, special condition (other than 12 Invalid transaction lost/stolen card) 10 Partial Approval 13 Invalid amount 11 V.I.P. approval 14 Invalid card number 12 Invalid transaction 15 Invalid issuer 13 Invalid amount (currency conversion field overflow); or amount exceeds maximum for card program 30 Format error. This response may also be returned on a Verification only request when the transaction type is not supported by the issuer. 14 Invalid account number (no such number) 41 Lost card 15 No such issuer 43 Stolen card 19 Re-enter transaction 51 Insufficient funds/over credit limit 21 No action taken (unable to back out prior 54 Expired card transaction) 25 Unable to locate record in file, or account number 55 Invalid PIN is missing from the inquiry 28 File is temporarily unavailable 57 Transaction not permitted to issuer/cardholder. This response may also be returned on a Verification only request when the transaction type is not supported by the issuer. 39 No Credit Account 41 Pickup card (lost card) 58 Transaction not permitted to acquirer/terminal 43 Pickup card (stolen card) 61 Exceeds withdrawal amount limit 51 Insufficient funds 62 Restricted card 52 No checking account 63 Security violation 53 No savings account 65 Exceeds withdrawal count limit 54 Expired card 70 Contact Card Issuer 55 Incorrect PIN 71 PIN Not Changed 57 Transaction not permitted to cardholder 75 Allowable number of PIN tries exceeded 58 Transaction not allowed at terminal 76 Invalid/nonexistent "To Account" specified 59 Suspected fraud 77 Invalid/nonexistent "From Account" specified 61 Activity amount limit exceeded 78 Invalid/nonexistent account specified (general) 62 Restricted card (for example, in Country Exclusion 84 Invalid Authorization Life Cycle table) 63 Security violation 85 Not declined Valid for AVS only, Balance Inquiry, or SET cardholder certificate requests (Visa Only) 64 Transaction does not fulfill AML requirement 86 PIN Validation not possible 65 Activity count limit exceeded 87 Purchase Amount Only, No Cash Back Allowed 75 Allowable number of PIN-entry tries exceeded 88 Cryptographic failure 76 Unable to locate previous message (no match on Retrieval Reference number) 89 Unacceptable PIN-Transaction Declined-Retry 2013 Merchant e-solutions, Inc. 36

39 Visa Authorization Response Codes MasterCard Authorization Response Codes Code Definition Code Definition 77 Previous message located for a repeat or reversal, but repeat or reversal data are inconsistent with original message 78 "Blocked, first used" - The transaction is from a new cardholder, and the card has not been properly unblocked. 79 Already Reversed (by Switch) 80 Visa transactions: credit issuer unavailable. Private label and check acceptance: Invalid date 81 PIN cryptographic error found (error found by VIC security module during PIN decryption) 82 Negative CAM, dcvv, icvv, or CVV results 85 No reason to decline a request for account number verification, address verification, CVV2 verification, or a credit voucher or merchandise return 86 Cannot Verify PIN 89 Ineligible to receive financial position information (GIV) 91 Issuer unavailable or switch inoperative (STIP not applicable or available for this transaction) 92 Destination cannot be found for routing 93 Transaction cannot be completed; violation of law 94 Duplicate transmission. A transaction was submitted that contains values in the tracing data fields that duplicate the values in a previously submitted transaction. 96 System malfunction System malfunction or certain field error conditions B1 B2 N0 N3 N4 N5 N7 P2 P5 P6 R0 R1 R3 Q1 Z3 XA XD Surcharge amount not permitted on Visa cards (U.S. acquirers only) Surcharge amount not supported by debit network issuer. This code appears only in responses to: Applicable Pin Debit Gateway transactions EBT transactions Force STIP Cash service not available Cashback request exceeds issuer limit Ineligible for resubmission Decline for CVV2 failure Invalid biller information PIN Change/Unblock request declined Unsafe PIN Stop Payment Order Revocation of Authorization Order Revocation of All Authorizations Order Card Authentication failed Unable to go online; declined Forward to issuer Forward to issuer 91 Authorization System or issuer system inoperative 92 Unable to route transaction 94 Duplicate transmission detected 96 System error 8.6 Merchant e-solutions Authorization Switch Error Codes Note: Payment Gateway will always return a 3 digit response code, all responses below will be preceded by a zero. Response Code TA TB Response Text Cause Resolution CT NOT ALLOWED REENTER EXP DATE Merchant doesn't accept the transaction's card type. Invalid hand-keyed expiration date. Check if card type set up in MeS System, contact certification team Merchant should correct expiration date and reenter transaction Merchant e-solutions, Inc. 37

40 Response Code Response Text Cause Resolution TC RETRY BAD ADDR Invalid AVS address or zip data. TD TE REV NOT ALLOWED BAD MERCHANT KEY 03 Merch ID Error Card type doesn't allow reversals. Merchant key is required but not supplied or incorrect. profileid (merch+term+store) is unknown or the profiles is disabled 12 Invalid Trans unsupported transaction type 13 Amount Error 77 No Action Taken 14 Card No. Error 19 RE Enter transaction amount is 0 or too long reversal amount larger then original amount card number has unknown BIN or fails check digit edit Communication error with Visa or MC switches 97 System Error System Malfunction 06 Error 25 Message Format Error 06 Error NN General Transaction Error 57 Error Error AVS Response Codes Unsupported International Transaction Type Merchant does not accept International Merchant should correct AVS data and reenter transaction. No resolution. Authorization cannot be reversed. Merchant's software needs to send the correct merchant key. Check the MID being submitted with the one set up on the MeS system. Contact the MeS Certification Team. MeS Authorization switch doesn't accept the type of transaction specified by the Transaction Code Re-submit transaction with a valid amount No action to take, transaction may not qualify for best level of Interchange Re-try card number again, verify with merchant it is a valid card with proper logos for card types the merchants accept customer should retry A bug in the MeS Authorization switch, escalate to the MeS Certification Team Check the format of your message or contact the MeS Certification Team Note the error code (NN) and escalate to the MeS Certification Team Trident International only supports card not present authorizations (tran code=56) Contact the MeS Certification Team Result Code Response Message Visa MC Amex 0 Approved x x x Address A Match x x x B C D E F G I K L Address Match Service Unavailable Exact Match x UK Exact Match x x Ver Unavailable x Ver Unavailable x x x x x x x Response Definition Address verification was not requested. Address match only. Street Address Match for international transaction Postal Code not verified because of incompatible formats (Acquirer sent both street and Postal Code) Street address and Postal Code not verified for international transaction because of incompatible formats (Acquirer sent both street and Postal Code) Street address and postal code match for international transaction. AMEX only-card Member Name incorrect, Postal Code Matches. Card Member Name incorrect, Address and Postal Code match Street address and postal code match. Applies to U.K. only. AMEX only-card Member Name incorrect, Address Matches Non-US Issuer does not participate Address information not verified for international transaction Card Member name matches Card Member name and Postal Code match 2013 Merchant e-solutions, Inc. 38

41 Result Code M N O P R S U W X Y Z Response Message Visa MC Amex Exact Match No Match Postal Code Match Retry AVS not supported x x x x x x x x x x x x x Verification Unavailable x x x Domestic and International 9 digit zip match Domestic and International 9 digit zip and address match Exact Match Zip Match x x x x x x x x x Response Definition Street Address match for international transaction AMEX only-card Member Name, Address and Postal Code match No address or ZIP/postal code match Card Member Name and Address match Postal code match. Acquirer sent both postal code and street address, but street address not verified due to incompatible formats Issuer system unavailable, retry For Visa if present, may be replaced with U for domestic or G for International. MasterCard may not translate to another value. AMEX only-amex Merchant ID (SE#) not allowed AAV function Address unavailable For Visa this code is not applicable, if a W returned Visa will replace with a Z for U.S. cards only. AMEX Only-No, Card Member name, address and postal code are all incorrect If this code is present in a response from Visa it will be replaced with a Y for Domestic cards only. Exact match, street address and postal code match 5 digit zip match only 8.8 CVV Response Codes American Express CID must be enabled on the MeS profile for merchants using this service. Code Description CVV2/CVC2 /Discover CID Match. M CVV2/CVC2/Discover CID - No Match. N Not Processed. P Merchant has indicated that Verification Code is not present on card. S U Issuer is not certified and/or has not provided Visa encryption keys. 8.9 Multi-Currency Code Table American Express CID must be enabled on the MeS profile for merchants using this service. Code M Description CVV2/CVC2 /Discover CID Match Merchant e-solutions, Inc. 39

42 Chapter 9 Request/Response Samples 9.1 Sales, Pre-Authorizations, Capture Transactions Sale Required Request Fields Field Name Description Required Length Format Comments profile_id Identifies the source Yes 20 N of the incoming request. profile_key Specifies the API Yes 32 A/N password assigned to the specified profile identifier. card_number Cardholder account Yes 5-22 N number card_exp_date Card expiration date Yes 4 N Submit at MMYY; if the month is single digit precede with a leading zero. transaction_amount Transaction amount Yes 12 N transaction_type Transaction type Yes 1 A D=Sale invoice_number cardholder_street_address cardholder_zip Request: Cardholders address data. When present an AVS request is issued. Example: 123 Main St. Cardholder zip or postal code. POST /mes-api/tridentapi HTTP/1.1 Yes, for preferred Interchange 17 A/N Defined by Visa as 0-9, a-z, A-Z or spaces. No special characters permitted. No Unlimited A/N/+ Special characters require URL encoding. System can only send 19 numeric characters of the address field, will send first 19. Yes, for preferred Interchange Content-Type: application/x-www-form-urlencoded Cache-Control: no-cache Pragma: no-cache User-Agent: Java/1.7.0_21 Host: cert.merchante-solutions.com Accept: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2 Connection: keep-alive Content-Length: or 9 N When present an AVS request is issued. Example: or profile_id= &profile_key=gvqzgkxoteodzpzjzrorqqzoklaeqxjf&tra nsaction_type=d&cardholder_street_address=123+main&cardholder_zip=55555&transaction_ amount=1.00&card_number= &card_exp_date=1111&invoice_number= Response: transaction_id=8fc94e10b12130f4ab8a8ceeac40fc69&error_code=000&auth_response_text= Exact Match&avs_result=Y&cvv2_result=M&auth_code=T2067H 2013 Merchant e-solutions, Inc. 40

43 9.1.2 Pre-Authorization Required Request Fields Field Name Description Required Length Format Comments profile_id Identifies the source Yes 20 N of the incoming request. profile_key Specifies the API Yes 32 A/N password assigned to the specified profile identifier. card_number Cardholder account Yes 5-22 N number card_exp_date Card expiration date Yes 4 N Submit at MMYY, if the month is single digit precede with a leading zero. transaction_amount Transaction amount Yes 12 N transaction_type Transaction type Yes 1 A P=Pre-Auth invoice_number cardholder_street_address cardholder_zip Cardholders address data. When present an AVS request is issued. Example: 123 Main St. Cardholder zip or postal code. Request: POST /mes-api/tridentapi HTTP/1.1 Yes, for preferred Interchange 17 A/N Defined by Visa as 0-9, a-z, A-Z or spaces. No special characters permitted. No Unlimited A/N/+ Special characters require URL encoding. System can only send 19 numeric characters of the address field, will send first 19. Yes, for preferred Interchange Content-Type: application/x-www-form-urlencoded Cache-Control: no-cache Pragma: no-cache User-Agent: Java/1.7.0_21 Host: cert.merchante-solutions.com Accept: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2 Connection: keep-alive Content-Length: or 9 N When present an AVS request is issued. Example: or profile_id= &profile_key=gvqzgkxoteodzpzjzrorqqzoklaeqxjf&tra nsaction_type=p&cardholder_street_address=123+main&cardholder_zip=55555&transaction_a mount=1.00&card_number= &card_exp_date=1111&invoice_number= Response: transaction_id=6117bf65fc4f38b7bc0ca4cd46eed6d1&error_code=000&auth_response_text= Exact Match&avs_result=Y&cvv2_result=M&auth_code=T2067H Successful Capture Required Request Fields Field Name Description Required Length Format Comments profile_id Identifies the source of the incoming request. Yes 20 N 2013 Merchant e-solutions, Inc. 41

44 Field Name Description Required Length Format Comments profile_key Specifies the API Yes 32 A/N password assigned to the specified profile identifier. transaction_type Transaction type Yes 1 A S=Settle Pre-Auth transaction_id Transaction Identifier Yes 32 A/N 32-character transaction id returned in the original authorization request. transaction_amount Transaction amount Yes 12 N invoice_number No 17 A/N Required if not submitted with the pre-auth request Request: POST /mes-api/tridentapi HTTP/1.1 Content-Type: application/x-www-form-urlencoded Cache-Control: no-cache Pragma: no-cache User-Agent: Java/1.7.0_21 Host: cert.merchante-solutions.com Accept: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2 Connection: keep-alive Content-Length: 578 profile_id= &profile_key=gvqzgkxoteodzpzjzrorqqzoklaeqxjf&tra nsaction_type=s&transaction_amount=1.00&transaction_id=8fc94e10b12130f4ab8a8ceeac40f c69&invoice_number= Response: transaction_id=12f3befbd035371b9b82d e071&error_code=000&auth_response_text =Settle Request Accepted Multi-Settle Required Request Fields Note: all fields sent with the original request will be copied to the new request (invoice, AVS, Client Reference Number, etc). Note: Multi-Settle requires all prior transactions to be written to the database. It is not intended to send multiple settlement requests concurrently. Field Name Description Required Length Format Comments profile_id Identifies the source Yes 20 N Original profile_id must be used of the incoming request. profile_key Specifies the API Yes 32 A/N Original profile_key must be used password assigned to the specified profile identifier. transaction_type Transaction type Yes 1 A S=Settle Pre-Auth transaction_id Transaction Identifier Yes 32 A/N 32-character transaction id returned in the original authorization request. transaction_amount Transaction amount Yes 12 N 2013 Merchant e-solutions, Inc. 42

45 9.1.5 Re-Auth Required Request Fields Field Name Description Required Length Format Comments profile_id Identifies the source Yes 20 N of the incoming request. profile_key Specifies the API Yes 32 A/N password assigned to the specified profile identifier. transaction_type Transaction type Yes 1 A J=Re-Auth transaction_id Transaction Identifier Yes 32 A/N 32-character transaction id returned in the original authorization request. transaction_amount Transaction amount No 12 N Amount is not required, if not submitted then Re-Auth will be for the remaining amount of original transaction. May submit an amount up to but not to exceed the original amount. Request: POST /mes-api/tridentapi HTTP/1.1 Content-Type: application/x-www-form-urlencoded Cache-Control: no-cache Pragma: no-cache User-Agent: Java/1.7.0_21 Host: cert.merchante-solutions.com Accept: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2 Connection: keep-alive Content-Length: 578 profile_id= xxxxx000000xx&profile_key=xxxxxx&transaction_type=j&transaction_id=726 13b899e3937cfa33efa c7d Response: transaction_id=xxxxxx&error_code=000&auth_response_text=zip Match&avs_result=Z&auth_code=T Refund, Credit, and Void Transactions Refund Resulting in a Credit Transaction Required Request Fields Field Name Description Required Length Format Comments profile_id Identifies the source Yes 20 N of the incoming request. profile_key Specifies the API Yes 32 A/N password assigned to the specified profile identifier. transaction_type Transaction type Yes 1 A U=Refund 2013 Merchant e-solutions, Inc. 43

46 Field Name Description Required Length Format Comments transaction_id Transaction Identifier Yes 32 A/N 32-character transaction id returned in the original authorization request. Request: POST /mes-api/tridentapi HTTP/1.1 Content-Type: application/x-www-form-urlencoded Cache-Control: no-cache Pragma: no-cache User-Agent: Java/1.7.0_21 Host: cert.merchante-solutions.com Accept: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2 Connection: keep-alive Content-Length: 578 profile_id= &profile_key=gvqzgkxoteodzpzjzrorqqzoklaeqxjf&tra nsaction_type=u&transaction_id=91bb6394dd883153ad90af804c7a5ce2 Response: transaction_id=aee8b06f9d f9b b63d&error_code=000&auth_response_text =Refund Request Accepted - Credit Refund Resulting in a Voided Transaction Required Request Fields Field Name Description Required Length Format Comments profile_id Identifies the source Yes 20 N of the incoming request. profile_key Specifies the API Yes 32 A/N password assigned to the specified profile identifier. transaction_type Transaction type Yes 1 A U=Refund transaction_id Transaction Identifier Yes 32 A/N 32-character transaction id returned in the original authorization request. Request: POST /mes-api/tridentapi HTTP/1.1 Content-Type: application/x-www-form-urlencoded Cache-Control: no-cache Pragma: no-cache User-Agent: Java/1.7.0_21 Host: cert.merchante-solutions.com Accept: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2 Connection: keep-alive Content-Length: 578 profile_id= &profile_key=gvqzgkxoteodzpzjzrorqqzoklaeqxjf&tra nsaction_type=u&transaction_id=e4f49b483d833695a39b2787c65bbef Merchant e-solutions, Inc. 44

47 Response: transaction_id=7c0ab9ec96da370886a116fa a&error_code=000&auth_response_text = Refund Request Accepted - Void Partial Refund Resulting in an Adjustment Required Request Fields Field Name Description Required Length Format Comments profile_id Identifies the source Yes 20 N of the incoming request. profile_key Specifies the API Yes 32 A/N password assigned to the specified profile identifier. transaction_type Transaction type Yes 1 A U=Refund transaction_id Transaction Identifier Yes 32 A/N 32-character transaction id returned in the original authorization request. transaction_amount Transaction amount Yes 12 N Required when refund amount is less than original sale amount. Note: This sample assumes the original transaction was for $1.00. This is a partial refund of $0.60 and the result message shows the new amount (to be settled). Adjustments occur when partial refunds are issued against transactions pending settlement. Request: POST /mes-api/tridentapi HTTP/1.1 Content-Type: application/x-www-form-urlencoded Cache-Control: no-cache Pragma: no-cache User-Agent: Java/1.7.0_21 Host: cert.merchante-solutions.com Accept: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2 Connection: keep-alive Content-Length: 578 profile_id= &profile_key=gvqzgkxoteodzpzjzrorqqzoklaeqxjf&tra nsaction_type=u&transaction_amount=0.60&transaction_id=9f57b a198d51b6a5074f d916 Response: transaction_id=38356d5c a9b3e55920f5f9e8a&error_code=000&auth_response_text =Refund Request Accepted - Adjustment $ Partial Refund Resulting in a Credit Required Request Fields 2013 Merchant e-solutions, Inc. 45

48 Field Name Description Required Length Format Comments profile_id Identifies the source Yes 20 N of the incoming request. profile_key Specifies the API Yes 32 A/N password assigned to the specified profile identifier. transaction_type Transaction type Yes 1 A U=Refund transaction_id Transaction Identifier Yes 32 A/N 32-character transaction id returned in the original authorization request. transaction_amount Transaction amount Yes 12 N Required when refund amount is less than original sale amount. Note: This sample assumes the original transaction was for $1.00, and has already been settled. Request: POST /mes-api/tridentapi HTTP/1.1 Content-Type: application/x-www-form-urlencoded Cache-Control: no-cache Pragma: no-cache User-Agent: Java/1.7.0_21 Host: cert.merchante-solutions.com Accept: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2 Connection: keep-alive Content-Length: 578 profile_id= &profile_key=gvqzgkxoteodzpzjzrorqqzoklaeqxjf&tra nsaction_type=u&transaction_amount=0.60&transaction_id=9f57b a198d51b6a5074f d916 Response: transaction_id=55e31d892e3131c38dd7bba706c1aa00&error_code=000&auth_response_text= Refund Request Accepted - Credit $ Credit Note: In order for credits to function, they must be enabled on the profile by a Merchant e- Solutions representative. Required Request Fields Field Name Description Required Length Format Comments profile_id Identifies the source Yes 20 N of the incoming request. profile_key Specifies the API Yes 32 A/N password assigned to the specified profile identifier. card_number Cardholder account Yes 5-22 N number card_exp_date Card expiration date Yes 4 N Submit at MMYY, if the month is single digit precede with a leading zero. transaction_amount Transaction amount Yes 12 N 2013 Merchant e-solutions, Inc. 46

49 Field Name Description Required Length Format Comments transaction_type Transaction type Yes 1 A C=Credit Request: POST /mes-api/tridentapi HTTP/1.1 Content-Type: application/x-www-form-urlencoded Cache-Control: no-cache Pragma: no-cache User-Agent: Java/1.7.0_21 Host: cert.merchante-solutions.com Accept: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2 Connection: keep-alive Content-Length: 578 profile_id= &profile_key=gvqzgkxoteodzpzjzrorqqzoklaeqxjf&tra nsaction_type=c&transaction_amount=1.00&card_number= &card_exp_dat e=1111 Response: transaction_id=c005384e51eb37359b14c798590d25b0&error_code=000&auth_response_text =Credit Approved Void Required Request Fields Field Name Description Required Length Format Comments profile_id Identifies the source Yes 20 N of the incoming request. profile_key Specifies the API Yes 32 A/N password assigned to the specified profile identifier. transaction_type Transaction type Yes 1 A V=Void transaction_id Transaction Identifier Yes 32 A/N 32-character transaction id returned in the original authorization request. Request: POST /mes-api/tridentapi HTTP/1.1 Content-Type: application/x-www-form-urlencoded Cache-Control: no-cache Pragma: no-cache User-Agent: Java/1.7.0_21 Host: cert.merchante-solutions.com Accept: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2 Connection: keep-alive Content-Length: 578 profile_id= &profile_key=gvqzgkxoteodzpzjzrorqqzoklaeqxjf&tra nsaction_type=v&transaction_id=bd d69399f8879cedb427879e Merchant e-solutions, Inc. 47

50 Response: transaction_id=d3b aba05101ae3d35340&error_code=000&auth_response_tex t=void Request Accepted 9.3 Store card Transactions profile_id Store card profile_key Required Request Fields Field Name Description Required Length Format Comments Identifies the source of the incoming request. Specifies the API password assigned to the specified profile identifier. Yes 20 N Yes 32 A/N transaction_type Transaction type Yes 1 A T= Store card data. card_number Cardholder account number Yes 5-22 N If a store card message is sent twice with the same card number and profile ID/hierarchy, a 000 response will be returned with the existing card ID value card_exp_date Card expiration date No 4 N Storing the expiration date is not required but recommend if using the Account Updater service. Also generally recommended to take advantage of any future enhancements to the store card feature. Request: POST /mes-api/tridentapi HTTP/1.1 Content-Type: application/x-www-form-urlencoded Cache-Control: no-cache Pragma: no-cache User-Agent: Java/1.7.0_21 Host: cert.merchante-solutions.com Accept: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2 Connection: keep-alive Content-Length: 578 profile_id= &profile_key=gvqzgkxoteodzpzjzrorqqzoklaeqxjf&tra nsaction_type=t&card_number= Response: transaction_id=446650ab2a8b3df68390d170cbc0fa0a&error_code=000&auth_response_text =Card Data Stored 2013 Merchant e-solutions, Inc. 48

51 9.3.2 Immediate Sale Using Stored Card ID from Store card Sample Above Required Request Fields Field Name Description Required Length Format Comments profile_id Identifies the source Yes 20 N of the incoming request. profile_key Specifies the API Yes 32 A/N password assigned to the specified profile identifier. card_id Card Identifier Yes character ID assigned during a previous store card request. card_exp_date Card expiration date Yes 4 N Submit at MMYY, if the month is single digit precede with a leading zero. If the card has expired and the expired date is submitted, and the moto_ecommerce_ind is set to a 2 or 3 (recurring), the Payment Gateway will submit 0000 as the expiration date in the authorization request. transaction_amount Transaction amount Yes 12 N transaction_type Transaction type Yes 1 A D=Sale invoice_number cardholder_street_address cardholder_zip Cardholders address data. When present an AVS request is issued. Example: 123 Main St. Cardholder zip or postal code. Yes, for preferred Interchange No Yes, for preferred Interchange Request: POST /mes-api/tridentapi HTTP/ A/N Defined by Visa as 0-9, a-z, A-Z or spaces. No special characters permitted. Unlimite d A/N/+ Content-Type: application/x-www-form-urlencoded Cache-Control: no-cache Pragma: no-cache User-Agent: Java/1.7.0_21 Host: cert.merchante-solutions.com Accept: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2 Connection: keep-alive Content-Length: 578 Special characters require URL encoding. System can only send 19 characters of the address field, will send first or 9 N When present an AVS request is issued. Example: or profile_id= &profile_key=gvqzgkxoteodzpzjzrorqqzoklaeqxjf&tra nsaction_type=d&cardholder_street_address=123+main&cardholder_zip=55555&transaction_ amount=1.00&card_exp_date=1111&invoice_number=123456&card_id=446650ab2a8b3df683 90d170cbc0fa0a Response: transaction_id=51e8ea7ef94e3813a00b2a2331cd2679&error_code=000&auth_response_text =Exact Match&avs_result=Y&cvv2_result=M&auth_code=T7362H 2013 Merchant e-solutions, Inc. 49

52 9.4 Batch Close profile_id Batch Close profile_key Required Request Fields Field Name Description Required Length Format Comments Identifies the source of the incoming request. Specifies the API password assigned to the specified profile identifier. Yes 20 N Yes 32 A/N transaction_type Transaction type Yes 1 A Z=Batch Close Batch_number Used to specify the batch number to close Request: POST /mes-api/tridentapi HTTP/1.1 Yes 3 N Valid values are System edits for duplicate batches and will reject a batch submitted with the same batch number within 5 calendar days Content-Type: application/x-www-form-urlencoded Cache-Control: no-cache Pragma: no-cache User-Agent: Java/1.7.0_21 Host: cert.merchante-solutions.com Accept: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2 Connection: keep-alive Content-Length: 578 profile_id= &profile_key=gvqzgkxoteodzpzjzrorqqzoklaeqxjf&tra nsaction_type=z&batch_number=1 Response: transaction_id=932f3671fa9f34bc8e1517ebb427b269&error_code=000&auth_response_text= Batch Closed 9.5 Verification Only Verification Only Required Request Fields Field Name Description Required Length Format Comments profile_id Identifies the source Yes 20 N of the incoming request. profile_key Specifies the API Yes 32 A/N password assigned to the specified profile identifier. card_number Cardholder account Yes 5-22 N number card_exp_date Card expiration date Yes 4 N Submit at MMYY, if the month is single digit precede with a leading zero. If the card has expired and the 2013 Merchant e-solutions, Inc. 50

53 Field Name Description Required Length Format Comments expired date is submitted, and the moto_ecommerce_ind is set to a 2 or 3 (recurring), the Payment Gateway will submit 0000 as the expiration date in the authorization request. transaction_amount Transaction amount Yes Must send a value of 0.00 for this transaction type. transaction_type Transaction type Yes 1 A A=Verification Only cardholder_street_address cardholder_zip Cardholders address data. When present an AVS request is issued. Example: 123 Main St. Cardholder zip or postal code. When present an AVS request is issued. Example: or Request: POST /mes-api/tridentapi HTTP/1.1 No Unlimite d A/N/+ Special characters require URL encoding. System can only send 19 characters of the address field, will send first 19. Only required of desired for validation No 5 or 9 N Note: cardholder_zip is also a field used for card-present transactions when the magnetic strip fails to be read. Only required of desired for validation. Content-Type: application/x-www-form-urlencoded Cache-Control: no-cache Pragma: no-cache User-Agent: Java/1.7.0_21 Host: cert.merchante-solutions.com Accept: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2 Connection: keep-alive Content-Length: 578 profile_id= &profile_key=gvqzgkxoteodzpzjzrorqqzoklaeqxjf&tra nsaction_type=a&cardholder_street_address=123+main&cardholder_zip=55555&transaction_a mount=0.00&card_number= &card_exp_date=1111 Response: transaction_id=6117bf65fc4f38b7bc0ca4cd46eed6d1&error_code=000&auth_response_text= Card OK&avs_result=Y&auth_code=T2067H 9.6 Inquiry Inquiry Transaction Required Fields Field Name Description Required Length Format Comments profile_id Identifies the source of the Yes 20 N incoming request. profile_key Specifies the API password Yes 32 A/N assigned to the specified profile identifier. transaction_type Transaction type Yes 1 A I=Inquiry Retry_id Used to look up an Inquiry transaction Yes 16 A/N 2013 Merchant e-solutions, Inc. 51

54 Request: POST /mes-api/tridentapi HTTP/1.1 Content-Type: application/x-www-form-urlencoded Cache-Control: no-cache Pragma: no-cache User-Agent: Java/1.7.0_21 Host: cert.merchante-solutions.com Accept: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2 Connection: keep-alive Content-Length: 578 profile_id= &profile_key=gvqzgkxoteodzpzjzrorqqzoklaeqxjf&tra nsaction_type=i&retry_id= Response: transaction_id=51e8ea7ef94e3813a00b2a2331cd2679&error_code=000&auth_response_text =Exact Match&avs_result=Y&cvv2_result=M&auth_code=T7362H&retry_count=2 9.7 Partial Authorization Sale with Partial Authorization Required Request Fields Field Name Description Required Length Format Comments profile_id Identifies the source Yes 20 N of the incoming request. profile_key Specifies the API Yes 32 A/N password assigned to the specified profile identifier. card_number Cardholder account Yes 5-22 N number card_exp_date Card expiration date Yes 4 N Submit at MMYY; if the month is single digit precede with a leading zero. transaction_amount Transaction amount Yes 12 N transaction_type Transaction type Yes 1 A D=Sale invoice_number cardholder_street_address cardholder_zip Cardholders address data. When present an AVS request is issued. Example: 123 Main St. Cardholder zip or postal code. Yes, for preferred Interchange No Yes, for preferred Interchange 17 A/N Defined by Visa as 0-9, a-z, A-Z or spaces. No special characters permitted. Unlimite d A/N/+ Special characters require URL encoding. System can only send 19 characters of the address field, will send first or 9 N When present an AVS request is issued. Example: or Rctl_partial_auth Partial_auth Y 12 D,P Will contain the authorized amount (not necessarily the request amount). Request: POST /mes-api/tridentapi HTTP/1.1 Content-Type: application/x-www-form-urlencoded 2013 Merchant e-solutions, Inc. 52

55 Cache-Control: no-cache Pragma: no-cache User-Agent: Java/1.7.0_21 Host: cert.merchante-solutions.com Accept: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2 Connection: keep-alive Content-Length: 578 profile_id= xxxxx000000xx&profile_key=xxxxxx&transaction_type=d&card_numb er=4012xxxxxxxx8888&card_exp_date=1216&transaction_amount=1.00&&cvv2=123&ca rdholder_street_address=123+n.+main&cardholder_zip=55555&invoice_number= &rctl_partial_auth=true Response: transaction_id=d96cdfb30aab3e8d9944f9ab4fd5b646&error_code=010&auth_response_t ext=partial Approval&avs_result=Y&cvv2_result=M&auth_code=T2055H&partial_auth= Merchant e-solutions, Inc. 53

56 Chapter 10 - Echo Fields Echo fields are provided to allow users to pass data in the API request that will be returned (echoed) in the response. Echo request parameters begin with the prefix echo_ and echo response parameters begin with the prefix eresp_ Echo Field Examples Examples: Request:... &echo_my_field=my_field_value Response:... &eresp_my_field=my_field_value Request:... &echo_customer_id= Response:... &eresp_customer_id= Merchant e-solutions, Inc. 54

57 11.1 Usage Chapter 11 - Response Control Interface The response control interface allows users to request specific fields to be returned in certain API responses. Response control request parameters all begin with the prefix rctl_. The response field will be the request field name with the rctl_ prefix removed. Example: If the rctl_product_level parameter is set in the request then the product_level parameter will be returned in the response. The response parameter will only be returned if the corresponding request parameter has one of the following values: yes, y, true. The value of the request parameter is not case sensitive Response Control Fields Request Field Name Response Field Name Response Format Response Length Tran Types rctl_product_level product_level A/N 2 A,D,P, J Comments See Response Field Values below. This functionality remains for legacy clients. Due to changes by both Visa and MC it is recommended to use the ARDEF tables available via the MeS Reporting API Rctl_commercial_card commercial_card A/N 1 A,D,P See Response Field Values below. Rctl_Extended AVS Extended_AVS A/N 5 A,D,P Note: this response is a 5 digit field with each digit corresponding in order to values in the sections listed below Rctl_account_balance Account_balance N 12 D,P Response will contain the pre-paid card balance if provided by the issuer. If the issuer does not return a balance the response field is not returned. Rctl_partial_auth Partial_auth N 12 D,P Will contain the authorized amount (not necessarily the request amount). rctl_card_number_truncated card_number_truncated AN 16 All Response will return a truncated version of the card number. Format is first 6, last 4 with xxxxxx in the middle: xxxxxx2456 rctl_resp_hash resp_hash AN 32 All Will return a security hash in the response. The security hash is a sha1 hash of (in this order): 1. Trident Transaction ID 2. Merchant's Profile Key 3. Truncated card number (Only If rctl_card_number_truncated was requested and is in the response). Example: 7569af60aede1bf00c9ece6fa3d3c75d 205b Response Field Values Field Name: product_level Field Name Visa Description MasterCard Description 2013 Merchant e-solutions, Inc. 55

58 Field Name Visa Description MasterCard Description A Visa Classic/Traditional MasterCard Consumer B Visa Traditional Rewards --- C Visa Signature MC World/Elite D Visa Signature Preferred --- E Reserved --- F Reserved --- G Visa Business MC Business/Corporate G1 Visa Signature Business MC World/Elite Business G2 Reserved MC Business Debit G3 Visa Business Enhanced (U.S.Only) H Reserved MasterCard Debit I Visa Infinite --- J Reserved --- J1 Reserved MasterCard General Prepaid J2 Reserved MC Prepaid Gift Card J3 Visa Healthcare MasterCard Prepaid Benefits J4 Reserved MasterCard Prepaid Commercial K Visa Corporate --- K1 Visa GSA Corporate T&E L Electron --- M MC/EuroCard and Diners(when unable to define) MC/EuroCard and Diners(when unable to define) N Reserved --- N1 Visa Rewards O Reserved --- P Reserved --- Q Private Label Private Label R Proprietary --- S Visa Purchasing MasterCard Purchasing S1 Visa Purchasing with Fleet MC Commercial with Fleet S2 Visa GSA Purchasing S3 S4 Visa GSA Purchasing with Fleet Government Services Loan 2013 Merchant e-solutions, Inc. 56

59 Field Name Visa Description MasterCard Description S5 Commercial Transport EBT S6 S7 Business Loan Visa Distribution T Reserved/Interlink --- U Visa TravelMoney --- V V-Pay --- Additional Card Types AX American Express American Express DI Discover (when code is not returned) Discover (when code is not returned) DN Diners JC JCB MC MasterCard (when code is not returned) MasterCard (when code is not returned) Note: Field name for product_level are standard Visa values, MasterCard product levels are mapped to Visa field names. Discover when available will be mapped to Visa Field names as well. Use Visa Descriptions for Discover. To obtain additional card characteristic values, the Account Range Definition Tables (ARDEF) for Visa and MC are available using the Reporting API. Field Name: commercial_card Field Name B D R S Values Business Card Visa Commerce (reserved for future use) Corporate Card Purchasing Card 0 Non-commercial Card <SPACE> Invalid Request Indicator Received Result Code Field Name: Rctl_Extended AVS Position 1(Billing Postal Code Result) Response Message Response Definition Y Match Postal Code Match N No Match Postal Code No Match ~ Data not sent Postal Code Data not sent U Data Unavailable Postal Code Data Unavailable R Retry Retry Transaction S Service Not Available Service Not Available Field Name: Rctl_Extended AVS Position 2(Billing Address Result) 2013 Merchant e-solutions, Inc. 57

60 Result Code Response Message Response Definition Y Match Billing Address Match N No Match Billing Address No Match ~ Data not sent Billing Address Data not sent U Data Unavailable Billing Address Data Unavailable R Retry Retry Transaction S Service Not Available Service Not Available Result Code Field Name: Rctl_Extended AVS Position 3(Billing First and Last Name) Response Message Response Definition Y Match Cardholder Name Match N No Match Cardholder Name No Match ~ Data not sent Cardholder Name Data not sent U Data Unavailable Cardholder Name Data Unavailable R Retry Retry Transaction S Service Not Available Service Not Available Result Code Field Name: Rctl_Extended AVS Position 4(Billing Phone) Response Message Response Definition Y Match Billing Phone Match N No Match Billing Phone No Match ~ Data not sent Billing Phone Data not sent U Data Unavailable Billing Phone Data Unavailable R Retry Retry Transaction S Service Not Available Service Not Available Result Code Field Name: Rctl_Extended AVS Position 5(Billing ) Response Message Response Definition Y Match Billing Match N No Match Billing No Match ~ Data not sent Billing Data not sent U Data Unavailable Billing Data Unavailable R Retry Retry Transaction S Service Not Available Service Not Available 2013 Merchant e-solutions, Inc. 58

61 Chapter 12 FraudDeflector 12.1 Introduction The MeS FraudDeflector is an additional service offered to merchant s using the MeS Payment Gateway for processing. In addition to basic velocity checks, white and black lists, the MeS FraudDeflector offers many external checks such as IP addresses and country of issue. Merchants that required detailed fraud analysis are encouraged to sign up for this integrated service Transaction Flow Merchant configures the MeS FraudDeflector via the Payment Gateway. Merchant processes transactions routed to the Payment Gateway. Based on MeS FraudDeflector settings, the Payment Gateway routes for both authorization and fraud checks. Transactions are approved, denied, or placed on hold for review. Merchant reviews held transactions and takes appropriate action to remove from the processing cycle or approve for settlement FraudDeflector Request Fields Field Name Description Required Length Format Comments cardholder_first_name Cardholders first name No 15 A cardholder_last_name Cardholders last name No 30 A cardholder_street_address First 20 characters of the cardholders billing No 19 A/N address. No leading, trailing zeros permitted cardholder_zip Cardholders billing No 9 A/N postal code country_code Cardholders billing No 3 N country code ship_to_first_name First name where goods No 15 A will be shipped ship_to_last_name Last name where goods No 30 A will be shipped ship_to_address Address where goods No 50 A/N will be shipped ship_to_zip Postal Code where No 9 A/N goods will be shipped dest_country_code 3 digit numeric country No code where goods will 3 N be shipped ip_address Customer s Internet IP No 15 A/N/+ address cardholder_ No Cardholders billing 60 A/N/+ account_creation_date account_name date the account was No created on the merchant system 10 mm/dd/yyyy name assigned to the account by the No Unlimited A/N Ex: customerabc@order.c om 2013 Merchant e-solutions, Inc. 59

62 account_ Field Name Description Required Length Format Comments account_last_change cardholder_phone digital_goods subscription Flag for the a subscripton (recurring) service currency_code 3-digit ISO 4217 currency code. For example, to process a request in Euros, the currency_code would be submitted as 978. In this example, a transaction_amount of would be 36 fraud_scan device_id browser_language merchant address A/N/+ associated with the No account at the merchant last date the account mm/dd/yyyy was changed No 10 Cardholders billing N phone number No 10 Flag for the purchase of No Boolean Boolean (Y, digital goods y, True) used to turn off the fraud scan for a single transaction device id generated by BlueCava or other vendor primary language used by the cardholder's browser N Boolean Boolean (Y, y, True) No, default is 840. Submit as: nnnnnnnnnn set to Y, y, or true if the purchase is digital goods set to Y, y, or true if the purchase is a subscription 3 N By default the API sets the currency code to 840 (US Dollars). This field is optional when Foreign Exchange (FX) processing is used. It is required if processing through the MeS International gateway No Boolean Boolean (Y, y, True) No Unlimited A/N See section 12.4 for details on acquiring the device_id No Unlimited A/N 12.4 Fingerprint Integration The MeS Fraud Deflector can be enhanced by additionally providing a digital fingerprint of the cardholder. The fingerprint contains many additional key data points for fraud evaluation, allowing Fraud Deflector to make a more accurate recommendation. In order to obtain the fingerprint, several elements need to be added to a merchant-hosted checkout page. 1. The following JavaScript should be added in the HTML head area: <script type="text/javascript" src=" <script type="text/javascript"> BCLD.getSnapshot(successFunc, errorfunc); function successfunc(fp, warningmessage) { var fingerprintdata = document.getelementbyid('bcfp'); fingerprintdata.value = fp; } function errorfunc(errormessage) { // Add debugging here if needed } </script> 2. Next, the following DIVs need to be embedded anywhere in the HTML body: <div id="bcldguiddiv" style="border: 0px; width: 0px; height: 0px;"></div> <div id="bcldflashplayer" style="border: 0px; width: 0px; height: 0px;"></div> 2013 Merchant e-solutions, Inc. 60

63 3. The Digital Fingerprint, will need to be sent to the merchant s web host where it will then be forwarded to the MeS Payment Gateway. This is typically accomplished by embedding a hidden input element into the checkout form itself. The following is an input element that should be embedded into a FORM element: <input type="hidden" id="bcfp" name="bcfp"/> 4. Lastly, in order for the process to function properly, a page named BCLD.html must be hosted by the merchant in the same location as the checkout page. This page may be empty FraudDeflector Response Fields Field Name Description Length Format Comments fraud_result Value returned based on parameters set by merchant in the Payment Gateway Back Office. A/N *Current valid values are: ACCEPT MANUAL_REVIEW DENY *Behavior for the fraud_result field is as follows: o o o ACCEPT: transaction will process as requested. Sale transactions will be captured and settled in the next batch close cycle. Pre-Authorization transactions may be captured by the merchant for processing. MANUAL_REVIEW: Sale requests are initially treated as a Pre-Authorization, if accepted it will convert to a sale and settle in the next batch close cycle. If denied, the Payment Gateway will issue and authorization reversal request. DENY: transaction was not authorized, if an override is initiated the transaction will go out for an authorization and if approved (and a sale request) will capture the transaction. If the request was a Pre-Authorization, approved transactions may be captured by the merchant for processing FraudDeflector Error Codes For a complete list of all Payment Gateway error codes please refer to the MeS Payment Gateway specification. Response Code Error Description Required Action 162 Invalid cardholder reference number Verify reference number and re-submit transaction Approved by issuer, held for fraud review Fraud system recommends denying, held for review Fraud system unavailable. Declined due to strict fraud setting Review transaction in the Payment Gateway Back Office Review transaction in the Payment Gateway Back Office Review transaction in the Payment Gateway Back Office 12.7 FraudDeflector Examples Sale with ACCEPT response 2013 Merchant e-solutions, Inc. 61

64 Request profile_id= &profile_key=eslvinonbtrsmxzzqaprppqqwvvja Ggi&transaction_type=D&card_number= &card_exp_date=1216&tran saction_amount=10.00&cvv2=123&invoice_number=123456&client_reference_number=f raud1&fraud_scan=true&cardholder_street_address=123+n.+main&cardholder_zip=555 55&account_creation_date=05%2F01%2F2012&account_name=John+Doe&account_em ail=jdoe%40 .com&account_last_change=05%2f20%2f2012&digital_goods=true&s ubscription=false&device_id=test&browser_language=en Response transaction_id=e9eba31db25431dba3165b0593ce5d4c&error_code=000&auth_response _text=exact Match&avs_result=Y&cvv2_result=M&auth_code=T1623H&fraud_result=ACCEPT Sale with DENY response Request profile_id= &profile_key=eslvinonbtrsmxzzqaprppqqwvvja Ggi&transaction_type=D&card_number= &card_exp_date=1216&tran saction_amount=10.41&cvv2=123&invoice_number=123456&client_reference_number=f raud1&fraud_scan=true&cardholder_street_address=123+n.+main&cardholder_zip=555 55&account_creation_date=05%2F01%2F2012&account_name=John+Doe&account_em ail=jdoe%40 .com&account_last_change=05%2f20%2f2012&digital_goods=true&s ubscription=false&device_id=test&browser_language=en Response transaction_id=f35f8c6ac1083e6bb37a0022a6103f74&error_code=244&auth_response_t ext=fraud system recommends denying, held for review&fraud_result=deny Pre-Authorization with MANUAL_REVIEW response Request profile_id= &profile_key=eslvinonbtrsmxzzqaprppqqwvvja Ggi&transaction_type=P&card_number= &card_exp_date=1216&tran saction_amount=110.41&cvv2=123&invoice_number=123456&client_reference_number =fraud1&fraud_scan=true&cardholder_street_address=123+n.+main&cardholder_zip=55 555&account_creation_date=05%2F01%2F2012&account_name=John+Doe&account_e mail=jdoe%40 .com&account_last_change=05%2f20%2f2012&digital_goods=true &subscription=false&device_id=test&browser_language=en Response transaction_id=7d d63971f25a1da60e607&error_code=243&auth_response _text=approved by issuer, held for fraud review&avs_result=y&cvv2_result=m&auth_code=000000&fraud_result=manual_revi EW 2013 Merchant e-solutions, Inc. 62

65 Chapter 13 Batch Processing Another processing option using the Payment Gateway interface, allows clients to submit a batch of transactions for processing. A file is delivered using the gateway name/pair values. MeS will confirmation that the file was received and a follow up once the batch has been processed. Batches may be submitted and response files retrieved via the MeS web portal or via an API call. Processing time will vary depending on the transaction type and overall size of the batch, however all batches will be processed within 24 hours of submission. The batch processing option may be used for large recurring files that require both authorization and capture (sale transaction), or in conjunction with the Payment Gateway (ex: captures at the end of day for all online authorizations). There are some functions in the Payment Gateway that may not be ideal when submitting transactions in a batch mode. Because some transactions rely on access to the database to reference a prior transaction, care should be taken to refrain from submission of transactions that require this access. While not typical, sending multiple settlements for a single authorization concurrently is not recommended within the same batch. In addition, transactions such as a settlement followed immediately by a void, etc. should also be avoided Submitting a Request File Upload via MeS Web Portal User ID must be configured for this service, a Batch Processing option will be displayed on the main menu once logged in. After selecting Batch Processing the following screen will be displayed. Select Upload Request File: Select or validate profile, attach file, and click submit: Once received, the screen will refresh with file confirmation: 2013 Merchant e-solutions, Inc. 63

66 Upload via API All batch API requests are handled by an HTTPS POST to the following URL: The parameters listed in the table below and the file data should be passed to the server using Content-Type: multipart/form-data. Upload Request Fields Field Name Length Format Required Description userid 32 A/N Yes MeS Login ID userpass 32 A/N Yes MeS Login Password profileid 20 N Yes The MeS Gateway profile ID the record is associated with. testflag 1 Y or N No Default value is N, Y may be set in order to send a test file that will process to the MeS simulator. Sample Batch File: (note that files are one line per transaction, sample shows continuation to a second line) transaction_type=p&card_number= &card_exp_date=1216&transaction_amount=1.00&cvv2=123 &cardholder_street_address=123+n.+main&cardholder_zip=55555&invoice_number= transaction_type=p&card_number= &card_exp_date=1216&transaction_amount=1.00&cvv2=123 &cardholder_street_address=123+n.+main&cardholder_zip=55555&invoice_number= transaction_type=p&card_number= &card_exp_date=1216&transaction_amount=1.00&cvv2=123 &cardholder_street_address=123+n.+main&cardholder_zip=55555&invoice_number= transaction_type=p&card_number= &card_exp_date=1216&transaction_amount=1.00&cvv2=123 &cardholder_street_address=123+n.+main&cardholder_zip=55555&invoice_number= Requesting a Response File Retrieval via MeS Web Portal Select Download Response File from the Batch Processing menu: 2013 Merchant e-solutions, Inc. 64

67 Input the Response File ID and Submit: File will be returned: Sample Text Response File: Retrieval via API All batch API requests are handled by an HTTPS POST to the following URL: Download Request Fields Field Name Length Format Required Description userid 32 A/N Yes MeS Login ID userpass 32 A/N Yes MeS Login Password respfileid 15 N Yes The File ID from the processed batch 2013 Merchant e-solutions, Inc. 65