MeS Gateway ver2.3 - MeS Public - Merchant e

Transcription

Merchant e-Solutions
Payment Gateway
Merchant e-Solutions
October 2013
Version 4.10
© 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.
Table of Contents
Chapter 1 – Related Documentation ................................................................................... 4
Applicable documents ................................................................................................... 4
1.2 Related documents ................................................................................................. 4
1.3 Document revisions ................................................................................................. 4
Chapter 2 – Overview .......................................................................................................... 5
2.1 Introduction .............................................................................................................. 5
2.2 Settlement to Bank .................................................................................................. 6
Chapter 3 – Credit Card Processing.................................................................................... 7
3.1 Introduction .............................................................................................................. 7
3.2 Transaction Method ............................................................................................... 10
3.3 Risk Management Tools ........................................................................................ 11
3.3.1 Address Verification Service ............................................................................ 11
3.3.2 Cardholder Validation ...................................................................................... 12
3.3.3 Commercial and Purchase Card Extended Data ............................................. 12
3.3.4 Dynamic Descriptors ........................................................................................ 13
3.3.5 Store Card........................................................................................................ 13
3.3.6 FraudDeflector ................................................................................................. 13
3.3.7 Settlement ........................................................................................................ 13
3.3.8 Card Security Obligation .................................................................................. 13
Chapter 4 – Back Office..................................................................................................... 15
Chapter 5 – Testing and Certification Roadmap ............................................................... 16
5.1 Testing ................................................................................................................... 16
5.2 Certification ........................................................................................................... 16
5.3 Test Card Numbers ............................................................................................... 17
5.4 Address Verification Testing.................................................................................. 17
5.5 CVV, CVC, CID Testing......................................................................................... 18
5.6 3D Secure (Verified by Visa, MC Secure Code) Testing....................................... 18
5.7 Amount Driven Response Testing......................................................................... 19
5.8 PINNED Debit Testing ........................................................................................... 19
5.9 American Express – AAV (Cardholder Email, Name and Phone Number
Verification) ................................................................................................................. 20
5.10 Partial Authorization and Balance Inquiry Testing .............................................. 20
Chapter 6 - Processing Interface ...................................................................................... 21
6.1 Communication Protocol ....................................................................................... 21
6.2 Batch Processing .................................................................................................. 21
6.3 Security.................................................................................................................. 21
Chapter 7 - Request Field Definitions............................................................................... 22
7.1 Request Fields ...................................................................................................... 22
7.2 FraudDeflector Recommended Required Fields ................................................... 24
7.2.1 FraudDeflector Field Definitions (Digital Goods) ............................................. 24
7.2.2 FraudDeflector Field Definitions (Physical Goods) .......................................... 24
7.3 Non-Card-Present Data Field Definitions .............................................................. 25
7.4 Commercial and Purchase Card Extended Data Field Definitions ....................... 25
7.5 Dynamic DBA Information Field Definitions .......................................................... 26
7.6 Verified by Visa (when using a third party for verification) .................................... 26
7.7 MasterCard Secure Code (when using a third party for verification) .................... 26
7.8 International Currency Field Definitions ................................................................ 26
7.9 Recurring Payments-Installment ........................................................................... 27
7.10 PINNED Debit (online only) ................................................................................. 27
7.11 American Express Enhanced Address and Cardholder Verification Service ...... 27
7.12 American Express Enhanced Data Fields ........................................................... 28
7.13 Hotel, Cruise, Auto Rental Enhance Data Fields ................................................ 29
7.14 Basic Request Sample ........................................................................................ 30
Chapter 8 - Response Field Definitions ............................................................................ 31
8.1 Required Fields ..................................................................................................... 31
8.2 Payment Gateway Error Codes ............................................................................. 31
Payment Gateway v4.10
©2013 Merchant e-Solutions, Inc.
1
8.3 Payvision International Error Codes ...................................................................... 34
8.4 Adyen International Error Codes ........................................................................... 34
8.5 Authorization Responses (as defined by Visa and MC) ........................................ 36
8.6 Merchant e-Solutions Authorization Switch Error Codes ...................................... 37
8.7 AVS Response Codes ........................................................................................... 38
8.8 CVV Response Codes .......................................................................................... 39
8.9 Multi-Currency Code Table ................................................................................... 39
Chapter 9 – Request/Response Samples ......................................................................... 40
9.1 Sales, Pre-Authorizations, Capture Transactions ................................................. 40
9.1.1 Sale .................................................................................................................. 40
9.1.2 Pre-Authorization ............................................................................................. 41
9.1.3 Successful Capture .......................................................................................... 41
9.1.4 Multi-Settle ....................................................................................................... 42
9.1.5 Re-Auth ............................................................................................................ 43
9.2 Refund, Credit, and Void Transactions ................................................................. 43
9.2.1 Refund Resulting in a Credit Transaction ........................................................ 43
9.2.2 Refund Resulting in a Voided Transaction ...................................................... 44
9.2.3 Partial Refund Resulting in an Adjustment ...................................................... 45
9.2.4 Partial Refund Resulting in a Credit................................................................. 45
9.2.5 Credit ............................................................................................................... 46
9.2.6 Void .................................................................................................................. 47
9.3 Store card Transactions ........................................................................................ 48
9.3.1 Store card ........................................................................................................ 48
9.3.2 Immediate Sale Using Stored Card ID from Store card Sample Above .......... 49
9.4 Batch Close ........................................................................................................... 50
9.4.1 Batch Close...................................................................................................... 50
9.5 Verification Only .................................................................................................... 50
9.5.1 Verification Only............................................................................................... 50
9.6 Inquiry .................................................................................................................... 51
9.6.1 Inquiry Transaction .......................................................................................... 51
9.7 Partial Authorization .............................................................................................. 52
9.7.1 Sale with Partial Authorization ......................................................................... 52
Chapter 10 - Echo Fields .................................................................................................. 54
10.1 Echo Field Examples ........................................................................................... 54
Chapter 11 - Response Control Interface ......................................................................... 55
11.1 Usage .................................................................................................................. 55
11.2 Response Control Fields ..................................................................................... 55
11.3 Response Field Values ....................................................................................... 55
Chapter 12 – FraudDeflector ............................................................................................. 59
12.1 Introduction .......................................................................................................... 59
12.2 Transaction Flow ................................................................................................. 59
12.3 FraudDeflector Request Fields............................................................................ 59
12.4 Fingerprint Integration ......................................................................................... 60
12.5 FraudDeflector Response Fields ......................................................................... 61
12.6 FraudDeflector Error Codes ................................................................................ 61
12.7 FraudDeflector Examples .................................................................................... 61
12.7.1 Sale with ACCEPT response ......................................................................... 61
12.7.2 Sale with DENY response ............................................................................. 62
12.7.3 Pre-Authorization with MANUAL_REVIEW response ................................... 62
Chapter 13 – Batch Processing ......................................................................................... 63
13.1 Submitting a Request File ................................................................................... 63
13.1.1 Upload via MeS Web Portal ........................................................................... 63
13.1.2 Upload via API ............................................................................................... 64
13.2 Requesting a Response File ............................................................................... 64
13.2.1 Retrieval via MeS Web Portal ........................................................................ 64
13.2.1 Retrieval via API ............................................................................................ 65
13.3 Error Codes ......................................................................................................... 66
2
13.4 Email Confirmation .............................................................................................. 66
Chapter 14 – Corporate Card Line Item Detail Processing ............................................... 68
14.1 Introduction .......................................................................................................... 68
14.2 Request Fields for Visa and MasterCard Level III ............................................... 68
14.3 Visa Line Item Subfields ...................................................................................... 69
14.4 MasterCard Line Item Subfields .......................................................................... 69
14.5 Request Fields American Express ...................................................................... 70
14.6 American Express Line Item Subfields ............................................................... 70
14.7 Level III Error Codes............................................................................................ 70
14.8 Sale (D) – Source Code Example ........................................................................ 71
14.9 Settle (S) – Source Code Example ...................................................................... 72
3
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: http://resources.merchantesolutions.com.
1.3 Document revisions
Chapter
Action
7
Add
8
Update
11
Update
Data
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.
4
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.
MeS Payment
Gateway
Credit Card
Association
Networks
https://authorization_req
uest…….
https://authorization_response….
Settlement to
Bank
Merchant Bank
5
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.
6
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
Sale
Pre-Authorization
Description
If the transaction receives an approval, it
will be automatically marked for settlement
at the same time.
The transaction will be authorized but not
marked for capture. To complete a PreAuthorization, 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.
Comments
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
7
Transaction Type
Settle PreAuthorization
Description
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.
Multi-Settle
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.
Re-Auth (of a
declined
transaction)
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.
Void
A Void request should only be processed
for a Pre-Authorization transaction.
Voiding a Sale should be done with a
Refund transaction. Voiding a PreAuthorization will initiate an auth-reversal.
Comments
approval date.
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: 5812 - Restaurants
5813 - Bars and Taverns
5814 - Fast Food Restaurants
4121 - Taxicabs & Limousines
7230 - Hair Salons
7298 - 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.
Best Practice: A Void transaction should
be restricted to Pre-Authorization
transactions. Once a Settlement has been
8
Transaction Type
Description
Comments
performed on a Pre-Authorization it is best
handled with a Refund transaction.
Refund
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.
Credit
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
Store card number. The transaction_id
returned by the store request can be used
in subsequent requests via the card_id
parameter.
Delete Store card
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.
Offline
Verification Only
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 eSolutions 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
9
Transaction Type
Description
it will not provide any status on the
account (open, closed, etc). In addition,
the card verification value is not validated.
MasterCard supports an AVS only
transaction with a zero amount and will
verify only address match and not the
status of the card.
Inquiry
Batch Close
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.
Comments
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.
10
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 $19.99.
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.
3.3.1 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.
11
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 PreAuthorization 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.
3.3.3 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.
12
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 7.5.
3.3.5 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.
3.3.6 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.
3.3.7 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.
3.3.8 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
13
Merchants that are not yet PCI certified will receive follow up from the Merchant eSolutions 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.
http://www.visa.com/cisp
https://www.pcisecuritystandards.org/
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:
https://www.pcisecuritystandards.org/security_standards/pa_dss.shtml
14
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.
15
Chapter 5 – Testing and Certification Roadmap
5.1 Testing
In order to obtain an ID for testing, the certification request form must be submitted online
at http://resources.merchantesolutions.com/display/TPGPUB/Payment+Gateway+Certification+Request+Form.
Upon receipt of a completed form, the test ID will be emailed within 24 hours.

