CDS346 - Process First Data Transaction

CDS346

Process First Data Global Gateway Transaction

This called routine is used to process a credit card transaction with First Data using their Global Gateway. This routine is still supported but has been replaced by CDS347 which is used with the First Data Payeezy Gateway.

Currently, only credit card transactions are supported, although check approval transactions may be supported in the future.

CDS346 requires java version 1.8 or higher to be installed on the server and to be executable without including a complete path. Earlier versions of java do not use tls version 1.2 as now required by First Data.

Calling Format:

CALL "CDS346", ERR=XXXX, Y$, S346$

CDS346 Arguments

Argument

Passed
To/From

Variable

Length

Transaction Type

Description

sale, credit, preAuth,
ForceTicket return,
postAuth void

ERR=XXXX

N/A

Error branch taken if:

Store# contains any blanks
Unable to open First Data auth.txt file
auth.txt file does not contain the keyword: Password:
Unable to open First Data keystore password ks.pw.txt file

Y$ To all N/A Session Control Variable

S346$ To .STORENO$ 10 No blanks permitted

.FOLDER$

20+

Defaults to $SMSDIR/bin/firstdata if not provided. Indicates the folder where the First Data script, FirstDataWSClient.sh, and dependent jar files, as well as the sub-directory for each store are located. See complete list below.

FDGGWSApiOrderService-client.jar FirstDataWSClient.class FirstDataWSClient.sh XmlSchema-1.4.3.jar axiom-api-1.2.10.jar axiom-impl-1.2.10.jar axis2-adb-1.5.3.jar axis2-kernel-1.5.3.jar axis2-transport-http-1.5.3.jar axis2-transport-local-1.5.3.jar commons-codec-1.3.jar commons-httpclient-3.1.jar commons-logging-1.1.1.jar httpcore-4.0.jar mail-1.4.jar neethi-2.0.4.jar wsdl4j-1.6.2.jar

An optional sub-folder named 'test' contains versions of 3 files used for 'test' accounts.

test/FDGGWSApiOrderService-test-client.jar

test/FirstDataWSClient.class

test/FirstDataWSClient.sh

A sub-folder is required for each store, where the folder name is the store#. Example:

1909805627

The store sub-folder contains the following files:

ExcellwareTest FDGGWS_Certificate_WS1909805627._.1.tar WS1909805627._.1.auth.txt WS1909805627._.1.key WS1909805627._.1.key.pw.txt WS1909805627._.1.ks WS1909805627._.1.ks.pw.txt WS1909805627._.1.p12 WS1909805627._.1.p12.pw.txt WS1909805627._.1.pem

The ExcellwareTest file, is an optional empty file named to describe the store associated with this store#. The .tar file is downloaded from the First Data web site http://www.firstdata.com/ecommerce for 'live' information, or https://www.staging.yourpay.com for 'test' accounts.. Click on the Virtual Terminal link, then login. You will need the merchants First Data Store#, User ID, and Password to login. Click Support, Download Center, and under Store CERT Files, click Download Now. You will need merchant's Federal Taxpayer ID. Click the Download button next to web service. Save the downloaded .tar file in the store# sub-directory, and un-tar into the 8 files listed above.

To .TEST$ 4+ Pass as 'test' when using a test account. This requires the test directory and 3 test files described above.

To .KEYSTORE$ 20+ Pass the complete path the keystore (.ks) file. Only required when the .ks file is not located in the folder as described above.

To .KEYSTOREPASSWORD$ 20+ Pass the keystore password. Only required when the ks.pw.txt file is not present in the store folder as described above.

From .USERNAME$ 20+ Currently set by CDS346 to the default value based on the store#.

To .PASSWORD$ 10+ Pass the First Data password. Only required when the auth.txt file is not present in the store folder as described above.

.TYPE$

Transaction Type

"cc"	Credit Card
"check"	Check Approval (Not currently implemented)

.TRANSTYPE$

10+

For .TYPE$='cc'
sale	Regular Credit Card Sale
preAuth	Authorization only. Verifies that account is active and transaction will not exceed credit limit
return	Return of original sale
credit	Similar to a return, when the initial transaction was not processed using CDS346.
forceTicket	Used when initial authorization was obtained using a voice telephone call to First Data (not currently implemented)
postAuth	Similar to a Sale when a preAuth transaction was processed previously
void	Used to cancel a prior sale, credit, or postAuth transaction made in the same day.

.ORIGIN$

ECI	Electronic Commerce
MOTO	Mail Order or Telephone Order
RETAIL	Face to Face

To .TRACKDATA$ 100+ X Pass data returned by card swipe device

To .CARDNUMBER$ 16+ X Pass the credit card# with no spaces nor hyphens. Not required when TRACKDATA$ is passed.

To .EXPMONTH$ 2 X Pass the 2 character card expiration month with leading zero when applicable. Not required when TRACKDATA$ is passed.

To .EXPYEAR$ 2 X Pass the 2 character card expiration year with leading zero when applicable. Not required when TRACKDATA$ is passed.

To .CHARGETOTAL 8+ X X Pass the amount to charge or credit. Not a signed field.

