ePay Data, Inc.

Integration Resources
Direct Post API Documentation
June 2007

Table of Contents
Methodology........................................................................................................ 2 Direct Post Method (Server to Server) FIG. 1 ................................................................ 2 Transaction Types .............................................................................................. 3 Sale (sale) ........................................................................................................................ 3 Authorization (auth) ........................................................................................................ 3 Capture (capture) ............................................................................................................ 3 Void (void) ...................................................................................................................... 3 Refund (refund) ............................................................................................................... 3 Credit (credit) .................................................................................................................. 3 Update (update) ............................................................................................................... 3 Transaction Variables ......................................................................................... 4 Sale/Authorization/Credit ............................................................................................... 4 Capture ............................................................................................................................ 5 Void................................................................................................................................. 5 Refund ............................................................................................................................. 5 Update ............................................................................................................................. 5 Transaction Response Variables....................................................................... 6 Standard Response .......................................................................................................... 6 Retail Data ........................................................................................................... 6 Passing Retail Magnetic Stripe Data............................................................................... 6 Testing Information ............................................................................................ 7 Transaction Testing Account .......................................................................................... 7 Transaction POST URL .................................................................................................. 7 Test Transaction Information .......................................................................................... 7 Triggering Errors in Test Mode ...................................................................................... 7 Examples ............................................................................................................. 8 Direct Post Format .......................................................................................................... 8 Changelog ........................................................................................................... 8 Appendix 1 AVS Response Codes ................................................................. 9 Appendix 2 CVV Response Codes ................................................................. 9 Appendix 3 response_code Lookup Table .................................................. 10

Direct Post API

Copyright 2001-2008

All Rights Reserved.

Page | 1

Methodology
There are two primary options in which transactions can be submitted through the Payment Gateway API. The simplest, most direct, and transparent method is our Direct Post Method. This document describes the Direct Post Method.

Direct Post Method (Server to Server) FIG. 1

1. The customer sends their payment information to the merchants web site. 2. The merchants web site posts the payment data to the Payment Gateway. 3. The Payment Gateway responds immediately with the results of the transactions. 4. The merchants web site displays the appropriate message to the customer.

The communication method used to send messages to the Payment Gateways server is the standard HTTP protocol over an SSL connection. In the Direct Post method, the communications with the cardholder (Steps 1 and 4) are developed completely by the merchant and therefore are not defined by the Payment Gateway. Step 1 should simply collect the payment data from the cardholder and Step 4 should display the appropriate transaction receipt or declined message. In Step 2, transaction details should be delivered to the Payment Gateway using the POST method with the appropriate variables defined below posted along with the request. In Step 3, the transaction responses are returned in the body of the HTTP response in a query string name/value format delimited by ampersands. For example: variable1=value1&variable2=value2&variable3=value3

Direct Post API

Copyright 2001-2008

All Rights Reserved.

Page | 2

Transaction Types
Sale (sale)
Transaction sales are submitted and immediately flagged for settlement. These transactions will automatically be settled.

Authorization (auth)
Transaction authorizations are authorized immediately but are not flagged for settlement. These transactions must be flagged for settlement using the capture transaction type. Authorizations typically remain activate for three to seven business days.

Capture (capture)
Transaction captures flag existing authorizations for settlement. Only authorizations can be captured. Captures can be submitted for an amount equal to or less than the original authorization.

Void (void)
Transaction voids will cancel an existing sale or captured authorization. In addition, non-captured authorizations can be voided to prevent any future capture. Voids can only occur if the transaction has not been settled.

Refund (refund)
Transaction refunds will reverse a previously settled transaction. If the transaction has not been settled, it must be voided instead of refunded.

Credit (credit)
Transaction credits apply a negative amount to the cardholders card. In most situations credits are disabled as transaction refunds should be used instead.

Update (update)
Transaction updates can be used to update previous transactions with specific order information, such as a tracking number and shipping carrier.