The certification request form is located at: http://resources.merchantesolutions.com/download/attachments/1411006/MeS+PG+Certification+Request+form+v1.1.doc?versi
on=1
Merchant e-Solutions will e-mail 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
Profile ID
Merchant Key
API Development URL
MeS PG Development TEST #
(unique profile id value)
(unique key value)
https://...
5.2 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.
16
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
16
4012301230123010
Visa
13
4012301230158
MasterCard
16
5123012301230120
American Express
15
349999999999991
Discover
16
6011011231231235
JCB
16
3528288605211810
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
4000700705251681
B - Business Card
MasterCard
5589548939080095
B - Business Card
MasterCard
5133598939080091
S - Purchasing Card
Visa
4000693061211474
R - Corporate Card
MasterCard
5119718939080093
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
123
Zip Code
55555
123
999991111
123
123
234
EH8 9ST
Other Zip
Any Zip
345
Any Zip
456
235
Other Address
Other Address
Any Zip
Any Zip
55555
EH8 9ST
AVS Result Code
Y – street and postal code match
Y – street and postal code match (Visa)
X – street and postal code match (MasterCard)
D - exact match, international
A - address match, zip mismatch
U - address unavailable
G - verification unavailable due to international issuer nonparticipation (Visa and MasterCard only)
R - issuer system unavailable, retry
S – AVS not supported
Z - address mismatch, 5-digit zip match
Z - address mismatch, international zip match
17
Street Address
Zip Code
AVS Result Code
Other Address
999991111
Other Address
Other Zip
Z- address mismatch, zip match (Visa)
W- address mismatch, zip match (MasterCard)
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
234
345
else
M-Match
P-Not Processed
U-Issuer is not certified
N-No Match
This table will test American Express CID:
CID Value
1234
Result Code
M-match (this response is generated when the CID flag is
enabled on the MeS Profile ID)
P-not processed (this response is generated when the CID
flag is enabled on the MeS Profile ID)
N-no match (with a response code of 000) (this response is
generated when the CID flag is enabled on the MeS Profile
ID)
2345
**** (any value other than 1234 or 2345)
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
5
ERERERERERERERERERERERERERE=
Result
Error code = 000
5
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
5
2
Error code = 000
6
1
Error code = 000
Result
18
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
0.00
085
“Card OK”
For card verification testing, submit a transaction code=A
0.01
001
"Call"
refer to issuer
0.02
002
"Call"
refer to issuer - special condition
0.04
004
"Hold-call"
pick up card (no fraud)
0.05
005
"Decline"
do not honor
0.07
007
"Hold-call"
pick up card (fraud)
0.14
014
"Card No. Error"
invalid card number
0.15
015
“No Such Issuer”
Invalid card number
0.19
019
"RE Enter"
re-enter transaction
0.41
041
"Hold-call"
pick up card (fraud: lost card)
0.43
043
"Hold-call"
pick up card (fraud: stolen card)
0.51
051
"Decline"
insufficient funds
0.54
054
"Expired Card"
issuer indicates card is expired
0.57
057
"Serv Not
Allowed"
transaction not permitted to cardholder
0.59
059
“Suspected
Fraud”
Do not honor card
0.84
084
“Invalid Auth”
Invalid Authorization Life Cycle
0.86
086
“Can’t Verify
PIN”
System is unable to validate the Pin #
1.10
0TA
"CT NOT
ALLOWED"
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
19
Encrypted PIN Block
KSN
Response Code
706E3CADE53F11CA
3941013211204321
00 – Approval
43197165510DDD89
3941013211204322
55 - Wrong PIN
CCCCCCCCCCCCCCCC
3941013211204323
81 - Encryption Error
5.9 American Express – AAV (Cardholder Email, 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
55555 or 999999999
Billing First Name
AAV
CHRIS
Billing Last Name
AAV
FROST
Billing Phone Number
AAV
7035551212
Customer Email
ITD
[email protected]
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.
5.10 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.
20
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.
21
Chapter 7 - Request Field Definitions
7.1 Request Fields
Field Name
profile_id
profile_key
card_number
card_exp_date
Description
Required
Length
Format
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 expiration date
Yes
4
N
Comments
Card number should be
submitted with only numbers – no
dashes or spaces?
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)
.
--
--
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.
card_id
Card Identifier
transaction_amount
Transaction amount
Yes (if
processing
a
transaction
with stored
cardholder
data).
32
Yes
12
If you are using the GET method,
be sure to properly URL encode
all track data.
32-character ID assigned during
a previous store card request.
N
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.
If processing via MeS
International gateway, this
amount should be in the foreign
currency desired.
22
Field Name
transaction_id
Description
Required
Length
Transaction Identifier
Yes, for
some Tran
Types. See
comments
32
Format
A/N
Comments
32-character transaction id
returned in the original
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
moto_ecommerce_ind
Indicates the type of
transaction.
No, default
is 7.
1
N
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
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.
MC Secure Code, set value to 5
when the EciFlag is 2, set value
to 6 when EciFlag=1
reference_number
Reference number is
assigned by the
Payment Gateway
Is assigned
by the MeS
Payment
Gateway
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.
client_reference_number
Merchant defined
number
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)
auth_code
Authorization code
obtained by means
outside of the MeS
API. This field should
only be included when
transaction type =
Yes, only
for Offline
transactions
.
6
A/N
23
Field Name
batch_number
Description
Offline.
Used to specify the
batch number to close
retry_id
Used to look up an
Inquiry transaction
store_card
Used to store
(tokenize) a card
during a pre-auth or
sale
cvv2
CVV2/CID value from
card. When present a
CVV2/CID match
request is made.
Required
Length
Format
Yes, only if
using batch
close
feature
3
N
Yes, only if
implementin
g the
Inquiry
transaction
type
No
16
A/N
Boolean
Boolean
(Y, y,
True)
No
3-4
N
Comments
Valid values are 1-999. System
edits for duplicate batches and
will reject a batch submitted with
the same batch number within 5
calendar days
This is only required if the Inquiry
transaction type is being
deployed. Number must be
unique per transaction within a 48
hour time period.
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.
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 12.
7.2.1 FraudDeflector Field Definitions (Digital Goods)
Field Name
cardholder_first_name
cardholder_last_name
ip_address
cardholder_email
cardholder_phone
device_id
Description
Cardholders first
name
Cardholders last
name
Customer’s Internet
IP address
Cardholders billing
email
Cardholders billing
phone number
Device id generated
by BlueCava or other
vendor
Required
No
No
No
No
Length
15
A
30
A
15
A/N/+
60
A/N/+
No
No
Format
10
Unlimited
N
A/N
Comments
Ex: [email protected]
Special characters require URL
encoding
Submit as:
nnnnnnnnnn
See section 12.4 for details on
acquiring the device_id
7.2.2 FraudDeflector Field Definitions (Physical Goods)
Field Name
Description
Cardholders first
name
Cardholders last
name
Required
No
No
Length
Format
15
A
30
A
Comments
24
Field Name
ip_address
cardholder_email
cardholder_phone
ship_to_first_name
ship_to_last_name
ship_to_address
ship_to_zip
device_id
Description
Customer’s Internet
IP address
Cardholders billing
email
Cardholders billing
phone number
First name where
goods will be shipped
Last name where
Address where goods
will be shipped
Postal Code where
Device id generated
by BlueCava or other
vendor
Required
No
No
Length
15
A/N/+
60
A/N/+
No
10
No
No
No
N
15
A
30
A
50
A/N
9
A/N
Unlimited
A/N
No
No
Format
Comments
Ex: [email protected]
encoding
Submit as:
nnnnnnnnnn
See section 12.4 for details on
acquiring the device_id
7.3 Non-Card-Present Data Field Definitions
Field Name
Description
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: 55555 or
555554444.
Required
Length
Format
Yes, for
preferred
Interchange
No
17
A/N
Unlimited
A/N/+
Yes, for
preferred
Interchange
5 or 9
AN
Comments
Defined by Visa as 0-9, a-z, A-Z
or spaces.
No special characters permitted.
encoding.
Addresses longer than 19
characters will be truncated
during authorization request.
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
invoice_number
tax_amount
Sales/Local Tax
Amount
ship_to_zip
Ship to zip or postal
code.
Required
Yes, for
preferred
Interchange
Yes, for
preferred
Interchange
Yes, for
preferred
Interchange
for level III
processing
Length
Format
17
A/N
12
Decimal
required.
5 or 9
A/N
Comments
or spaces.
This field is only used when
implementing Level III
processing.
25
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
merchant_name
DBA Name to appear on the
cardholder statement.
No
25
A/N/+
merchant_phone
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
10
N
No
13
AN
No
4
N
Dm_contact_info
merchant_category_code
Comments
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 dashes, special
characters, etc.
EX: 2069991212
Consult Merchant eSolutions for valid MCC
code.
7.6 Verified by Visa (when using a third party for verification)
Field Name
xid
Description
Verified By Visa
Transaction ID
Verified By Visa CAVV
cavv
Required
Length
Format
Yes
varies
Base 64
Yes
varies
Base 64
Comments
This value comes from the XID field in
the 3D response.
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
ucaf_collection_ind
ucaf_auth_data
MasterCard Secure
Code Collection
Indicator.
MasterCard Secure
Code cardholder
authentication data.
Required
Yes
Yes
Length
Format
varies
A/N
varies
Comments
Valid Values:
1 = Supported by the merchant, but UCAF
data was not present.
2 = Both merchant and issuer are UCAF
enabled
Base 64
Cardinal Centinel Users: Use the value
returned in the ECI Flag.
Cardinal Centinel Users: Use the value
returned in the CAVV.
7.8 International Currency Field Definitions
Field Name
Description
Required
Length
Format
currency_code
3-digit ISO 4217 currency code.
For example, to process a request
in Euros, the currency_code would
No,
default is
840.
3
N
Comments
By default the API sets the currency
code to 840 (US Dollars).
This field is needed when using either
26
be submitted as 978. In this
example, a transaction_amount of
36.00 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
The payment
number of the
current
transaction.
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
recurring_pmt_count
The total number
of payments.
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
Length
Format
7.10 PINNED Debit (online only)
Field Name
Description
Required
Comments
debit_pin_block
Contains the
DUKPT encrypted
pin block from the
pin pad device
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
debit_ksn
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
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
Cardholders first name
cardholder_email
Required
Length
Format
No
15
A
Cardholders last name
No
30
A
Cardholders billing email
(on file with American
Express)
No
60
A/N/+
Comments
Ex:
[email protected]
27
cardholder_phone
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
ship_to_first_name
First name where goods
will be shipped
ship_to_last_name
Last name where goods
will be shipped
Required
Length
Format
No
15
A
No
30
A
Comments
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
Ship_to_phone
Phone number where
No
10
N
ship_to_address
Address where goods will
be shipped
No
50
A/N
ship_to_zip
Postal Code where goods
will be shipped
No
9
A/N
5 or 9 digit zip for US
addresses, International
may be any format and
A/N
dest_country_code
3 digit numeric country
code where goods will be
shipped
No
3
N
Example: 840 (USA) or
124 (Canada), etc.
ip_address
Customer’s Internet IP
address
No
15
A/N/+
Cust_host_name
Customer Hostname
No
1-60
No
1-60
http_browser_type
HTTP Browser Type
Customer Ani
Customer ANI
No
15
Customer2Digits
Customer II Digits
No
2
A/N/+
A/N/+
A/N/+
A/N
Format is
nnn.nnn.nnn.nnn
Example:
555.223.225.123
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: 4256664587
Telephone companyprovide ANI ii (Information
Identifier) coding digits
associated with Customer
28
Field Name
Description
Required
Length
Format
Prod_sku
Unique SKU (Stock
Keeping Unit) inventory
reference number of
product
No
15
A/N
ship_method
Method goods were
shipped
No
2
A/N
Comments
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
statement_date_begin
Date of hotel check in,
cruise departure, start date
for auto rental
Yes
10
Date
Comments
mm/dd/yyyy
mm/dd/yyyy
statement_date_end
Requester_name
name_of_place
rate_daily
no_show_ind
industry_code
Date of hotel check out,
cruise end date, return
date for auto rental
Yes
10
Date
Name of individual
checking in/picking up
Yes
38
A/N
Yes
25
A/N
Yes
12
N
Yes
1
Y/N
Yes
1
A/N
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
Identifies type of industry
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).
29
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, az, A-Z or spaces.
No special characters
permitted.
7.14 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=94100009999900000001&profile_key=A7B8C9A7A7B8C9A7A7B8C9A7A7B8
C9A7&transaction_type=D&card_number=4262369999996102&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.
30
Chapter 8 - Response Field Definitions
8.1 Required Fields
Field Name
Description
Required
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
Length
Format
Yes—for
some Tran
Types. See
comments
32
A/N
YES
3 or 4
A/N
YES
64
A/N
YES
6
A/N
YES
1
A/N
YES
1
A/N
YES
2
N
Comments
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
See error code table below. 4 digit
codes for Payvision International
Only.
encoding.
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
Error Description
Required Action
No errors - Transaction Approved.
(approved Verification Only will return
a code of 085)
Authorization request failed.
xx = Authorization Response Code.
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.
000
0xx
31
Response
Code
Error Description
Required Action
111
Merchant Category Code Length
Error.
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.
119
120
121
122
123
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.
Client Reference Number length error
Resubmit with appropriate length, maximum is 96.
124
Batch Number Required
A batch number is required when submitted a transaction_type
of Z
125
Invalid Batch Number
Batch number must be between 1-999
168
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.
Transaction Already Settled.
Void failed because transaction has already settled, submit
credit.
204
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.
CVV2 result is declined by user.
Correct CVV2 data retry request.
211
212
213
214
215
216
217
218
219
Refund amount must be between
zero and the original amount.
Only sale transactions can be
refunded.
Correct amount and retry request.
Provide a valid transaction ID.
Only one type of card data allowed
per request.
Only use one of the following:
* card_number
* card_swipe
* card_id.
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
32
Response
Code
Error Description
Required Action
220
Failed to delete card data, retry
request
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
228
229
230
231
232
233
234
235
236
237
238
239
240
300
301
302
FX rate ID required for foreign
currency transactions.
Base and consumer amounts are
inconsistent with the FX rate.
Failed to find currency code for the
requested country code.
Failed to post transaction the FX
service.
FX amount in base currency is
required.
FX transactions not accepted for this
account.
Request currency code must match
FX rate currency code
Pin debit transactions require track 2
swipe data.
Invalid pin debit transaction type.
Non-USD pin debit transactions are
not supported.
Batch Close Failed
Quit Duplicate Batch
Provide a valid rate ID
Correct provided amounts
Check country code and retry request
Internal Only
Provide the base amount
Contact Merchant e-Solutions
Retry request with a currency code that matches the FX
currency code.
Verify track 2 data is sent with the request
Only a sale (D) is supported
PINNED Debit for USD transactions only
Please verify parameters are correct and re-submit
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
Returned when an Inquiry message
is sent and there is no transaction
matching the submitted retry ID
within 48 hours of the original
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.
Failed to load declined auth data
System was unable to successfully locate data needed for a new
authorization request (only when submitting re-auth or multisettle requests)
Failed to capture International
transaction.
Failed to void International
transaction.
Failed to refund International
transaction.
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
351
Adyen request failed
352
Failed to capture Adyen transaction
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.
Should also contain a three digit Adyen error code listed in
section 8.4.
Retry request
353
Failed to refund Adyen transaction
Retry request
354
Transaction type not supported by
Adyen
Retry request
355
Adyen credit failed
Retry request
356
Adyen request failed
Retry request
33
Response
Code
Error Description
Required Action
357
Adyen void failed
Retry request
400
VBV/MSC Enrollment Check
Retry request.
VBV/MSC Verification Failed.
Retry request.
401
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
412
413
430
431
999
Retry request
FX not supported for re-auth of declines
Internal Error.
Retry request.
Level III Error Codes
Fraud Deflector Error Codes
8.3 Payvision International Error Codes
Response
Code
Error Description
0
Required Action
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.
1000
2000
3000
3100
3200
4000
5000
Groups all unexpected errors.
6000
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.)
Text portion of response will contain a 2 digit error code that
provides additional data to assist with resolution
8.4 Adyen International Error Codes
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 000000 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)
34
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
103
CVC is not the right length
104
Billing address problem
The system was not able to determine the variant of the card
number
The length of the CVC code is not correct for the given card
number
There was an error in the specified billing address fields
105
Invalid paRes from issuer
107
Recurring is not enabled
108
Invalid bankaccount number
The specified paRes from the issuer in the 3D secure
authorisation request is not correct
You are trying to use recurring, but it is not (yet) enabled for your
account
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
117
Invalid billing addresss
The specified bankCountryCode is not supported (bank
payment)
The specified billing address is not valid
125
Invalid recurring contract specified
The specified recurring contract value is not valid
126
127
Bank Account or Bank Location Id
not valid or missing
Account holder missing
The specified bank account or bank location Id is not valid or
missing (elv payment)
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
138
Unsupported currency specified
The specified amount is invalid, or above the equivalent of
50,000.00 EUR.
The specified currency is not supported
139
No shopperEmail or shopperReference specified
800
Recurring requires shopperEmail and
shopperReference
Invalid expiryMonth[1..12] /
expiryYear[>2000], or before now
Invalid expiryMonth[1..12] /
expiryYear[>2000]
Bank Name or Bank Location not
valid or missing
Invalid startMonth[1..12] /
startYear[>2000], or in the future
Contract not 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
Invalid Merchant Account
The specified recurringDetailReferece is not available for the
specified recurring contract
No request specified, or invalid namespace
903
Shouldn't have gotten here without a
request!
Internal error
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
140
141
142
144
901
902
The specified expiry month/year is not valid or in the past
The specified expiry month/year is not valid
The specified bank name or bank location Id is not valid or
missing (elv payment)
The specified start month/year is not valid or in the future
The specified recurring contract could not be found
The specified merchant account is not valid
An internal error occurred while processing the request
35
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
verification is valid
Refer to card issuer
Refer to card issuer, special condition
Invalid merchant or service provider
Pickup card
Do not honor
Error
Pickup card, special condition (other than
lost/stolen card)
Partial Approval
V.I.P. approval
Invalid transaction
Invalid amount (currency conversion field
overflow); or amount exceeds maximum for card
program
00
Approved or completed successfully
01
03
04
05
08
10
12
Refer to card issuer
Invalid merchant
Capture card
Do not honor
Honor with ID
Partial Approval
Invalid transaction
13
14
15
30
Invalid amount
Invalid card number
Invalid issuer
Format error. This response may also be
41
43
51
54
Lost card
Stolen card
Insufficient funds/over credit limit
Expired card
55
Invalid PIN
28
Invalid account number (no such number)
No such issuer
Re-enter transaction
No action taken (unable to back out prior
transaction)
Unable to locate record in file, or account number
is missing from the inquiry
File is temporarily unavailable
57
Transaction not permitted to issuer/cardholder.
39
41
43
51
52
53
54
55
57
58
59
61
No Credit Account
Pickup card (lost card)
Pickup card (stolen card)
Insufficient funds
No checking account
No savings account
Expired card
Incorrect PIN
Transaction not permitted to cardholder
Transaction not allowed at terminal
Suspected fraud
Activity amount limit exceeded
58
61
62
63
65
70
71
75
76
77
78
62
84
63
Restricted card (for example, in Country Exclusion
table)
Security violation
Transaction not permitted to acquirer/terminal
Exceeds withdrawal amount limit
Restricted card
Security violation
Exceeds withdrawal count limit
Contact Card Issuer
PIN Not Changed
Allowable number of PIN tries exceeded
Invalid/nonexistent "To Account" specified
Invalid/nonexistent "From Account" specified
Invalid/nonexistent account
specified (general)
Invalid Authorization Life Cycle
64
65
Transaction does not fulfill AML requirement
Activity count limit exceeded
86
87
75
76
Allowable number of PIN-entry tries exceeded
Unable to locate previous message (no match on
Retrieval Reference number)
88
89
01
02
03
04
05
06
07
10
11
12
13
14
15
19
21
25
85
returned on a Verification only request when
the transaction type is not supported by the
issuer.
This response may also be returned on a
Verification only request when the transaction
type is not supported by the issuer.
Not declined Valid for AVS only, Balance
Inquiry, or SET cardholder certificate requests
(Visa Only)
PIN Validation not possible
Purchase Amount Only, No Cash Back
Allowed
Cryptographic failure
Unacceptable PIN-Transaction Declined-Retry
36
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
"Blocked, first used" - The transaction is from a
new cardholder, and the card has not been
properly unblocked.
Already Reversed (by Switch)
Visa transactions: credit issuer unavailable.
Private label and check acceptance: Invalid date
PIN cryptographic error found (error found by VIC
security module during PIN decryption)
Negative CAM, dCVV, iCVV, or CVV results
No reason to decline a request for account
number verification, address verification, CVV2
verification, or a credit voucher or merchandise
return
Cannot Verify PIN
Ineligible to receive financial position information
(GIV)
Issuer unavailable or switch inoperative (STIP not
applicable or available for this transaction)
Destination cannot be found for routing
Transaction cannot be completed; violation of law
Duplicate transmission. A transaction was
submitted that contains values in the tracing data
fields that duplicate the values in a previously
submitted transaction.
System malfunction System malfunction or certain
field error conditions
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
78
79
80
81
82
85
86
89
91
92
93
94
96
B1
B2
N0
N3
N4
N5
N7
P2
P5
P6
R0
R1
R3
Q1
Z3
XA
XD
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
Response Text
TA
CT NOT ALLOWED
TB
REENTER EXP DATE
Cause
Merchant doesn't accept the
transaction's card type.
Invalid hand-keyed expiration
date.
Resolution
Check if card type set up in MeS
System, contact certification team
Merchant should correct expiration
date and reenter transaction.
37
Response
Code
Response Text
Cause
Resolution
TC
RETRY BAD ADDR
Invalid AVS address or zip data.
TD
REV NOT ALLOWED
TE
BAD MERCHANT KEY
03
Merch ID Error
12
Invalid Trans
unsupported transaction type
13
Amount Error
transaction amount is 0 or too
long
77
No Action Taken
reversal amount larger then
original amount
14
Card No. Error
card number has unknown BIN
or fails check digit edit
19
RE Enter
Communication error with Visa
or MC switches
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
97
System Error
System Malfunction
06
Error 25
Message Format Error
06
Error NN
General Transaction Error
57
Error 57
Unsupported International
Transaction Type
59
Error 59
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
8.7 AVS Response Codes
Result
Code
Response
Message
0
Approved
A
Address
Match
Visa
MC
Amex
x
x
x
x
x
x
B
Address
Match
x
C
Service
Unavailable
x
D
Exact Match
x
E
F
G
I
x
x
UK Exact
Match
Ver
Unavailable
Ver
Unavailable
x
x
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
Address information not verified for international transaction
x
x
L
Address verification was not requested.
Non-US Issuer does not participate
x
K
Response Definition
x
Card Member name matches
Card Member name and Postal Code match
38
Result
Code
Response
Message
M
Exact Match
N
No Match
Visa
MC
x
x
Amex
x
x
O
x
x
P
Postal Code
Match
R
Retry
S
AVS not
supported
U
Verification
Unavailable
W
Domestic and
International 9
digit zip match
X
Domestic and
International 9
digit zip and
address
match
Y
Exact Match
Z
Zip 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
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
x
x
x
x
x
x
x
x
x
x
x
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.
x
x
x
x
x
x
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
Description
CVV2/CVC2 /Discover CID – Match.
M
39
Chapter 9 – Request/Response Samples
9.1 Sales, Pre-Authorizations, Capture Transactions
9.1.1 Sale
Required Request Fields
Field Name
Description
profile_id
Required
Length
Format
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
Yes
4
N
transaction_amount
transaction_type
invoice_number
Transaction amount
Transaction type
12
1
17
N
A
A/N
Cardholders address
data. When present
an AVS request is
issued. Example:
123 Main St.
Cardholder zip or
postal code.
Yes
Yes
Yes, for
preferred
Interchange
No
Unlimited
A/N/+
Yes, for
preferred
Interchange
5 or 9
N
profile_key
card_number
card_exp_date
cardholder_zip
Comments
Submit at MMYY; if the month is
leading zero.
D=Sale
or spaces.
encoding.
System can only send 19 numeric
characters of the address field,
will send first 19.
When present an AVS request is
issued.
Example: 55555 or 555554444.
Request:
Pragma: no-cache
Content-Length: 578
profile_id=94100009999900000001&profile_key=gvQzgKXOTEoDzpzJzROrQQzoKLaEqxjf&tra
nsaction_type=D&cardholder_street_address=123+Main&cardholder_zip=55555&transaction_
amount=1.00&card_number=4012301230123010&card_exp_date=1111&invoice_number=123
456
Response:
transaction_id=8fc94e10b12130f4ab8a8ceeac40fc69&error_code=000&auth_response_text=
Exact Match&avs_result=Y&cvv2_result=M&auth_code=T2067H
40
9.1.2 Pre-Authorization
Field Name
Description
profile_id
Required
Length
Format
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
Yes
4
N
transaction_amount
transaction_type
invoice_number
Transaction amount
Transaction type
12
1
17
N
A
A/N
Cardholders address
data. When present
an AVS request is
issued. Example:
123 Main St.
Cardholder zip or
postal code.
Yes
Yes
Yes, for
preferred
Interchange
No
Unlimited
A/N/+
Yes, for
preferred
Interchange
5 or 9
N
profile_key
card_number
card_exp_date
cardholder_zip
Comments
Submit at MMYY, if the month is
leading zero.
P=Pre-Auth
or spaces.
encoding.
System can only send 19 numeric
characters of the address field,
will send first 19.
issued.
Example: 55555 or 555554444.
Request:
Pragma: no-cache
Content-Length: 578
nsaction_type=P&cardholder_street_address=123+Main&cardholder_zip=55555&transaction_a
mount=1.00&card_number=4012301230123010&card_exp_date=1111&invoice_number=1234
56
Response:
transaction_id=6117bf65fc4f38b7bc0ca4cd46eed6d1&error_code=000&auth_response_text=
Exact Match&avs_result=Y&cvv2_result=M&auth_code=T2067H
9.1.3 Successful Capture
Field Name
profile_id
Description
of the incoming
request.
Required
Yes
Length
Format
20
N
Comments
41
Field Name
profile_key
transaction_type
transaction_id
transaction_amount
invoice_number
Description
Required
Length
Format
Specifies the API
identifier.
Transaction type
Yes
32
A/N
Yes
Yes
1
32
A
A/N
Transaction amount
Yes
No
12
17
N
A/N
Comments
S=Settle Pre-Auth
Required if not submitted with the
pre-auth request
Request:
Pragma: no-cache
Content-Length: 578
nsaction_type=S&transaction_amount=1.00&transaction_id=8fc94e10b12130f4ab8a8ceeac40f
c69&invoice_number=123456
Response:
transaction_id=12f3befbd035371b9b82d5920465e071&error_code=000&auth_response_text
=Settle Request Accepted
9.1.4 Multi-Settle
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
profile_id
Description
Required
Length
Format
Comments
Yes
20
N
Original profile_id must be used
Yes
32
A/N
Original profile_key must be used
transaction_type
transaction_id
of the incoming
request.
Specifies the API
password assigned
to the specified
profile identifier.
Transaction type
Yes
Yes
1
32
A
A/N
S=Settle Pre-Auth
transaction_amount
Transaction amount
Yes
12
N
profile_key
42
9.1.5 Re-Auth
Field Name
profile_id
Description
Required
Length
Format
Yes
20
N
Yes
32
A/N
transaction_type
transaction_id
of the incoming
request.
Specifies the API
identifier.
Transaction type
Yes
Yes
1
32
A
A/N
transaction_amount
Transaction amount
No
12
N
profile_key
Comments
J=Re-Auth
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:
Pragma: no-cache
Content-Length: 578
profile_id=9410000xxxxx000000xx&profile_key=xxxxxx&transaction_type=J&transaction_id=726
13b899e3937cfa33efa1711973c7d
Response:
transaction_id=xxxxxx&error_code=000&auth_response_text=Zip
Match&avs_result=Z&auth_code=T00001
9.2 Refund, Credit, and Void Transactions
9.2.1 Refund Resulting in a Credit Transaction
Field Name
profile_id
profile_key
transaction_type
Description
of the incoming
request.
Specifies the API
identifier.
Transaction type
Required
Length
Format
Yes
20
N
Yes
32
A/N
Yes
1
A
Comments
U=Refund
43
Field Name
transaction_id
Description
Required
Yes
Length
Format
32
A/N
Comments
Request:
Pragma: no-cache
Content-Length: 578
nsaction_type=U&transaction_id=91bb6394dd883153ad90af804c7a5ce2
Response:
transaction_id=aee8b06f9d73353296f9b5076358b63d&error_code=000&auth_response_text
=Refund Request Accepted - Credit
9.2.2 Refund Resulting in a Voided Transaction
Field Name
profile_id
profile_key
transaction_type
transaction_id
Description
of the incoming
request.
Specifies the API
identifier.
Transaction type
Required
Length
Format
Yes
20
N
Yes
32
A/N
Yes
Yes
1
32
A
A/N
Comments
U=Refund
Request:
Pragma: no-cache
Content-Length: 578
nsaction_type=U&transaction_id=e4f49b483d833695a39b2787c65bbef1
44
Response:
transaction_id=7c0ab9ec96da370886a116fa7942447a&error_code=000&auth_response_text
= Refund Request Accepted - Void
9.2.3 Partial Refund Resulting in an Adjustment
Field Name
profile_id
Description
Required
Length
Format
Yes
20
N
Yes
32
A/N
transaction_type
transaction_id
of the incoming
request.
Specifies the API
identifier.
Transaction type
Yes
Yes
1
32
A
A/N
transaction_amount
Transaction amount
Yes
12
N
profile_key
Comments
U=Refund
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:
Pragma: no-cache
Content-Length: 578
nsaction_type=U&transaction_amount=0.60&transaction_id=9f57b14932943a198d51b6a5074f
d916
Response:
transaction_id=38356d5c6625379a9b3e55920f5f9e8a&error_code=000&auth_response_text
=Refund Request Accepted - Adjustment $0.40
9.2.4 Partial Refund Resulting in a Credit
45
Field Name
Description
profile_id
Required
Length
Format
Yes
20
N
Yes
32
A/N
transaction_type
transaction_id
of the incoming
request.
Specifies the API
identifier.
Transaction type
Yes
Yes
1
32
A
A/N
transaction_amount
Transaction amount
Yes
12
N
profile_key
Comments
U=Refund
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:
Pragma: no-cache
Content-Length: 578
nsaction_type=U&transaction_amount=0.60&transaction_id=9f57b14932943a198d51b6a5074f
d916
Response:
transaction_id=55e31d892e3131c38dd7bba706c1aa00&error_code=000&auth_response_text=
Refund Request Accepted - Credit $0.60
9.2.5 Credit
Note: In order for credits to function, they must be enabled on the profile by a Merchant eSolutions representative.
Field Name
profile_id
Description
Required
Length
Format
Yes
20
N
Yes
32
A/N
Yes
5- 22
N
card_exp_date
of the incoming
request.
Specifies the API
identifier.
Cardholder account
number
Yes
4
N
transaction_amount
Transaction amount
Yes
12
N
profile_key
card_number
Comments
single digit precede with a leading
zero.
46
Field Name
Description
transaction_type
Transaction type
Required
Yes
Length
Format
1
A
Comments
C=Credit
Request:
Pragma: no-cache
Content-Length: 578
nsaction_type=C&transaction_amount=1.00&card_number=4012301230123010&card_exp_dat
e=1111
Response:
transaction_id=c005384e51eb37359b14c798590d25b0&error_code=000&auth_response_text
=Credit Approved
9.2.6 Void
Field Name
profile_id
profile_key
transaction_type
transaction_id
Description
of the incoming
request.
Specifies the API
identifier.
Transaction type
Required
Length
Format
Yes
20
N
Yes
32
A/N
Yes
Yes
1
32
A
A/N
Comments
V=Void
Request:
Pragma: no-cache
Content-Length: 578
nsaction_type=V&transaction_id=bd5661892d69399f8879cedb427879e7
47
Response:
transaction_id=d3b221224235331aba05101ae3d35340&error_code=000&auth_response_tex
t=Void Request Accepted
9.3 Store card Transactions
9.3.1 Store card
Field Name
profile_id
profile_key
transaction_type
card_number
card_exp_date
Description
Required
Length
Format
Comments
of the incoming
request.
Specifies the API
identifier.
Transaction type
Cardholder account
number
Yes
20
N
Yes
32
A/N
Yes
Yes
1
5- 22
A
N
T= Store card data.
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.
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
Request:
Pragma: no-cache
Content-Length: 578
nsaction_type=T&card_number=4012301230123010
Response:
transaction_id=446650ab2a8b3df68390d170cbc0fa0a&error_code=000&auth_response_text
=Card Data Stored
48
9.3.2 Immediate Sale Using Stored Card ID from Store card Sample Above
Field Name
Description
profile_id
Required
Length
Format
Yes
20
N
Yes
32
A/N
card_id
of the incoming
request.
Specifies the API
password assigned
to the specified
profile identifier.
Card Identifier
Yes
32
card_exp_date
Yes
4
profile_key
N
Comments
32-character ID assigned during a
previous store card request.
zero.
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_type
invoice_number
Transaction amount
Transaction type
Cardholders address
data. When present
an AVS request is
issued. Example:
123 Main St.
Cardholder zip or
postal code.
cardholder_zip
Yes
Yes
Yes, for
preferred
Interchange
No
12
1
17
N
A
A/N
Unlimite
d
A/N/+
Yes, for
preferred
Interchange
5 or 9
N
D=Sale
Defined by Visa as 0-9, a-z, A-Z or
spaces.
encoding.
System can only send 19
characters of the address field, will
send first 19.
issued. Example: 55555 or
555554444.
Request:
https://cert.merchante-solutions.com/mesPOST /mes-api/tridentApi HTTP/1.1
Pragma: no-cache
Content-Length: 578
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
49
9.4 Batch Close
9.4.1 Batch Close
Field Name
profile_id
profile_key
transaction_type
Batch_number
Description
of the incoming
request.
Specifies the API
identifier.
Transaction type
Used to specify the
batch number to close
Required
Length
Format
Yes
20
N
Yes
32
A/N
Yes
Yes
1
3
A
N
Comments
Z=Batch Close
Valid values are 1-999. System
edits for duplicate batches and will
reject a batch submitted with the
same batch number within 5
calendar days
Request:
Pragma: no-cache
Content-Length: 578
nsaction_type=Z&batch_number=1
Response:
transaction_id=932f3671fa9f34bc8e1517ebb427b269&error_code=000&auth_response_text=
Batch Closed
9.5 Verification Only
9.5.1 Verification Only
Field Name
profile_id
profile_key
card_number
card_exp_date
Description
of the incoming
request.
Specifies the API
password assigned
to the specified
profile identifier.
Cardholder account
number
Required
Length
Format
Yes
20
N
Yes
32
A/N
Yes
5- 22
N
Yes
4
N
Comments
zero.
50
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
12
0.00
transaction_type
Transaction type
Cardholders address
data. When present
an AVS request is
issued. Example:
123 Main St.
Yes
No
1
Unlimite
d
A
A/N/+
cardholder_zip
Cardholder zip or
postal code. When
present an AVS
request is issued.
Example: 55555 or
555554444.
No
5 or 9
N
Must send a value of 0.00 for this
transaction type.
A=Verification Only
encoding.
send first 19. Only required of
desired for validation
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.
Request:
Pragma: no-cache
Content-Length: 578
nsaction_type=A&cardholder_street_address=123+Main&cardholder_zip=55555&transaction_a
mount=0.00&card_number=4012301230123010&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
9.6.1 Inquiry Transaction
Required Fields
Field Name
profile_id
profile_key
transaction_type
Retry_id
Description
Identifies the source of the
incoming request.
Specifies the API password
assigned to the specified
profile identifier.
Transaction type
Used to look up an Inquiry
transaction
Required
Length
Format
Yes
20
N
Yes
32
A/N
Yes
Yes
1
16
A
A/N
Comments
I=Inquiry
51
Request:
Pragma: no-cache
Content-Length: 578
nsaction_type=I&retry_id=123456
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
9.7.1 Sale with Partial Authorization
Field Name
Description
profile_id
Required
Length
Format
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
Yes
4
N
transaction_amount
transaction_type
invoice_number
Transaction amount
Transaction type
12
1
17
N
A
A/N
Cardholders address
data. When present
an AVS request is
issued. Example:
123 Main St.
Cardholder zip or
postal code.
Yes
Yes
Yes, for
preferred
Interchange
No
Unlimite
d
A/N/+
Yes, for
preferred
Interchange
Y
5 or 9
N
12
D,P
profile_key
card_number
card_exp_date
cardholder_zip
Rctl_partial_auth
Partial_auth
Comments
Submit at MMYY; if the month is
zero.
D=Sale
Defined by Visa as 0-9, a-z, A-Z or
spaces.
encoding.
send first 19.
issued. Example: 55555 or
555554444.
Will contain the authorized amount
(not necessarily the request
amount).
Request:
52
Pragma: no-cache
Content-Length: 578
profile_id=9410000xxxxx000000xx&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=12345
6&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=0.33
53
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_.
10.1 Echo Field Examples
Examples:
Request: ... &echo_my_field=my_field_value
Response: ... &eresp_my_field=my_field_value
Request: ... &echo_customer_id=123456
Response: ... &eresp_customer_id=123456
54
Chapter 11 - Response Control Interface
11.1 Usage
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.
11.2 Response Control Fields
Request Field Name
Response Field Name
Response
Format
Response
Length
Tran
Types
Comments
rctl_product_level
product_level
A/N
2
A,D,P,
J
See Response Field Values below.
Rctl_commercial_card
Rctl_Extended AVS
commercial_card
Extended_AVS
A/N
A/N
1
5
A,D,P
A,D,P
Rctl_account_balance
Account_balance
N
12
D,P
Rctl_partial_auth
Partial_auth
N
12
D,P
rctl_card_number_truncated
card_number_truncated
AN
16
All
rctl_resp_hash
resp_hash
AN
32
All
See Response Field Values below.
Note: this response is a 5 digit field
with each digit corresponding in order
to values in the sections listed below
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.
Will contain the authorized amount
(not necessarily the request amount).
Response will return a truncated
version of the card number. Format is
first 6, last 4 with xxxxxx in the middle:
487165xxxxxx2456
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
205b3665
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
11.3 Response Field Values
Field Name: product_level
Field
Name
Visa Description
MasterCard Description
55
Field
Name
Visa 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
--MasterCard Purchasing
S
Visa Purchasing
S1
Visa Purchasing with Fleet
S2
Visa GSA Purchasing
S3
Visa GSA Purchasing with Fleet
S4
Government Services Loan
MC Commercial with Fleet
56
Field
Name
Visa Description
S5
Commercial Transport EBT
S6
Business Loan
S7
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
Values
B
Business Card
D
Visa Commerce (reserved for future use)
R
Corporate Card
S
Purchasing Card
0
Non-commercial Card
<SPACE>
Invalid Request Indicator Received
Field Name: Rctl_Extended AVS Position 1(Billing Postal Code Result)
Result
Code
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
Field Name: Rctl_Extended AVS Position 2(Billing Address Result)
57
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
Field Name: Rctl_Extended AVS Position 3(Billing First and Last Name)
Result
Code
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
Field Name: Rctl_Extended AVS Position 4(Billing Phone)
Result
Code
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
Field Name: Rctl_Extended AVS Position 5(Billing Email)
Result
Code
Response Message
Response Definition
Y
Match
Billing Email Match
N
No Match
Billing Email No Match
~
Data not sent
Billing Email Data not sent
U
Data Unavailable
Billing Email Data Unavailable
R
Retry
Retry Transaction
S
58
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.
12.2 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.
12.3 FraudDeflector Request Fields
Field Name
cardholder_zip
country_code
ship_to_first_name
ship_to_last_name
ship_to_address
ship_to_zip
dest_country_code
ip_address
cardholder_email
account_creation_date
account_name
Description
Cardholders first name
Cardholders last name
First 20 characters of
the cardholders billing
address. No leading,
trailing zeros permitted
Cardholders billing
postal code
Cardholders billing
country code
First name where goods
will be shipped
Last name where goods
will be shipped
Address where goods
will be shipped
Postal Code where
3 digit numeric country
code where goods will
be shipped
Customer’s Internet IP
address
Cardholders billing
email
date the account was
created on the merchant
system
name assigned to the
account by the
Required
Length
Format
15
A
30
A
19
A/N
No
9
A/N
No
3
N
15
A
30
A
50
A/N
9
A/N
3
N
15
A/N/+
60
A/N/+
10
mm/dd/yyyy
No
No
No
No
No
No
No
No
No
No
Comments
Ex:
[email protected]
om
No
No
Unlimited
A/N
59
Field Name
Description
account_email
account_last_change
cardholder_phone
digital_goods
subscription
merchant
email address
associated with the
account at the merchant
last date the account
was changed
Cardholders billing
phone number
Flag for the purchase of
digital goods
Flag for the a
subscripton (recurring)
service
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
36.00 would be €36
currency_code
fraud_scan
device_id
browser_language
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
Required
Length
Format
Comments
A/N/+
No
mm/dd/yyyy
No
10
No
No
10
Boolean
N
Boolean
No, default
is 840.
N
Boolean (Y,
y, True)
Boolean (Y,
y, True)
3
N
No
Boolean
Boolean (Y,
y, True)
No
Unlimited
A/N
No
Unlimited
A/N
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
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
See section 12.4 for
details on acquiring
the device_id
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="https://ds.bluecava.com/V50/LD/BCLD5.js"></script>
<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>
60
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.
12.5 FraudDeflector Response Fields
Field Name
Description
fraud_result
Length
Value returned based
on parameters set by
merchant in the
Payment Gateway
Back Office.
Format
A/N
Comments
*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.
12.6 FraudDeflector Error Codes
For a complete list of all Payment Gateway error codes please refer to the MeS Payment
Gateway specification.
Response
Code
162
243
244
245
Error Description
Invalid cardholder reference number
Approved by issuer, held for fraud
review
Fraud system recommends denying,
held for review
Fraud system unavailable. Declined
due to strict fraud setting
Required Action
Verify reference number and re-submit transaction
Review transaction in the Payment Gateway Back Office
12.7 FraudDeflector Examples
12.7.1 Sale with ACCEPT response
61
Request
profile_id=94100009999900000006&profile_key=EslVInonBTrSMXZzQapRPPQQwVvjA
Ggi&transaction_type=D&card_number=4012888812348882&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%40email.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
12.7.2 Sale with DENY response
Request
Ggi&transaction_type=D&card_number=4012888812348882&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%40email.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
12.7.3 Pre-Authorization with MANUAL_REVIEW response
Request
Ggi&transaction_type=P&card_number=4012888812348882&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%40email.com&account_last_change=05%2F20%2F2012&digital_goods=true
&subscription=false&device_id=test&browser_language=en
Response
transaction_id=7d38088309123d63971f25a1da60e607&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
62
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 email confirmation that the file was received and a follow up email 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.
13.1 Submitting a Request File
13.1.1 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:
63
13.1.2 Upload via API
All batch API requests are handled by an HTTPS POST to the following URL:
https://www.merchante-solutions.com/srv/api/bpUpload. 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
userID
userPass
profileID
testFlag
Length
32
32
20
Format
A/N
A/N
N
Required
Yes
Yes
Yes
1
Y or N
No
Description
MeS Login ID
MeS Login Password
The MeS Gateway profile
ID the record is
associated with.
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=4012888812348882&card_exp_date=1216&transaction_amount=1.00&cvv2=123
&cardholder_street_address=123+N.+Main&cardholder_zip=55555&invoice_number=123456
13.2 Requesting a Response File
13.2.1 Retrieval via MeS Web Portal
Select Download Response File from the Batch Processing menu:
64
Input the Response File ID and Submit:
File will be returned:
Sample Text Response File:
13.2.1 Retrieval via API
All batch API requests are handled by an HTTPS POST to the following URL:
https://www.merchante-solutions.com/srv/api/bpUpload.
Download Request Fields
Field Name
userID
userPass
respFileID
Length
32
32
15
Format
A/N
A/N
N
Required
Yes
Yes
Yes
Description
MeS Login ID
MeS Login Password
The File ID from the
processed batch
65
Download Response Fields
Field Name
rspCode
Length
3
Format
N
Required
Yes
45
A/N
Yes
rspMessage
Description
Three digit
response/error code.
See section 13.3
Text Message that
accompanies rspCode.
See section 13.3
13.3 Error Codes
Note: these error codes are specific to the batch upload process, like codes are used
when transactions are processed through the Payment Gateway and may be referenced
in section 8.
Response
Code
Error Description
Required Action
000
OK
Batch was successfully received
001
System Error
Contact MeS for research and resolution
002
Authentication Error
Invalid access right or invalid user ID and/or user password
003
Invalid Parameter
Check format to correct the invalid parameter
004
Missing parameter
Check format for missing parameter
300
Invalid Profile ID
301
Invalid response file ID
302
Invalid test flag
303
Batch processing not allowed
Verify Profile ID is correct and resend batch
Verify that user ID, user password, and file ID are valid and
retry
Valid values are Y and N, default is N, field not required.
Please check request file message
Contact MeS, batch processing must be enabled for the profile
ID used
13.4 Email Confirmation
An email will be sent upon successful receipt of a batch, and a follow up email will be sent
once the batch has processed and will contain a response file. Email address is
configured by MeS at the profile ID level.
Sample File Received:
66
-----Original Message----From: [email protected] [mailto:[email protected]]
Sent: Tuesday, November 08, 2011 1:25 PM
To: Benjamin Rice
Subject: MES Payment Gateway Batch File processing was received
DO NOT REPLY TO THIS MESSAGE - This email has been automatically generated.
MERCHANT E-SOLUTIONS
MeS Payment Gateway batch file processing has received and prepared your file for processing. You will
be receiving a second email with the response data.
Please keep in mind that the response data is also available via our standard MeS web reporting options.
If you have any questions about this email, your Merchant e-Solutions merchant account or processing
procedures, please contact our 24-hour Help Desk at 888-288-2692 or [email protected].
Sample File Received:
MERCHANT E-SOLUTIONS
MeS Payment Gateway batch file processed your transactions and prepared a response file. The
attached .txt file contains a response for each of your transactions.
Here is a summary of your file.
# of Transaction: 4 $ Amount: $4.00
# Approved:
4 $ Approved: $4.00
# Declined:
0 $ Declined: $0.00
Please remember this response data is also available via our standard MeS web reporting options.
If you have any questions about this email, your Merchant e-Solutions merchant account or processing
procedures, please contact our 24-hour Help Desk at 888-288-2692 or [email protected].
67
Chapter 14 – Corporate Card Line Item Detail Processing
14.1 Introduction
In order to process Visa and MasterCard Level III transactions and/or American Express
Level II; you must be certified for basic processing on the MeS Payment Gateway. It is
important to submit all fields in the core Payment Gateway specifications for Commercial
Card (table 7.4) for Visa, MasterCard, and American Express.
These additional fields are only supported by Immediate Sale (D) and Settle (S)
transaction types. Attempting to send this additional data with other transaction types will
result in an error (EC 136). In the case of submission of a pre-authorization followed by a
settle, these additional fields should only be included in the Settle (S) message.
14.2 Request Fields for Visa and MasterCard Level III
Field Name
Description
line_item_count
Number of line item records
included in the request.
Length
Format
Comments
3
N
merchant_tax_id
customer_tax_id
summary_commodity_code
discount_amount
Merchant VAT Tax Number.
Customer VAT Registration Number
Summary Commodity Code
Discount Amount
20
13
4
12
AN
AN
N
nnnnnnnnnn.nn
shipping_amount
Freight Amount
12
N
nnnnnnnnnn.nn
duty_amount
Duty Amount
12
N
nnnnnnnnnn.nn
ship_to_zip
ship_from_zip
dest_country_code
Destination Postal/Zip Code
Ship from Postal/Zip Code
Destination Country Code
10
10
3
AN
AN
N
vat_invoice_number
order_date
Invoice Reference Number
Order Date
15
6
AN
N
vat_amount
Value Added Tax Amount
12
N
nnnnnnnnnn.nn
alt_tax_amount
MasterCard Alternate Tax Amount
12
N
nnnnnnnnnn.nn
alt_tax_amount_indicator
MasterCard Alternate Tax Indicator
1
Y or N
visa_line_item
Visa Line Item Detail Data
See Visa
table
below
See Visa
table
below
mc_line_item
MasterCard Line Item Detail Data
See MC
table
below
See MC
table
below
Total number of line item detail
records for the transaction.
Required by VI and MC
Required by VI
Required by VI
Required by VI
Required by VI
http://en.wikipedia.org/wiki/ISO_
3166-1_numeric.
Required by VI
YYMMDD
Required by VI
Required by VI
Required by MC
If Y indicate tax amount, if N fill
tax amount with all zeros
Required by MC
Note that subfields are
separated by <|>
For multiple line items, send the
field name followed by the detail
for each item.
Note that subfields are
separated by <|>
For multiple line items, send the
field name followed by the detail
for each item.
68
14.3 Visa Line Item Subfields