To .CARDCODEVALUE$ 4+ X Pass the 3 or 4 digit numeric card security code.

.CARDCODEIND$

10+

Pass the reason the CARDCODEVALUE$ was not provided.

PROVIDED	Indicates the `CARDCODEVALUE` is provided.
ILLEGIBLE	Security Code was not legible on card
NO_IMPRINT	Security Code was not present on card
NOT_PRESENT	The Credit Card was not present to obtain the Security Code
NOT_PROVIDED	Customer declined to provide Security Code

To .NAME$ 35+ X Pass the card holders name. Not required with TRACKDATA$ is passed.

To .ADDRESS1 35+ X Pass the first line of the card holders billing address. Used when address verification is desired.

To .ADDRESS2 35+ X Pass the second line of the card holders billing address when needed. Used when address verification is desired.

To .CITY$ 28+ X Pass the card holders billing city. Used when address verification is desired.

To .STATE$ 2+ X Pass the card holders billing 2 character state code. Used when address verification is desired.

To .ZIPCODE$ 10+ X Pass the card holders billing zip code. Used when address verification is desired.

To .CUSTOMERID$ 10+ X Pass an optional customer identifier.

To .INVOICENUMBER$ 10+ X Pass an optional invoice number to identify the transaction. Appears on First Data reports to assist in reconciling transactions.

To/From

.ORDERID$

50+

From

Order ID generated by First Data to identify a transaction.

TransType	Use
sale	Returned to calling program. Required for 'return' or 'void' transactions.
return	Pass OrderID of original sale to CDS346.
void	Pass OrderID of original sale to CDS346.
preAuth	Returned to calling program. Required for 'postAuth' transactions.
postAuth	Pass OrderID of PreAuth transaction.
credit	Returned to calling program. Required for 'void' transactions.

To/From .TDATE$ 10+ X To Transaction Date in a unique FirstData format, that is used the same as the table above for ORDERID.

To .CHECKNUMBER$ 10+ Pass Check# used for 'check' TYPE.

To .ACCOUNTNUMBER$ 15+ Pass Bank account number for 'check' TYPE.

To .DRIVINGLICENSENO$ 15+ Pass Drivers License# for Check verification.

To .DRIVINGLICENSEST$ 2+ Pass 2 character state code indicating the state that issued the Driver's License.

From

.RESULT$

20+

Transaction Result

APPROVED	Transaction was processed
DECLINED	Transaction was declined
FAILED	Transaction failed, typically because a required field was missing or invalid
FRAUD	Transaction was not processed due to possible fraud such as a stolen credit card.
DUPLICATE	Transaction was not processed as it appears to be a duplicate of a recent transaction.

From .PROCESSORRESCODE$ 1+ X This code is set by First Data but not documented. Use with caution.

From .PROCESSORREFNO$ 20+ X Brief reference number set by First Data used when communication with First Data about a specific transaction.

From .AVSRESPONSE$ 4+ X Codes set by First Data to indicate if the Address and Zip Code provided match the bank's records for the cardholder. Refer here for details.

To .XMLOUT$ 4 X X X Pass as "true" to request XML sent to First Data be returned in XML$ for testing purposes.

From .XML$ 100+ X X X Returned as XML sent to First Data when XMLOUT$="true"

From .ERRORMESSAGE$ 50+ X Error message set by First Data when a transaction is processed, but not approved.

From .ERROR$ 50+ X Error message set by the Dynamo Tools java class when required parameters are missing, or the java class encounters an error.

From .MSG$ 50+ X Set by CDS346 when the ERR= branch will be taken to further describe the situation causing the error.

Note that CDS346 will create an error file named tmp/FirstDataError.txt and should a java error occur, append to this file the java stack trace that is useful when debugging the java code that CDS346 uses.

Example

1230 CALL "CDS041","CDS346",S346$,"YY"
1240 LET S346.STORENO$=CW11.CCSTORENO$
1250 LET S346.CUSTOMERID$=SO40.CUSTNO$
1260 LET S346.INVOICENUMBER$=SO40.SONO$

1270 SWITCH POS(ENT$="CAV"); REM "ENT$=C Charge, A=Authorize Only, V=Void Prior Transaction 1280 CASE 1 1290 IF SO49A.CCSTATUS$="A" THEN LET S346.TRANSTYPE$="postAuth",S346.ORDERID$=SO49A.ORDERID$ ELSE IF SO49A.AMT>0 THEN LET S346.TRANSTYPE$="sale" ELSE IF POS(" "<>SO49A.ORDERID$) THEN LET S346.TRANSTYPE$="return",S346.ORDERID$=

SO49A.ORDERID$ ELSE LET S346.TRANSTYPE$="credit" 1300 BREAK 1310 CASE 2; LET S346.TRANSTYPE$="preAuth"; BREAK 1320 CASE 3; LET S346.TRANSTYPE$="void",S346.ORDERID$=SO49A.ORDERID$,S346.TDATE$=SO49A.TDATE$; BREAK 1330 SWEND 1380 CALL "CDS346",Y$,S346$