Direct Post API

Copyright 2001-2008

All Rights Reserved.

Page | 3

Transaction Variables
Sale/Authorization/Credit
Variable Name type Required* Required Format sale / auth / credit Description sale = Transaction Sale auth = Transaction Auth credit = Transaction Credit Username assigned to merchant account Password for the specified username Credit card number Credit card expiration (ie. 0711 = 7/2011) The name on the customers ACH Account. The customers bank routing number The customers bank account number The customers type of ACH account The customers ACH account entity ACH Standard Entry Class codes Total amount to be charged (i.e. 10.00) Card security code Set Payment Type to ACH or Credit Card If using Multiple MIDs, route to this processor. processor_id is obtained under
Options->Load Balancing in the Control Panel

username password ccnumber ccexp checkname checkaba checkaccount account_holder_type account_type sec_code amount cvv payment processor_id dup_seconds descriptor descriptor_phone product_sku_# orderdescription orderid ipaddress tax shipping ponumber firstname lastname company address1 address2 city state zip country phone fax email validation shipping_firstname shipping_lastname

Required Required Required** Required** Required** Required** Required** Required** Required** Optional** Required Recommended Optional ** Optional Optional Optional Optional Optional Optional Optional Recommended Level II Level II Level II Recommended Recommended Optional Recommended Optional Recommended Recommended Recommended Recommended Recommended Optional Recommended Optional Optional Optional

MMYY

business / personal checking / savings

PPD/WEB/TEL/CCD

x.xx creditcard / check

Disable Duplicate checking (in seconds)

(On supported processors)

Set payment descriptor

(On supported processors)

Set payment descriptor phone

(On supported processors)

product_sku_1

xxx.xxx.xxx.xxx x.xx x.xx

CC CC (ISO-3166)

Associate API call with Recurring SKU Order description Order Id IP address of the cardholder Total tax amount Total shipping amount Original Purchase Order Cardholders first name Cardholders last name Cardholders company Card billing address Card billing address line 2 Card billing city Card billing state (2 character abbrev.) Card billing zip code Card billing country (ie. US) Billing phone number Billing fax number Billing email address Specify which Validation processors to use. If
variable is passed blank, use none.

Shipping first name Shipping last name

Direct Post API

Copyright 2001-2008

All Rights Reserved.

Page | 4

shipping_company shipping_address1 shipping_address2 shipping_city shipping_state shipping_zip shipping_country shipping_email

Optional Optional Optional Optional Optional Optional Optional Optional

CC (ISO-3166)

Shipping company Shipping address Shipping address line 2 Shipping city Shipping state Shipping zip code Shipping country (ie. US) Shipping email address

*These fields are required by default. Level II fields are required for Level II processing. Recommended fields help provide additional address and cardholder verification. Please Note, Certain banks may require some optional fields. **You can pass only Credit Card or E-Check transaction variables in a request not both in the same request.

Capture
Variable Name type username password transactionid amount Required Required Required Required Required Required Format capture Description capture = Transaction Capture Username assigned to merchant account Password for the specified username Original Payment Gateway transaction id Total amount to be settled (i.e. 10.00) This amount must be equal to or less than the original authorized amount. Shipping Tracking Number Shipping Carrier Order Id

x.xx

tracking_number shipping_carrier orderid

Optional Optional Optional

ups/fedex/dhl/usps

Void
Variable Name type username password transactionid Required Required Required Required Required Format void Description void = Cancel unsettled Transaction Username assigned to merchant account Password for the specified username Original Payment Gateway transaction id

Refund
Variable Name type username password transactionid amount Required Required Required Required Required Optional Format refund Description refund = Refund Transaction Username assigned to merchant account Password for the specified username Original Payment Gateway transaction id Total amount to be refunded (i.e. 10.00) This amount may be equal to or less than the settled amount.

x.xx