Subfields are separated by <|>

Example: 5096<|>carbon dioxide
equipment<|>sales<|>1<|>each<|>33439.93<|>2340.79<|>7.0<|>0.00<|>33439.93<|>D
Field Description
Notes
Item Commodity Code
Maximum 12 characters
Item Descriptor
Product Code
Quantity
Maximum 12 digits
Unit Of Measure
Unit Cost
Maximum 12 digits. Example: 1.35
Vat Tax Amount
Maximum 12 digits
Vat Tax Rate
Maximum 4 digits. 7.5 = 7.5%
Discount Per Line Item
Maximum 12 digits
Line Item Total
Maximum 12 digits
Debit Or Credit Indicator D or C
14.4 MasterCard Line Item Subfields


Example:Signage<|>Pylon<|>1<|>ea<|>000000000000000<|>5.0<|>stat<|>1400.00<|>N<|>N<|>31064.00<|>D<|>0.
00
Field Description
Notes
Item Description
Product Code
Item Quantity
Maximum 12 digits
Item Unit Of Measure
Alternate Tax Identifier
Tax Rate Applied
Maximum 4 digits. 5.25 = 5.25%
Tax Type Applied
Tax Amount
Maximum 12 digits
Discount Indicator
Y or N
Net Or Gross Indicator
G or N
69
Field Description
Notes
Extended Item Amount
Maximum 9 digits
Debit Or Credit Indicator D or C
Discount Amount
Maximum 12 digits
14.5 Request Fields American Express
Field Name
Description
requester_name
cardholder_reference_num
ber
ship_to_zip
vat_amount
line_item_count
amex_line_item
Length
Name of the requester; i.e., the
person who ordered or purchase the
product or service
Reference number used by the
cardholder to identify the
transaction
Destination Postal/Zip Code
Value Added Tax Amount
Sequential number beginning with 1
for each line item.
Submit this name value followed by
subfields
Format
38
A/N,
Upper
Case
17
A/N
10
12
AN
N
3
N
Comments
Optional field, however this data
must be sent if provided by the
merchant’s customer.
nnnnnnnnnn.nn
14.6 American Express Line Item Subfields


