Upload
dokhuong
View
234
Download
0
Embed Size (px)
Citation preview
Advanced Gateway Interface (AGI)
Integration Guide
Version 3.03 Updated January 29, 2014
For the latest update, visit our website:
www.forte.net
Forte Payment Systems
500 W. Bethany Road Ste 200
Allen, Texas 75013
(866) 290-5400 / Fax (469) 675-8730
©2008 Payments Gateway Proprietary and Confidential 2
TTaabbllee ooff CCoonntteennttss
Welcome .............................................................................................................. 5 The Integration Process ............................................................................. 6 How to Use This Manual ............................................................................ 7
Message Delivery ............................................................................................... 8
Direct Socket Interface............................................................................... 8 Windows COM Object................................................................................ 9
Raw HTTP POST ...................................................................................... 9 Other Methods ......................................................................................... 10
Message Definitions ......................................................................................... 11 Formatting ................................................................................................ 11
Notes about formatting: ................................................................. 12 Message Composition ............................................................................. 13
The Type Indicator for Data Fields ................................................ 13 Field Requirements ....................................................................... 13
Fields ............................................................................................ 14 Transaction Message Template .................................................... 14 Header Fields ................................................................................ 15
Customer/Order Information Fields ............................................... 15 Recurring Transaction Templates ................................................. 17
Simple monthly payments example .................................................................... 17 Different recurring amount and deferred recurring start date example ............... 17
Recurring Transaction Fields ........................................................ 18
Miscellaneous Fields ..................................................................... 18 Credit Card Transaction Addendum .............................................. 19
Electronic Funds Transfer Message Addendum ........................... 21
Administrative Message Template ................................................ 22
Response Message Addendum .................................................... 23 Convenience Fee Addendum ........................................................ 25 Line Item Addendum ..................................................................... 25
Messages ................................................................................................ 26 Transaction Type .......................................................................... 26
Notes About Setting Up Credit Card Messages ............................ 28 Templates: .......................................................................................................... 28 Fields: ................................................................................................................. 28 Settlement: ......................................................................................................... 28
About Credit Card Transaction Qualification ................................. 29
Electronic Funds Transfer Messages ............................................ 30 Templates: .......................................................................................................... 30 Fields: ................................................................................................................. 30 Settlement: ......................................................................................................... 30
©2008 Payments Gateway Proprietary and Confidential 3
About Recurring Transaction Administration / Messages .............. 31 Varying the payment amount between the first and subsequent payments ........ 31 Varying the date of recurring payments .............................................................. 32
Creating recurring transactions without a payment on the date of sale .............. 32 Response Messages ............................................................................... 34
Testing ............................................................................................................... 35 How to Prepare for Testing ...................................................................... 35
Port Numbers and URLs ............................................................... 35
Differences Between Test and Live Servers ............................................ 36 Going Live ......................................................................................................... 37
Are You Ready? ...................................................................................... 37 Setting Up the Live Account ..................................................................... 37
Best Practices ................................................................................................... 38 Tools Available to Help You ..................................................................... 38 Central Point of Contact ........................................................................... 38
How to Obtain Help from Payments Gateway .......................................... 38
Reconciliation is Critical for EFTs ............................................................ 39 Documentation is the Key to Easier Maintenance ................................... 39 Ask Questions .......................................................................................... 40
Appendices ....................................................................................................... 41
Appendix A: Response Codes ................................................................. 41
Approved and Declined Responses .............................................. 41 Formatting Error Responses ......................................................... 45
Fatal Exceptions Responses ......................................................... 45 Appendix B: ATMVerify ............................................................................ 47
Overview1
...................................................................................... 47 ATMVerify Level 2 (account verification) ....................................... 47
ATMVerify Level 4 (negative database) ........................................ 47 Using ATMVerify ........................................................................... 48 Response Values .......................................................................... 48
Approval and ATMVerify ............................................................... 49 Testing .......................................................................................... 49
How the Authorization Process Works with ATMVerify ............................ 50 Appendix C: AVS (Address Verification System) and other Verification Services ................................................................................................... 51
Notes about AVS verifications ....................................................... 51 Credit Card Account Checks (positions 1 & 2):................................................... 51
State/Zipcode and State/Area Code Checks (positions 3 & 4): .......................... 52 Anonymous Email Check (position 5): ................................................................ 52 Implicit AVS checks ............................................................................................ 52
Appendix D: Example Messages ............................................................. 53
Credit Card Message Examples.................................................... 53
Glossary ............................................................................................................ 58 ACH .............................................................................................. 58 Approval ........................................................................................ 58 Authorization ................................................................................. 58
©2008 Payments Gateway Proprietary and Confidential 4
Authorization Code ........................................................................ 58 Auth Only ...................................................................................... 58 Capture ......................................................................................... 59
COM .............................................................................................. 59 Decline .......................................................................................... 59 DSI ................................................................................................ 59 EFT ............................................................................................... 59 Merchant ID .................................................................................. 59
Pre Auth ........................................................................................ 59 Pre Notification .............................................................................. 59
Procurement Card ......................................................................... 60 RAW .............................................................................................. 60 Reversal ........................................................................................ 60 Settlement ..................................................................................... 60 SIC ................................................................................................ 60
SSL ............................................................................................... 60
Travel and Entertainment Card ..................................................... 60 Void ............................................................................................... 60
Index .................................................................................................................. 62
©2008 Payments Gateway Proprietary and Confidential 5
CChhaapptteerr 11
WWeellccoommee
Thank you for selecting the Payments Gateway (PG) system to process your financial transactions. We at Payments Gateway (Payments Gateway) appreciate your business and look forward to a successful integration project.
The PG system processes financial transactions for merchants, including credit card, recurring transactions (such as recurring payments), and electronic funds transfers (EFTs). Once your system is properly set up and integration is complete, credit card and purchase information will be entered at your point of purchase via card swipe or key entry, then transmitted automatically to the PG system. There the system will process the information and approve, deny or otherwise respond to the transaction, then return a response to the point of purchase.
In addition to processing the transaction, the PG system allows your team to view transaction details online as soon as they are complete via the Virtual Terminal website at www.PaymentsGateway.net (subject to security clearance, which you control).
This guide is intended for use by your technical team or developer who has an understanding of and experience with the following:
Basic programming skills
Basic integration skills and formats
Your in-house swipe card system’s formats and protocols
SSL, Windows COM or RAW HTTP Data methods of data transmission
In addition to technical instructions, we have also included tips for running a successful integration project, including best practices for integration setup, testing and go-live.
For assistance during integration, please contact please contact technicians at Payments Gateway.
After integration is complete, contact Customer Service at the following number: 800-337-3060, option 1.
©2008 Payments Gateway Proprietary and Confidential 6
TThhee IInntteeggrraattiioonn PPrroocceessss
This process is used by:
New customers who want to set up and integrate PG with their current payment processing system.
Current users of PG who wish to make changes to their delivery method or messages.
The integration process includes the following stages:
1. Define Delivery Method
2. Define Message Composition
3. Testing
4. Going Live
This manual provides information you need to complete the integration process, including many best practices we’ve learned through many years of helping customers with integration projects.
For example, see the following tip.
Tip: Project Management Best Practices
It has been our experience that the clients who have the easiest, most trouble-free integration projects usually assign an integration project manager. For this reason, we recommend that all clients assign someone to manage their integration project.
In large organizations project managers are normally assigned full-time to integration projects, but in smaller organizations, this is not necessarily so. For a smaller project, the project manager may be the same person who performs the setup work, or perhaps the manager of the technical team. The person assigned to take on the role of project manager should be able to:
Create a comprehensive list of tasks to be completed
Create a list of needed resources (either full- or part-time), and work with management to obtain those resources for the dates and durations needed
Manage team members to ensure they complete all tasks on time
Be available on a full time basis, if needed, during the testing and go-live phases of the integration project to ensure that:
All testing is complete and thorough
All staff members are trained on the new system, and
Go-live is handled efficiently and is successful.
©2008 Payments Gateway Proprietary and Confidential 7
HHooww ttoo UUssee TThhiiss MMaannuuaall
First you must decide which delivery method is appropriate for your integration. In the Define Delivery Method chapter, each method is described, along with recommendations for their use and pros and cons for each.
The Message Composition chapter describes how to complete the second phase of the integration process, composing messages using message types and associated data fields. This chapter is an essential reference tool for any user setting up new messages, but we also recommend that you supplement this chapter by adding your own notes about the messages you create, what they mean within your organization, and what action is to be taken when they are encountered.
The Testing chapter describes how to test the messages you’ve composed, and the options and test methods available on the test server. The importance of complete and thorough testing cannot be overemphasized. It is the key to positive go-live experience for your staff and will keep overall costs of integration low (in terms of time and effort spent on training and troubleshooting problems).
The Go-Live chapter details the final steps in the integration process. When testing is completed, all data can be moved from the test server to the live server, a process called “go-live” or “going live.” If testing has been thorough, this process will be smooth and problem free.
We offer the Recommendations chapter to provide your team with additional best practices information and suggestions about what types of documentation you should create and maintain for your system administrator and users.
The Appendices offer additional details and reference information.
A Glossary is located near the end of the document to provide explanations of unfamiliar terms, and an Index is provided to make this guide easier to use.
©2008 Payments Gateway Proprietary and Confidential 8
CChhaapptteerr 22
MMeessssaaggee DDeelliivveerryy
The first stage in the integration process is selecting the correct message delivery method for your situation. There are several options available for delivering messages:
Direct Socket Interface (DSI): Our recommended method, this is the native method for the PG system and is a Secure Sockets Layer connection
Windows COM Object: If you use a WindowsTM platform, you may use a COM object to deliver transaction messages securely
RAW HTTP Post: This method uses the HTTP POST protocol to securely deliver messages, and this is not a preferred method. It is not as efficient since all transactions are routed through the PaymentsGateway.net web server. We recommend that you use this method only if:
You are unable to do SSL operations, and
You do not run on Windows platforms
Other options
Each of these options is described in the following pages.
DDiirreecctt SSoocckkeett IInntteerrffaaccee
The Direct Socket Interface (DSI) delivery method is the native communication method for the PG system, and uses the Secure Sockets Layer (SSL) protocol. Therefore, authorization request messages are written to an SSL connection, and response messages are subsequently read from an SSL connection. This is the preferred method of message delivery since messages are transmitted directly to the transaction processors.
It is important to note that when sending messages via DSI, the newline (hard return) character must be used as the end-of-line (EOL) character. Also, test and live messages will be sent to different ports.
1. Secure socket is connected
2. Transaction message text is written to socket
3. Response message text is read from socket
4. Secure socket is closed
Figure 2.1: Sequence of events for DSI transactions
©2008 Payments Gateway Proprietary and Confidential 9
The DSI method may be implemented using the merchant’s custom server-side software, or CGI scripts using any programming language that supports secure sockets. There are some coding examples in Perl and Java available on the Payments Gateway website for download.
NOTE: Be sure the appropriate ports are allowed through the merchant’s firewall.
WWiinnddoowwss CCOOMM OObbjjeecctt
Merchants using a Windows platform can use the PG COM object to deliver their transaction messages securely. Messages sent and received will be newline delimited. The calls to the COM objects will include an argument to indicate whether the message is to be sent to the live or test server. For merchants anticipating a high transactional volume, we recommend considering other message delivery options as detailed in this chapter. The COM object comes in a zip file containing the DLLs, installation instructions and some example code.
1. Concatenate message into a newline delimited string
2. Call COM object with message string and test/live indicator
3. Response message is returned by COM object
Figure 2.2-Basic COM object steps
RRaaww HHTTTTPP PPOOSSTT
This method uses the HTTP POST protocol to securely deliver messages. It is intended for non-Windows merchants unable to do SSL operations but with access to HTTPS routines. The use of this method is discouraged if DSI integration or use of the Windows COM object is possible.
This method is not as efficient as the DSI method since all transactions are routed through the PaymentsGateway.net web server.
1. URL encode the field values (to escape special characters)
2. Concatenate message into an ampersand delimited string
3. Set the message to be passed as the “content” resource
4. Perform the POST (URL provided to approved merchants)
5. Newline delimited response message is returned (not HTML)
Figure 2.3-Generic Raw POST steps
NOTE: This method is designed to be used to send POST messages from the merchant’s server, not from the customer’s browser.
©2008 Payments Gateway Proprietary and Confidential 10
OOtthheerr MMeetthhooddss
The DSI and COM object methods will suit the needs of most merchants integrating with the Payments Gateway. Those merchants unable to use either of those or the Raw POST method should contact technical support to discuss other integration solutions.
©2008 Payments Gateway Proprietary and Confidential 11
CChhaapptteerr 33
MMeessssaaggee DDeeffiinniittiioonnss
This chapter describes how to create messages, including how to format, create content and process PaymentsGateway.net messages.
Generally, there are rules for formatting messages correctly, and there are fields which may be used to create content. A correct combination of formatting and fields creates an acceptable message. To ensure your message is processed correctly by the PG system, you must test them and have them certified by Payments Gateway before they can be moved to the “live” production server (and therefore made available for use in your system).
This chapter addresses the content and format of messages. Later, in the testing section, we’ll explain how to access the system and enter the messages you compose here.
Tip: Document message meanings and follow-up instructions
You may find it easier to compose and document messages at the same time by drafting messages in a word processing program. As you create messages, document the purpose of each and who approved the content. This will make future maintenance easier for you or whoever is responsible for maintenance. We also recommend that someone in your organization document the purpose and follow-up procedures for each message, for employee training purposes. This may be done by whoever is responsible for training employees, or by the integration project manager.
FFoorrmmaattttiinngg
PaymentsGateway.net messages are made up of pairs of name/value fields in the following format: name=number. For example, a merchant ID field might look like the following: pg_merchant_id=1000.
©2008 Payments Gateway Proprietary and Confidential 12
Notes about formatting:
Fields are always ASCII text; no binary data.
Fields must be separated by a newline character when using the DSI and Windows COM Object delivery methods, or an ampersand character when using other delivery methods.
Fields may be placed in any order.
An ‘endofdata’ tag should be placed at the end of the message followed immediately by a newline character for the DSI and Windows COM Object delivery methods. Messages for other delivery options should use the appropriate delimiting character after the tag.
pg_merchant_id=1000
pg_password=abc123
pg_transaction_type=20
pg_total_amount=1.00
ecom_billto_postal_name_first=John
ecom_billto_postal_name_last=Smith
ecom_payment_check_account_type=S
ecom_payment_check_account=012345
ecom_payment_check_trn=123456789
pg_merchant_data_1=just a test
endofdata
Figure 3.1-Example Message
©2008 Payments Gateway Proprietary and Confidential 13
MMeessssaaggee CCoommppoossiittiioonn
Specific types of transactions require that certain content be present for the transaction to be successful. This section provides tables listing which fields are required for each transaction type, along with a description of formatting and any other general requirements for that transaction type.
The Type Indicator for Data Fields
In the following pages, each table includes a Type column/field. The entry in the Type column indicates the expected format of the field. For example, if there is an “N” in the Type column, the field is a numeric field. A list of value data types appears below, and may be used to interpret the tables in this chapter.
Type Description Characters allowed Case sensitive
M Money 0-9 (and an optional period) N/A
N Numeric 0-9 (no period) N/A
A Alphanumeric any printable ASCII Yes
L List-based value value must be in the specified list No
D Date Format: DD/MM/YYYY N/A
T True/False “TRUE” or “FALSE” only No
Table 3.1-Field value data types
List-based values refer to an additional table that lists acceptable values. The value used in the message must be one included in the value list.
True/False fields are considered false if there is no indicator present in the Type field of the message.
Field Requirements
In the following pages, each table includes a Requirements column. The entry in the Requirements column indicates the when (in what circumstances) the fields may be used. For example, if there is an “M” in the Type column, the field’s use is mandatory. Some fields may have the notation “C” for “Conditional.” When this notation occurs, use of the field is explained in the description section that follows the table.
A list of value data types appears in the following table and may be used to interpret the tables in this chapter.
©2008 Payments Gateway Proprietary and Confidential 14
Code Requirement Description
M Mandatory Must appear when table’s fields are used
O Optional May appear when table’s fields are used
C Conditional See description for exact requirements
R Response Only Only appears in response messages
Table 3.2-Requirement Definitions
Fields
The tables below list the four main field groups with their types and requirements. Detailed information about how to use these fields is provided in subsequent sections of this chapter.
Transaction Message Template
This group of fields makes up a template for the main portion of the transaction message. It is used in conjunction with credit card or EFT addendum groups that follow.
Field Group Field Name Type Requirements
Header
pg_merchant_id N8 M
pg_password A20 M
pg_transaction_type L M
pg_merchant_data_[1-9] A40 O
Customer/ Order Information
pg_total_amount M M
pg_sales_tax_amount M C (PC)
pg_consumer_id A15 O
ecom_consumerorderid A15 O
ecom_walletid A15 O
pg_billto_postal_name_company A20 O
ecom_billto_postal_name_first A25 M
ecom_billto_postal_name_last A25 M
ecom_billto_postal_street_line1 A35 C (AVS)
ecom_billto_postal_street_line2 A35 O
ecom_billto_postal_city A25 O
ecom_billto_postal_stateprov A10 C (AVS)
ecom_billto_postal_postalcode A10 C (AVS)
ecom_billto_postal_countrycode A2 O
ecom_billto_telecom_phone_number A15 C (AVS)
ecom_billto_online_email A40 C (AVS)
pg_billto_ssn A11 O
pg_billto_dl_number A20 O
©2008 Payments Gateway Proprietary and Confidential 15
Field Group Field Name Type Requirements
pg_billto_dl_state A2 O
pg_billto_date_of_birth D O
pg_entered_by A10 O
Recur
pg_schedule_quantity N9 C (R)
pg_schedule_frequency L C (R)
pg_schedule_recurring_amount M C (R)
pg_schedule_start_date D C (R)
Misc.
pg_customer_ip_address A80 O
pg_merchant_recurring T O
pg_software_name A20* O
pg_software_version A20* O
pg_avs_method N5 O
Table 3.3-Transaction Message Template
Header Fields
These fields identify the merchant and transaction type. There are nine additional merchant data fields that will be echoed in the response message.
pg_merchant_id-merchant’s six digit ID code
pg_password-merchant’s processing password
pg_transaction_type-indicates transaction type (see Table 10)
pg_merchant_data_[1-9]-nine fields returned with response fields
Customer/Order Information Fields
These fields contain the transaction details: order, amount and customer information.
pg_total_amount-amount to be charged/credited to customer
pg_sales_tax_amount-sales tax amount; required field for procurement card transactions, optional otherwise
pg_consumer_id-assigned by merchant, returned with response
ecom_consumerorderid-assigned by merchant, returned with response
ecom_walletid-assigned by merchant, returned with response
pg_billto_postal_name_company-company name
ecom_billto_postal_name_first-customer’s first name
ecom_billto_postal_name_last-customer’s last name
©2008 Payments Gateway Proprietary and Confidential 16
ecom_billto_postal_street_line1-customer’s street address
ecom_billto_postal_street_line2-customer’s street address (if necessary)
ecom_billto_postal_city-customer’s city
ecom_billto_postal_stateprov-customer’s state (abbreviated)
ecom_billto_postal_postalcode-customer’s ZIP code
ecom_billto_postal_countrycode-customer’s country
ecom_billto_telecom_phone_number-customer’s phone number
ecom_billto_online_email-customer’s email address
pg_billto_ssn-customer’s social security number
pg_billto_dl_number-customer’s driver’s license number
pg_billto_dl_state-customer’s driver’s license state of issue
pg_billto_date_of_birth-customer’s date of birth (MM/DD/YYYY)
pg_entered_by-name or ID of the person entering the data; appears in the Virtual Terminal transaction display window
(PC) – required for Procurement Card transactions, optional otherwise
(AVS) – required for AVS checks specified in the pg_avs_method field, optional otherwise
©2008 Payments Gateway Proprietary and Confidential 17
Recurring Transaction Templates
Recurring fields are used to establish a recurring transaction. Transactions will be created and processed at the stated frequency (as long as the recurring transaction is in an ‘active’ state). The transactions will be created and processed until the specified quantity is reached (if it is non-zero) or until the transaction is suspended or deleted by the merchant. Voided and declined transactions do not count towards the specified quantity.
If pg_schedule_recurring_amount is specified, the initial transaction will be for pg_total_amount and the subsequent transactions will be for the specified recurring amount. In this case, the initial transaction does not count towards the specified quantity.
The pg_schedule_start_date field is used with pg_schedule_recurring_amount and indicates when the first recurring amount transaction should be created. If the start date is on or before the day the initial transaction is processed, the next start date will be the following day.
It is important to understand that recurring transactions submitted in this manner are based on the initial approved transaction. This means that no recurring transactions will be scheduled if the original transaction is declined. It also means that this method cannot be used to create recurring transactions that do not begin at the time of submission. Setting the initial amount to less than $1 will result in a decline from most credit card processors/banks.
The recurring system cannot create recurring transactions to begin at a later date without the initial transaction approved at time of submission. Setting the initial value to zero will cause most credit card and bank processors to reject the transaction.
Simple monthly payments example
pg_total_amount=10.00
pg_schedule_quantity=12
pg_schedule_frequency=20
In this example, if the transaction is approved, 11 more $10 transactions will be processed on the same day of the month that the initial transaction was approved.
Different recurring amount and deferred recurring start date example
pg_total_amount=100.00
pg_schedule_quantity=8
pg_schedule_frequency=20
pg_schedule_recurring_amount=25.00
pg_schedule_start_date=6/1/2005
In this example, if the initial $100 transaction is approved, 8 more $25 transactions will be processed monthly beginning 6/1/2005.
©2008 Payments Gateway Proprietary and Confidential 18
Recurring Transaction Fields
The following fields are used for processing recurring transactions:
pg_schedule_quantity-specifies the number recurring transactions
pg_schedule_frequency-specifies the frequency of the recurring transaction
Value Frequency Period
10 weekly every seven days
15 biweekly every fourteen days
20 monthly same day every month
25 bi-monthly every two months
30 quarterly every 3 months
35 semiannually twice a year
40 yearly once year
Table 3.4 Frequency Values for Recurring Transactions
pg_schedule_recurring_amount-specifies the amount of the recurring transactions if different from the initial transaction
pg_schedule_start_date-specifies start date of the next recurring transaction, may only be used with pg_schedule_recurring_amount(MM/DD/YYYY)
(R) -recurring transactions must have both pg_schedule_quantity and pg_schedule_frequency, but pg_schedule_recurring_amount and pg_schedule_start_date optional
Miscellaneous Fields
These fields are used by the processor for a variety of applications.
Field Required for
ecom_billto_postal_street_line1 CC street check
ecom_billto_postal_stateprov all state checks
ecom_billto_postal_postalcode ZIP/state check, CC ZIP check
ecom_billto_telecom_phone_number state/area code check
ecom_billto_online_email anonymous email check
Table 3.5-Fields required for AVS checks
©2008 Payments Gateway Proprietary and Confidential 19
pg_customer_ip_address-customer’s originating IP address (will be used for fraud prevention in the future)
pg_merchant_recurring-when used in conjunction with CC transactions, a recurring indicator will be included with the authorization message to the issuer which may affect qualification
pg_software_name-name of the software application used to create the transaction
pg_software_version-version information related to pg_software_name
Note: combined length of both pg_software_name & pg_software_version should be 20 characters or less
pg_avs_method-specifies which AVS checks to perform on the transaction (if any); makes some optional fields required. See Appendix C for more information on AVS.
Credit Card Transaction Addendum
These fields are used in conjunction with the Transaction Message Template, documented starting on page 14.
ecom_payment_card_type-credit card issuer from Table 5-Credit Card Issuer Types below
ecom_payment_card_name-cardholder name as it appears on the card
ecom_payment_card_number-card account number
ecom_payment_card_expdate_month-numeric month of expiration (Jan = 1)
ecom_payment_card_expdate_year-four-digit year of expiration
ecom_payment_card_verification-CVV2/verification number
pg_procurement_card-indicates procurement card transaction, requires pg_sales_tax and pg_customer_acct_code fields
pg_customer_acct_code-accounting information for procurement card transactions
pg_cc_swipe_data-magstripe data from track one or two
pg_cc_enc_swipe_data-full set of swipe data received from the encrypting device
pg_cc_enc_decryptor-eight digit device part number in parenthesis below specifying which swipe device was used. Currently, only the following models and part numbers are supported when capturing encrypted card data:
IPAD w/PIN entry (30050203)
Dynamag (21073062)
iDynamo - used for iPhone mobile apps (21073084)
uDynamo - used for Android mobile apps (21073092)
ecom_3d_secure_data-hexadecimal formatted VPAS/UCAF authorization string that the merchant received from it’s 3D sponsoring organization. 40 bytes for VPAS and 64 bytes for UCAF. Supported authorizing vendor: FirstData
©2008 Payments Gateway Proprietary and Confidential 20
ecom_3d_secure_authenticated-boolean flag indicating VPAS is authenticated (true) or attempted only (false). Supported authorizing vendor: FirstData
Note: The value is converted to ‘true’ by PaymentsGateway’ transaction processor when MasterCard UCAF data is present.
pg_partial_auth_allowed_flag -For merchants approved to process partial authorizations, set this field to override default merchant settings. Merchant accounts are generally provisioned with partial authorizations defaulted to off but can be defaulted to on by contacting our customer service department. Supported authorizing vendors: GlobalPayments and FirstData
pg_mail_or_phone_order-indicates mail order or phone order transaction (as opposed to an Internet-based transaction)
(PC) -pg_customer_acct_code required for procurement card transactions
Type Issuer
VISA VISA
MAST Master Card
AMER American Express
DISC Discover Card
DINE Diner’s Club
JCB JCB
Table 3.6-Credit Card Issuer Types
©2008 Payments Gateway Proprietary and Confidential 21
Field Group
Field Name Type Comments
Credit Card
Ecom_payment_card_type L M
ecom_payment_card_name A50 M
ecom_payment_card_number N16 M
ecom_payment_card_expdate_month N2 M
ecom_payment_card_expdate_year N4 M
ecom_payment_card_verification N5 O
pg_procurement_card T O
pg_customer_acct_code A17 C (PC)
pg_cc_swipe_data A80 O
pg_cc_enc_swipe_data A1500 O
pg_cc_enc_decryptor L20 O
ecom_3d_secure_data
A40 (byte): VPAS authorization string
—or—
A64 (byte): UCAF authorization string
O
ecom_3d_secure_authenticated T O
pg_partial_auth_allowed_flag T O
pg_mail_or_phone_order T O
Table 3.7-Credit Card Message Addendum
Electronic Funds Transfer Message Addendum
The following fields are used in conjunction with the Transaction Message Template, documented starting on page 14.
ecom_payment_check_trn-transit routing number (ABA) for customer’s account
ecom_payment_check_account-customer’s account number
ecom_payment_check_account_type-‘S’ for savings or ‘C’ for checking
ecom_payment_check_checkno-check number for POS transactions
pg_entry_class_code-standard entry class code { ARC, CCD, CIE, CTX, POP, POS, PPD, RCK, TEL, or WEB }
©2008 Payments Gateway Proprietary and Confidential 22
Important: If the entry class code is not specified, the pg_entry_class_code will be defaulted to ‘PPD’ or, if established, the override entry class code value within the Merchant setup. It is important to specify the proper entry class code for each transaction. Improper entry class code usage can result in fines for NACHA rules violations or hurt merchant’s ability to prevent items from being returned (charged back) in customer dispute situations.
Field Name Type Comments
EFT
ecom_payment_check_trn N9 M
ecom_payment_check_account N17 M
ecom_payment_check_account_type L M
ecom_payment_check_checkno N10 O
pg_entry_class_code A3 O
Table 3.8-Electronic Funds Transfer Message Addendum
Administrative Message Template
The Administrative Message Template may be used for various administrative messages. The first four (shaded) fields are in the Header field group and described starting on page 15.
pg_original_trace_number-the trace number returned by the original transaction to be affected
pg_original_authorization_code-the authorization code returned with the above trace number (voids and captures only)
(AC) -The pg_original_authorization_code field is only required for credit card and EFT capture and void transactions.
Field Name Type Comments
Admin
Pg_merchant_id N8 M
pg_password A20 M
pg_transaction_type L M
pg_merchant_data_[1-9] A40 O
pg_original_trace_number A36 M
pg_original_authorization_code A80 C (AC)
Table 3.9-Administrative Message Template
©2008 Payments Gateway Proprietary and Confidential 23
Response Message Addendum
The following table lists fields that may appear in the response message. Some fields are always present, some will be present if they were in the original message, and others will be present based on other criteria including original message transaction type.
The Comments column indicates in what circumstances the fields will appear in the message.
Field Name Type Comments
pg_merchant_id N8 Always present
pg_transaction_type L Always present
pg_merchant_data_[1-9] A40 Echoed if specified
pg_total_amount M Echoed if specified
pg_sales_tax_amount M Echoed if specified
pg_consumer_id A15 Echoed if specified
ecom_consumerorderid A15 Echoed if specified
ecom_walletid A15 Echoed if specified
ecom_billto_postal_name_first A25 Echoed if specified
ecom_billto_postal_name_last A25 Echoed if specified
pg_billto_postal_name_company A20 Echoed if specified
ecom_billto_online_email A40 Echoed if specified
pg_response_type L Always present
pg_response_code A3 Always present
pg_response_description A80 Always present
pg_avs_result N5 Present if AVS method specified
pg_trace_number A36 Always present
pg_authorization_code A80 Present if authorization performed
pg_preauth_result L Present if preauth performed
pg_preauth_description A80 Present if preauth performed
pg_preauth_neg_report A80
Generally provides details on the negative preauth decline and contact information for consumer inquiries when it is available
pg_cvv2_result A1 Present for credit card transactions with CVV2 information sent to GlobalPayments and Vital
pg_3d_secure_result L Present for credit card responses if 3DS verification was performed
©2008 Payments Gateway Proprietary and Confidential 24
Field Name Type Comments
pg_available_card_balance M
Present if partial authorization or balance inquiry was performed and balance was returned by authorizing vendor
pg_requested_amount M The originally requested amount for partially authorized transactions
Table 3.10-Response Message Definition
pg_response_type-single letter response that indicates the success or failure of a transaction: ‘A’ means APPROVAL, ‘D’ means DECLINED, ‘E’ indicates an error occurred.
pg_response_code-three character code representing the transaction result (see the tables in Appendix A)
pg_response_description-text description of transaction result
pg_avs_result-five digits representing the outcome of the requested AVS checks (see Appendix C for detailed information)
pg_trace_number-36 character code uniquely identifying the transaction
pg_authorization_code-approval code from the vendor providing authorization
pg_preauth_result-preauthorization check result (i.e. ATM Verify): POS means positive result, NEG means negative result and UNK means that no information was available.
pg_preauth_description-text description of the preauthorization result
pg_preauth_neg_report-negative database response information (unformatted)
pg_cvv2_result–this field is present in Global and Vital responses for credit card transactions with cvv2 information. Single character result code (“M” for match –or– “N” for no match) Other responses are possible but may be ignored.
Note: Transactions declining or being approved on basis of the CVV2 code is at the sole discretion of the card issuing financial institution.
pg_3d_secure_result–returns values ‘POS’itive,’NEG’ative, or ‘UNK’nown. Like with CVV/AVS, credit card transactions can be approved even with NEG result data. It is up to the merchant to decide if they wish to void the transaction after receiving a NEG or UNK response.
pg_available_card_balance–Field present if partial authorization or balance inquiry was performed and balance was returned by authorizing vendor
pg_requested_amount–The originally requested amount for partially authorized transactions
©2008 Payments Gateway Proprietary and Confidential 25
Convenience Fee Addendum
For merchant accounts approved to process convenience fee transactions, there is an additional field in the transaction request and an additional field in the transaction response. Transaction Request Message pg_total_amount (existing field): the total amount, including convenience fee, to be charged pg_convenience_fee (new field): the amount of the convenience fee The PaymentsGateway will calculate the original amount (total – convenience fee) and check it against the convenience fee information in the database for the merchant account specified in pg_merchant_id. If the convenience fee is incorrect, the transaction will be declined with : pg_response_code=U28 pre_response_description=CONV FEE INCORRECT
Transaction Response Message pg_convenience_fee (new field): the amount of the convenience fee
Line Item Addendum
Up to 100 line items may be included by passing these fields in your transaction message:
Pg_line_item_header – Max: 256 characters* Description of the data elements contained within each line item. This header will be displayed when viewing transaction details within Virtual Terminal. Pg_line_item_[1-100] – Max: 256 characters* Contents of line item formatted according to pg_line_item_header.
*Maximum 8000 characters for all header and item lines
Syntax: Example: pg_line_item_header=col1,col2,col3 pg_line_item_header=SKU,Price,Qty pg_line_item_1=value1,value2,value3 pg_line_item_1=021000021,45.00,2 pg_line_item_2=value1,value2,value3 pg_line_item_2=021000022,36.99,10 pg_line_item_3=value1,value2,value3 pg_line_item_3=021000023,27.50,7
©2008 Payments Gateway Proprietary and Confidential 26
MMeessssaaggeess
This section describes the content of the various messages that the Payments Gateway servers process.
Transaction Type
Every transaction processed must be assigned a transaction type via the pg_transaction_type field. Valid entries for this field are listed in the following table, along with descriptions and comments that explain what the type means in more depth.
Type Description Comments
Credit Card
10 SALE Customer is charged
11 AUTH ONLY Authorization only, CAPTURE transaction required
12 CAPTURE Completes AUTH ONLY transaction
13 CREDIT Customer is credited
14 VOID Cancels non-settled transactions
15 PRE-AUTH Customer charge approved from other source
18 BALANCE INQUIRY
Requests the available balance from a card
EFT
20 SALE Customer is charged
21 AUTH ONLY Authorization only, CAPTURE transaction required
22 CAPTURE Completes AUTH ONLY transaction
23 CREDIT Customer is credited
24 VOID Cancels non-settled transactions
25 FORCE Customer charged (no validation checks)
26 VERIFY ONLY Verification only, no customer charge
Recur
40 SUSPEND Suspends a recurring transaction
41 ACTIVATE Reactivates a recurring transaction
42 DELETE Deletes a recurring transaction
Table 3.11-Transaction Types
10 Credit Card Sale-Customer’s card is charged and will be automatically settled at the end of the day.
11 Credit Card Auth Only-Customer’s card is charged but will not be settled until a Capture message is completed.
12 Credit Card Capture-Completes an Auth Only transaction. The original charge will be settled at the end of the day.
©2008 Payments Gateway Proprietary and Confidential 27
13 Credit Card Credit-Customer’s card is credited and will be automatically settled at the end of the day.
14 Credit Card Void-If the target transaction has not been settled, it will be voided (and will never be settled). Attempts to void a settled transaction will be declined (with an appropriate response code).
15 Credit Card Pre-Auth-The customer’s card is charged using a merchant supplied authorization code (received from the card processor directly). This is sometimes referred to as a Force transaction.
18 Balance Inquiry-For merchant accounts approved to process partial authorization transactions, requests the available balance from a card. For this transaction type, do not include the ‘pg_total_amount’ field. Supported authorizing vendors: GlobalPayments and FirstData
20 EFT Sale-Transaction is completed and the funds will be captured at the end of the day.
21 EFT Auth Only-Transaction is authorized, but the funds are not captured until a Capture message is completed.
22 EFT Capture-Completes an Auth Only transaction. The funds for the original transaction will be captured at the end of the day.
23 EFT Credit-Transaction is completed and the funds will be transferred at the end of the day.
24 EFT Void-If the target transaction has not been settled, it will be voided (and will never be settled). Attempts to void a settled transaction will be declined (with an appropriate response code).
25 EFT Force-Transaction is completed and the funds will be captured at the end of the day. Verification checks are skipped for this type of transaction. You must contact Payments Gateway Customer Service to put an EFT Force into place.
26 EFT Verify Only-Transaction is verified but no authorization is obtained and it cannot be settled. This is for use with ATM Verify. For these transactions, the “Customer/Order Information” fields are all optional except for amount (see Listing 5-EFT Verify Only Transaction).
40 Recurring Suspend-The (active) recurring transaction is put into a suspended state. No more transactions will be generated on its behalf until it is reactivated.
41 Recurring Activate-The (suspended) recurring transaction is returned to an active state. Transactions will be again be generated on its behalf.
42 Recurring Recur - The recurring transaction will be deleted permanently.
©2008 Payments Gateway Proprietary and Confidential 28
Notes About Setting Up Credit Card Messages
Templates:
When setting up messages for Sale, Auth Only, Credit and Pre-Auth messages (types 10,11,13 and 15) use the Transaction Message Template and Credit Card Message Addendum fields.
When creating Capture and Void messages (types 12 and 14), use the Administrative Message Template.
Fields:
The AVS field can be used with Sale and Auth Only transactions (because Credits do not require preauthorization, and Pre-Auth transactions have already been authorized).
Recurring fields can be used only for Sale and Credit messages.
The miscellaneous “Preauth” fields are not used in credit card messages.
Procurement Card transactions must have the pg_procurement_card field set to TRUE and require the sales tax and customer account code as indicated in the tables above.
Magstripe data (track one or two) may be included in the swipe data field. Mail order and phone order transactions must include the pg_mail_or_phone_order field set to “TRUE.”
Settlement:
Sale, Credit and Force transactions are settled at the end of the day.
Auth Only transactions are settled at the end of the day their corresponding Capture message is approved.
Only unsettled transactions may be voided. Voided transactions are never settled.
Capture and Void messages require the original authorization code in addition to the original trace number.
©2008 Payments Gateway Proprietary and Confidential 29
About Credit Card Transaction Qualification
“Downgrading” can occur when a portion of information is missing from the credit card authorization request. This may result in a higher fee for the offending transaction. Downgrading typically (although not always) occurs when a card has to be manually keyed into the system, and some information required by the credit provider is omitted.
To qualify as swipe transactions, retail transactions typically require information in the swipe data fields.
Contact your credit card provider for specific rules. Each credit provider has different rules about what data elements constitute a fully-qualified transaction.
Payments Gateway is not responsible for transaction downgrading. It is your responsibility to contact your credit providers, learn which data elements are required, and ensure your messages contain that data.
TIP: After go-live, contact your credit providers to verify your transactions are fully qualified
We recommend that immediately after go-live, you contact your credit providers to ensure that the information you are sending them meets their standards for a fully-qualified transaction. Contacting them early can help you avoid much needless expense. Some customers have waited until receiving a statement from their provider, only to discover that they were neglecting to enter a key piece of data, resulting in thousands of downgraded transactions.
The following tips may help prevent the downgrading of credit card transactions:
1. Non-swipe transactions should include street address and zipcode so an AVS check can be performed. We also recommend keying in CCV2/CVV2/CIV/CID data.
2. Include invoice, ticket or P.O. numbers in the ecom_consumerorderid field.
3. When keying in purchase and/or corporate cards, use the pg_sales_tax_amount and pg_customer_acct_code fields.
©2008 Payments Gateway Proprietary and Confidential 30
Electronic Funds Transfer Messages
Setting up electronic funds transfer (EFT) messages works exactly as for any other message, with the following notes and exceptions:
Templates:
The Sale, Auth Only, Credit and Force messages (types 20,21,23 and 25) use the Transaction Message Template and Electronic Funds Transfer Message Addendum fields.
The Capture and Void messages (types 22 and 24) use the Administrative Message Template.
Fields:
The AVS field can be used with Sale and Auth Only transactions.
Only Sale, Credit and Force messages can include the recurring fields.
The check number field is only used for Point Of Sale transactions.
Settlement:
Sale, Credit and Force transactions are settled at the end of the day.
Auth Only transactions are settled at the end of the day their corresponding Capture message is approved.
Only unsettled transactions may be voided.
Voided transactions are never settled.
Capture and Void messages require the original authorization code in addition to the original trace number.
©2008 Payments Gateway Proprietary and Confidential 31
About Recurring Transaction Administration / Messages
These messages are used to activate, suspend and delete existing recurring transactions. They use the Administrative Message Template and differ only in their transaction type. Deleted recurring transactions cannot be activated or suspended. The trace number returned by the original transaction is required by these messages.
Recurring transactions are the source of most confusion by end users, because there are several options in how to set up the recurring payments. Instructions for the most-frequently used scenarios are provided below. If you have a question not covered by this guide, please contact Payments Gateway.
Basic Information Appearing Earlier in this Guide
Before going further, please note that there is information about basic recurring transaction fields beginning on page 16 of this guide. Please refer to that section first, before attempting to use the instructions provided here.
All recurring transactions are based and dependent upon the original transaction. At a minimum they must include the following fields:
pg_total_amount amount to be charged on the date of the sale
pg_schedule_quantity number of payments including the original payment (for example, if this number is 12, then there will be 11 more payments following the initial payment on the date of sale)
pg_schedule_frequency how often the payments will recur (for a table of valid codes, see page 18)
Recurring transactions with these three fields have the simplest setup and will produce the following payment structure:
Original date of sale is the same day of the month future payments will be made
All payments will be the same amount; the amount charged on the date of sale
Varying the payment amount between the first and subsequent payments
To create transactions where the amount on the original date of sale is different from the amount of subsequent payments, use the pg_total_amount field to specify the amount to be processed on the date of sale and the pg_schedule_recurring_amount field to specify the amount of recurring payments. For example:
pg_total_amount=53.20 pg_schedule_quantity=12 pg_schedule_frequency=20 pg_schedule_recurring_amount=100.00
In this example, the first payment is in the amount of $53.20. On the same day of the month as the first payment, $100.00 will be deducted from the customer’s account until a
©2008 Payments Gateway Proprietary and Confidential 32
total of 12 payments have been deducted (including the first payment). In other words, there are a total of 12 payments, so the total amount paid equals:
11 x 100 = $1,100.00
1 x 53.20 = $ 53.20
$1,153.20
Varying the date of recurring payments
In many instances, customers want their payments to fall on a specific day of the month. This may be accomplished by using the pg_schedule_start_date field.
To create transactions where the date of the recurring payments is different from that of the original date of sale, use the pg_schedule_start_date field to specify the date when recurring payments should begin. If the start date is on or before the day the initial transaction is processed, the next start date will be the following day. For example:
pg_total_amount=53.20 pg_schedule_quantity=12 pg_schedule_frequency=20 pg_schedule_recurring_amount=100.00 pg_schedule_start_date=5/1/2006
In this example, all details are the same as with the previous example except that the second and subsequent payments will be deducted on the first day of every month.
11 x 100 = $1,100.00 Deducted on the first of every month
1 x 53.20 = $ 53.20 Taken on the date of sale
$1,153.20
Creating recurring transactions without a payment on the date of sale
Since there must be an initial transaction to create the recurring transaction, how can a recurring transaction be created to begin on a future date? You cannot accomplish this by creating a $0 or a $.01 transaction on today’s transaction. Almost all systems will reject those transactions.
Payments Gateway is currently working on an easier way to accomplish this task, but for now we have several options that will work. You may choose the method that works best for you and your staff.
1) Do not submit the transaction until you want the payments to begin. This is a semi-manual workaround which would require your staff to hold transaction records and submit them on the exact date to be used for all future payments. A payment would be taken on that date and on every month thereafter, on the same day of the month. For example, if a customer wishes to purchase a new chair for $1000 and will pay for it over a period of 10 months beginning on the first of next month, your staff member
©2008 Payments Gateway Proprietary and Confidential 33
would need to hold the sales slip until the first of the month, then submit the transaction.
2) Submit a small payment on the day the transaction is set up (e.g., $1.00 is adequate to ensure the transaction is not voided), and then set up the remainder of the payments at the correct amount. For example, to set up the purchase of a $1000 chair over 10 months beginning June 1, 2006, you could set it up as follows: pg_total_amount=1.00 pg_schedule_quantity=10 pg_schedule_frequency=20 pg_schedule_recurring_amount=99.90 pg_schedule_start_date=6/1/2006 In this example, the customer pays $1.00 on the date of purchase and will pay $99.90 per month every month for 10 months, beginning on June 1, 2006. OR, you may also use this method when the purchase amount is not evenly divisible by the number of payments. For example, if the chair, including sales tax cost $1003.38, your staff member could (with the customer’s permission) charge $3.38 to the customer’s card on the day of the sale, and set up the remaining 10 payments of $100, as shown below: pg_total_amount=3.38 pg_schedule_quantity=10 pg_schedule_frequency=20 pg_schedule_recurring_amount=100.00 pg_schedule_start_date=6/1/2006 Note that in this example, the recurring payments have been set up to happen on the first of the month.
3) Set up and run the recurring transaction, then void the original transaction, resulting in recurring payments but no payment on the date of sale. If you choose to use this method, set up the transaction exactly as for method 2, above. Following instructions for that setup (after obtaining confirmation that the transaction is accepted), immediately void the transaction. The first payment (the $1.00 payment) will have been authorized but voided, resulting in no actual charge to the customer’s bank account. However, the recurring transaction information will have been submitted and authorized, causing the future payments to occur as scheduled.
©2008 Payments Gateway Proprietary and Confidential 34
RReessppoonnssee MMeessssaaggeess
There are three possible outcomes for a transaction message: approved, declined or error. The three response fields (type, code and description) will give different levels of detail in all cases.
The response codes are listed in Appendix A and can be classified into three groups: results, formatting errors and exceptions. The results group (codes beginning with “U” or “A”) are responses for successfully processed transactions (approved or declined). The formatting errors group (codes beginning with “F”) are for messages not processed due to one or more errors in the message formatting. The response description field will list the offending fields and the original message is archived to assist in technical support. The exceptions group (codes beginning with “E”) are codes for messages encountering some fatal condition preventing further processing (i.e. bad merchant ID, security error, communications timeout).
The “preauth” fields are responses for EFT transactions utilizing the ATM Verify product. The pg_preauth_result field indicates the status of the account in question. (See Appendix B for more information on ATM Verify processing.)
©2008 Payments Gateway Proprietary and Confidential 35
CChhaapptteerr 44
TTeessttiinngg
Previous chapters detailed the message fields, their use in various message types and the message delivery method. This chapter provides the final pieces of information you need to actually setup, test, certify and bring your system up live with your messages.
When you perform testing on the PG system:
Our servers are available 24x7, every day.
You can build and test at your own pace.
We have provided examples of code you may use.
There are “canned” or preset responses for some messages so you’ll know what response indicates a successful test when conducting testing (listed in Appendices).
When testing is complete, messages are ready to be placed in a live production environment, and the system is ready for operation.
HHooww ttoo PPrreeppaarree ffoorr TTeessttiinngg
In previous chapters, there was no discussion of “hands on” work, or instructions for how to sign on to the PG system, because the task of composing messages should be worked out before entering them into the system.
When you have composed messages you wish to enter into the PG system, you will need a system sign on. This consists of a Merchant ID and processing password that should have been included in the new merchant’s approval letter or package.
Port Numbers and URLs
The port numbers used for testing the DSI delivery method are listed in the table below. The test URL for the POST method is also listed below. If you are using the COM object method, you need only have its second argument set to perform a “test.”
DSI port 6050 (newline delimited, SSL)
DSI port 6051 (ampersand delimited, SSL)
POST https://www.paymentsgateway.net/cgi-bin/posttest.pl
COM Set second argument to “test”
Figure 4.1-Parameters for Test Transactions
©2008 Payments Gateway Proprietary and Confidential 36
DDiiffffeerreenncceess BBeettwweeeenn TTeesstt aanndd LLiivvee SSeerrvveerrss
The test and live servers are virtually the same. The major differences are listed below.
Test CC transactions are run through the authorizing vendors test system
Test CC transactions are never settled
Test EFT transactions are never settled
Test recurring transactions are never processed
Test ATM Verify transactions are run against an internal StarChek test bed
©2008 Payments Gateway Proprietary and Confidential 37
CChhaapptteerr 55
GGooiinngg LLiivvee
“Going live” or “go-live” means that your system is ready to work in a production environment. From a technical standpoint, this step involves a minor change to the delivery method and a call to Payments Gateway to have your live account set up.
Of course, from a logistical standpoint and the point of view of end users, go-live can be a stressful experience if testing has not been conducted thoroughly and adequate training has not been provided. We recommend that you involve the integration project manager and any education/training personnel involved with the project to coordinate schedules and efforts for go-live.
AArree YYoouu RReeaaddyy??
If you have not yet tested all messages you have created, we encourage you to STOP and go back to the testing stage. Time spent on testing will be repaid in terms of time not spent trying to explain what went wrong to every user on the system during go-live.
If training has not been conducted related to messages that users are unfamiliar with, we recommend you STOP and ensure that all users receive instructions on the meaning of messages that have been created and any new procedures for dealing with those messages.
SSeettttiinngg UUpp tthhee LLiivvee AAccccoouunntt
When you are ready, contact Technical Support at Payments Gateway and request that your live account be set up. The following table shows the parameters for live transactions.
DSI port 5050 (newline delimited, SSL)
DSI port 5051 (ampersand delimited, SSL)
POST https://www.paymentsgateway.net/cgi-bin/postauth.pl
COM set second argument to “live”
Figure 5.1-Parameters for Live Transactions
©2008 Payments Gateway Proprietary and Confidential 38
CChhaapptteerr 66
BBeesstt PPrraaccttiicceess
This chapter summarizes best practices for integrating and maintaining the PG system.
TToooollss AAvvaaiillaabbllee ttoo HHeellpp YYoouu
Payments Gateway maintains an excellent web site, which includes the following tools:
Knowledge Base Where your questions can be posted and answered by our experts (http://www.paymentsgateway.com/community/knowledgeBase.aspx).
Integration Support Support for customers currently undergoing integration, or needing assistance with integration or testing issues ([email protected]).
Developer Site Sample code, developer forum, updated documentation, etc. (https://www.paymentsgateway.net/development/login.asp).
CCeennttrraall PPooiinntt ooff CCoonnttaacctt
We have found it is always best to route communications through a central point of contact whenever it is feasible to do so. This allows one person in your organization to understand fully what is going on within the business relationship between you and Payments Gateway, and to keep Payments Gateway updated on important issues.
Please note that it is critical that someone from your organization keep Payments Gateway informed about any changes to messages, schedules or issues that relate to the PG system.
HHooww ttoo OObbttaaiinn HHeellpp ffrroomm PPaayymmeennttss GGaatteewwaayy
We often we receive calls from a member of a client’s staff who needs help with a transaction. While we are always happy to help our customers, there are specific pieces of information we must have to provide assistance. Please train your employees to have the following information on hand when they contact Payments Gateway for help:
Merchant ID
©2008 Payments Gateway Proprietary and Confidential 39
Date of transaction in question
Amount of transaction
Name of purchaser
RReeccoonncciilliiaattiioonn iiss CCrriittiiccaall ffoorr EEFFTTss
The reconciliation process is your responsibility, and it is an often-overlooked process which can be costly if not done properly.
With credit card transactions, you know immediately whether those transactions will be paid. However, with ACH and EFT transactions, settlement will not occur for a minimum of 3-4 days, and chargebacks can occur for up to 90 days.
For this reason, it is very important that you reconcile settlement information with your authorizations on a regular basis. You may obtain your settlement information from Payments Gateway and compare it to your authorizations. If you are pulling down EFT settlement info, a match against transaction results is a good way to ensure accuracy.
Settlement files are available for download from Payments Gateway’s web site. Please see the File Specification Document, available for download from the developer’s repository at https://www.paymentsgateway.net/development/login.asp (if you need a login for that site, contact your Customer Support Representative), or via the Virtual Terminal.
DDooccuummeennttaattiioonn iiss tthhee KKeeyy ttoo EEaassiieerr MMaaiinntteennaannccee
Even if you have the perfect, trouble free integration and go-live, it is critical that you document what you did carefully. Why? So that those having to maintain the system after you will understand what you did and why you did it. You may plan to do the maintenance yourself, but if you are unavailable, say, out with the flu, when a key change must be made immediately, good documentation will allow the needed changes to be made correctly.
Generally, you should document the following:
Delivery Method: Document why the delivery method is selected, the thought process that leads you to select that method, who approves it and the date of the approval.
Messages: Document the business purpose of each message, any alternate drafts considered, who approves the message and the date approved.
Testing: Document the test methods you use (including any test scripts), who participates in the tests, who approves the test results, and dates.
©2008 Payments Gateway Proprietary and Confidential 40
Certification: If any changes are made to messages as a result of certification testing, be sure to adjust the documentation. If staff training is delivered during this phase, archive copies of the training materials. Also, you may wish to document who is trained and on what dates.
Go-live: Document all problems encountered during go-live (if any). Document individuals having problems with particular parts of the system (even if they were trained on how to use it, because there are occasional misunderstandings during training classes).
The reason for all this documentation? In a few months when a problem occurs, you’ll know if it was ever encountered when the system was integrated, tested or during go-live, and whether users were ever trained on that topic. You will then know how to go about researching the problem and contacting the users who need to understand about the correction, or who may need additional information.
Documentation seems to some an unnecessary chore, but the resulting tools can make finding problems in the future faster and easier (and therefore much cheaper).
AAsskk QQuueessttiioonnss
During the integration process or after you are running on a “live” system, be sure to ask questions when you don’t understand something or need a clarification. Please contact Payments Gateway; don’t guess or assume. We’re here to help you!
©2008 Payments Gateway Proprietary and Confidential 41
RReeffeerreennccee
AAppppeennddiicceess
AAppppeennddiixx AA:: RReessppoonnssee CCooddeess
Updated lists of codes, sample files and other information located in these appendices may be found on the Payments Gateway web site for developers:
https://www.paymentsgateway.net/development/login.asp
Please consult the web for the most updated version of this guide and supplemental materials. If you do not yet have a developers login, contact your Payments Gateway Customer Support Representative for assistance.
The pg_response_code values returned in the response message are listed in the tables below.
Approved and Declined Responses
These responses are returned for all processed transactions. The A01 response is the only code ever returned for approved transactions. The “U” codes are for declined transactions. In some cases the pg_response_description field value will differ from that in the “description” column.
Code Description Comments Test Parameters
A01 APPROVED Transaction approved/completed
example transaction messages available in appendix D
A03 PARTIAL AUTHORIZATION
Transaction approved for a partial authorization (CC only)
not available
U01 MERCH AUTH REVOKED
Merchant not allowed to access customer account (EFT only)
not available
U02 ACCOUNT NOT APPROVED
Customer account is in the Payments Gateway “known bad” account list (EFT only)
send eCheck sale transaction with:
routing number : 021000021
account number: 987654321
©2008 Payments Gateway Proprietary and Confidential 42
Code Description Comments Test Parameters
U02 TRN NOT APPROVED Routing number passes checksum test but not valid for ACH
send eCheck sale transaction with routing number: 064000101 and any account number
U03 DAILY TRANS LIMIT Merchant daily limit exceeded (EFT only)
not available
U04 MONTHLY TRANS LIMIT Merchant monthly limit exceeded (EFT only)
not available
U05 AVS FAILURE ZIPCODE AVS state/zipcode check failed
set pg_avs_method = 00200 and send a state and zipcode that do not match
U06 AVS FAILURE AREACODE
AVS state/area code check failed
set pg_avs_method = 00020 and send a state and area code that do not match
U07 AVS FAILURE EMAIL AVS anonymous email check failed
set pg_avs_method = 00002 and send an email address for hotmail.com
U10 DUPLICATE TRANSACTION
Transaction has the same attributes as another transaction within the time set by the merchant
send the same transaction twice within five minutes
U11 RECUR TRANS NOT FOUND
Transaction types 40-42 only
not available
U12 UPDATE NOT ALLOWED Original transaction not voidable or capture-able
send void transaction for declined transaction
U13 ORIG TRANS NOT FOUND
Transaction to be voided or captured was not found
send void transaction for trace number 00000000-0000-0000-0000-000000000000
U14 BAD TYPE FOR ORIG TRANS
Void/capture and original transaction types do not agree (CC/EFT)
send a void cc transaction for an eCheck transaction
U15 ALREADY VOIDED ALREADY CAPTURED
Transaction was previously voided or captured
void the same transaction twice
U18 UPDATE FAILED Void or Capture failed
send a transaction for $19.18 or $1918
U19 INVALID TRN Account ABA number if invalid
send eCheck transaction with TRN of 123456789
U20 INVALID CREDIT CARD NUMBER
Credit card number is invalid
send a CC transaction with a card number of 1111111111111111
©2008 Payments Gateway Proprietary and Confidential 43
Code Description Comments Test Parameters
U21 BAD START DATE Date is malformed send a transaction with scheduling data but
start date of 13/1/2008 or 1/1/2001
U22 SWIPE DATA FAILURE Swipe data is malformed
send CC transaction with pg_cc_swipe_data = ABC123
U23 INVALID EXPIRATION DATE
Malformed expiration date
send CC transaction with Ecom_Payment_Card_ExpDate_Month=13
U25 INVALID AMOUNT Negative amount send a transaction for a negative amount
(-$1.00)
U26 INVALID DATA** Invalid data present in transaction
send a void transaction with pg_original_authorization_code=.
U27 CONV FEE NOT ALLOWED
Merchant sent a convenience fee but is not configured to accept one
For merchants not configured to accept a convenience fee, send a transaction with a convenience fee in pg_convenience_fee
U28 CONV FEE INCORRECT
Merchant configured for convenience fee but did not send one
For merchants configured to accept a convenience fee, send a transaction with an incorrect convenience fee in pg_convenience_fee
U29 CONV FEE DECLINED
Convenience fee transaction failed – SplitCharge model only
N/A
U30 PRINCIPAL DECLINED Principal transaction failed – SplitCharge model only
N/A
U51 MERCHANT STATUS Merchant is not “live”
send a transaction for a non-Live merchant id
U52 TYPE NOT ALLOWED Merchant not approved for transaction type (CC or EFT)
send a transaction of a type (CC,eCheck) that the account is not allowed to process
U53 PER TRANS LIMIT Transaction amount exceeds merchant’s per transaction limit (EFTs only)
send a transaction that exceeds the mechants eCheck limit(s)
U54 INVALID MERCHANT CONFIG
Merchant’s configuration requires updating – call customer support
send a transaction for $19.54 or $1954
U80 PREAUTH DECLINE Transaction was declined due to preauthorization (ATM Verify) result
send a transaction for $19.80 or $1980
©2008 Payments Gateway Proprietary and Confidential 44
Code Description Comments Test Parameters
U81 PREAUTH TIMEOUT Preauthorizer not responding (Verify Only transactions only)
send a transaction for $19.81 or $1981
U82 PREAUTH ERROR Preauthorizer error (Verify Only transactions only)
send a transaction for $19.82 or $1982
U83 AUTH DECLINE* Transaction was declined due to authorizer declination
send a transaction for $19.83, $1983, or $1.33
U84 AUTH TIMEOUT Authorizer not responding
send a transaction for $19.84 or $1984
U85 AUTH ERROR Authorizer error send a transaction for $19.85 or $1985
U86 AVS FAILURE AUTH Authorizer AVS check failed
send a transaction for $19.86 or $1986
U87 AUTH BUSY Authorizing Vendor busy, may be resubmitted (CC only)
send a transaction for $19.87 or $1987
U88 PREAUTH BUSY Verification vendor busy, may be resubmitted (type 26 only)
send a transaction for $19.88 or $1988
U89 AUTH UNAVAIL Vendor service unavailable (CC only)
send a transaction for $19.89 or $1989
U90 PREAUTH UNAVAIL Verification service unavailable (type 26 only)
send a transaction for $19.90 or $1990
POS
pg_3d_secure_result=POS
[response message field]
3DS credit card verification service for enrolled merchants
Send a credit card sale transaction with an ecom_3d_secure_data value starting with ‘7’
UNK
pg_3d_secure_result=UNK [response message field]
3DS credit card verification service for enrolled merchants
Send a credit card sale transaction with an ecom_3d_secure_data value starting with ‘8’
NEG
pg_3d_secure_result=NEG [response message field]
3DS credit card verification service for enrolled merchants
Send a credit card sale transaction with an ecom_3d_secure_data value starting with ‘9’
Table A.1 - Approved and Declined Responses
©2008 Payments Gateway Proprietary and Confidential 45
*pg_response_description will contain the text of the vendor’s response
**pg_response_description will contain a more specific message
Formatting Error Responses
These are the codes returned when formatting errors are found. The response description field will actually list all offending fields in the message (to the 80 character limit). The description field will be formatted as:
<code>:<fieldname>[,<code>:<fieldname> …]
The pg_response_code will contain the first error type encountered. All formatting errors begin with “F”.
Code Description Comments
F01 MANDATORY FIELD MISSING Required field is missing
F03 INVALID FIELD NAME Name is not recognized
F04 INVALID FIELD VALUE Value is not allowed
F05 DUPLICATE FIELD Field is repeated in message
F07 CONFLICTING FIELD Fields cannot both be present
Table A.2- Formatting Error Codes
Fatal Exceptions Responses
These exceptions will stop the processing of a well-formed message due to security or other considerations. All fatal exceptions begin with an “E.”
Code Description Comments
E10 INVALID MERCH OR PASSWD Merchant ID or processing password is incorrect
E20 MERCHANT TIMEOUT Transaction message not received (I/O flush required?)
E55 INVALID TOKEN Specified token was invalid, could not be located, or may have been deleted
Client Token Transactions
For client-token transactions where neither payment fields nor a payment token were specified, the client record does not have a default payment method matching the transaction type
Payment Token Transactions
For payment token transactions where no client token is specified, the payment token must clientless
©2008 Payments Gateway Proprietary and Confidential 46
Both Client and Payment Tokens Present
For transactions with client and payment tokens, the specified payment token is not associated with the client or is clientless
E90 BAD MERCH IP ADDR Originating IP not on merchant’s approved IP list
E99 INTERNAL ERROR An unspecified error has occurred
Table A.3 – Fatal Exceptions
©2008 Payments Gateway Proprietary and Confidential 47
AAppppeennddiixx BB:: AATTMMVVeerriiffyy
Overview1
1ATMVerify is an additional, optional service that provides additional verification of the EFT account number to be debited. These “preauthorization” searches (also called “checks,” not to be confused with a financial “check”) are performed automatically for subscribing merchants (no additional fields required in authorization messages). There are two levels of the ATMVerify service. They can be used in conjunction with each other for maximum coverage and accuracy.
ATMVerify Level 2 (account verification)
This service consults the status reported by the bank to see if the account is valid and in good standing. The response will indicate if the account is open and valid, closed, NSF or one of the other conditions listed in the table below.
There is no charge for transactions involving non-participating banks. (Most tier I & II banks are participants but some local banks and smaller credit unions may not be.) Transactions not receiving a definitive response (such as POS or NEG) may then be checked against our national negative check database. Note that the status of the account may change between the bank’s report and settlement.
ATMVerify Level 4 (negative database)
This service searches a large national database for any negative reports against the account in question. If there are negative reports, the type of report (i.e., NSF) and a phone number for inquiries will be included in the response in the pg_preauth_neg_report field.
The service uses an online inquiry service against a very large experiential database that includes information on 158 million accounts. This database is usually used for accounts that do not participate in ATMVerify. 130 million contain positive information and 28 million contain negative information.
The only definitive responses received from ATMVerify Level 4 are:
P20 There records of one or more are previous bad transactions or checks not reimbursed or “made good”
P21 There were no reports of previous bad transactions or checks in the database
A force can be set up and used to make the system ignore a P20 response. To set up a force, contact Payments Gateway customer service.
©2008 Payments Gateway Proprietary and Confidential 48
Using ATMVerify
If ATMVerify searches are performed there will be up to four additional response fields (see below). The most important field is pg_preauth_result which will indicate the result of the verification. POS will indicate a positive response from a verification service just as NEG will indicate a negative response. UNK means nothing more is known about the account (for various reasons).
pg_preauth_result – The value in this field may cause a transaction to be declined, depending upon your setup. Values which may appear include POS, NEG or UNK.
pg_preauth_description - This field provides additional information about the status of the account. It is the current state of the account as provided by the verifying agent.
pg_preauth_code - This field is not used at the current time.
pg_preauth_neg_report - This field is used with negative database responses and will normally contain the negative report details and (usually) the name and phone number of the reporting entity.
Response Values
The following values are returned in the result and description fields listed above. The possible results are grouped by service level. The listed test account numbers may be used on the test server (with any valid ABA number) to force the indicated response.
Result Description Test Account #
NEG P15:HIGH RISK 99915
UNK P40:NO NEG INFO 99940
NEG P41:NEGATIVE INFO 99941
UNK P50:NO INFO 99950
POS P70:VALIDATED 99970
POS P71:LOW RISK APPROVAL 99971
POS P73:MEDIUM RISK APPROVAL 99973
UNK P80:PREAUTH VENDOR BUSY 99980
UNK P90:PREAUTH VENDOR UNAVAIL 99990
UNK P91:PREAUTH VENDOR ERROR 99991
UNK P92:PREAUTH SERVER UNAVAIL 99992
Table B.1 - ATMVerify Level 2 Responses
©2008 Payments Gateway Proprietary and Confidential 49
Result Description Test Account #
NEG P20:NEG REPORT ITEMS 99920
POS P21:NO NEG REPORTS 99921
NEG P23:INVALID ACCT/ABA NUMBER 99923
UNK P90:PREAUTH VENDOR UNAVAIL 99990
Table B.1 - ATMVerify Level 4 Responses
Approval and ATMVerify
ATMVerify applies only to Sales, Auth Only and Verify Only transactions (types 20, 21 and 26). Transactions with a NEG ATMVerify result will normally be declined for that reason. Those with UNK and POS responses will not be declined and may be subject to other checks. This means that UNK and POS will normally be approved. If the merchant is only using Verify Only transactions they may want to use pg_preauth_result instead of pg_response_type for their decision making.
Testing
The test system will normally generate a POS result for any account (no participating bank check is performed). It can issue specific preauth results by using the account numbers indicated in Table 11-ATMVerify Responses above.
©2008 Payments Gateway Proprietary and Confidential 50
HHooww tthhee AAuutthhoorriizzaattiioonn PPrroocceessss WWoorrkkss wwiitthh AATTMMVVeerriiffyy
For ACH transactions, it is helpful to understand how the PG system works with ATMVerify, and how authorizations are approved based upon the responses received.
Within the PG system, you may set up multiple levels of account verification for ACH items. Each ATMVerify level described in the previous pages is one action available to use in setting up your verification model, and actions can be strung together to obtain the results you want.
In all cases…if the final response is positive, UNK, or account is not found the transaction will be APPROVED. If the final response has negative reports, the transaction will be DECLINED.
Example: Account verifications can be performed in order you prefer:
In this example, the client has chosen to use only ATMVerify Levels 2 and 4, so the system is set up to look only to those levels for verification.
Action 1 Perform ATMVerify Level 2
Result 1 Response UNK received, or account is not a participant,
This model specifies the PG system should go to…
Action 2 Perform ATMVerify Level 4
Result 2 Response received.
©2008 Payments Gateway Proprietary and Confidential 51
AAppppeennddiixx CC:: AAVVSS ((AAddddrreessss VVeerriiffiiccaattiioonn SSyysstteemm)) aanndd
ootthheerr VVeerriiffiiccaattiioonn SSeerrvviicceess
AVS is normally associated with the Address Verification System used by credit card companies (matching the street address number and zipcode with that of the card holders). The Payments Gateway system offers a few more checks along the same lines: State/Zipcode match, State/Area Code match and an Anonymous Email check.
The pg_avs_method field is used to specify what checks to perform and whether or not to decline a transaction if they fail. The pg_avs_results field indicates which checks passed, failed, or where not performed. Both fields consist of five digits, each representing one of the checks mentioned above. The checks represented by each digits position are listed in the table below.
Where X1X2X3X4X5 is the value specified by one of the AVS fields:
X1 = Credit Card Account/Zipcode Check
X2 = Credit Card Account/Street Number Check
X3 = State/Zipcode Check
X4 = State/Area Code Check
X5 = Anonymous Email Check
Figure C.1 - AVS Field: Value Position Definitions
The digits have different values for the method and result fields (as indicated in the listing below).
Pg_avs_method Pg_avs_results
0 Do not perform check 0 Check not performed
1 Check only, do not decline on fail
3 Passed
2 Check and decline on fail 4 Failed
Table C.1 – AVS Field: Value Digit Definitions
Notes about AVS verifications
There are a few unique properties of AVS checks and therefore important things to remember about using them. Please review the following notes.
Credit Card Account Checks (positions 1 & 2):
These checks are only performed for credit card transactions and are ignored for EFT transactions. The merchant’s assigned authorizing agent (i.e. Nova) will perform the checks. The authorizer will authorize the transaction if the AVS checks fail and there is no other reason to decline. If the pg_avs_method position representing a failed check is
©2008 Payments Gateway Proprietary and Confidential 52
set to “2”, the Payments Gateway processor will decline the transaction (and it will not settle).
Note: It is recommended that merchants at least have these checks performed (positions 1 and 2 set to “1”) as they will usually get a better rate from the authorizer.
State/Zipcode and State/Area Code Checks (positions 3 & 4):
These checks compare the customer’s billing address state (official two character abbreviation) and zipcode or area code.
Anonymous Email Check (position 5):
This check compared the customers specified email address against a list of known anonymous email services (i.e. hotmail.com).
Examples:
Method Results Declined Comments
22000 34000 YES declined because the CC street number check failed
11000 34000 NO CC street check failed, but it was “check only”
22001 33004 NO anon email check failed, but was “check only”
00222 00334 YES anon email check failed and was “decline on fail”
Table C.2 – Example of Anonymous Email Check
NOTE: If the required data for a requested AVS check (value of “1” or “2”) is missing, a F01 (mandatory field missing) response code will be return indicating the missing field(s).
Implicit AVS checks
If the zip code and/or street address fields are present for a credit card transaction without pg_avs_method, an AVS check will still be performed. This implicit AVS check will be done silently and no pg_avs_result will be returned.
©2008 Payments Gateway Proprietary and Confidential 53
AAppppeennddiixx DD:: EExxaammppllee MMeessssaaggeess
The following messages illustrate various message types. They are all presented as newline delimited, and the merchant ID and password values have been omitted. A newline character is present after the ‘endofdata’ tag in each messaging example.
Credit Card Message Examples
Example D.1 - Credit Card Sale Transaction
©2008 Payments Gateway Proprietary and Confidential 54
Example D.2 - Credit Card Auth Only Transaction
Example D.3 - Credit Card Capture Transaction
©2008 Payments Gateway Proprietary and Confidential 55
Example D.4 - Credit Card Force Transaction
Example D.5 - Credit Card Sale (initial charge +11 monthly charges)
©2008 Payments Gateway Proprietary and Confidential 56
Example D.6 - EFT Sale Transaction
Example D.7 - EFT Verify Only Transaction
©2008 Payments Gateway Proprietary and Confidential 57
Example D.8 - EFT Void Transaction
Example D.9 - Recurring Admin Delete Transaction
Example D.10 - EFT Sale Transaction Response (with ATM Verify)
©2008 Payments Gateway Proprietary and Confidential 58
GGlloossssaarryy
ACH
Automated Clearing House is a national network for batch-oriented electronic funds transfer. ACH transactions are governed by NACHA operating rules, and provide a method for transferring funds between banks using the Federal Reserve System. Most (but not all) financial institutions use the ACH network.
Types of ACH payments include:
Direct deposits of all types including tax refunds, payroll and government benefits (like Social Security)
Direct payment of bills such as utilities, mortgages, loans and insurance policies;
Federal, state and local tax payments;
Business-to-business payments;
E-checks; and
E-commerce payments.
Approval
An approval is any transaction approved by the credit provider or the check writer’s bank. Approvals are granted after an authorization has been requested by a merchant.
Authorization
Only used for credit card transactions, an authorization is a request from a merchant to charge a cardholder. If approved, the authorization will decrease the customer’s available credit, but will not actually capture any funds. An authorization is the first step in the delayed settlement process, where the merchant may obtain an approval, but it is not settled within a specific period of time, the authorization will expire. The credit provider determines the delay period.
Authorization Code
Numeric or alphanumeric code issued by the credit provider and used to reference the authorization.
Auth Only
In this type of authorization, the merchant does not intent to capture funds until a later date. Often, funds are not captured on these authorizations.
©2008 Payments Gateway Proprietary and Confidential 59
Capture
Refers to the “capture” of funds at the end of a transaction. This typically follows “settlement” of the transaction, where the amount is actually debited to the customer’s account.
COM
Acronym for Component Object Model, COM is a software architecture created by Microsoft and used as a basis for their interprocess communication. COM is language-independent, works within object-oriented programs/designs and is extremely versatile.
In the PG system, COM is an accepted method for data posts, though not the preferred method. DSI is our preferred method (see below).
Decline
A transaction which is not approved by the credit provider/issuer. No authorization is issued.
DSI
Direct Socket Interface (DSI): Our recommended method, this is the native method for the PG system and is a Secure Sockets Layer connection
EFT
Electronic Funds Transfer (EFT) provides for electronic payments and collections. EFT is safe, secure, efficient, and less expensive than paper check payments and collections. EFT is the preferred method of payment for the government. As stated by the Treasury web site “it costs the U.S. government $.83 to issue each check payment, it costs only $.08 to issue an EFT payment.”
Merchant ID
This is the identification number for your organization, used by Payments Gateway to identify you in all communications. It is critical that anyone contacting Payments Gateway for assistance know this ID number.
Pre Auth
This has the same meaning as Auth Only. See that definition, please.
Pre Notification
Prior to sending the first ACH transaction to an ACH receiver or the ACH receiver’s account, the ACH originator may (optionally) send a pre-notification to be processed to the customer’s account. This provides notice of the intent to send additional items and the date on which they will be drafted from the customer’s account.
©2008 Payments Gateway Proprietary and Confidential 60
Procurement Card
Similar to credit cards and gift cards, procurement cards are typically issued by organizations to enable employees to purchase supplies or items for company use.
RAW
In computer terminology, this refers to unprocessed data. This term came originally from the UNIX platform and generally refers to data that is passed along without being interpreted or processed in any way.
The PG system will accept RAW HTTP data posts, but this is not a preferred method. We strongly recommend users adopt the DSI or Windows methods for posting data.
Reversal
If a transaction has already settled and should have been voided, it can be reversed by issuing a credit to correct the error.
Settlement
In this process, authorized transactions are sent to the processor for payment to the merchant. This process finalizes the transaction and allows funds due the merchant to be “captured” and routed to the merchant’s bank for deposit. (In other words, the merchant cannot be paid until the transaction is settled.) It can take several days for funds to reach settlement. Credit card settlement may be within one day, while settlement for checks may take up to 90 days.
SIC
Acronym for Standard Industry Classification, this four-digit code is used to classify types of businesses and industries.
SSL
SSL is an acronym for Secure Sockets Layer, a communications protocol used to transmit private documents or information via the Internet. SSL encrypts data using a private key that is transferred over the SSL connection. Web sites that require an SSL connection have an address that begins with https:// rather than http://.
Travel and Entertainment Card
These credit cards usually require payment in full every month (e.g., American Express, Diner’s Club and Carte Blanche).
Void
To void a transaction is to cancel one that has been authorized, but not yet settled. Settled transactions may not be voided, they must be reversed.
©2008 Payments Gateway Proprietary and Confidential 61
©2008 Payments Gateway Proprietary and Confidential 62
IInnddeexx
A
AC defined, 22
Account verification. See ATMVerify
Account verification order, 50
ACH
defined, 58
Address verification system
about. See AVS
Administrative message template, 22
Anonymous email check. See AVS
Approval
defined, 58
Approved responses
list, 41
Assistance
how to obtain, 5
ATMVerify
about, 47
approval, 49
fields, 48
how the auth process works with, 50
response values list, 48
Auth only
example, 58
Authorization
defined, 58
Authorization code
defined, 58
Authorizations
and ATMVerify, 50
AVS about, 51
field - value digit definitions, 51
field - value position definitions, 51
fields, 16
fields’ unique characteristics, 51
important notes to review, 51
AVS field
use, 30
C
Capture
defined, 59
Check verification. See ATMVerify
Codes
how to obtain updated lists, 41
COM
defined, 59
Convenience Fee
addendum, 25
Credit card
auth only example, 54
auth only transaction type, 26
capture example, 54
capture transaction type, 26
credit transaction type, 27
fields, notes about, 28
force example, 55
issuer types table, 20
message addendum table, 21
message example, 53
pre-auth transaction type, 27
qualification, 29
sale example, 55
sale transaction type, 26
setting up messages, 28
settlement, 28
templates, 28
void transaction type, 27
D
Decline
defined, 59
Declined responses
list, 41
Developer
required skills, 5
Direct Sockets Interface
native method. See DSI
Downgrading, 29
DSI
defined, 59
native method, 8
E
ecom_billto_online_email defined, 16
ecom_billto_postal_city defined, 16
ecom_billto_postal_countrycode defined, 16
ecom_billto_postal_name_first defined, 15
ecom_billto_postal_name_last defined, 15
ecom_billto_postal_postalcode defined, 16
ecom_billto_postal_stateprov defined, 16
ecom_billto_postal_street_line1 defined, 16
ecom_billto_postal_street_line2 defined, 16
ecom_billto_telecom_phone_number defined, 16
©2008 Payments Gateway Proprietary and Confidential 63
ecom_consumerorderid defined, 15
use, 29
ecom_payment_card_expdate_month defined, 19
ecom_payment_card_expdate_year defined, 19
ecom_payment_card_name defined, 19
ecom_payment_card_number defined, 19
ecom_payment_card_type defined, 19
ecom_payment_card_verification defined, 19
ecom_payment_check_account defined, 21
ecom_payment_check_account_type defined, 21
ecom_payment_check_checkno defined, 21
ecom_payment_check_trn defined, 21
ecom_walletid defined, 15
EFT
auth only transaction type, 27
capture transaction type, 27
credit transaction type, 27
defined, 59
esale trans. response w/ATM verify example, 57
fields, 30
force transaction type, 27
message addendum, 21
messages, 30
reconciliation, 39
sale example, 56
sale transaction type, 27
settlement, 30
templates, 30
verify only example, 56
verify only transaction type, 27
void example, 57
void transaction type, 27
F
FAQs
frequently-asked questions, 38
Fatal exceptions responses
list, 45
Fields
ASCII text, 12
conditional, 13
data types, 13
formatting, 12
list-based, 13
mandatory, 13
order & placement, 12
pg_transaction_type, 26
recurring transaction fields, 18
requirements, 13
use newline character, 12
Formatting error responses
list, 45
G
Go live
about. See Going live
Going live
about, 37
H
Help
how to obtain, 38
Help tools, 38
I
Integration
overview of process, 6
project management, 6
K
Knowledge base, 38
L
Line Item
addendum, 25
Live account setup
about, 37
Live production
about. See Going live
M
Merchant identifier / ID
defined, 59
Message delivery
DSI
port numbers, 35
POST method URLs, 35
Messages
administrative - template, 22
composition, 13
content, 26
definitions, 11
delivery method, 8
EFT, 30
examples / samples, 53
formatting, 11
qualification with credit vendors, 29
transaction type, 26
why documentation is important, 11
P
PC defined, 16
©2008 Payments Gateway Proprietary and Confidential 64
pg_authorization_code defined, 24
pg_avs_method
defined, 19
use, 19, 51
pg_avs_result defined, 24
pg_avs_results
use, 51
pg_billto_date_of_birth defined, 16
pg_billto_dl_number defined, 16
pg_billto_dl_state defined, 16
pg_billto_postal_name_company defined, 15
pg_billto_ssn defined, 16
pg_cc_swipe_data defined, 19
pg_consumer_id defined, 15
pg_convenience_fee defined, 25
use, 25
pg_customer_acct_code defined, 19
use, 29
pg_customer_ip_address
defined, 19
pg_cvv2_result defined, 24
pg_entered_by defined, 16
pg_entry_class_code defined, 21
use, 21
Pg_line_item_[1-100] defined, 25
use, 25
Pg_line_item_header defined, 25
use, 25
pg_mail_or_phone_order defined, 20
use, 28
pg_merchant_data_[1-9] defined, 15
pg_merchant_id
defined, 15
pg_merchant_recurring defined, 19
pg_original_authorization_code defined, 22
pg_original_trace_number defined, 22
pg_password defined, 15
pg_preauth_code defined, 48
pg_preauth_description
defined, 24, 48
pg_preauth_neg_report defined, 24
pg_preauth_neg_reports defined, 48
pg_preauth_result defined, 24, 48
use, 34, 49
pg_procurement_card field defined, 19
use, 28
pg_response_code and error type, 45
and error type / code, 45
defined, 24
list of acceptable values, 41
use, 25
pg_response_description defined, 24
list of acceptable values, 41
use and contents, 45
pg_response_type defined, 24
use, 49
pg_sales_tax_amount defined, 15
use, 29
pg_schedule_frequency defined, 18
use, 31
pg_schedule_quantity
defined, 18
use, 31
pg_schedule_recurring_amount defined, 18
use, 31
pg_schedule_start_date defined, 18
use, 32
pg_software_name
defined, 19
use, 19
pg_software_version
defined, 19
use, 19
pg_total_amount defined, 15
use, 25, 31
pg_trace_number defined, 24
pg_transaction_type defined, 15
use, 26
Point of contact, 38
Port numbers, 35
Pre auth
defined, 59
Pre notification
defined, 59
pre_response_description use, 25
Procurement card
©2008 Payments Gateway Proprietary and Confidential 65
defined, 60
Production go-live
about. See Going live
Q
Qualification
for transactions, 29
R
R. See Recurring transactions
RAW
defined, 60
RAW HTTP Post, 9
Reconciliation
EFT, 39
Recurring transactions
about, 31
activate transaction type, 27
delete transaction example, 57
examples, 31
fields, 18
messages, 31
no payment on date of sale, 32
recur (works as delete) transaction type, 27
suspend transaction type, 27
templates, 17
varying date of first and subsequent transactions, 32
Varying first and subsequent payments, 31
Response codes
listing, 41
Responses
approved list, 41
declined list, 41
fatal exceptions list, 45
formatting error list, 45
messages, 34
Reversal
defined, 60
S
Sample files
how to obtain updated lists, 41
Servers, 36
Settlement
defined, 60
SIC
defined, 60
Software downloads, 38
SSL
defined, 60
StarChek, 36
State/Area Code match. See AVS
State/Zipcode match. See AVS
Swipe transactions
what qualifies as, 29
T
Technical support, 38
Templates
administrative message template, 22
credit card transaction addendum, 19
customer/order information, 14, 15
for administrative messages, 22
header, 14, 15
miscellaneous, 15
miscellaneous template and fields, 18
recurring transactions, 15, 17
response message addendum, 23
transaction message main portion, 14
Testing
how to prepare for, 35
overview, 35
servers, 36
Training, 38
Travel and entertainment card
defined, 60
U
URLs, 35
V
Void
defined, 60
W
Windows COM Object, 9