Update
Variable Name type username password transactionid Required Required Required Required Required Format update Description update = Update an un-captured Transaction Username assigned to merchant account Password for the specified username Original Payment Gateway transaction id

Direct Post API

Copyright 2001-2008

All Rights Reserved.

Page | 5

tracking_number shipping_carrier orderid

Optional Optional Optional

ups/fedex/dhl/usps

Shipping Tracking Number Shipping Carrier Order Id

Transaction Response Variables

Standard Response
Variable Name response Format 1/2/3 Description 1 = Transaction Approved 2 = Transaction Declined 3 = Error in transaction data or system error Textual response Transaction authorization code Payment Gateway transaction id AVS Response Code (See Appendix 1) CVV Response Code (See Appendix 2) The original order id passed in the transaction request. Numeric mapping of processor responses (See Appendix 3)

responsetext authcode transactionid avsresponse cvvresponse orderid response_code

C C C

Retail Data
Passing Retail Magnetic Stripe Data
The payment gateway supports passing of magnetic strip data collected from a card reader.
Variable Name track_1 track_2 track_3 Format raw raw raw Description Raw Magnetic Stripe Data Raw Magnetic Stripe Data Raw Magnetic Stripe Data

Direct Post API

Copyright 2001-2008

All Rights Reserved.

Page | 6

Testing Information
Transaction Testing Account
Transactions can be tested using one of two methods. First, transactions can be submitted to any merchant account that is in test mode. Keep in mind that if an account is in test mode, all valid credit cards will be approved but no charges will actually be processed. The Payment Gateway demo account can also be used for testing at any time. Please use the following username and password for testing with this account: Username: Password: demo password

Transaction POST URL

All transactions should be submitted to the following URL: https://secure.epaydatagateway.com/api/transact.php This URL is the same for both Live and Test Mode environments.

Test Transaction Information

Test transactions can be submitted with the following information: Visa MasterCard DiscoverCard American Express Credit Card Expiration: Amount 4111111111111111 5431111111111111 6011601160116611 341111111111111 10/10 > 1.00

Direct Post API

Copyright 2001-2008

All Rights Reserved.

Page | 7

Triggering Errors in Test Mode

To cause a declined message, pass an amount less than 1.00. To trigger a fatal error message, pass an invalid card number. To simulate an AVS Match, pass 888 in the address1 field, 77777 for zip. To simulate a CVV Match, pass 999 in the cvv field.

Examples
Direct Post Format

Data posted by merchants web site to Payment Gateway

username=demo&password=password&type=sale&ccnumber=4111111111 111111&ccexp=0711&cvv=999&amount=10.00
Response data returned to merchants web site in HTML body

response=1&responsetext=SUCCESS&authcode=123456&transactionid=2 81719471&avsresponse=&cvvresponse=M&orderid=&type=sale&response_code=100

Changelog
June 2007 January 2007 July 2006 April 2006 February 2006 Documented product_sku_x Variable Documented processor_id Variable Added Transaction Type Update Added Response Code Appendix Documented Browser Redirect Capability

Direct Post API

Copyright 2001-2008

All Rights Reserved.

Page | 8

Appendix 1 AVS Response Codes

X Y D M A B W Z P L N C U G I R E S 0 O B Exact match, 9-character numeric ZIP Exact match, 5-character numeric ZIP Address match only 9-character numeric ZIP match only 5-character Zip match only No address or ZIP match Address unavailable Non-U.S. Issuer does not participate Issuer system unavailable Not a mail/phone order Service not supported AVS Not Available

Appendix 2 CVV Response Codes

M N P S U CVV2/CVC2 Match CVV2/CVC2 No Match Not Processed Merchant has indicated that CVV2/CVC2 is not present on card Issuer is not certified and/or has not provided Visa encryption keys

Direct Post API

Copyright 2001-2008

All Rights Reserved.

Page | 9

Appendix 3 response_code Lookup Table

Direct Post API

Copyright 2001-2008

All Rights Reserved.

Page | 10