Example: &line_item_count=4&amex_line_item=SKILL
SAW<|>4<|>205.50&amex_line_item=NAILS<|>2<|>410.50&amex_line_item=CEDAR LUMBER<|>5<|>399.99&
amex_line_item=BRICKS<|>10<|>675.45
Description
Length
Concise description of the item(s)
purchased. Generic descriptions
like “MERCHANDISE” should be
avoided.
This field contains the quantities
that correspond to the item(s)
described in the preceding field.
This field contains the unit cost that
corresponds to the item(s)
described in the preceding field.
Format
40
A/N,
Upper
Case
3
numeric
12
numeric
Comments
Depending on a submitter’s
processing method this field
may be required. Moreover, if a
merchant’s customer provides
Charge Description Data, these
fields are required.
This field is required if data is
submitted in the corresponding
charge description field
This field is required if data is
submitted in the corresponding
charge description field
14.7 Level III Error Codes
Error
Code
127
Error Description
Invalid Level III Line Item Detail.
Required Action
Correct the data in the line item detail record and
resubmit.
128
Invalid Level III Merchant Tax ID.
Provide a valid Merchant Tax ID.
129
Invalid Level III Customer Tax ID.
Provide a valid Customer Tax ID.
130
Invalid Level III Summary Commodity Code.
Provide a valid Summary Commodity Code.
70
Error
Code
Error Description
Required Action
131
Invalid Level III Ship To Zip.
Provide a valid destination postal code.
132
Invalid Level III Ship From Zip.
Provide a valid source postal code.
133
Invalid Level III Destination Country Code.
Provide a valid Destination Country Code.
134
Invalid Level III VAT Invoice Number.
Provide a valid VAT Invoice Number.
135
Invalid Level III Alternate Tax Indicator.
Provide a valid Alternate Tax Indicator.
136
Transaction type does not support Level III
Remove the level III data OR use a valid transaction
data.
type.
137
Invalid Level III Discount Amount.
Provide a valid Discount Amount.
138
Invalid Level III Duty Amount.
Provide a valid Duty Amount.
139
Invalid Level III Order Date.
Provide a valid Order Date.
140
Invalid Level III VAT Amount.
Provide a valid VAT Amount.
141
Invalid Level III VAT Rate.
Provide a valid VAT Rate.
142
Invalid Level III Alternate Tax Amount.
Provide a valid Alternate Tax Amount.
143
Invalid Level III Line Item Count.
Provide a valid Line Item Count.
144
Invalid Level III Card Type.
Provide valid line item detail data for the card type.
14.8 Sale (D) – Source Code Example
Request Params (line item detail is URL encoded):
Pragma: no-cache
Host: api.merchante-solutions.com
Content-Length: 578
profile_id=94100008043900000004&profile_key=gvQzgKXOTEoDzpzJzROrQQzoKLaEqxjf&tran
saction_type=D&cardholder_street_address=123&cardholder_zip=55555&cvv2=123&transaction
_amount=1.00&card_number=4012888812348882&card_exp_date=1111&invoice_number=209e
3212d67d2b49d&ship_to_zip=99216&ship_from_zip=99212&line_item_count=1&merchant_tax_i
d=123&customer_tax_id=123&summary_commodity_code=123&discount_amount=1.00&shippin
g_amount=1.00&duty_amount=1.00&dest_country_code=840&vat_invoice_number=123&order_
date=090908&vat_amount=1.00&alt_tax_amount=1.00&alt_tax_amount_indicator=Y&visa_line_it
em=5096%3C%7C%3EStuff%3C%7C%3Esales%3C%7C%3E1%3C%7C%3Eeach%3C%7C%3
E123.123%3C%7C%3E1.95%3C%7C%3E7.0%3C%7C%3E0.00%3C%7C%3E66.66%3C%7C%
3ED
Response:
71
transaction_id=8fc94e10b12130f4ab8a8ceeac40fc69&error_code=000&auth_response_text=Ex
act Match&avs_result=Y&cvv2_result=M&auth_code=T2067H
14.9 Settle (S) – Source Code Example
Request Params (line item detail is URL encoded):
Pragma: no-cache
Host: api.merchante-solutions.com
Content-Length: 578
profile_id=94100008043900000004&profile_key=gvQzgKXOTEoDzpzJzROrQQzoKLaEqxjf&tran
saction_type=S&transaction_amount=1.00&transaction_id=0dd82a4f676730c1b789c1f43279dc4
0&invoice_number=e19b17e690b5c053f&ship_from_zip=99212&line_item_count=1&merchant_t
ax_id=123&customer_tax_id=123&summary_commodity_code=123&discount_amount=1.00&shi
pping_amount=1.00&duty_amount=1.00&dest_country_code=840&vat_invoice_number=123&ord
er_date=090908&vat_amount=1.00&alt_tax_amount=1.00&alt_tax_amount_indicator=Y&visa_lin
e_item=5096%3C%7C%3EStuff%3C%7C%3Esales%3C%7C%3E1%3C%7C%3Eeach%3C%7C
%3E123.123%3C%7C%3E1.95%3C%7C%3E7.0%3C%7C%3E0.00%3C%7C%3E66.66%3C%7
C%3ED
Response:
transaction_id=12f3befbd035371b9b82d5920465e071&error_code=000&auth_response_text=S
ettle Request Accepted
72

MeS Gateway ver2.3 - MeS Public - Merchant e

Transcription

Similar documents

Validated Parking at Autopark at Gallery Mall

Private Label Card Management Software

CreditDebit Card Dispute Form

RE/MAX vs. THE INDUSTRY

instructions for housing deposit ($250.00 usd)

XR650 Brochure

Morgan Stanley Smith Barney Benefit Access Quick

Exporting a Transaction History Report

Harborstone Credit Union

Helsinki | 12 November, 2015