cybersource payment manager™ 6 - online credit...

CyberSource Payment Manager™ 6.4API Reference Guide

October 2008

CPM API Reference Guide • CyberSource Corporation • October 2008 ii

CyberSource Contact Information

For questions about CyberSource Payment Manager, [email protected].

For general information about our company, products, and services, go tohttp://www.cybersource.com.

For sales questions about any CyberSource Service, email [email protected] or call 650-965-6000 or 888-330-2300 (toll-free in the United States).

For support information about any CyberSource service, visit the Support Center athttp://www.cybersource.com/support.

Copyright© 2008 CyberSource Corporation. All rights reserved. CyberSource Corporation ("CyberSource") furnishes this document and the software described in this document under the applicable agreement between the reader of this document ("You") and CyberSource ("Agreement"). You may use this document and/or software only in accordance with the terms of the Agreement. Except as expressly set forth in the Agreement, the information contained in this document is subject to change without notice and therefore should not interpreted in any way as a guarantee or warranty by CyberSource. CyberSource assumes no responsibility or liability for any errors that may appear in this document. The copyrighted software that accompanies this document is licensed to You for use only in strict accordance with the Agreement. You should read the Agreement carefully before using the software. Except as permitted by the Agreement, You may not reproduce any part of this document, store this document in a retrieval system, or transmit this document, in any form or by any means, electronic, mechanical, recording, or otherwise, without the prior written consent of CyberSource.

Restricted Rights LegendsFor Government or defense agencies. Use, duplication, or disclosure by the Government or defense agencies is subject to restrictions as set forth the Rights in Technical Data and Computer Software clause at DFARS 252.227-7013 and in similar clauses in the FAR and NASA FAR Supplement.

For civilian agencies. Use, reproduction, or disclosure is subject to restrictions set forth in subparagraphs (a) through (d) of the Commercial Computer Software Restricted Rights clause at 52.227-19 and the limitations set forth in CyberSource Corporation's standard commercial agreement for this software. Unpublished rights reserved under the copyright laws of the United States.

TrademarksCyberSource, the CyberSource logo, SmartCert, and PaylinX are registered trademarks of CyberSource Corporation in the U.S. and other countries. The Power of Payment, CyberSource Payment Manager, CyberSource Risk Manager, CyberSource Decision Manager, and CyberSource Connect are trademarks and/or service marks of CyberSource Corporation. All other brands and product names are trademarks or registered trademarks of their respective owners.

mailto:[email protected]

http://www.cybersource.com

mailto:[email protected]

http://www.cybersource.com/support/

Contents

Documentation Changes and Enhancements ...........................................................................x

Chapter 1Introduction.....................................................................................................................................1CPM API Basics ...............................................................................................................................1

Generic Function Overview....................................................................................................1Generic Flow Chart of Functions ...........................................................................................1Generic Function Detail...........................................................................................................3

Start up ...............................................................................................................................3Shut down ..........................................................................................................................3Set configuration file.........................................................................................................3Open connection ...............................................................................................................3Close connection ...............................................................................................................3Open transaction ...............................................................................................................3Close transaction ...............................................................................................................3Set connection information..............................................................................................4Run transaction .................................................................................................................4Set session ID .....................................................................................................................4Get session ID ....................................................................................................................4Set value .............................................................................................................................4Get value ............................................................................................................................4Get value length ................................................................................................................4Get value pointer...............................................................................................................4Clear values........................................................................................................................5Dump values......................................................................................................................5Print values ........................................................................................................................5

Compatibility ...................................................................................................................................5Supported Platforms.......................................................................................................................5Supported Payment Environments ..............................................................................................6Supported Processor Gateways.....................................................................................................6

CPM API Reference Guide • CyberSource Corporation • October 2008 iii

Contents

CPM API Transactions ...................................................................................................................7Credit Card and Debit Card Transactions............................................................................7

Authorization ....................................................................................................................8Capture ...............................................................................................................................9Authorize and Capture ....................................................................................................9Reversal ..............................................................................................................................9Return ...............................................................................................................................10Void...................................................................................................................................10Manual Authorization....................................................................................................11Lookup..............................................................................................................................11BIN Lookup .....................................................................................................................12

ACH Transactions..................................................................................................................13ACH Verify ......................................................................................................................14ACH Deposit ...................................................................................................................14ACH Refund ....................................................................................................................14ACH Void.........................................................................................................................15ACH Lookup ...................................................................................................................15

Direct Debit Transactions......................................................................................................15Validate.............................................................................................................................16Deposit..............................................................................................................................16Refund ..............................................................................................................................16Void...................................................................................................................................17Lookup..............................................................................................................................17

Generic CPM API Transactions............................................................................................17Admin Command ...........................................................................................................17Begin Session ...................................................................................................................17End Session ......................................................................................................................18Other functions................................................................................................................18

Using the API Transactions .........................................................................................................18Building the CPM API Integration .............................................................................................20

Financial Processor Specifications .......................................................................................20Using the API in a Retail Environment...............................................................................21

Chapter 2CPM API Groups..........................................................................................................................22Base Group .....................................................................................................................................23

PIN-less Debit Cards..............................................................................................................26Extended Information Group ......................................................................................................28

BIN Lookup.............................................................................................................................31Using the Amex Retail Info Field.........................................................................................31

Address Verification Service Group...........................................................................................32Standard AVS .........................................................................................................................32

Visa RED Regulations for AVS .....................................................................................33Enhanced AVS and Automated Address Verification Plus.............................................33

Enhanced AVS.................................................................................................................33Automated Address Verification Plus (AAV+)..........................................................34Configuring the AVS Level for American Express Phoenix.....................................34

PS2000 Group.................................................................................................................................37

CPM API Reference Guide • CyberSource Corporation • October 2008 iv

Contents

Extended Customer Information Group....................................................................................38Customer Name and AVS.....................................................................................................39

Terminal Setup Group..................................................................................................................40Card Verification Value Group ...................................................................................................42ECommerce Group........................................................................................................................44Internet Transaction Data (ITD) Group .....................................................................................48Billing Group (Soft Descriptors)..................................................................................................50Purchasing Card Group ...............................................................................................................51

Using the TAA1 and Charge Description Fields with American Express Phoenix .....54American Express Retail TAA Group ........................................................................................54Level III Purchasing Card Group................................................................................................56Level III Purchasing Card Line Item Detail Group ..................................................................57Health Benefit Card Group..........................................................................................................58Pre-Paid Card Group ....................................................................................................................59User Defined Group......................................................................................................................61Magnetic Track Group..................................................................................................................61

PIN-based Debit Cards..........................................................................................................63Processing a Debit...........................................................................................................63Using the Last Record Number with NOVA..............................................................64

CPM Reserved Group...................................................................................................................65Security Group...............................................................................................................................67Processor Specific Response Group............................................................................................67Private Label Card Group ............................................................................................................68Electronic Fund Transfer Group .................................................................................................70Direct Debit Group........................................................................................................................71Maestro (Switch/Solo) Card Group ...........................................................................................72Hotel and Car Rental Group........................................................................................................72Admin Command Group.............................................................................................................75API Input Notes.............................................................................................................................77

Amount Field..........................................................................................................................77Authorization ..................................................................................................................77Capture .............................................................................................................................77Authorize and Capture ..................................................................................................78Reversal ............................................................................................................................78Return ...............................................................................................................................79Void...................................................................................................................................79Manual Authorization....................................................................................................80Lookup..............................................................................................................................80ACH Verify ......................................................................................................................80ACH Deposit ...................................................................................................................81ACH Refund ....................................................................................................................81

Sequence Number Field ........................................................................................................81

Chapter 3CPM API Function Requirements ............................................................................................83Authorization.................................................................................................................................84

Input.........................................................................................................................................84Output......................................................................................................................................91

CPM API Reference Guide • CyberSource Corporation • October 2008 v

Contents

Capture ...........................................................................................................................................93Input.........................................................................................................................................93Output....................................................................................................................................104

Authorize and Capture...............................................................................................................106Input.......................................................................................................................................106Output....................................................................................................................................117

Reversal.........................................................................................................................................119Input.......................................................................................................................................120Output....................................................................................................................................125

Return............................................................................................................................................127Input.......................................................................................................................................127Output....................................................................................................................................132

Void ...............................................................................................................................................133Input.......................................................................................................................................133Output....................................................................................................................................133

Manual Authorization ................................................................................................................133Input.......................................................................................................................................134Output....................................................................................................................................134

Lookup ..........................................................................................................................................134Input.......................................................................................................................................134Output....................................................................................................................................135

BIN Lookup..................................................................................................................................138Input.......................................................................................................................................138Output....................................................................................................................................138

ACH Verify ..................................................................................................................................139Input.......................................................................................................................................139Output....................................................................................................................................140

ACH Deposit................................................................................................................................141Input.......................................................................................................................................141Output....................................................................................................................................142

ACH Refund ................................................................................................................................143Input.......................................................................................................................................143Output....................................................................................................................................145

ACH Void.....................................................................................................................................146Input.......................................................................................................................................146Output....................................................................................................................................146

ACH Lookup................................................................................................................................147Input.......................................................................................................................................147Output....................................................................................................................................148

Direct Debit Validate ..................................................................................................................149Input.......................................................................................................................................149Output....................................................................................................................................150

Direct Debit Deposit....................................................................................................................151Input.......................................................................................................................................151Output....................................................................................................................................152

Direct Debit Refund ....................................................................................................................153Input.......................................................................................................................................153Output....................................................................................................................................154

CPM API Reference Guide • CyberSource Corporation • October 2008 vi

Contents

Direct Debit Void.........................................................................................................................155Input.......................................................................................................................................155Output....................................................................................................................................156

Direct Debit Lookup ...................................................................................................................157Input.......................................................................................................................................157Output....................................................................................................................................157

Admin Command .......................................................................................................................158Input.......................................................................................................................................158

Begin Session................................................................................................................................159Input.......................................................................................................................................159Output....................................................................................................................................160

End Session...................................................................................................................................160Input.......................................................................................................................................160Output....................................................................................................................................161

Chapter 4CPM API Output Codes............................................................................................................162Transaction Response Code.......................................................................................................162Authorization Response Code...................................................................................................163Address Verification Service Code ...........................................................................................163

Visa RED Regulations for AVS ..........................................................................................164Address Match......................................................................................................................164ZIP Match ..............................................................................................................................165

Card Verification Value Codes..................................................................................................165

Chapter 5CPM API Identifiers ..................................................................................................................167Transaction Type Identifiers ......................................................................................................167CPM API Field Identifiers..........................................................................................................168

Chapter 6CPM Error Identifiers................................................................................................................179Error Descriptions .......................................................................................................................179

Chapter 7Environment and Implementation .........................................................................................184CPM Port Usage ..........................................................................................................................184

CPM API Reference Guide • CyberSource Corporation • October 2008 vii

Contents

ActiveX..........................................................................................................................................185Merchant Information .........................................................................................................185

Configuration File .........................................................................................................185Configuration File Format ...........................................................................................185Server Port and IP Address .........................................................................................186Registry...........................................................................................................................186

Environment Set Up ............................................................................................................186Binding ...........................................................................................................................186

Class Details ..........................................................................................................................187Merchant Class ..............................................................................................................187LCCStoreList Class .......................................................................................................188LCCPayment Class .......................................................................................................190

Sample Code .........................................................................................................................194Batch API ......................................................................................................................................208

Configuration Files ..............................................................................................................209Merchant Information ..................................................................................................209LCC_BATCH.CFG File.................................................................................................210LCC_BATCH_IDS.CFG File ........................................................................................211LCC_BATCH_LENGTHS.CFG File ...........................................................................211

Input File Description..........................................................................................................211Implementing Purchase Card Level III Usage..........................................................212LCC_BATCH_LAYOUT.TXT File ..............................................................................212

Output Files...........................................................................................................................213Working With Output Files.........................................................................................213

Sample Code .........................................................................................................................213C API (Solaris, Win32 dll) ..........................................................................................................226

C Solaris .................................................................................................................................226C Win32 dll............................................................................................................................227Merchant Information .........................................................................................................227

Configuration File .........................................................................................................227Configuration File Location.........................................................................................228

User Security.........................................................................................................................229Environment Set Up ............................................................................................................229

C Solaris..........................................................................................................................229C Win32 dll ....................................................................................................................229

Function Detail .....................................................................................................................229Sample Code .........................................................................................................................238

Java (API)......................................................................................................................................245Merchant Information .........................................................................................................245

Configuration File Format ...........................................................................................245Server Port and IP Address .........................................................................................246

Environment Settings ..........................................................................................................246Security Policy Files .............................................................................................................247

For All Java SDK Users: Updating the Security Policy Files ..................................247For Users of Previous Versions of the Java SDK ......................................................248

Method Details .....................................................................................................................248Sample Code .........................................................................................................................253

CPM API Reference Guide • CyberSource Corporation • October 2008 viii

Contents

Chapter 8CPM Server Test Mode Emulation .........................................................................................259Restrictions ...................................................................................................................................259Approval Codes...........................................................................................................................259Address Match.............................................................................................................................260ZIP Match .....................................................................................................................................260

Chapter 9CPM Server Database Schema.................................................................................................261Sizing the CPM Database ...........................................................................................................261Maintaining the CPM Database ................................................................................................261

Managing the Database.......................................................................................................262CPM RDBMS Support .........................................................................................................262Amount Field Length ..........................................................................................................263

CPM Database Tables .................................................................................................................263Security Tables......................................................................................................................263AGREEMENT Table ............................................................................................................264AGREEMENT_VALUES Table ..........................................................................................264CC_LINEITEM_DETAIL Table..........................................................................................265CC_SETTLEMENT Table ....................................................................................................266CC_TRANSACTION Table ................................................................................................267DB_STATUS Table ...............................................................................................................280EFT_TRANSACTION Table ...............................................................................................280GATEWAY Table .................................................................................................................283GATEWAY_VALUES Table ...............................................................................................284HBC_TRANSACTION Table .............................................................................................284HR_TRANSACTION Table ................................................................................................285MERCHANT Table ..............................................................................................................287MERCHANT_AGREEMENT Table ..................................................................................287MERCHANT_VALUES Table............................................................................................288PLCARD_BENEFICIAL Table ...........................................................................................288PLCARD_GECC Table ........................................................................................................289PX_MESSAGE Table............................................................................................................290SETTLEMENT_LOCK Table ..............................................................................................291TAA_RETAIL_TRANSACTION Table .............................................................................291TAA_TRANSACTION Table .............................................................................................293TID_POOL Table..................................................................................................................294

Database Field and CPM API Field Mapping.........................................................................295CC_TRANSACTION Table ................................................................................................295CC_LINEITEM_DETAIL Table..........................................................................................298EFT_TRANSACTION Table ...............................................................................................298PLCARD_BENEFICIAL Table ...........................................................................................299PLCARD_GECC Table ........................................................................................................300HR_TRANSACTION Table ................................................................................................301TAA_RETAIL_TRANSACTION Table .............................................................................302TAA_TRANSACTION Table .............................................................................................303

Index .............................................................................................................................................304

CPM API Reference Guide • CyberSource Corporation • October 2008 ix

Documentation Changes and Enhancements

The following table lists changes made in recent releases of this document:

Release Changes

6.4 • Added Pre-Paid Card Group.

• Added Health Benefit Card Group.

• Updated database schema.

6.3.3 • Updated the CPM version to 6.3.3.

• Added new methods of payment to the Card Type Fields. See Table 5.

• Added new value to Customer Present Flag. See Table 11.

6.3 • Updated the CPM version to 6.3.

• Added a new group: Internet Transaction Data (ITD) Group on page 48.

• For Paymentech New Hampshire:

- If you are using the ORDER_NUMBER API field, the first 8 bytes (8 characters) must be unique. See ORDER_NUMBER in the CC_TRANSACTION Table on page 267.

- UK Domestic Maestro SecureCode is supported for the Maestro (Switch/Solo) card types. See ECommerce Group on page 44.

- The Merchant Billing Name must be in one of three specific formats. See Billing Group (Soft Descriptors) on page 50.


• Updated gateway processor name: changed Midwest Payment Systems (MPS) to Fifth

Third Processing Solutions (FTPS).


• Updated the descriptions for POS entry mode and terminal capability in Table 11 on

page 40 and Table 105 on page 268.

CPM API Reference Guide • CyberSource Corporation • October 2008 x

Changes


• Added a new field to the Extended Customer Information Group on page 38: Customer

Country.

• Updated the description for CVV Indicator in the Card Verification Value Group on

page 42.

• Added several new API fields to the Purchasing Card Group on page 51: TAA amounts

and TAA quantities.

• Updated Using the TAA1 and Charge Description Fields with American Express Phoenix

on page 54.

• Added a new group: American Express Retail TAA Group on page 54.

• Add information about when track 1 data and/or track 2 data is required to the text

immediately preceding Table 23 on page 62.

• Added several new CPM API field identifiers to Table 93 on page 168: Customer Country,

TAA amounts, TAA quantities, and all the retail fields.

• Added the new TAA fields and retails fields to the requirements for Capture on page 93

and to the requirements for Authorize and Capture on page 106.

• Added new fields to CC_TRANSACTION Table on page 267: POS_DATA_CODE,

CUSTOMER_COUNTRY, and RECUR_ADVICE_CODE.

• Added a new database table: TAA_RETAIL_TRANSACTION Table on page 291.

• Added new fields to TAA_TRANSACTION Table on page 303: TAA quantities and TAA

amounts.

• Added most of the previously mentioned new fields to Database Field and CPM API Field

Mapping on page 295. In addition, added CUSTOMER_COUNTRY, RECUR_ADVICE_CODE, and POS_DATA_CODE to Table 121 on page 295.


• Added the TID_POOL database table. See TID_POOL Table on page 294.

6.2 • Updated the CPM version to 6.2.

• Added a new processing gateway: BA Merchant Services. It is in the list of processors in

Supported Processor Gateways on page 6 and in the list of possible values for the Gateway List API field in Table 32 on page 75.

• Added information about security policy files for Java. See Security Policy Files on

page 247.

Release Changes

CPM API Reference Guide • CyberSource Corporation • October 2008 xi

Chapter 1

Introduction

The CyberSource Payment Manger™ (CPM) API Reference Guide provides information to create an application programming interface (API) for maintaining and extracting merchant information or to create an interface for performing credit card, debit card, direct debit, and Automated Clearing House (ACH) functions on a CPM Server.

You can use the CPM Merchant Editor for managing the merchant information stored in the Windows registry used by CPM Client and the configuration files. For APIs using a configuration file, you can use a text editor such as Windows Notepad or the vi or pico editors in Unix to manage the merchant information. Developing an integration to the CPM API or the CyberSource SDK allows you to maintain merchant information without performing the changes manually on every client computer.

CPM API Basics

Generic Function OverviewThe CPM API consists of a small set of functions that allow the developer to create, execute, and examine transactions. This chapter describes the basic concepts of the CPM API functions. This overview does not apply to the Batch API.

Generic Flow Chart of FunctionsTo perform a transaction, perform the following steps. See Generic Function Detail on page 3 for information for the function names.

1 Initialize the CPM API.

The Start up function initializes the CPM programming API. You must call the Start up function before any other CPM API calls. This function is not used by ActiveX and Java.

CPM API Reference Guide • CyberSource Corporation • October 2008 1

Chapter 1 Introduction CPM API Basics

2 Set the session identifier. This step is optional.

If transaction security is enabled, call the Set session ID function to set the session identifier.

3 Specify the CPM API configuration file.

Call the Set configuration file function to identify which configuration file the CPM API should use. If the configuration is not specified, the CPM API uses the default configuration file, lcc_client.cf. The Windows registry may be used to store configuration information.

4 Examine the session identifier. This step is optional.

If transaction security is enabled, call the Get session ID function to retrieve the session identifier.

5 Create the transaction handle.

Call the Open transaction function to allocate memory for the transaction data. This function’s handle is the identifier with which to perform subsequent CPM API calls for this transaction. This function is not used by ActiveX and Java.

6 Set transaction fields.

The Set value function sets the values of the transaction fields. To set each transaction field, you must have one call to the Set value function per field.

7 Perform the transaction.

Call the Run transaction function to start the transaction. The Run transaction function returns the transaction response code.

8 Examine the results of the transaction.

Use the Get value function to retrieve output fields from the transaction.

9 Remove the transaction values.

Call the Clear values function to remove the values of the transaction fields.

10 Destroy the transaction handle.

Call the Close transaction function to clear the memory used by the transaction. This function is not used by ActiveX and Java.

11 Shutdown the CPM API.

Shutdown the CPM API after performing all transactions. Call the Shut down function to terminate the CPM API. This function is not used by ActiveX and Java.



Generic Function Detail

Start upInitializes the CPM API. You must call this function before performing any other CPM API calls. This function is not used by ActiveX and Java.

Shut downTerminates the CPM API. Call this function after performing all CPM API calls. This function is not used by ActiveX and Java.

Set configuration fileEnables the CPM API to read from the specified configuration file other than the default configuration file.

Open connectionThis function establishes a persistent connection to the CPM Server that allows the transmission of multiple transactions over one connection. This function may decrease processing time especially if you are using SSL encryption.

Close connectionThis function closes a connection to the CPM Server that was opened with the Open Connection function. Using this function is optional.

Open transactionOpens a unique transaction handle. The transaction uses this handle for identification. Other function calls use this handle to manipulate the transaction. This function is not used by ActiveX and Java.

Close transactionCloses the handle corresponding to the specified transaction. This function is not used by ActiveX and Java.



Set connection informationThis function sets the connection information for the specified transaction at run time. This function overrides the settings in the configuration file.

Run transactionSends a transaction to the CPM Server for execution.

Set session IDSets the session ID for a transaction. You must use this function when the CPM Server is configured to use security. Using this function is optional.

Get session IDRetrieves the session ID for a transaction. The session ID is used when the CPM Server is configured to use security. Using this function is optional.

Set valueSets the value of a field for a transaction.

Get valueRetrieves a field's value for a transaction.

Get value lengthReturns the length of a field's value for a transaction.

Get value pointerRetrieves the pointer value to a field's value for a transaction.

Note This function is not supported for all programming languages, such as VisualBasic.


Chapter 1 Introduction Compatibility

Clear valuesRemoves all the values associated with an open transaction.

Dump valuesDumps all the values associated with the specified transaction into lcc_test.txt.

Print valuesPrints all the values associated with the specified transaction to stdout.

CompatibilityCustom applications written for previous versions of the CPM API will work with the current version of the CPM API. However, you will not be able to take advantage of the new API functionality.

To insure smooth operation with the current CPM API, recompile your custom application using the newer CPM API.

Supported PlatformsThe following API platforms are currently supported:

• Active X

• Batch

• C (Solaris, Win32)

• Java (API)

Note If you have an interest in an API platform for CPM that is not currently sup-ported, contact your sales representative.


Chapter 1 Introduction Supported Payment Environments

Supported Payment EnvironmentsWith CPM, you can process card payments that occur:

• In card-not-present environments: mail order/telephone order or e-commerce orders at your Web store

• In card-present retail environments: keyed entry or card swipe

Generally, both credit and debit cards can be used in both card-present and card-not-present environments. Debit cards, however, are typically used in card-present retail environments. Electronic checks (ACH transactions) and direct debits are used in mail order/telephone or e-commerce situations.

Supported Processor GatewaysCPM provides these payment processor gateways:

• American Express Phoenix

• BA Merchant Services

• FDMS Nashville

• FDMS North

• FDMS South—for credit cards

• FDMS South Debit—CPM has a separate FDMS South gateway for debit cards

• Global Payments (previously called the NDC East gateway)

• Fifth Third Processing Solutions (FTPS)

• NOVA—for credit cards

• NOVA Debit—for debit cards

• Paymentech New Hampshire—for credit cards, ACH, direct debits, and PIN-less debit

• Paymentech Tampa—for credit cards and debit cards

• RBS WorldPay SSL

• Vital VirtualNet Frame

• Vital VirtualNet SSL


Chapter 1 Introduction CPM API Transactions

CPM does not support the same features across all of the gateways or support all of the features offered by each payment processor.

CPM API TransactionsCPM uses four types of transactions:

• For credit cards and debit cards. See the following section.

• For ACH electronic funds transfers. See page 13.

• For direct debits. See page 15.

• For generic functions used by the CPM software. See page 17.

Credit Card and Debit Card TransactionsTable 1 lists the transaction types to use with cards. The transaction types are described in the sections after the table.

Table 1 CPM Card Transaction Types

Transaction Type Numeric ID Use With

Authorization 100 Credit cards only

Capture 102 Credit cards only

Authorize and Capture 104 Credit and debit cards

Reversal 101 Credit and debit cards

Return 103 Credit and debit cards

Void 106 Credit cards only

Manual Authorization 105 Credit cards only

Lookup 121 Credit and debit cards

BIN Lookup 122 Credit and debit cards



AuthorizationYou can use the Authorization transaction, which is transaction type 100, with credit cards.

The Authorization claims a portion of credit without actually transferring funds. The merchant’s bank holds the authorization for a set number of days before the credit automatically returns to the customer. The merchant’s bank determines the credit holding duration. When the purchase occurs, the merchant performs a Capture, which is transaction type 102, to place the authorization into the batch for settlement.

If the authorization results in a call response, the merchant’s bank requires verbal authorization. A client application must be able to accept an approval code when a call response occurs. The client application then calls the Manual Authorization, which is transaction type 105, to update the system accordingly. If verbal authorization results in a denial, no action is required.

If the authorized amount is greater than the actual purchase amount, perform a Reversal, which is transaction type 101, to correct the authorized amount. Not all processors or card types support the reversal transaction. Then perform a Capture with the new amount. If the authorized amount is not used, perform a Reversal for the full amount. The merchant can only perform authorization increments by making a second authorization for the difference.

The results of an Address Match, ZIP Match, and CVV, CVC, or CID check may be returned from the financial processor in an Authorization transaction if you subscribe to these financial processor services and provide the required input information with the transaction.

Verified by Visa and MasterCard SecureCode. Verified by Visa and MasterCard SecureCode are payer authentication programs that reduce the risk of unauthorized use of a credit cardholder account.

Note SecureCode is also available for the Maestro (Switch/Solo) card type on thePaymentech New Hampshire gateway.

The programs enable card issuers to verify a cardholder's identity through the use of a password, and they provide results to you in real time during the checkout process. Payer authentication reduces your exposure to fraud and disputes, and protects cardholders from fraudulent use of their credit cards.

Cardholders go through the same online purchase process they currently use. After they have entered the credit card number and hit the "BUY" button, the card number is sent to the card-issuing bank alerting them the cardholder is about to make an online purchase. The bank, through your Web site, triggers a daughter window to appear in the cardholder's browser. The cardholder is asked to enter a password for identification by the



issuing bank. Upon verification, the bank issues a success message to you assuring you that they have authenticated the identity of the cardholder, the purchase is completed, and a digitally signed receipt is stored for record-keeping. The cardholder receives a message indicating that the purchase has been approved.

To use Verified by Visa or MasterCard SecureCode with credit card transactions, you must send the appropriate data in the eCommerce group fields when you request an authorization or sale. See ECommerce Group on page 44.

CaptureThe Capture transaction, which is transaction type 102, marks an authorization ready for settlement. The CPM Server’s database holds these transactions until the next settlement occurs. At settlement time, the CPM Server reads the transactions out of the database and sends them to the banks for processing. The banks move funds from the customer’s account to the merchant’s account.

Authorize and CaptureThe Authorize and Capture transaction, which is transaction type 104, is a shortcut version of the Authorization transaction and the Capture transaction. This transaction performs the authorization and, if successful, immediately captures the authorization for settlement. This transaction is useful in retail Point-of-Sale environments where there is no time between the credit card authorization and when the customer receives their goods. It is also the only transaction type to use for debit cards.

If a credit card authorization results in a call response, voice authorization is required. The person performing the authorization calls the card issuing bank for instructions. If the issuing bank authorizes the purchase, the client application should accept that approval code and perform a Capture transaction to place the transaction back into the CPM Server database with the approval code.

ReversalThe Reversal, which is transaction type 101, works differently for credit cards and debit cards.

For Credit Cards. For a credit card, the Reversal transaction lowers or negates previously authorized credit to a customer’s account. Many processors request that a merchant use this transaction to match the authorized amount against the settlement amount before settlement. Not doing so may result in higher merchant fees. Not all credit card companies and card issuing banks currently support the reversal transaction, but CyberSource recommends implementation in preparation of industry acceptance of the transaction. Not all processors or card types support the reversal transaction.



Note A Reversal works on an authorization that has not been settled. If an autho-rization has been settled, perform a Return, which is transaction type 103, to returnthe money to the cardholder’s account.

For Debit Cards. For debit cards, use the Reversal transaction if an error occurs while performing the debit card Authorization and Capture. You must perform the Reversal immediately after the Authorization and Capture occurs.

Specifically for the FDMS South Debit gateway, you only need to perform the reversal if you receive a timeout error, 136 ERR_TIME_OUT, and you receive a Retrieval Reference Number in the reply.

For the Paymentech Tampa gateway, perform a reversal if any type of error occurs during the Authorization and Capture.

For the Paymentech New Hampshire gateway, perform a reversal to return funds to a customer’s debit account. The reversal amount must equal the original authorized amount and must be submitted within 90 minutes of the original authorization. Debit reversals are done at the issuer’s discretion. Any PIN-less debit reversal that fails and cannot be submitted within the time limit must be issued as a debit adjustment.

Return The Return transaction, which is transaction type 103, returns money to a credit cardholder’s account. The CPM Server database holds these transactions until the next settlement occurs. At settlement time, the CPM Server reads the transactions out of the database and sends them to the banks for processing. The banks move funds from the merchant’s account to the customer’s account.

Do not use the Return transaction with debit cards processed with FDMS South or Paymentech Tampa. If you need to refund the customer’s money, provide the refund in cash.

For debit cards processed with NOVA, you may use the Return transaction to process refunds if the debit network supports debit Returns. In this case, you do not need to provide the refund in cash. Otherwise, you need to provide the refund in cash.

VoidThe Void transaction, which is transaction type 106, causes the CPM Server to void a captured transaction or return transaction marked for settlement.



Note Void works on a captured authorization that has not been settled. If an autho-rization has been settled, perform a Return transaction to return the money to thecardholder’s account.

Manual AuthorizationYou use the Manual Authorization transaction, which is transaction type 105, after receiving a call response from either an Authorization, which is transaction type 100, or an Authorization and Capture, which is transaction type 104. If you receive voice authorization from the card issuing bank, you perform a Manual Authorization and include the approval code. The Manual Authorization is a database update only; it inserts a new Manual Authorization record into the database with the approval code. You must also follow up with a Capture transaction according to the type of original transaction:

• If the original transaction was an Authorization (100): The Manual Authorization updates the original Authorization transaction record in the database with the correct approval code. You must still perform a Capture transaction if you want to settle the authorization. When you perform the Capture, or if you need to perform a Reversal later, you must reference the original Authorization‘s sequence number and not the Manual Authorization’s sequence number.

• If the original transaction was an Authorization and Capture (104): The Manual Authorization does NOT update the original Authorization and Capture transaction record in the database with the correct approval code. To do this and therefore make the transaction settleable, you must perform a Capture transaction and include the approval code. When you perform the Capture, or if you need to perform a Reversal later, you must reference the original Authorization and Capture’s sequence number and not the Manual Authorization’s sequence number.

For more information about the sequence number, see Sequence Number Field on page 81.

Do not use the Manual Authorization transaction with debit cards.

LookupA Lookup transaction, which is transaction type 121, retrieves an existing transaction from the CPM Server database and returns the card transaction to the user. The Lookup transaction views transaction information in the CC_TRANSACTION table of the CPM



database only. You can retrieve an existing transaction based on any combination of the fields below.

Note You cannot use the Account Number field to retrieve a transaction from anencrypted CPM database.

BIN LookupCPM has the ability to store and look up BIN information. You might look up BIN information to determine how to process a card presented to you for payment: as a credit card, PIN-based debit card, PIN-less debit card, and so on. For example, if your organization is an educational institution, and a customer presents you with a Visa-branded debit card for a tuition payment, you will want to know if you can process the card as a PIN-less debit card.

These are the three steps to using BIN information:

1 Obtain the BIN information.

2 Create the BIN information database table.

3 Before processing a card, look up the card’s BIN information from the database table.

Obtaining the BIN Information. You first must obtain the BIN information from your payment processor or merchant bank. Each processor or merchant bank has a different format for the BIN information they provide. You receive this information in one or more files which you store locally. You then use CyberSource’s Database Utility to load that information into a database table. You can then use CyberSource’s BIN Lookup function to easily look up the BIN information for a particular card number.

You must discuss with your processor or bank how you can determine from the BIN information they provide whether a card can be processed as a PIN-based or PIN-less debit card. The processor or bank may have specific business rules that you should follow when deciding whether to accept a card for a certain type of payment. When you receive the reply from CyberSource’s BIN Lookup function, you must parse the reply for the information that you need to make that decision.

• Sequence Number • Account Number • User Defined 1

• Order Number • Transaction ID • User Defined 2

• Amount • Retrieval Reference Number • User Defined 3

• Tax Amount • User Sequence Number • User Defined 4

• Lookup Transaction Type • User Defined 5



Your processor or bank will tell you how often they update their BIN files and how you obtain the updated information.

Creating the BIN Information Database Table. After you have received the BIN file(s) from your processor, you must create a database table to hold the BIN information. When it comes time for you to update the BIN information, you should create a new, separate database table with the updated information so as to not create availability conflicts while you are in the process of updating. A possible strategy for managing this is to have one database table for each day of the week. You update the BIN information daily and switch to the next day’s BIN information table at midnight. Another possible method is to have only two tables and to switch between the two each day.

For instructions on creating BIN tables, see the CPM Database Utility Guide.

Looking Up BIN Information from the Database Table. To look up BIN information, you use the BIN Lookup transaction, which is transaction type 122, which uses the account number on the card and the name of the database table you have created to retrieve the BIN information.

BIN Lookup returns the BIN information in one reply containing name-value pairs separated by commas. The specific name-value pairs you receive depend on the processor or bank’s particular specification for BIN information. Obtain that specification and then parse the BIN Lookup name-value pairs to locate the information that you want.

ACH TransactionsACH is a type of Electronic Funds Transfer (EFT). The ACH transaction is verified or rejected by the Federal Reserve Automated Clearing House network. Use of ACH instantly verifies the customer’s check reducing the chances of fraud. Further, the funds are instantly transferred from the customer’s checking account to the merchant’s acquiring account. The use of ACH is gaining in popularity quickly in all point of sale types.

Table 2 lists the transaction types you use with ACH transactions. The transaction types are described in the sections after the table.

Table 2 CPM ACH Transaction Types

Transaction Type Transaction Type ID

ACH Verify 108

ACH Deposit 109

ACH Refund 110



ACH VerifyThe ACH Verify transaction, which is transaction type 108, is only applicable to US banks. The ACH Verify transaction allows the merchant to compare each transaction to an external negative file maintained by third party vendors to locate accounts which have a history of bad checks outstanding or are closed for cause. These negative file databases, which are usually located on the processor system, are updated daily.

The ACH Verify transaction does not check if sufficient funds exist in the account nor does it guarantee that the money will be present at the time of settlement. The ACH verify transaction is not required before performing a deposit or refund. The ACH verify transaction occurs in real time and is the only ACH real-time transaction.

ACH DepositThe ACH Deposit transaction, which is transaction type 109, is processed as part of a settlement batch and is sent to the financial processor. The financial processor, when processing the ACH Deposit transaction, takes funds from the customer’s account and places those funds in the merchant's account. The settlement of a ACH deposit transaction can only fail if there is syntactically incorrect information in the transaction. If insufficient funds exist to perform the transaction, the financial processor or acquiring bank calls the merchant directly.

ACH RefundThe ACH Refund transaction, which is transaction type 110, is processed as part of a settlement batch and is sent to the financial processor. The financial processor, when processing the ACH Refund transaction, takes funds from the merchant's account and places it in the customer’s account. The settlement of a ACH refund transaction can only fail if there is syntactically incorrect information in the transaction. If insufficient funds exist to perform the transaction, the financial processor or acquiring bank calls the merchant directly.

ACH Void 111

ACH Lookup 112

Table 2 CPM ACH Transaction Types




ACH VoidAn ACH Deposit or ACH Refund transaction can be voided, which is transaction type 111, in the CPM database as long as the transaction has not already been assigned to a settlement batch. The state of an ACH transaction can be determined by reviewing the state of the ACH transaction in the EFT_TRANSACTION table in the CPM database.

ACH LookupThe ACH Lookup transaction, which is transaction type 112), retrieves an existing ACH transaction from the CPM Server database and returns the ACH/EFT transaction to the user. This information is returned from the EFT_TRANSACTION database table.

Direct Debit TransactionsDirect debits are a payment type used commonly in other countries, particularly within Europe. Direct debits are similar to electronic checks (ACH) used in the U.S.: Customers provides you with their bank account information and authorize you to transfer money out of their accounts. Direct Debits through CPM are available with the Paymentech New Hampshire processor and only if the customer’s bank is in one of these countries:

• Austria

• Belgium

• France

• Germany

• Netherlands

• United Kingdom

Depending on the country, there may be particular rules you must follow when processing direct debits. For example, you may need to obtain a mandate from the customer, which is a signature or other form of permission to transfer funds from the customer’s account. Contact Paymentech to determine any rules you must follow.

As you will be dealing with bank accounts in non-U.S. countries, you should understand the different bank account number structures used in each of these countries. See Paymentech’s direct debit merchant user guide for this information.



Table 3 lists the transaction types you use with direct debits. The transaction types are described in the sections after the table.

ValidateThe Validate transaction, which is transaction type 113, validates the customer’s bank account number. “Validate” means the service determines if the bank sort code is valid for the specified country, and if the bank account number matches the expected format for the bank. The service does NOT determine the status of the account, if the account has sufficient funds, or if the customer is on a negative list.

Validate is an online transaction, so it immediately tells you if the account information is valid, giving you the opportunity to have customers correct their information if they entered it incorrectly. Typically you will want to request a Validate prior to processing a Deposit or Refund for that account; however, the Validate step is optional. Paymentech always validates the account information at settlement time for a Deposit or Refund and will reject the settlement if the account is not valid.

When you request Validate in a production environment, set the amount to 0.

DepositThe Deposit transaction, which is transaction type 114, performs the direct debit, causing the money to be transferred from the customer’s account to your account. As with credit card captures, the CPM Server’s database holds these transactions until the next settlement occurs. At settlement time, the CPM Server reads the transactions out of the database and sends them to the banks for processing.

RefundThe Refund transaction, which is transaction type 115, is also processed as part of a settlement batch. A Refund causes funds from the merchant's account to be transferred to the customer’s account.

Table 3 CPM Direct Debit Transaction Types


Validate 113

Deposit 114

Refund 115

Void 116

Lookup 117



VoidA Deposit or Refund transaction can be voided, which is transaction type 116, in the CPM database as long as the transaction has not already been settled. The state of a direct debit transaction can be determined by reviewing the transaction’s state in the EFT_TRANSACTION table in the CPM database.

LookupThe Lookup transaction, which is transaction type 117, retrieves an existing direct debit transaction from the EFT_TRANSACTION table in the CPM database.

Generic CPM API TransactionsTable 4 lists the generic API transaction types you use with the CPM Server. The transaction types are described in the sections after the table.

Admin CommandThe Admin Command function, which is transaction type 130, is used for issuing administrative commands to the CPM server.

Currently, the only command available is settle_now, which initiates the settlement process. The settle_now command is analogous to the “Settle Now” button in the Admin Client. The command only initiates the settlement process; it does not report the results of the settlement.

Begin SessionThe Begin Session function, which is transaction type 150, is used for security only. If security is enabled, the user must log into the CPM Server with their username and password to obtain their session identifier. This session identifier is the user's key to

Table 4 CPM Generic Transactions


Admin Command 130

Begin Session 150

End Session 151


Chapter 1 Introduction Using the API Transactions

performing future transactions with the CPM Server. All subsequent transactions must contain this identifier to obtain access to the CPM Server.

Note If server security is disabled, Begin Session can be ignored and the sessionidentifier field in the transaction function is left NULL.

End SessionThe End Session function, which is transaction type 151, logs a user out of the CPM Server by turning in their session ID.

Other functionsOther functions for working with the API are described in the Chapter 7, Environment and Implementation, on page 184.

Using the API TransactionsTo gain an understanding when various credit card transactions are performed using the CPM API functions, let’s follow Sam as he makes several credit card transactions.

Example Begin Session, Authorize and Capture, End Session

At a local bookstore Sam presents a credit card to pay for his purchase. The CPM Server is installed at this store with security enabled and the session timeout set. Because security is enabled on the CPM Server, when the sales clerk initiates Sam’s transaction, a begin session function takes place. This begin session requires the sales clerk to login to the CPM Server with a username and password to obtain a session identifier.

The sales clerk can then perform an authorize and capture so that authorization for the sale is immediately captured for settlement. This method assures the payment in this situation where the sales clerk hands over the purchased books to the customer. After Sam leaves the store, the CPM Server is idle for several minutes because the sales clerk has no other customers.

The CPM Server automatically performs an end session function to log out the sales clerk. The session is ended and no other transactions can take place until the sales clerk logs into the CPM Server and starts another session.

That same night, the CPM Server reads all the transactions out of the database and sends them to the bank for settlement. The bank moves funds from Sam’s account to the merchant’s bank account.


Chapter 1 Introduction Using the API Transactions

Example Authorization

At a call center for catalog sales the CPM Server is installed with the security featured enabled. The sales representative initiates a begin session and logs in to the CPM Server with her username and password at the start of her shift.

Sam calls in to the call center, the sales representative answers Sam’s call, then enter’s Sam’s purchase and credit card information into the CPM Server through a transaction client. The sales representative selects the authorization transaction. Authorization claims a portion of credit available on Sam’s credit card without transferring funds.

Example Reversal

The next day Sam decides he does not want one of the items ordered in Example 2. Sam calls the call center to cancel the item. Because capture has not occurred, the clerk uses a reversal transaction. The CPM API reversal function lowers the previously authorized credit amount to Sam’s credit card account.

A few days later, when Sam’s corrected order ships, the CPM Server is notified and performs a capture transaction. The capture marks the authorization in a batch for settlement. That same night, the CPM Server reads all the transactions out of the database and sends it to the bank for settlement.

During the days in between, the sales representative began and ended sessions with the CPM Server.

Example Void

At a hardware store Sam presents a credit card to pay for his purchase. The CPM Server is installed at this store with security disabled. The sales clerk performs an authorize and capture. After Sam leaves the store, he decides he does not want the item purchased. Because capture occurred and settlement has not occurred, the sales clerk must perform a void transaction.

The CPM API void transaction cancels a transaction marked for settlement.

Example Return

Sam decides to return one of the books to the bookstore. Because settlement occurred, the sales clerk must perform a return transaction.

The CPM API return transaction returns the purchase amount of the book plus any tax to Sam’s credit card account when the CPM Server reads the return transaction out of the database and settles with the merchant’s bank.


Chapter 1 Introduction Building the CPM API Integration

Building the CPM API IntegrationThe CPM API provides a software developer with an easy-to-use interface to perform credit card and ACH functions on a CPM Server.

CPM API functionality is only limited by the calling application’s API and the business functionality an integration supports.

A CPM API integration may not need full transaction functionality. For example, if an integration only supports a Web store front, the integration may only need to support the authorization and authorize and capture transaction. However, to perform a return, reversal, or void on a transaction, the CPM Client or other customer CPM API client must by used. Order entry software may need to be manually updated to indicate an order change.

At the very minimum, to perform a credit card transaction, include the following CPM API groups in an integration:

• Base group

• Extended information group

The CPM API groups are described in Chapter 2, CPM API Groups, on page 22.

Note Additional information and integration functionality, such as AVS and CVV,can help the merchant receive reduced interchange rates for credit card transac-tions. Contact your financial processor for more information on interchange reduc-tion programs.

When building a CPM API integration, include all fields for an API group or a transaction type to be supported by the integration. This strategy makes sure the integration is compatible with all CPM gateways and financial processor requirements. Fields are listed as required or optional when implementing the API fields at the point of sale or transaction processing client using the CPM API.

Financial Processor SpecificationsThis section describes the types of data passed to the CPM API. However, if building a custom CPM API integration or modifying a CPM API integration provided by CyberSource, the financial processor may place additional restrictions and requirements on these fields. Refer to the financial processor’s specifications to maintain character compatibility, field length, and to assure correct transaction billing.


Chapter 1 Introduction Building the CPM API Integration

Using the API in a Retail EnvironmentWhen implementing the CPM API for a retail, card-present workflow environment, you must consider how the data is obtained and passed through to the CPM API. In many retail environments, a credit card magnetic stripe reader is used. This device is typically called a card swiper. When a card swiper reads encoded information from the credit card magnetic stripe, it must pass the data directly to the CPM Server through the API. For merchants accepting transactions in a retail environment, always populate the magnetic track group as read by the card swiper in the CPM API to reduce interchange fees. Consult with your acquiring bank and the card issuer for the best use of the magnetic track group. See Magnetic Track Group on page 61 for more information.

When developing your implementation, include a method that allows a sales representative to enter the credit card number and expiration date. The API must be reset to accept the manually entered mode as set in the POS entry mode API fields. Send the data directly to the credit card number and expiration date fields in the CPM API.

Various rules apply that are unique for each credit card that your implementation accepts. For example, if a Visa card is used in the transaction, Visa only permits settlement of a transaction after the service completes or the product ships. Contact each credit card company for more information on usage requirements as you develop your implementation for the various card types.


Chapter 2

CPM API Groups

This chapter explains the CPM API groups, and information for the Amount and Sequence Number fields.

The CPM API is ordered into groups reflecting transaction and business functionality. The CPM API provides the developer with an interface to the financial processor. Strict adherence to these specifications allows the user to switch between financial processors without impact to the CPM API integration.

The API groups comprise API fields based on transaction type and credit card, ACH, or direct debit transaction function. Not all groups are necessary for a transaction.

Each API field has an identifier listed in Chapter 5, CPM API Identifiers, on page 167. The tables in this chapter include each field’s numeric identifier.

The chapter includes these sections:

• Base Group

• Extended Information Group

• Address Verification Service Group

• PS2000 Group

• Extended Customer Information Group

• Terminal Setup Group

• Card Verification Value Group

• ECommerce Group

• Internet Transaction Data (ITD) Group

• Billing Group (Soft Descriptors)

• Purchasing Card Group

• American Express Retail TAA Group

• Level III Purchasing Card Group

• Level III Purchasing Card Line Item Detail Group

• Health Benefit Card Group

• Pre-Paid Card Group

• User Defined Group

• Magnetic Track Group

• CPM Reserved Group

• Security Group

• Processor Specific Response Group

• Private Label Card Group

• Electronic Fund Transfer Group

• Direct Debit Group

• Maestro (Switch/Solo) Card Group

• Hotel and Car Rental Group

• Admin Command Group

• API Input Notes


Chapter 2 CPM API Groups Base Group

Base GroupThe base group contains the basic information for most transactions. This group includes information about the type of credit or debit card used and the transaction. CyberSource recommends that all CPM API integrations include all fields in the base group.

Table 5 Base Group Fields

FieldNumeric Identifier

Description Length

Merchant ID 51 Which CPM Merchant ID to use on the CPM Server. You set up your Merchant ID(s) in the CPM Administration Client. This field is required with every transaction.

32

Merchant Name 100 The Merchant Name functions very similarly to your Merchant ID. It is a descriptive version of your Merchant ID. You set up your Merchant Name in the CPM Administration Client when you set up your Merchant ID. In your transaction requests, you may send either the Merchant ID or Merchant Name, but CyberSource prefers that you send the Merchant ID.

no limit

Account Number 101 The credit card or debit card number. Do not include spaces or dashes.

28

Expiration Date 102 The credit card expiration date for the function. The format is MMYY.

4

Amount 103 The amount for the transaction. For all gateways except NOVA, the format is DDDDDDDDDDCC. For the NOVA gateway, the format is DDDDDCC.

Note Do not include a decimal point in the transaction amount.

Note For PIN-based debit transactions, the Amount that you provide for the transaction should include the Cash Back Amount, which is described in Table 6, which starts on page 28.

7 for NOVA

12 for all other gateways



Card Type 104 The type of card used in the transaction. This field should be filled by the cardholder. The CPM Server performs syntax checks for the Account Number against the contents of this field. This field is used for authorizations, authorize and capture, reversal, and return transactions.

CyberSource recommends that you send this field, even if it is optional for your processor, to help avoid any confusion caused by overlapping BIN ranges. Omitting the card type can cause the transaction to be processed with the wrong card type.

Possible values:

• 000: Other

• 001: Visa

• 002: MasterCard

• 003: American Express

• 004: Discover

• 005: Diners Club

• 006: Carte Blanche

• 007: Japanese Credit Bank

• 008: Optima

• 009: Maestro (Switch/Solo)

• 010: GE Capital

• 011: GECC

• 012: Beneficial

• 013: Citibank Encryption Program

• 022: Liz Claiborne

• 029: Debit—PIN-based or PIN-less

• 030: NYCE

• 031: Pulse

• 032: Star

3

Table 5 Base Group Fields (Continued)


Description Length



Sequence Number

105 A unique number assigned to each transaction. The sequence number is updated with the output of every transaction.

The sequence number provides an index to refer to the transaction and tracks the detail fields of an authorization. By inserting the sequence number of an authorization into the sequence number field of a reversal, capture, or void, the CPM Server looks up all detail fields of the authorization and copies them to the corresponding fields of the subsequent transaction.

NOTE When performing a Capture or Reversal that references a manually authorized Authorization or combined Authorization and Capture, provide the sequence number for the original Authorization, which is the 100 transaction, or the Authorization and Capture, which is the 104 transaction, and NOT for the Manual Authorization, which is the 105 transaction. See Manual Authorization on page 11.

See Sequence Number Field on page 81 for more information.

15

Approval Code 106 Contains a code assigned by the financial processors to approved authorizations. The data returned in this field from authorizations is required input into subsequent reversals and captures based on the authorization.

For FDMS South and Paymentech Tampa PIN-based debits, if the request is approved, the field contains a reference number that you must print on the customer’s receipt. See PIN-based Debit Cards on page 63.

9



Description Length



PIN-less Debit CardsA particular application of the Base Group fields is for PIN-less debit cards, which you can process if you use the FDMS South Debit gateway or Paymentech NH gateway.

Authorization Response Code

107 A processor-independent response for all authorization requests. This field is only used for authorizations, reversals, and authorize and capture. Possible values:

• A: Approval. Authorization is approved.

• C: Call. Voice authorization is required. Call the processor.

• D: Decline. The approval was declined. Check the Authorization Response Message or Processor Authorization Response Code for details.

• E: Error. A processing error occurred. Check the Authorization Response Message or Processor Authorization Response Code for details

• P: Pickup Card. The credit card has a problem. Remove the card from the cardholder. Check the Authorization Response Message or Processor Authorization Response Code for details.

• X: Expired Card. This credit card is expired.

1

Authorization Response Message

108 A text message supplied by the financial processor or CPM Server describing the results of the authorization request. This field is only supplied for authorizations, reversal, and authorize and capture requests.

20

Return Code Message

109 A description of the return code supplied from the CPM API function call.

Note The returned message generated by the API might exceed 40 characters. The corresponding database field is 40 characters long.

40



Description Length



Note PIN-less debit cards are different from PIN-based debit cards. See PIN-basedDebit Cards on page 63.

You can use PIN-less debit transactions if your business is in one of the acceptable merchant categories where a card-not-present debit transaction is low risk. The categories include educational institutions, insurers, utilities, and telecommunications, among others. Contact your payment processor to determine if your business may support PIN-less debit cards.

If the card can be used for PIN-less debit transactions, you request an Authorization and Capture transaction with these fields:

• Merchant ID

• Card Type=029

• Account Number (the debit card number)

• Amount

• Tax Amount (optional)

• Terminal Setup Group Fields

The main reply fields of interest are the same ones you receive for a credit card:

• Approval Code (from the debit network)

• Authorization Response Code

• Authorization Response Message

• Return Code Message

• Processor Auth Response Code

• Retrieval Reference Number (required in case you need to do a reversal)

See CPM Messages and Processors Codes for a mapping of the authorization response codes to the CPM Authorization Response Code.

If an error occurs while processing a PIN-less debit card transaction, you must reverse the transaction. For more information, see Reversal on page 119.

Later, if you need to refund the customer’s money, you must provide a cash or check refund. Do not use the Return transaction as you would with a credit card.


Chapter 2 CPM API Groups Extended Information Group

Extended Information GroupThe extended information group provides detailed information returned with an authorization. Processors return many identifiers with every authorization to help them track the authorization request from authorization through settlement. Typically, the merchant does not need to be concerned with the content of these fields. However, the merchant must make sure the processor received the extended information from an authorization during the reversal or capture of that transaction. The CPM Server assists the merchant in this function with the Sequence Number. See Sequence Number Field on page 81 for more information.

Table 6 Extended Information Group Fields


Description Length

Transaction Identifier

120 Returns the authorization system’s Transaction Identifier. Supply this field with any subsequent capture or reversal functions. Financial processors use this field to associate authorization, reversal, and capture transactions.

15

Transaction Date 121 The date the transaction occurred. The format is YYMMDD. If the Transaction Date fields are set in the API, that date is sent to the processor when required. This data is stored in the LOCAL_DATE_TIME database field. Use this field for authorization, capture, authorize and capture, return or reversal transactions.

6

Transaction Time 121 The time the transaction occurred. The format is HHMMSS. If the Transaction Time field is set in the API, that time is sent to the processor when required. This data is stored in the LOCAL_DATE_TIME database field. Use this field for authorization, capture, authorize and capture, return or reversal transactions.

6

Validation Code 123 Returns the issuing bank’s Validation Code for this transaction. Supply this field with any subsequent capture or reversal functions. Financial processors use this field to associate authorization, reversal, and capture transactions.

4

Original Amount 124 The amount authorized in the original authorization. Use this field only with Reversal functions. The format is DDDDDDDDDDCC.


12



Response Indicator

125 Details information about this authorization. 2

Returned ACI 126 The value of the requested transaction’s Custom Payment Services qualification status. Typically this field is handled by the CPM Server and should not be altered.

1

Requested ACI 127 The value of the returned transaction Custom Payment Services qualification status. Typically this field is handled by the CPM Server and should not be altered.

1

POS Mode Code 128 Details point-of-sale mode about this authorization.

2

Market Specific Indicator

129 Details market specific identifier about this authorization.

For the FTPS and FDMS North gateways, this field has a special usage. Customers may pay bills by using their Visa cards. Visa requests that you include a special bill payment flag in the authorization or credit request so that Visa can separate the transactions from normal credit card purchases/credits. To indicate that the authorization or credit is for a bill payment, set this field to B.

2

Retrieval Reference Number

130 Returns the authorization system’s Retrieval Reference Number. Supply this field with any subsequent capture or reversal functions. Financial processors use this field to associate authorization, reversal, and capture transactions.

12

Account Data Source

131 The processor specific representation of the source of the customer data that was entered.

1

Card Holder ID 132 The processor specific representation of the method used to verify card holder identity.

1

Authorization Source Code

133 The processor specific representation of the authorization code.

1

Table 6 Extended Information Group Fields (Continued)


Description Length



Current Amount 134 This field contains the amount authorized in the original authorization. Use this field only with Reversal functions. The format is DDDDDDDDDDCC.


12

Transaction Attribute

135 This field is reserved for future use. 2

Current Tax Amount

136 The current tax amount for the transaction. This field is added to the purchase amount field for the total purchase amount. The format is DDDDDDDDDDCC.


12

Lookup Transaction Type

137 This field identifies the transaction type. This field is for the Lookup transaction.

3

Cash Back Amount

138 Optional cash back amount for PIN-based debit card transactions. The format is DDDDDDDDDDCC.

Note For PIN-based debits, the Amount that you provide for the Authorization and Capture transaction should include the Cash Back Amount. See PIN-based Debit Cards on page 63.

12

BIN Table 6 The BIN information table to use when looking up BIN information for a card. See BIN Lookup on page 31.

20

BIN Information 139 The reply information for a BIN Lookup transaction. See BIN Lookup on page 31 for more information.

255

Amex Retail Info 900 Numeric information required specifically for the Paymentech Tampa gateway for both authorizations and captures of retail transactions using American Express cards. Includes a reference number and item codes for up to five items being purchased. See Using the Amex Retail Info Field below.

26



Description Length



BIN LookupThe BIN Table and BIN Information fields in the Extended Information Group are used for BIN Lookup, which is transaction type 122, which retrieves information about the card based on the account number. See BIN Lookup on page 12 and page 138 for more information.

To use BIN Lookup, you simply provide the Account Number and BIN Table fields. The BIN Lookup returns the BIN Information field, which contains name-value pairs separated by commas. The specific name-value pairs you receive depend on the issuing bank’s particular specification for BIN information. Obtain that specification and then parse the BIN Lookup name-value pairs to locate the information that you want.

Using the Amex Retail Info FieldThe Amex Retail Info field is required for both authorizations and captures of retail transactions using American Express cards processed with the Paymentech Tampa gateway. It is not required for MOTO or e-commerce transactions. You must format the contents of the field as described below. Contact Paymentech Tampa for the specific values to use for the reference number and the item codes.

Recur Advice Code

1039 Recurring payment advice code returned in the authorization response for MasterCard recurring transactions. Applies to Paymentech New Hampshire, RBS Worldpay SSL, and Vital gateways. Possible values:

• 01: New account information available. Obtain new account information.

• 02: Try again later. Recycle transaction in 72 hours.

• 03: Do not try again. Obtain another type of payment from the customer.

• 21: Recurring payment cancellation.

2

Last Record Number

2100 The expected last record number assigned to that particular transaction in the TID’s daily batch. See Using the Last Record Number with NOVA on page 64.

3



Description Length


Chapter 2 CPM API Groups Address Verification Service Group

Address Verification Service Group

Standard AVSThe address verification service (AVS) response group provides the merchant two output fields with independent results for address verification requests. AVS verifies the cardholder’s billing address and postal code.

Not all financial processors provide this service.

Note The results of address verification do not affect the results of the authoriza-tion. The merchant receives authorization if the credit card has enough availablecredit, but the address information is incorrect. The merchant must make the deci-sion to accept a transaction where address verification failed.

Table 7 Format for Amex Retail Info Field

Position ContentsRequired or Optional

1-6 A numeric invoice or reference number that can be included on the cardholder statement.

Required

7-10 Numeric retail item code for item 1 Optional







Visa RED Regulations for AVSVisa is implementing RED (Re-Engineering Disputes) regulations that affect chargebacks and chargeback processing. Starting in Spring 2004, Visa will only permit representments for fraud if:

• You send full AVS information, which consists of the address and the postal code, with both the Authorization request and the Capture request. Remember that if you supply the Authorization’s sequence number with the Capture request, CPM automatically retrieves the AVS information that you supplied from the CPM database and sends it with the Capture.

• You receive a full AVS match, which is indicated by Visa codes I1 or I3. Transactions with an AVS match for postal code only, which is indicated by Visa code I4, will not be eligible for representment.

• You can provide an itemized bill with shipping information

CyberSource strongly encourages you to pursue full AVS authorization both to combat fraud and to effectively manage chargeback losses.

Important If you process on Paymentech's New Hampshire gateway, supplyingthe customer’s first name and last name prompts CyberSource software to sendboth the address and postal code information to Paymentech with the Capture. Ifyou do not supply the customer’s name, CyberSource sends only the postal code toPaymentech with the Capture.

Enhanced AVS and Automated Address Verification PlusEnhanced AVS and automated address verification plus (AAV+) are available only for the American Express Phoenix gateway.

Note You must contact American Express to sign up for Enhanced AVS and AAV+.

Enhanced AVSIf you are using the American Express Phoenix gateway, you can sign up to use Enhanced AVS. Enhanced AVS includes the standard AVS capability and adds verification of the customer’s last name. To use Enhanced AVS, you must send in either the Customer Name field or the Customer Firstname and Customer Lastname fields in your request. See Customer Name and AVS on page 39 for more information.



Important To determine the results of Enhanced AVS, look at the results in the Pro-cessor AVS Result field. See Processor Specific Response Group on page 67 forinformation about the field. See American Express’s specification for the most up-to-date list of the AVS result codes they return.

Automated Address Verification Plus (AAV+)If you are using the American Express Phoenix gateway, you can sign up to use Automated Address Verification Plus (AAV+). AAV+ includes both the standard and Enhanced AVS capability and adds verification of the ship-to information inside the U.S. This service is intended for merchants who deliver physical goods to a different address than the billing address. AAV+ verifies the ship-to information only if the standard and Enhanced AVS tests first pass.

To use AAV+, you must send in these additional fields:

• Customer Phone

• Ship To Firstname

• Ship To Lastname

• Ship to Address1

• Ship to Zip Code

• Ship to Phone

• Ship to Country

These fields are not all documented as part of the AVS Group. The Ship to Zip Code field is listed in the Purchasing Card Group. See page 51.

Important To determine the results of AAV+, look at the results in the ProcessorAVS Result field. See Processor Specific Response Group on page 67 for informa-tion about the field. See American Express’s specification for the most up-to-datelist of the AVS result codes they return.

Configuring the AVS Level for American Express PhoenixAVS is performed by the issuing bank, not the CPM software. The CPM software, however, requests that a certain level of AVS be performed based on the AVS level you request and the data that you provide.



You control the AVS level with three items:

• Default setting for AVS level

• AVS Level API field

• Data you provide for AVS

In the CPM Administration Client agreement settings dialog box, you set the default AVS level to use for all transactions. You can override the default setting on a transaction level by using the AVS Level API field described in Table 8. You then must supply the data required to support the AVS level that you want. If you do not supply the data needed, the CPM software will request the AVS level that the data supports. This way, you will only be charged by American Express for the AVS level that your data supports.

For example, if you set the default value to AAV+, which verifies the ship-to address, but you do not send the ship-to address information in the request, then you will only get results back for Standard and Enhanced AVS, if you sent the required information for Standard and Enhanced AVS.

Conversely, if you set the default to Standard, and you send in the ship-to address information, which is used by AAV+, then you will not get results for AAV+ unless you use the AVS Level API field to request AAV+ for the transaction.

Table 8 Address Verification Response Group Fields


Description Length

Address Match 140 The results of the address portion of the address verification check. Possible values:

• N: No match

• R: Invalid AVS response from card issuer or address verification data contains EDIT ERROR.

• X: Service unavailable

• Y: Match

To determine the results of Enhanced AVS and AVV+, look at the results in the Processor AVS Result field. See Processor Specific Response Group on page 67 for information about the field. See American Express’s specification for the most up-to-date list of the AVS result codes they return.

1



Zip Match 141 The results of the postal code portion of the address verification check. Possible values:

• N: No match

• R: Invalid AVS response from card issuer or address verification data contains EDIT ERROR.


• Y: Match

To determine the results of Enhanced AVS and AVV+, look at the results in the Processor AVS Result field. See Processor Specific Response Group on page 67 for information about the field. See American Express’s specification for the most up-to-date list of the AVS result codes they return.

1

AVS Level 142 The level of AVS service to use for the transaction. Used only for the American Express Phoenix gateway. Possible values:

• 1: Standard

• 2: Enhanced

• 3: AAV+

The AVS level you specify in this field overrides the merchant configuration setting. You must sign up with American Express Phoenix to use Enhanced AVS or AAV+.

1

Ship To Firstname 1012 First name of person receiving the shipment. This field is required to use AAV+ with the American Express Phoenix gateway. Other Ship To fields are also required. See description of AAV+ above.

60

Ship To Lastname 1013 Last name of person receiving the shipment. This field is required to use AAV+ with the American Express Phoenix gateway. Other Ship To fields are also required. See description of AAV+ above.

60

Ship to Address 1 460 The street address to where the product is shipped.

20

Ship to Address 2 461 The street address to where the product is shipped.

20

Table 8 Address Verification Response Group Fields (Continued)


Description Length


Chapter 2 CPM API Groups PS2000 Group

PS2000 GroupThe Payment Service (PS2000) group contains three input fields that assist direct marketing merchants in lowering their processing costs in card-not-present situations. Included in this group are the address verification fields. These fields allow the merchant to check a cardholder’s billing address against a given address. On viewing the results of the address verification, the merchant can decide to accept or decline an authorization. CyberSource recommends that all CPM API integrations include all fields in the PS/2000 group.

Ship to City 462 The city to where the product is shipped. 20

Ship to State 463 The state to where the product is shipped. 2

Ship to Phone 464 The phone number of the location to where the product is shipped.

14

Table 8 Address Verification Response Group Fields (Continued)


Description Length

Table 9 PS2000 Group Fields


Description Length

Order Number 150 A merchant-assigned order number.

For Paymentech New Hampshire, the first 8 bytes (8 characters) must be unique. If you don't provide the order number, this field defaults to the SEQUENCE_NUMBER, for which CyberSource guarantees uniqueness.

17 for NOVA

25 for all other gateways

Customer Street 151 The cardholder’s billing street address. The format is StreetNumber StreetName. See Visa RED Regulations for AVS on page 33.

20

Customer Zip 152 The cardholder’s billing postal code. The postal code can be international and contain alphanumeric characters. See Visa RED Regulations for AVS on page 33.

Note Do not include a dash (–).

9


Chapter 2 CPM API Groups Extended Customer Information Group

Extended Customer Information GroupThe extended customer information group contains additional fields for storing customer information. CyberSource recommends that all CPM API integrations include all fields in the extended customer information group.

Table 10 Extended Customer Information Group Fields


Description Length

Customer Name 170 The customer’s name. The format is FirstName MiddleInitial LastName. See information below this table about AVS and the Customer Name field. Also see Visa RED Regulations for AVS on page 33.

26

Customer Firstname

176 Customer’s first name. See information below this table about AVS and the Customer Firstname field.

25

Customer Lastname

175 Customer’s last name. See information below this table about AVS and the Customer Lastname field.

25

Customer Phone 171 The customer’s phone number. 14

Customer City 172 The city in which the customer resides. 20

Customer State 173 The state in which the customer resides. 2

Customer Country 174 Two-letter ISO country code of the country in which the customer resides. See the processor specification for a list of ISO country codes.

Note Customer Country is a required field for Paymentech New Hampshire International AVS transactions, which consist of Authorization transactions and Authorization and Capture transactions, if Ship To Country is not set.

2

Customer Hostname

177 DNS-resolved hostname. 60

Customer IP Address

465 The customer’s IP address if applicable to the transaction type or POS type.

30

Customer Email 466 The customer’s email address if applicable to the transaction type or POS type.

50


Chapter 2 CPM API Groups Extended Customer Information Group

Customer Name and AVSThe CPM API uses a single field, Customer Name, for the entire customer’s name. The American Express Phoenix gateway requires two separate name fields for AVS: a firstname field and a lastname field. To accommodate this requirement, the CPM software splits the contents of the Customer Name field as follows for users of the American Express Phoenix gateway:

The lastname starts with the last character in the field and works backwards to the first space encountered. The firstname is everything before that space.

For example, for the name John S. Doe:

Lastname=Doe

Firstname=John S.

This algorithm may encounter a problem if the name includes a suffix, such as Jr.

For example, for the name John S. Doe Jr.:

Lastname=Jr.

Firstname=John S. Doe

To work around this problem, if you are using the American Express Phoenix gateway, you can use the Customer Firstname and Customer Lastname fields instead of using the Customer Name field.

Important If you are using a gateway other than the American Express Phoenixgateway, and you send the two separate name fields instead of the single CustomerName field, the CPM software will concatenate the values in the Customer First-name and Customer Lastname fields with a space in between. The field will betruncated to 26 characters.


Chapter 2 CPM API Groups Terminal Setup Group

Terminal Setup GroupThe terminal setup group describes the authorization environment for the authorization transaction request to the financial processor. This group is typically used with retail point of sale devices in card present transactions but can be used in any point of sale environment.

When implementing a CPM API integration supporting card present transactions, you must include all fields in the Magnetic Track group.

Table 11 Terminal Setup Group Fields


Description Length

Card Present Flag 350 Indicates if the card is present at the time of the transaction. Possible values:

• 0: The card is not present (call center or IVR)

• 1: The card is present (retail POS)

• 2: Unknown

1

Terminal Capability

351 Indicates POS terminal capability used in transaction. Possible values:

• 0: Unknown

• 1: Terminal has a magnetic stripe reader and manual entry capabilities

• 2: Magnetic stripe reader

• 3: No magnetic stripe reader

• 4: Contactless chip read capability

• 5: Contactless magnetic stripe read capability

1

Terminal Type 352 Indicates POS terminal type used in transaction. Possible values:

• 0: Unknown

• 1: Standalone credit card terminal

• 2:Electronic Cash Register/POS system

• 3: Unattended device

1


Chapter 2 CPM API Groups Terminal Setup Group

POS Entry Mode 353 Indicates entry method of credit card information into POS terminal used in transaction. Possible values:

• 0: Unknown

• 1: Read from credit card magnetic track 1 (card swiper)


• 3: Credit card number manually keyed in to POS terminal

• 4: Read from contactless M/chip or Visa smart card

• 5: Contactless mobile commerce

• 6: Read from contactless chip magnetic strip

1

Customer Present Flag

354 Indicates whether the cardholder is present at the time of the transaction. Possible values:

• 0: Customer present

• 1: Customer not present

• 2: Recurring

• 3: Deferred

• 4: Telephone transaction

• 6: Debt transaction

• 7: Billing installment

• 8: Interactive Voice Response (IVR) for PIN-less debit only

The recurring value is typically used in environments supporting recurring transactions. For example, a recurring shipment of product based on merchant’s customer agreement that results in recurring charges on the customer’s credit card bill.

1

Table 11 Terminal Setup Group Fields (Continued)


Description Length


Chapter 2 CPM API Groups Card Verification Value Group

Card Verification Value GroupThe Card Verification Value (CVV) is a number printed on a credit card that reduces the risk of fraud by helping to make sure your customer has physical possession of the card. The number is typically printed, and not embossed, on the back of the card in the signature area or on the front of the card. The number is not embedded in the magnetic strip, so it is never transferred during a card swipe.

During a card-not-present transaction, you request the CVV number from the customer, and you then pass it through the CPM API. The issuing bank compares the number to the expected value to assess the possibility of fraud.

Each card association has its own name for this number. Visa calls it the Card Verification Value (CVV2). MasterCard calls it the Card Validation Code (CVC2). Both Diners Club and American Express call it the Card Identifier (CID).

Important You must contact American Express and sign up with them if you wantto use the CID with American Express cards. If you are using the American ExpressPhoenix gateway, after you are signed up with American Express to use the CID,you must then select the Send CID checkbox in the agreement settings dialog in theCPM Administration Client. If you do not select the checkbox, the CPM softwarewill not send the CID to American Express for validation.

Table 12 CVV Group Fields


Description Length

CVV 165 The contents of the CVV. 3 (Visa, MasterCard, Discover)

4 (American Express)


Chapter 2 CPM API Groups Card Verification Value Group

CVV Result Code

166 The result of the CVV. This field contains the payment processor’s raw result code. Typical processor codes:

• M: Match

• N: No match

• S: Merchant code was not on the card

• I, U, or P: Unknown/service unavailable

See your payment processor’s specification for the most up-to-date list of the CVV result codes they return.

NOTE American Express does not return a CVV result code. If you are processing an American Express card with any of the payment processors, and the card fails the card verification check, American Express refuses the card without indicating that it was because of the card verification failure.

4

CVV Indicator 167 Reason why you did not include the CVV in the request. It is recommended that you include this field whenever you do not supply the CVV number in the authorization or authorization and capture request. Use one of these values:

• 0: Bypassed. CVV value deliberately not sent.

• 1: CVV value is present.

• 2: Illegible. Customer maintains that CVV is on the card but is not readable.

• 3: Not on card.

1

Table 12 CVV Group Fields


Description Length


Chapter 2 CPM API Groups ECommerce Group

ECommerce GroupThe eCommerce group is for transactions originating from Web sites. CPM supports Verified by Visa and MasterCard SecureCode payer authentication for FDMS North, FDMS Nashville, Paymentech New Hampshire, RBS Worldpay SSL, and Vital. SecureCode is also supported for the Maestro (Switch/Solo) card type on the Paymentech New Hampshire gateway.

Table 13 ECommerce Group Fields


Description Length

ECommerce Type 300 E-commerce flag for Web transactions. Possible values:

• null: Not a Web transaction. At the point of sale, if not a Web transaction, this field should be empty.

• 01: Not secure. Channel encryption was not used between the browser and Web server.

• 02: Secure. Channel encryption was used between the browser and Web server.

• 03: Successful Verified by Visa transaction.

• 04: Verified by Visa transaction was attempted but not authenticated.

• 05: MasterCard SecureCode or Maestro (Switch/Solo) SecureCode transaction.

2



UCAF Indicator 467 Indicates whether the UCAF data was collected for a SecureCode transaction. Required when ECommerce Type=05. Used for FDMS Nashville, Paymentech New Hampshire, RBS Worldpay SSL, and Vital. Possible values:

• 0: UCAF data collection is not supported at your Web site. This value is accepted only for Paymentech New Hampshire and Vital.

• 1: UCAF data collection is supported, but UCAF data was not populated. This value is accepted for FDMS Nashville, Paymentech New Hampshire, RBS Worldpay SSL, and Vital. In this case, you do not need to send the CAVV field.

• 2: UCAF data collection is supported, and UCAF data was populated. This value is accepted for FDMS Nashville, Paymentech New Hampshire, RBS Worldpay SSL, and Vital. You must also send the CAVV field with the AAV (UCAF data).

For Paymentech New Hampshire, CPM uses the UCAF indicator to derive the Transaction Type as follows:

• If UCAF_INDICATOR = 0 or 1, the transaction type (ECI Indicator) will be set to 6, which signifies a non-authenticated e-commerce transaction.

• If UCAF_INDICATOR = 2, the transaction type (ECI Indicator) will be set to 5, which signifies an authenticated e-commerce transaction.

1

Table 13 ECommerce Group Fields (Continued)


Description Length



CAVV 301 Cardholder Authentication Verification Value used for payer authentication. Use this field for the Verified by Visa CAVV and the MasterCard SecureCode AAV (the UCAF data). Supported for FDMS Nashville, Paymentech New Hampshire, RBS Worldpay SSL, and Vital.

For FDMS Nashville, send the value in hex binary format for Verified by Visa, and in base64 format for MasterCard SecureCode.

For Paymentech New Hampshire, send the value in base64 format.

For RBS Worldpay SSL and Vital, send the value in hex binary format.

40

XID 302 XID value used for Verified by Visa. Supported for Paymentech New Hampshire, RBS Worldpay SSL, and Vital. The field is optional for both gateways.

For Paymentech New Hampshire, send the value in base64 format.

For RBS Worldpay SSL and Vital, send the value in hex binary format.

40

Raw ECI 701 Raw ECI data from payer authentication, if you received any for the transaction. Your processor might require this information to guarantee charge protection. Contact your processor for information about their requirements. Supported for Paymentech New Hampshire.

2



Description Length



CAVV Result 304 Visa validates the CAVV that you provide in the authorization request. This reply field contains the processor’s response indicating whether the CAVV passed the validation check. Returned only for Paymentech New Hampshire.

For the Paymentech New Hampshire gateway, at the time of the CPM 5.6 release, the possible values you can receive are:

• Blank: CAVV not validated

• 0: CAVV not validated due to erroneous data submitted

• 1: CAVV failed validation

• 2: CAVV passed validation

• 3: CAVV validation could not be performed; a 3-D secure authentication value of 5 from ACS indicates an attempt, but not able to complete

• 4: CAVV validation could not be performed; a 3-D secure authentication value of 6 from ACS indicates system error or failure by AC

For the most up-to-date list, see Paymentech New Hampshire’s specification.

1



Description Length


Chapter 2 CPM API Groups Internet Transaction Data (ITD) Group

Internet Transaction Data (ITD) GroupFor card-not-present merchants, ITD subfields may contain source data, including the cardmember’s Web and e-mail addresses, host computer name, HTTP browser, product SKU (stock keeping unit) inventory reference number, shipping method, and country to which product will be shipped. This optional information is used to support Amex Data Field 47.

Table 14 Internet Transaction Data (ITD) Group Fields


Description Length

Customer Email 466 The customer’s email address if applicable to the transaction type or POS type.

50

Customer Hostname

177 DNS-resolved hostname. 60

HTTP Browser Type

303 Customer’s browser as identified from the HTTP header data. For example, Mozilla is the value that identifies the Netscape browser.

60

Ship To Country 471 Two-letter ISO country code of the location the product is shipped to. See the processor specification for a list of ISO country codes.

NOTE Ship To Country is a required field for Paymentech New Hampshire International AVS transactions, which are Authorization transactions and Authorization and Capture transactions, if Customer Country is not set.

2

Shipping Method 1015 Method used to ship goods or services. Possible values:

• 01: Same Day

• 02: Overnight/Next Day

• 03: Priority, 2-3 days

• 04: Ground, 4 or more days

• 05: Electronic Delivery

2

Merchant Product SKU

159 Product’s identifier code. 15

Customer IP Address

465 The customer’s IP address if applicable to the transaction type or POS type.

30


Chapter 2 CPM API Groups Internet Transaction Data (ITD) Group

Customer ANI 178 ANI-specified phone number that the customer used to place the order.

10

Customer Information ID

179 Telephone-company-provided ANI-ii-coding digits associated with the customer ANI phone number that correspond to call type. Examples of call type are cellular, government, or institution.

2

Table 14 Internet Transaction Data (ITD) Group Fields (Continued)


Description Length


Chapter 2 CPM API Groups Billing Group (Soft Descriptors)

Billing Group (Soft Descriptors)The billing information group contains soft descriptor fields. These fields provide data for processors to change the merchant information that appears on the cardholder’s statement. Not all processors have this feature.

Some processors that support the use of soft descriptors require that you work with them to determine the content for these fields. Check with your processor to determine their requirements.

Important If Paymentech New Hampshire is your processor, Paymentech will usea default descriptor for your transactions unless you override it by using the Mer-chant Billing Name and Merchant Billing Location fields listed in Table 15. How-ever, if you use these API fields to dynamically change the soft descriptor for oneparticular transaction, all of the subsequent transactions in that settlement batchfile will use the same soft descriptor, unless you dynamically set the soft descriptorfor each of the transactions. You cannot control the order in which the transactionsappear in the settlement file. Therefore, you should always use the soft descriptorAPI fields for every transaction, or never use them for any of your transactions.

CyberSource recommends that all CPM API integrations include all fields in the billing information group.

Table 15 Billing Information Group Fields


Description Length

Merchant Billing Name

190 Merchant’s billing name and/or item description. This is the information that appears on the cardholder’s statement. If used for ACH/EFT transaction, additional information in an 'M' record that appears on the customer's statement.

For Paymentech New Hampshire, this value must be in one of these formats:

• <12-character merchant name>*<9-character product description>



25

Merchant Billing State

191 Merchant’s billing state. 2


Chapter 2 CPM API Groups Purchasing Card Group

Purchasing Card GroupSome companies use special credit cards, called purchasing cards, to facilitate the purchasing process. Issuing banks provide detailed reports to their customers about the usage of the card in the previous period. The CPM Server supports Purchasing Card level II and III support. Level II support provides the customer with a customer supplied purchase order number and tax amount. Level III support provides the customer information regarding each item in a purchase. See page 56. Level III support is available for the following gateways:

• FDMS South

• Paymentech New Hampshire

• FTPS

• Vital

Merchant Billing Location

192 Merchant’s billing location. This is the city or customer service phone number that will appear on the cardholder’s statement. If used for ACH/EFT transaction, additional information in an 'M' record that appears on the customer's statement.

13

Table 15 Billing Information Group Fields (Continued)


Description Length



Note The purchasing card support does not provide a merchant with additionalfeatures. A merchant can provide Purchasing Card Level II support to their cus-tomers. Use these fields only if the credit card presented is a purchasing card.

Table 16 Purchasing Card Group Fields


Description Length

Purchase Card Order Number

155 The customer supplied identifier associated with a purchase.

16

Tax Amount 156 The tax amount for the transaction. This field is added to the purchase amount field for the total purchase amount. The format is DDDDDDDDDDCC.


12

Commercial Card Type

157 The type of corporate card used. Possible values:

• 00: Not a commercial card

• 01: Purchasing card

• 02: Corporate card

• 03: Business card

• 04: Unknown

2

Ship To Zip Code 158 The postal code to where the product is shipped. Can be used as input for the field Ship To Zip Code AVS.

9


159 Product’s identifier code. 15

Transaction Advice Addendum 1

900 Transaction Advice Addendum field. Used for

• Paymentech New Hampshire American Express purchasing cards.

• American Express Phoenix Level II purchasing cards and non-Level II cards. See Using the TAA1 and Charge Description Fields with American Express Phoenix on page 54 for more information.

The field is used to display descriptive information about the transaction in the customer’s statement. Supported only for transactions using USD and CAD currencies.

40




901 See description for Transaction Advice Addendum 1 field above.

40



40



40

Transaction Advice Addendum Amount 1

904 The unit cost for the Transaction Advice Addendum 1 field.

12



12



12



12

Transaction Advice Addendum Quantity 1

908 The quantity purchased for the Transaction Advice Addendum 1 field.

3



3



3



3

Table 16 Purchasing Card Group Fields (Continued)


Description Length


Chapter 2 CPM API Groups American Express Retail TAA Group

Using the TAA1 and Charge Description Fields with American Express Phoenix

If you are using the American Express Phoenix gateway, you can use the TAA1 field regardless of whether or not you are a Level II merchant.

The TAA1 field is required for Level II captures and returns. If you are a Level II merchant, you must specify a default value for the TAA1 field in the agreement settings dialog box in the Administration Client. The software uses the default value as follows:

• For captures, if you included the TAA1 field in your request, the CPM software stores the TAA1 value in the database. When it is time for settlement, the software looks in the database for the value and puts it in the settlement record. If there is no TAA1 value in the database, which occurs if you did not send in the API field, the software uses the default value from the agreement settings.

• For returns, the CPM software automatically uses the default value from the agreement settings.

You can include up to four TAA API fields in a capture request.

In the American Express Phoenix agreement settings dialog box in the Administration Client there is also a value for a Retail Charge Description. If you are a Level II merchant, the TAA1 value overrides the charge description value: Only the TAA1 value will be sent in the settlement record. If you are a retail merchant, you can specify a default charge description on the Agreement Settings dialog. You can include up to six retail charge description API fields in a capture request.

American Express Retail TAA GroupThe American Express retail TAA group contains information about retail purchases.

Table 17 American Express Retail TAA Group Fields


Description Length

Retail Department Name

912 Name of the department where the retail transaction took place.

40

Retail Item 1 Description

913 Description of retail item 1. 19




Chapter 2 CPM API Groups American Express Retail TAA Group









Retail Item 1 Amount

919 Unit cost of retail item 1. 12











Retail Item 1 Quantity

925 Quantity purchased of retail item 1. 3











Table 17 American Express Retail TAA Group Fields (Continued)


Description Length


Chapter 2 CPM API Groups Level III Purchasing Card Group

Level III Purchasing Card GroupThe Level III purchasing card group contains fields for additional tax, shipping, and handling charges for purchasing cards. The Level III purchasing line item detail group, which is described on page 57, contains line item information fields that can be repeated for each item in the purchase. CPM provides Level III support for FDMS South, Paymentech New Hampshire, FTPS, and Vital gateways only.

If the CPM API integration is to support purchase card Level III compatibility, include all API fields in the following API groups:

• Level III purchase card group

• Level III purchase card line item detail group

To enhance business to business functionality, also include the purchasing card group. See page 51.

Table 18 Level III Purchasing Card Group Fields


Description Length

Freight Amount 500 Total freight or shipping and handling charges. The format is DDDDDDDDDDCC.

20

Duty Amount 501 Total of any import or export duties for this transaction. The format is DDDDDDDDDDCC.

20

Ship from Zip Code

503 The postal code from which the product is shipped.

9

Ship To Country 471 Two-letter ISO country code of the location to where the product is shipped. See the processor specification for a list of ISO country codes.

NOTE Ship To Country is a required field for Paymentech New Hampshire International AVS transactions, which are Authorization transactions and Authorization and Capture transactions, if Customer Country is not set.

2

Discount Amount Applied

504 Total amount of the discount applied to the merchant for this transaction. The format is DDDDDDDDDDCC.

20

VAT Tax Amount 505 VAT or other tax included in this transaction. The format is DDDDDDDDDDCC.

20

VAT Tax Rate 506 Rate of VAT or other tax. 20


Chapter 2 CPM API Groups Level III Purchasing Card Line Item Detail Group

Level III Purchasing Card Line Item Detail GroupThe Level III purchasing card line item detail group contains fields for information regarding each item in a purchase. CPM provides Level III support for FDMS South, Paymentech New Hampshire, FTPS, and Vital gateways only.

Alternative Tax ID 507 Tax identifier for the alternate tax included in this transaction.

20

Alternative Tax Amount

508 Total amount of the alternate tax included in this transaction. The format is DDDDDDDDDDCC.

20

Line Item Detail Count

509 The number of line item detail records in this purchase.

3

Table 18 Level III Purchasing Card Group Fields (Continued)


Description Length

Table 19 Level III Purchasing Card Line Item Detail Group Fields


Description Length

Item Description 10000 Text description of the item purchased. 35

Item Product Code

11000 Product code of the item purchased. 12

Item Quantity 12000 Number of units of the item purchased. For Visa customers, the format is DDDDDDDDCCCC. For MasterCard customers, the format is DDDDDDDDDDCC.

12

Item Unit of Measure

13000 Unit of measurement used in international trade for the item purchased.

12

Item Tax Amount 14000 Tax amount for item purchased. The format is DDDDDDDDDDCC.

12

Item Tax Rate 15000 Tax rate applied to item purchased. 5

Item Total Amount 16000 Total amount charged for item purchased. The format is DDDDDDDDDDCC.

12

Item Discount Amount

17000 Amount of discount applied to this line item. The format is DDDDDDDDDDCC.

12


Chapter 2 CPM API Groups Health Benefit Card Group

Health Benefit Card GroupHealth benefit cards, also known as Flexible Spending Account (FSA) and Heath Reimbursement Account (HRA) cards are supported on the Paymentech New Hampshire and Global Payments gateways. These cards are funded based on the various healthcare plan requirements and depleted as the cards are used. The health benefit card group contains the QHP Amount field that identifies the transaction as an FSA/HRA transaction. The remaining optional fields categorize the types of health care related purchases.

Item Commodity Code

18000 Commodity code used to classify the item purchased.

12

Item Unit Cost 19000 Unit cost of the item purchased. For Visa customers only. The format is DDDDDDDDCCCC.

12

Item Discount Indicator

20000 Indicates if a discount was applied to the item purchased. Possible values:

• Y: Yes

• N: No

1

Item Tax Type Applied

21000 Type of Value-Added tax applied to the item purchased. For non-U.S. purchases.

4

Item Tax Applied 22000 Tax applied. Possible values:

• Y: Yes

• N (default): No

1

Item Tax Exempt 23000 Tax exempt. Possible values:

• Y: Yes

• N (default): No

1

Item Return Indicator

24000 Indicates if the item is a return. Possible values:

• Y: Yes

• N (default): No

1

Table 19 Level III Purchasing Card Line Item Detail Group Fields (Continued)


Description Length


Chapter 2 CPM API Groups Pre-Paid Card Group

Pre-Paid Card GroupPre-paid cards use similar functionality as credit cards, but draw against the amount funded on the pre-paid card rather than the user’s line of credit. Since it is difficult to deplete the exact amount on the card, merchants may choose to support partial authorization. When partial authorization is enabled, transaction amounts in excess of the remaining balance on the card will be partially approved and the remaining transaction amount must be tendered with a different form of payment.

Table 20 Health Benefit Card Group Fields


Description Length

QHP Amount 3000 Qualified health benefit (FSA/HRA) amount of the transaction.

12

RX Amount 3001 Prescription drug portion of the QHP amount.

12

Vision Amount 3002 Vision portion of the QHP amount. 12

Clinic Other Amount

3003 Clinic/Other portion of the QHP amount. 12

Dental Amount 3004 Dental portion of the QHP amount. 12


Chapter 2 CPM API Groups Pre-Paid Card Group

Table 21 Pre-Paidt Card Group Fields


Description Length

Partial Auth Flag 3005 Partial redemption indicator. Allows for approval if the transaction amount is greater than the remaining balance on a pre-paid card. This flag is used to override merchant level default.

• Y: Partial authorization is allowed for the account.

• N: Partial authorizaion is not allowed for the account.

Note Applies to Visa, Master-Card, American Express, andDiscover cards on the Pay-mentech New Hampshire andGlobal Payments gateways.

• B: Both sale amount and cash back may be partially approved. The sale amount must be fully approved before the cash back amount can be partially approved.

• C: The sale amount must be fully approved before the cash back amount may be partially approved.

• X: Merchant may support partial auth, but the sale amount must be fully approved before the cash back amount can be approved. Neither the sale amount nor the cash back amount can be partially approved.

Note Applies only to Discovercard on the Paymentech NewHampshire gateway.

1

Remaining Balance

360 Available balance left on a pre-paid card. 12


Chapter 2 CPM API Groups User Defined Group

User Defined GroupThe CPM Server provides seven user fields for CPM API integration software developers to save additional transaction information to the CC_TRANSACTION database table with every transaction performed. The API passes these fields to the CPM Server database where they are saved. These fields are NOT passed through to the financial processor.

Magnetic Track GroupThe magnetic track, or card swipe data, group passes data to the CPM server in Card Present situations when the credit or debit card is swiped through a card magnetic stripe card reader:

• For Track 1 (IATA), the magnetic strip contains 79 characters. CPM accepts only the 76 non-control characters.

• For Track 2 (ABA), the magnetic strip contains 40 characters. CPM accepts only the 37 non-control characters.

The reason for the difference is that CPM does not accept the passing of the start sentinel, the end sentinel, or the LRC values that are stored in the magnetic strip. Some magnetic card readers are configured to pass these three control characters, and so the application that passes the data must remove the characters before sending the data to the CPM server.

Table 22 User Defined Group Fields


Description Length

User Sequence Number

200 Field usage defined by merchant. Can store a merchant-generated sequence number.

50

User Defined 1 201 Field usage defined by merchant. 50





User Source Name

296 Field usage defined by merchant. 31


Chapter 2 CPM API Groups Magnetic Track Group

When implementing a CPM API integration that uses the magnetic track group:

• You must include all the fields in the Terminal setup group. See Terminal Setup Group on page 40.

• For PIN-based debit card authorizations, returns, and reversals, track 2 data is required and track 1 data is not used.

• For all other types of transactions, you can provide track 1 data or track 2 data or both.

Table 23 Magnetic Track Group Fields


Description Length

Track 1 Data 250 Track 1 data from a credit or debit card strip. Do not include the start sentinel, end sentinel, or LRC values.

76

Track 2 Data 251 Track 2 data from a credit or debit card strip. Do not include the start sentinel, end sentinel, or LRC values.

NOTE This field is required for PIN-based debit card authorizations, returns, and reversals.

37

PIN Block 252 Contains the encrypted customer PIN obtained from the PIN pad during a PIN-based debit transaction.

16

Key Sequence Number

253 The key sequence number obtained from the PIN pad during a PIN-based debit transaction. Remove any leading Fs before sending the value.

16

Terminal Fee 254 For Paymentech Tampa PIN-based debits, if you have arranged with the processor to charge a terminal fee, this output field will contain the amount of that fee. If the amount is not zero, you must print the fee amount on the customer’s receipt and label it “Terminal Fee.” The format for Paymentech Tampa is DDDDDCC.

For NOVA PIN-based debits, use this field as a request field to specify any terminal fee that you are charging for the transaction. The format for NOVA Debit is DDCC.

12



PIN-based Debit CardsOne particular application of the Magnetic Track Group fields is for processing PIN-based debit transactions using Automated Teller Machine (ATM) cards. These types of transactions are also referred to as online debit transactions, and are available only through the FDMS South Debit, NOVA Debit, and Paymentech Tampa gateways.

Note PIN-based debit cards are different from PIN-less debit cards. See PIN-lessDebit Cards on page 26.

PIN-based debit cards are used in retail, card-present environments. An example of a common location for PIN-based debit is grocery stores. The customer swipes the card and then enters a personal identification number (PIN). If the merchant supports it, the customer may also request to receive cash back from the transaction. The authorization is processed online immediately through a debit network. The customer does not sign a receipt to authorize the transaction.

To process PIN-based debit cards, you must have a PIN pad that is compatible with DUKPT PIN encryption. The PIN pad must also contain the appropriate encryption key from the payment processor.

Processing a DebitTo process the debit card, you must use the combined Authorization and Capture transaction. Do not use an Authorization followed later by a separate Capture.

When requesting the Authorization and Capture for a PIN-based debit card:

• Set the Card Type field to 029. See the field description in Table 5 on page 23.

• Include the Track 2, PIN Block, and Key Sequence Number fields. See Table 23 on page 62.

• Optionally include the Cash Back Amount field. See the field description in Table 6, which starts on page 28. The Cash Back Amount should be included in the overall Amount for the transaction.

• For NOVA, if you are charging a terminal fee, include that value in the Terminal Fee field. Include the amount of the terminal fee in the overall Amount for the transaction.

The main reply fields of interest are the same ones you receive for a credit card:

• Approval Code (from the debit network). Print the Approval Code on the customer’s receipt. See the field description in Table 5 on page 23.

• Authorization Response Code.



• Authorization Response Message.

• Return Code Message.

• Processor Auth Response Code.

• Retrieval Reference Number (for NOVA). Keep track of the Retrieval Reference Number as you will need it if you need to process a Return. See the field description in Table 6, which starts on page 28.

• For FDMS South and Paymentech Tampa, if in the reply you receive the Terminal Fee field with a value, print the value on the customer’s receipt. See Table 23 on page 62.

For FDMS South and Paymentech Tampa, if an error occurs while processing a PIN-based debit, you must reverse the transaction. For more information, see Reversal on page 119.

For FDMS South and Paymentech Tampa, if you need to refund the customer’s money, you must provide a cash or check refund. Do not use the Return transaction as you would with a credit card.

For NOVA, if you need to refund the customer’s money, use the Return transaction. If the return request is successful, you do not need to provide the refund in cash. If the debit network does not support refunds, the return request will be declined. In this case, you need to provide the refund in cash. In the Return request, you need to provide these API fields:

• Card Type

• Transaction Amount

• Track 2 Data

• PIN Block

• Key Sequence Number

• Retrieval Reference Number—with the reference number you received in the debit reply

• Last Record Number

Using the Last Record Number with NOVADebit transactions are submitted to NOVA on a Terminal ID (TID) basis. Typically, each PIN pad device is assigned a unique TID for which a sequential count of debit


Chapter 2 CPM API Groups CPM Reserved Group

transactions is maintained. You need to assign a TID to each PIN device and keep track of the Last Record Number for each TID as follows:

• NOVA batches PIN-based transactions by TID on a daily basis. For each TID that you have, NOVA assigns a Last Record Number to each transaction (each sale or return) in the TID’s daily batch. The Last Record Number is 0 for the first transaction in the TID’s daily batch and increments by 1 for each subsequent transaction. After the TID’s daily batch is closed, the numbering again starts with 0 for the first transaction in the TID’s next batch.

• You must provide the Last Record Number API field for each transaction. You will not know when NOVA closes the TID’s batch, so you will not know when the numbering starts again at 0. However, NOVA replies to each transaction with the Last Record Number that you should use for the next transaction that you send for that TID. When a TID’s batch closes, the reply for the next transaction will have a 1 as the Last Record Number, indicating that the transaction you just sent was the first transaction (the 0 transaction) for the TID’s new batch. Use Last Record Number=1 for the next transaction that you send.

• To stay in sync with NOVA for each TID, store the most recent Last Record Number sent by NOVA for that TID. Use the stored number as the Last Record Number for the next transaction you submit for the TID.

• If you get out of sync with NOVA and submit a Last Record Number that NOVA does not expect for the TID, you will receive Authorization Response Message=SEQ ERR PLS CALL. The Last Record Number that NOVA replies with is the one they expected to receive. You do not need to call NOVA; all you need to do is resubmit the transaction with the Last Record Number that NOVA provided in the reply. This error does not occur when you send the first transaction of a batch with a value other than the expected 0; NOVA will accept that transaction, assuming you supply the rest of the required information correctly, and will reply with Last Record Number=1.

If you have multiple merchant IDs and multiple PIN devices for each merchant ID, then you might want to use the NOVA Debit Controller so that you don’t have to keep track of the TIDs and Last Record Numbers. The Controller lets CPM dynamically assign the TID and Last Record Number for each NOVA Debit transaction. See the CPM NOVA Debit Controller Administration Guide.

CPM Reserved GroupThese fields are reserved for future use with the CPM Server. Do not used these fields.


Chapter 2 CPM API Groups CPM Reserved Group

Table 24 Payment Server Reserved Group Fields


Description Length

Reserved 1 222 Reserved field. Do not use.

Reserved 2 223 Reserved field. Do not use.


Chapter 2 CPM API Groups Security Group

Security GroupThe security group contains input fields for logging into the CPM Server. Use these fields when transaction security is enabled on the CPM Server. All CPM API integrations should include all fields in the security group to support CPM security.

Processor Specific Response GroupThe CPM Server provides a processor independent interface to perform credit card functions. The processor specific return codes are available to the user through these fields. All CPM API integrations should include all fields in the processor specific response group.

Table 25 Security Group Fields


Description Length

Username 450 The CPM Server logon username. 31

Password 451 The password associated with the username.

128

Table 26 Processor Specific Response Group Fields


Description Length

Processor AVS Result

400 The processor specific address verification result codes.

3

Processor Authorization Response Code

401 The processor specific authorization response codes.

4


Chapter 2 CPM API Groups Private Label Card Group

Private Label Card GroupGeneral Electric Capital Corporation (GECC) and Beneficial Finance Corporation are financial processors as well as a private label card issuers. GECC and Beneficial enable participating businesses to brand the card before issuing the card to their customers. These branded cards are used for promotions, sales, or specific customer plans. For example, an airline may issue a card under its private label to a frequent flyer customer, and the customer may be able to obtain free travel after accumulating frequent flyer miles. The GECC and Beneficial private label card provides fields and identifiers to handle this specialized processing.

The workflow for private label cards is variable when implementing the fields in a CPM API integration. It is necessary to coordinate with the private card issuer, the financial processor, and the acquiring bank for the correct use of the fields for your business type.

Note Only the Paymentech New Hampshire gateway supports GECC and Benefi-cial private label card processing.

Table 27 Private Label Card Detail Group Fields


Description Length

Promotional Plan 600 This field is defined by GECC. 1

Promotional End Date

601 This field is defined by GECC. 4

Sale Type 602 This field is defined by GECC. 1

Line item 1 603 GECC private card line item detail. Defined by GECC.

4


4


4


4


4


4


Chapter 2 CPM API Groups Private Label Card Group


4

Microfiche Sequence Number

610 GECC Microfiche sequence number associated with the transaction.

8

Plan Number 611 This field is defined by GECC. 5

Credit Plan 650 This field’s use is defined by the merchant and Beneficial.

5

Department Codes

651 This field’s use is defined by the merchant and Beneficial.

4

SKU Number 652 The Stock Keeping Unit (SKU) number associated with the transaction based on the merchant’s unique SKU schema.

9

Item Description 653 Description of item associated with the transaction. Defined by merchant.

40

Store Number 654 This field’s use is defined by the merchant and Beneficial.

5

Table 27 Private Label Card Detail Group Fields (Continued)


Description Length


Chapter 2 CPM API Groups Electronic Fund Transfer Group

Electronic Fund Transfer GroupThe electronic funds transfer group facilitates EFT and ACH transactions by the CPM Server.

Note Only the Paymentech New Hampshire gateway supports EFT and ACH pro-cessing.

Table 28 ACH Group Fields

FieldNumeric identifier

Description Length

Bank Account Number

110 The bank account number in which to credit or debit funds.

17

Bank ID 111 The transit routing number of the bank holding the target account. This field is also known as the ABA number or RDFI number.

9

Account Type 112 Type of bank account used in this transaction. Check the financial processor specification for the proper variables used for this field. These values are set at the point of sale.

1

Verification Result 113 CPM independent field detailing the result of the verification for this transaction. Possible values:

• A: Verification successful

• D: Verification rejected

1

Processor Response Code

114 Financial processor dependent result code of the verification.

4

Processor Response Message

115 Financial processor dependent result message of the verification.

20


Chapter 2 CPM API Groups Direct Debit Group

Direct Debit GroupThe Direct Debit group allows you to send direct debit transactions. See Direct Debit Transactions on page 15 for more information.

Note Only the Paymentech New Hampshire gateway supports this transactiongroup.

Table 29 Direct Debit Group Fields

FieldNumeric identifier

Description Length

Bank Sort Code 2000 Bank’s sort code. 10

Bank Country Code

2001 Country code of country where bank is located. Valid values:

• AT: Austria

• BE: Belgium

• DE: Germany

• FR: France

• NL: Netherlands

• GB: United Kingdom

2

RIB Code 2002 Bank’s RIB code; used for direct debits in France.

2


Chapter 2 CPM API Groups Maestro (Switch/Solo) Card Group

Maestro (Switch/Solo) Card GroupThe Maestro (Switch/Solo) card group allows you to send Maestro (Switch/Solo) card transactions.

Note Only the Paymentech New Hampshire gateway supports this transactiongroup.

Hotel and Car Rental GroupThe hotel and car rental group provides detailed information for hotel registration or rental agreements. You cannot send car and hotel information in the same transaction. You can use this transaction group for capture and authorize and capture transactions only; do not use this group for authorization transactions.

Note Only the FDMS South gateway supports this transaction group. You can usethis transaction group for the Visa, MasterCard, and American Express card types.

Table 30 Maestro (Switch/Solo) Card Group Fields


Description Length

Card Start Date 700 Card starting date. The format is MMYY. 4

Card Issue Number

701 The Maestro (Switch/Solo) card issue number.

2

Table 31 Hotel and Car Rental Group Fields


Description Length

Hotel Folio Number

800 Hotel number assigned to track expenses. 10

Rental Agreement Number

801 Rental contract or agreement number. 9

Check In Date 802 Hotel check in date. The format is YYYYMMDD. 8

Check Out Date 803 Hotel check out date. The format is YYYYMMDD. 8


Chapter 2 CPM API Groups Hotel and Car Rental Group

Pick Up Date 804 Rental pickup date. The format is YYYYMMDD. 6

Drop Off Date 805 Rental drop off date. The format is YYYYMMDD. 8

Extra Charges Indicator

806 Extra charges for either hotel or rental.

Possible values for hotel transactions:

• 2: Restaurant

• 3: Gift shop

• 4: Mini bar

• 5: Telephone

• 6: Other

• 7: Laundry

Possible values for rental transactions:

• 1: Gas

• 2: Extra mileage

• 3: Late return

• 4: One way service fee

• 5: Parking violation

6

No Show Indicator 807 Hotel or rental value. Possible values:

• 0 (default): Not applicable.

• 1: No show.

1

Return City 808 City the rental was returned to. Use the full city name.

18

Return State 809 State the rental was returned to. Use the state or country code.

3

Return Location ID

810 Rental return location identifier, such as rental code, address, or phone number.

10

Charge Type 811 Type of charge. Possible values:

• 1: Lodging

• 2: Restaurant

• 3: Gift shop/other

1

Duration Of Stay 812 Number of nights cardholder stays at hotel. 2

Room Rate 813 Room rate of last night’s stay. The format is NNN.NN.

5

Table 31 Hotel and Car Rental Group Fields (Continued)


Description Length


Chapter 2 CPM API Groups Hotel and Car Rental Group

Special Program Code

814 Special program code. Possible values:

• 1: Intentionally not used.

• 2: Assured reservation/no show.

• 3: CARDeposit. Cardholder’s account number charged for an advance deposit

• 4: Delayed charge.

• 5: Express Service. Assured reservation made against the cardholder’s account number.

• 6: Assured reservation.

1

Food Amount 815 Total cost of food and food/beverage. The format is NNNNNN.NN.

8

Beverage Amount 816 Total cost of beverages if broken out separately on charge. The format is NNNNNN.NN.

8

Tip 1 Amount 817 Employee tip if on charge. The format is NNNNNN.NN.

8

Tip 2 Amount 818 Second employee tip if on charge. The format is NNNNNN.NN.

8

Table 31 Hotel and Car Rental Group Fields (Continued)


Description Length


Chapter 2 CPM API Groups Admin Command Group

Admin Command GroupThe admin command group issues administrative commands to the CPM server. Currently the only administrative command available is used to initiate the settlement procedure.

Table 32 Admin Command Group Fields


Description Length

Admin Command String

1 Contains the command to be carried out by the server. Currently the only valid value is settle_now, which initiates the settlement procedure.

Undefined

Merchant List 2 Comma-separated list of merchant IDs to be settled. If specified, only those merchants in the list will have their transactions settled. If omitted, all merchants will have their transactions settled.

Undefined


Chapter 2 CPM API Groups Admin Command Group

Gateway List 3 Comma-separated list of gateways to be settled. if specified, only those gateways in the list will have their transactions settled. If omitted, all gateways will have their transactions settled. Below is a list of valid values. Spaces and case are significant.

• AMEX

• BA Merchant Services

• FDMS Nashville Frame

• FDMS South Frame

• FDMS South Debit

• FDMS North Frame

• Global Payments Frame (previously this value was NDC East Frame)

• FTPS Frame

• NOVA

• NOVA Debit

• Paymentech Frame (for Paymentech New Hampshire)

• PTampa (for Paymentech Tampa)

• RBS Worldpay SSL

• Vital VirtualNet IP Frame

• Vital VirtualNet SSL

Undefined

Start Date 4 Controls which transactions will be settled. Transactions issued after this date and time will be included in the settlement. If not specified, the Settlement Floor specified for each merchant will be used for the start date. The format is yyyy-mm-dd hh:mm:ss.

19

End Date 5 Controls which transactions will be settled. Transactions issued before this date will be included in the settlement. If not specified, all transactions to the end of the database will be included. The format is yyyy-mm-dd hh:mm:ss.

19

Table 32 Admin Command Group Fields


Description Length


Chapter 2 CPM API Groups API Input Notes

API Input Notes

Amount FieldThe CPM database schema allows the last four positions of an amount to be interpreted as the decimal (cents). However, the CPM API and CPM Server only interpret the last two positions as the decimal.

When an amount is recorded to the CPM Server database, an implied decimal is added. As the amount is read from the database and then submitted back to the CPM API calling application or the financial processor, the decimal is removed from the amount.

The following tables describe how each transaction uses the amount fields.

Authorization

Capture

Table 33 Authorization Amount Field Usage

Field Name Usage

AMOUNT The purchase amount from the CPM API.

Note For PIN-based debit transactions, the Amount should include the Cash Back Amount.

ORIGINAL_AMOUNT The purchase amount plus the tax amount.

CURRENT_AMOUNT The purchase amount plus the tax amount. If this transaction is reversed, update this field from the Reversal Current_Amount field.

TAX_AMOUNT The tax amount from the API.

Table 34 Capture Amount Field Usage

Field Name Usage

AMOUNT Copy this amount from the API if present or copy from the parent transaction if the SEQUENCE_NUMBER is provided.

ORIGINAL_AMOUNT Copy this amount from the API if present or copy from the parent transaction if the SEQUENCE_NUMBER is provided.



Authorize and Capture

Reversal

CURRENT_AMOUNT Copy this amount from the API if present or copy from the parent transaction if the SEQUENCE_NUMBER is provided.

TAX_AMOUNT Copy this amount from the API if present or copy from the parent transaction if the SEQUENCE_NUMBER is provided.

Table 35 Authorize and Capture Amount Field Usage

Field Name Usage

AMOUNT Authorize - The purchase amount from the CPM API.

Note For PIN-based debit transactions, the Amount for the authorization should include the Cash Back Amount.

Capture - Copy this amount from the API if present or copy from the parent transaction if the SEQUENCE_NUMBER is provided.

ORIGINAL_AMOUNT Authorize - The purchase amount plus the tax amount.


CURRENT_AMOUNT Authorize - The purchase amount plus the tax amount. If this transaction is reversed, update this field from the Reversal Current_Amount field.


TAX_AMOUNT Authorize - The tax amount from the API.


Table 36 Reversal Amount Field Usage

Field Name Usage

AMOUNT For credit cards, amount the authorization should reflect.

For debit cards, the amount to reverse, which should be the entire amount of the original Authorization or Authorization and Capture transaction.

Table 34 Capture Amount Field Usage

Field Name Usage



Return

Void

ORIGINAL_AMOUNT Copy this amount from the Orginal_Amount of the parent transaction.

CURRENT_AMOUNT Copy from the Current_Amount field of the parent transaction. If the reversal is successful, update this field to equal AMOUNT plus TAX_AMOUNT.

TAX_AMOUNT The tax amount from the API if present or 0.

Table 37 Return Amount Field Usage

Field Name Usage

AMOUNT Copy this amount from the API or copy from the parent transaction if the SEQUENCE_NUMBER is provided.

ORIGINAL_AMOUNT Not used.

CURRENT_AMOUNT Not used.

TAX_AMOUNT Copy this amount from the API if present or copy from the parent transaction if the SEQUENCE_NUMBER is provided.

Table 38 Void Amount Field Usage

Field Name Usage

AMOUNT Copy this amount from the parent transaction.



TAX_AMOUNT Not used.

Table 36 Reversal Amount Field Usage

Field Name Usage



Manual Authorization

Lookup

ACH Verify

Table 39 Manual Authorization Amount Field Usage

Field Name Usage


ORIGINAL_AMOUNT The purchase amount plus the tax amount.

CURRENT_AMOUNT The purchase amount plus the tax amount. If this transaction is reversed, update this field from the Reversal Current_Amount field.

TAX_AMOUNT The tax amount from the API.

Table 40 Lookup Amount Field Usage

Field Name Usage

AMOUNT Copy this amount from the parent transaction.

ORIGINAL_AMOUNT Copy this amount from the parent transaction.

CURRENT_AMOUNT Copy this amount from the parent transaction.

TAX_AMOUNT Copy this amount from the parent transaction.

Table 41 ACH Verify Amount Field Usage

Field Name Usage







ACH Deposit

ACH Refund

Sequence Number Field The Sequence Number field is more than an output field providing an index to the transaction table in the database. The sequence number field has two important functions when used as an input field:

• Associates a series of related transactions in the database.

• Aids in transferring authorization detail information to subsequent transactions.

Note The use of the Sequence Number is not required, but highly recommended.

The process of transferring funds with credit card functions can take a series of steps. For example, an authorization may need a reversal, leading to a capture. You can tie these transactions together by saving the Sequence Number of the original transaction and inputting this Sequence Number into the Sequence Number field of the next transaction based on the original authorization. The original transaction field is stored in the database

Table 42 ACH Deposit Amount Field Usage

Field Name Usage





Table 43 ACH Refund Amount Field Usage

Field Name Usage







so that the system can perform any audit trail necessary from the authorization through the capture.

The second use of the Sequence Number helps reduce the work necessary by the developer by decreasing the number of fields needed in reversals and captures. The CPM Server must often resubmit information received from an authorization to the processor during a reversal or capture. If the user loads the sequence number of an authorization in the Sequence Number field of an associated reversal or capture, the CPM Server retrieves the authorization information from the database and loads the input fields to the transaction properly.

Important When performing a Capture or Reversal that references a manuallyauthorized Authorization or combined Authorization and Capture, provide thesequence number for the original Authorization, which is the 100 transaction, orthe Authorization and Capture, which is the 104 transaction, and NOT for the Man-ual Authorization, which is the 105 transaction. See Manual Authorization onpage 11.

When using the Sequence Number field to copy authorization information to subsequent transactions, the user still has the ability to override the information in the database. Information passed to the CPM Server through the CPM API has priority over the information in the database.

For example, a merchant performs an authorization for $100 and the authorization returns an approval code of 123456 and a Sequence Number of 0012. When the merchant performs the corresponding capture, the merchant realizes she only wants to use $90 of the original $100. The merchant can submit the capture with the following data: Purchase Amount = $90, Sequence Number = 000100000000012. The CPM Server looks up the approval code of 123456 and purchase amount of $100. However, only the approval code is copied to the capture transaction as the purchase amount of $90 has priority.


Chapter 3

CPM API Function Requirements

This chapter lists all the possible inputs and outputs for each of the API transaction types. For descriptions of each input and output field, see Chapter 2, CPM API Groups, on page 22.

API field requirements are recommendations at the point of sale (POS). For example, if your business accepts Purchase Card Level III, enable acceptance of this transaction information at your points of sale. Only some field outputs are appropriate for the customer or merchant representative at the POS. See Chapter 4, CPM API Output Codes, on page 162 or your financial processor for more information.

The CPM Server will not process a transaction if the required fields are not submitted from the CPM API to the CPM Server.

The chapter is divided into these sections:

Credit and Debit Cards Transactions: ACH Transactions:

• Authorization • ACH Verify

• Capture • ACH Deposit

• Authorize and Capture • ACH Refund

• Reversal • ACH Void

• Return • ACH Lookup

• Void Direct Debit Transactions:

• Manual Authorization • Direct Debit Validate

• Lookup • Direct Debit Deposit

• BIN Lookup • Direct Debit Refund

General Transactions: • Direct Debit Void

• Admin Command • Direct Debit Lookup

• Begin Session

• End Session


Chapter 3 CPM API Function Requirements Authorization

Authorization

Input

Table 44 Authorization Input Requirements

Field POS Field Requirement Comments

Merchant ID Required.

Account Number Required. Either Account Number and Expiration Date, or Track 1 Data, or Track 2 Data is required.

Card Type Required.

Expiration Date Required.

Amount Required.

Address Recommended for direct marketing merchants. Also see Visa RED Regulations for AVS on page 33.

Zip Code Recommended for direct marketing merchants. Also see Visa RED Regulations for AVS on page 33.

AVS Level Optional Level of AVS to use for the transaction. Overrides the merchant configuration setting. See Address Verification Service Group on page 32 for more information.

Ship To Firstname Optional. Required to use AAV+ with the American Express Phoenix gateway.

Ship To Lastname Optional. Required to use AAV+ with the American Express Phoenix gateway.

Order Number Recommended for direct marketing merchants.




CVV Optional.

ECommerce Type Required for Web-based transactions.


Optional For the FTPS and FDMS North gateways, set this field to B to indicate a bill payment. See the field’s description in Table 6 on page 28 for more information.

Track 1 Data Required for transactions where the card is swiped through a card reader.


Amex Retail Info Required only for the Paymentech Tampa gateway for retail transactions using American Express cards.

See Using the Amex Retail Info Field on page 31 for the format.

Requested ACI Optional. See Extended Information Group on page 28 for more information.

Customer Name Optional. See Visa RED Regulations for AVS on page 33.

Customer Firstname

Optional. Required to use Enhanced AVS with the American Express Phoenix gateway.

Customer Lastname


Customer Phone Optional.

Customer City Optional.

Customer State Optional.

Customer Country Optional.

Customer Hostname

Optional.

Table 44 Authorization Input Requirements (Continued)




Card Present Flag Optional.


Optional.

Terminal Type Optional.

Terminal Capability Optional.

POS Entry Mode Optional.

UCAF Indicator Optional Used for payer authentication. See ECommerce Group on page 44 for information about how to use the payer authentication fields and when each is required.

CAVV Optional Used for payer authentication.

XID Optional Used for payer authentication.

Raw ECI Optional Used for payer authentication.

HTTP Browser Type

Optional.


Required for purchasing cards only.

Tax Amount Required for purchasing cards only.



Ship To Zip Code Required for purchasing cards. Also required to use AAV+ with the American Express Phoenix gateway.


Optional.


Optional.






Optional. If Paymentech New Hampshire is your processor:

• See the important note on page 50.

• In the same section, see the description of the Merchant Billing Name for the format requirements.


Optional.


Optional. See the important note on page 50 if Paymentech New Hampshire is your processor.

User Defined 1 Optional.





User Source Name Optional.

Session ID Required if transaction security is enabled.

Set the session identifier with the Set Session ID function in the CPM API. See Chapter 7, Environment and Implementation, on page 184 for more information.

Ship to address 1 Optional. Required to use AAV+ with the American Express Phoenix gateway.

Ship to address 2 Optional.

Ship to city Optional.

Ship to state Optional.

Ship to phone Optional. Required to use AAV+ with the American Express Phoenix gateway.

Customer IP address

Optional.

Customer email Optional.





Freight Amount Required for purchasing card Level III only.

Duty Amount Required for purchasing card Level III only.

Ship from Zip Code Required for purchasing card Level III only.

Ship To Country Required for purchasing card Level III.

Required for Paymentech New Hampshire International AVS transactions if Customer Country is not set.


Required for purchasing card Level III only.

VAT Tax Amount Required for purchasing card Level III only.

VAT Tax Rate Required for purchasing card Level III only.

Alternative Tax ID Required for purchasing card Level III only.





Item Description Required for purchasing card Level III only.

Item Product Code Required for purchasing card Level III only.

Item Quantity Required for purchasing card Level III only.



Item Tax Amount Required for purchasing card Level III only.

Item Tax Rate Required for purchasing card Level III only.





Item Total Amount Required for purchasing card Level III only.



Item Commodity Code


Item Unit Cost Required for purchasing card Level III only.





Item Tax Applied Required for purchasing card Level III only.

Item Tax Exempt Required for purchasing card Level III only.



Promotional Plan Required for GECC private label card.


Required for GECC private label card.

Sale Type Required for GECC private label card.

Line item 1 Required for GECC private label card.













Plan Number Required for GECC private label card.

Credit Plan Required for Beneficial private label card.

Department Codes Required for Beneficial private label card.

SKU Number Required for Beneficial private label card.

Item Description Required for Beneficial private label card.

Store Number Required for Beneficial private label card.

QHP Amount Required for Health Benefit card.

RX Amount Optional for Health Benefit card.

Vision Amount Optional for Health Benefit card.

Dental Amount Optional for Health Benefit card.

Clinic Other Amount

Optional for Health Benefit card.

Partial Auth Flag To override the merchant default.





Output

Table 45 Authorization Output Fields

Field Comments

Merchant ID

Account Number

Expiration Date

Amount

Card Type

Sequence Number

Approval Code



Return Code Message


Transaction Date

Transaction Time

Validation Code

Response Indicator

Returned ACI

Requested ACI

POS Mode Code



Account Data Source

Card Holder ID


Address Match

Zip Match



Order Number

Card Present Flag

Terminal Capability

Terminal Type

POS Entry Mode


CVV Result

ECommerce Type


Tax Amount


Ship To Zip Code


User Defined 1

User Defined 2

User Defined 3

User Defined 4

User Defined 5

User Source Name

Track 1 Data

Track 2 Data

Terminal Fee

Username If using CPM Security

Password If using CPM Security



Address Field

Table 45 Authorization Output Fields (Continued)

Field Comments


Chapter 3 CPM API Function Requirements Capture

Capture

Input

Zip Code

CAVV Result

Recur Advice Code

Remaining Balance Returned for pre-paid cards depending on the issuer.

Table 45 Authorization Output Fields (Continued)

Field Comments

Table 46 Capture Input Requirements



Account Number Required. This field is filled in if Sequence Number is used.

Card Type Required.

Expiration Date Required. This field is filled in if Sequence Number is used.

Amount Required. This field is filled in if Sequence Number is used.

Current Amount Required.


Required. This field is filled in if Sequence Number is used.



Approval Code Required. This field is filled in if Sequence Number is used EXCEPT when capturing a manually authorized Authorization and Capture transaction. See Manual Authorization on page 11 for important information about including the Approval Code in this situation.

Transaction Date Required. This field is filled in if Sequence Number is used.

Order Number Recommended for direct marketing merchants. This field is filled in if Sequence Number is used.


Customer Street Optional. See Visa RED Regulations for AVS on page 33.

Customer Zip Optional. See Visa RED Regulations for AVS on page 33.




Transaction ID Required. This field is filled in if Sequence Number is used.

ECommerce Type Required for Web-based transactions. This field is filled in if Sequence Number is used.

Table 46 Capture Input Requirements (Continued)




Transaction Time Required. This field is filled in if Sequence Number is used.

Sequence Number Optional. Highly recommended.

NOTE When performing a Capture that references a manually authorized Authorization or combined Authorization and Capture, provide the sequence number for the original Authorization, which is the 100 transaction, or the Authorization and Capture, which is the 104 transaction, and NOT for the Manual Authorization, which is the 105 transaction. See Manual Authorization on page 11.

Validation Code Optional.

Response Indicator Optional.

Returned ACI Optional.

Requested ACI Optional.

POS Mode Code Optional.


Optional.

Account Data Source

Optional. This field is filled in if Sequence Number is used.

Card Holder ID Optional. This field is filled in if Sequence Number is used.





CVV Result Required if CVV check was performed. This field is filled in if Sequence Number is used.





Card Present Flag Optional. This field is filled in if Sequence Number is used.



Terminal Type Optional. This field is filled in if Sequence Number is used.

Terminal Capability Optional. This field is filled in if Sequence Number is used.

POS Entry Mode Optional. This field is filled in if Sequence Number is used.


Required for purchasing cards only. This field is filled in if Sequence Number is used.

Tax Amount Required for purchasing cards only. This field is filled in if Sequence Number is used.


Required for purchasing cards only. This field is filled in if Sequence Number is used.

Ship To Zip Code Required for purchasing cards only. This field is filled in if Sequence Number is used.



User Defined 1 Optional. This field is filled in if Sequence Number is used.









User Source Name Optional. This field is filled in if Sequence Number is used.





If Paymentech New Hampshire is your processor:







See the important note on page 50 if Paymentech New Hampshire is your processor.


Set the session identifier with the Set Session ID function in the CPM API. See the appropriate language in the Chapter 7, Environment and Implementation, on page 184 for more information.





Ship to phone Optional.





Customer IP address

Optional.





Ship To Country Required for purchasing card Level III only.
























Item Commodity Code


































Hotel Folio Number Required for Hotel and car rental only.


Required for Hotel and car rental only.

Check In Date Optional for Hotel and car rental only.

Check Out Date Optional for Hotel and car rental only.

Pickup Date Optional for Hotel and car rental only.

Drop Off Date Optional for Hotel and car rental only.


Optional for Hotel and car rental only.

No Show Indicator Optional for Hotel and car rental only.

Return City Optional for Hotel and car rental only.

Return State Optional for Hotel and car rental only.





Return Location ID Optional for Hotel and car rental only.

Charge Type Required for American Express hotel and car rental. Optional for other hotel and car rental.

Duration Of Stay Optional for Hotel and car rental only.

Room Rate Optional for Hotel and car rental only.


Required for American Express hotel and car rental. Optional for other hotel and car rental.

Food Amount Optional for Hotel and car rental only.

Beverage Amount Optional for Hotel and car rental only.

Tip 1 Amount Optional for Hotel and car rental only.


TAA1 Required for American Express Phoenix Level II purchasing cards. Optional for Paymentech New Hampshire American Express purchasing cards, or for American Express Phoenix non-Level II cards.

If sending any TAA fields, start with TAA1, then TAA2, etc. Skipping a field will cause the later fields to be ignored.

See Using the TAA1 and Charge Description Fields with American Express Phoenix on page 54 for important information.

TAA2 Optional for American Express Phoenix Level II purchasing cards and non-Level II cards. Optional for Paymentech New Hampshire American Express Level II purchasing cards.

TAA3 See description for TAA2.






TAA Amount 1 Optional for American Express Level II purchasing card transactions.

TAA Amount 2 See description for TAA Amount 1.



TAA Quantity 1 Optional for American Express Level II purchasing card transactions.

TAA Quantity 2 See description for TAA Quantity 1.




Optional for American Express retail transactions.













































Clinic Other Amount







Output

Table 47 Capture Output Fields

Field Comments

Merchant ID

Account Number

Expiration Date

Amount

Original Transaction Amount

Card Type

Sequence Number

Approval Code



Return Code Message


Transaction Date

Transaction Time

Response Indicator

Returned ACI

Requested ACI

POS Mode Code



Address Match

Zip Match

Order Number

Card Present Flag

Terminal Capability



Terminal Type

POS Entry Mode


ECommerce Type


Tax Amount


Ship To Zip Code


User Defined 1

User Defined 2

User Defined 3

User Defined 4

User Defined 5

User Source Name

Track 1 Data

Track 2 Data





Validation Code

Address Field

Zip Code

Hotel Folio Number


Check In Date

Table 47 Capture Output Fields (Continued)

Field Comments


Chapter 3 CPM API Function Requirements Authorize and Capture

Authorize and Capture

Input

Check Out Date

Pickup Date

Drop Off Date


No Show Indicator

Return City

Return State

Return Location ID

Table 47 Capture Output Fields (Continued)

Field Comments

Table 48 Authorize and Capture Input Requirements



Account Number Required. Either Account Number and Expiration Date, or Track 1 Data, or Track 2 Data is required.

Card Type Required.

Expiration Date Required for credit cards but not debit cards.

Amount Required. For PIN-based debit transactions, the Amount should include the Cash Back Amount.



Address Recommended for direct marketing merchants. Also see Visa RED Regulations for AVS on page 33.

Zip Code Recommended for direct marketing merchants. Also see Visa RED Regulations for AVS on page 33.

AVS Level Optional Level of AVS to use for the transaction. Overrides the merchant configuration setting. See Address Verification Service Group on page 32 for more information.

Ship To Firstname Optional. Required to use AAV+ with the American Express Phoenix gateway.

Ship To Lastname Optional. Required to use AAV+ with the American Express Phoenix gateway.

Order Number Recommended for direct marketing merchants.


CVV Optional.



Optional For the FTPS and FDMS North gateways, set this field to B to indicate a bill payment. See the field’s description in Table 6 on page 28 for more information.

UCAF Indicator Optional Used for payer authentication. See ECommerce Group on page 44 for information about how to use the payer authentication fields and when each is required.

CAVV Optional Used for payer authentication.

XID Optional Used for payer authentication.

Raw ECI Optional Used for payer authentication.

Table 48 Authorize and Capture Input Requirements (Continued)





Either Account Number and Expiration Date, or Track 1 Data, or Track 2 Data is required.


Required specifically for PIN-based debits. See PIN-based Debit Cards on page 63.


PIN Block Required for PIN-based debits. See PIN-based Debit Cards on page 63.

Key Sequence Number

Required for PIN-based debits. See PIN-based Debit Cards on page 63.

Cash Back Amount Optional for PIN-based debits. See PIN-based Debit Cards on page 63.

For PIN-based debit transactions, the Amount should include the Cash Back Amount.

Terminal Fee Optional for PIN-based debits with NOVA. See PIN-based Debit Cards on page 63.

Last Record Number

Required for PIN-based debits with NOVA. See Using the Last Record Number with NOVA on page 64.


Customer Firstname


Customer Lastname


Customer Phone Optional.





Customer City Optional.

Customer State Optional.

Customer Country Optional.

Customer Hostname

Optional.



Optional.






HTTP Browser Type

Optional.






Ship To Zip Code Required for purchasing cards. Also required to use AAV+ with the American Express Phoenix gateway.


Optional.










Optional.


Optional. See the important note on page 50 if Paymentech New Hampshire is your processor.


Optional.








Set the session identifier with the Set Session ID function in the CPM API. See the appropriate language in Chapter 7, Environment and Implementation, on page 184 for more information.

Ship to address 1 Optional. Required to use AAV+ with the American Express Phoenix gateway.




Ship to phone Optional. Required to use AAV+ with the American Express Phoenix gateway.

Customer IP address

Optional.









Ship To Country Required for purchasing card Level III.

Required for Paymentech New Hampshire International AVS transactions if Customer Country is not set.
























Item Commodity Code


































Hotel Folio Number Required for Hotel and car rental only.


Required for Hotel and car rental only.

Check In Date Optional for Hotel and car rental only.

Check Out Date Optional for Hotel and car rental only.

Pickup Date Optional for Hotel and car rental only.

Drop Off Date Optional for Hotel and car rental only.


Optional for Hotel and car rental only.

No Show Indicator Optional for Hotel and car rental only.

Return City Optional for Hotel and car rental only.





Return State Optional for Hotel and car rental only.

Return Location ID Optional for Hotel and car rental only.

Charge Type Required for American Express hotel and car rental. Optional for other hotel and car rental.

Duration Of Stay Optional for Hotel and car rental only.

Room Rate Optional for Hotel and car rental only.


Required for American Express hotel and car rental. Optional for other hotel and car rental.

Food Amount Optional for Hotel and car rental only.

Beverage Amount Optional for Hotel and car rental only.



TAA1 Required for American Express Phoenix Level II purchasing cards. Optional for Paymentech New Hampshire American Express purchasing cards, or for American Express Phoenix non-Level II cards.

If sending any TAA fields, start with TAA1, then TAA2, etc. Skipping a field will cause the later fields to be ignored.

See Using the TAA1 and Charge Description Fields with American Express Phoenix on page 54 for important information.

TAA2 Optional for American Express Phoenix Level II purchasing cards and non-Level II cards. Optional for Paymentech New Hampshire American Express Level II purchasing cards.







TAA Amount 1 Optional for American Express Level II purchasing card transactions.




TAA Quantity 1 Optional for American Express Level II purchasing card transactions.


















































Clinic Other Amount







Output

Table 49 Authorize and Capture Output Fields

Field Comments

Merchant ID


Account Number

Address Match

Zip Match

Expiration Date

Amount

Card Type

Sequence Number

Approval Code See PIN-based Debit Cards on page 63 for information about what to do with this value for PIN-based debits.



Return Code Message


Transaction Date

Transaction Time

Validation Code

Response Indicator

Returned ACI

Requested ACI

POS Mode Code


Retrieval Reference Number See PIN-based Debit Cards on page 63 for information about what to do with this value for PIN-based debits.

Account Data Source



Card Holder ID

Order Number

Card Present Flag

Terminal Capability

Terminal Type

POS Entry Mode


Terminal Fee See PIN-based Debit Cards on page 63 for information about what to do with this value for PIN-based debits.

Last Record Number Returned for PIN-based debits with NOVA. See Using the Last Record Number with NOVA on page 64.

CVV Result

Recur Advice Code

ECommerce Type

CAVV Result


Tax Amount


Ship To Zip Code

User Defined 1

User Defined 2

User Defined 3

User Defined 4

User Defined 5


User Source Name



Table 49 Authorize and Capture Output Fields (Continued)

Field Comments


Chapter 3 CPM API Function Requirements Reversal

ReversalYou use the Reversal transaction differently for credit cards and debit cards.

For credit cards, you use a reversal to reverse all or part of a successful Authorization. Either you must send all of the same information that you sent in the Authorization, or you must provide the Authorization’s Sequence Number and CPM will retrieve the Authorization information from the database.

For debit card transactions with FDMS South or Paymentech Tampa only, you use a Reversal immediately after an Authorization and Capture in these cases:

• For the FDMS South Debit gateway, if a timeout error, 136 ERR_TIME_OUT, occurred during the transaction and you received a Retrieval Reference Number. See the note below about the timing of the Reversal requests.

• For the Paymentech Tampa gateway, if any error occurred during the transaction

Address Field

Zip Code

Hotel Folio Number


Check In Date

Check Out Date

Pickup Date

Drop Off Date


No Show Indicator

Return City

Return State

Return Location ID

Remaining Balance Returned for pre-paid cards depending on the issuer.

Table 49 Authorize and Capture Output Fields (Continued)

Field Comments



You always reverse the entire amount of the Authorization and Capture. Also, when you request the Reversal, you must provide all of the same information you provided in the Authorization and Capture, plus the Retrieval Reference Number from the reply. Do not rely on the Sequence Number for retrieving information from the database.

Note If a timeout occurs when requesting an Authorization and Capture, FDMSSouth recommends that you try the first Reversal attempt 60 seconds after the tim-eout. If no response is received within 50 seconds, wait two minutes or until anynetwork or application issues have been resolved, if applicable, and then retry theReversal request. If again no response is received within 50 seconds, wait five min-utes or until any network or application issues have been resolved, if applicable,and then try the third Reversal request. If the third attempt fails, contact your pro-cessor or your merchant bank.

Input

Table 50 Reversal Input Requirements



Account Number Required. This field is filled in for a credit card reversal if Sequence Number is used.


Card Type Required. This field is filled in for a credit card reversal if Sequence Number is used.

Used for both credit and debit card reversals.

Expiration Date Required for credit cards, but not debit cards. This field is filled in for a credit card reversal if Sequence Number is used.


Original Amount Required for credit cards. This field is filled in for a credit card reversal if Sequence Number is used.

Also required for debit card reversals.

Amount Required for both credit and debit cards.

For credit cards, the amount the authorization should reflect. For debit cards, the full amount of the Authorization and Capture.




Required for credit cards. This field is filled in for a credit card reversal if Sequence Number is used.

Approval Code Required for credit cards. This field is filled in for a credit card reversal if Sequence Number is used.

Transaction Date Required for credit cards. This field is filled in for a credit card reversal if Sequence Number is used.


Required for both credit and debit cards. This field is filled in for a credit card reversal if Sequence Number is used.

Transaction ID Required for credit cards. This field is filled in for a credit card reversal if Sequence Number is used.

ECommerce Type Required for Web-based credit card transactions. This field is filled in for a credit card reversal if Sequence Number is used.

Track 1 Data Required for credit card transactions where the card is swiped through a card reader.


Track 2 Data Required for credit card transactions where the card is swiped through a card reader.

Also required for PIN-based debit transactions.


PIN Block Required for PIN-based debit transactions.

Key Sequence Number

Required for PIN-based debit transactions.

Table 50 Reversal Input Requirements (Continued)




Sequence Number Optional but highly recommended for credit card reversals.

NOTE When performing a Reversal that references a manually authorized Authorization or combined Authorization and Capture, provide the sequence number for the original Authorization, which is the 100 transaction, or the Authorization and Capture, which is the 104 transaction, and NOT for the Manual Authorization, which is the 105 transaction. See Manual Authorization on page 11.

Transaction Time Required for credit cards. This field is filled in for a credit card reversal if Sequence Number is used.

Validation Code Required if you received it in the credit card authorization reply. This field is filled in for a credit card reversal if Sequence Number is used.

Response Indicator Required if you received it in the credit card authorization reply. This field is filled in for a credit card reversal if Sequence Number is used.

Returned ACI Required if you received it in the credit card authorization reply. This field is filled in for a credit card reversal if Sequence Number is used.

Requested ACI Required if you received it in the credit card authorization reply. This field is filled in for a credit card reversal if Sequence Number is used.

POS Mode Code Required if you received it in the credit card authorization reply. This field is filled in for a credit card reversal if Sequence Number is used.






Required if you received it in the credit card authorization reply. This field is filled in for a credit card reversal if Sequence Number is used.

Account Data Source


Card Holder ID Required if you received it in the credit card authorization reply. This field is filled in for a credit card reversal if Sequence Number is used.



Order Number Optional. For Paymentech New Hampshire, the first 8 bytes (8 characters) must be unique. If you don't provide the order number, this field defaults to the SEQUENCE_NUMBER, for which CyberSource guarantees uniqueness.

Address Field Optional.

Zip Code Optional.

Card Present Flag Required for credit cards if provided during the authorization. This field is filled in for a credit card reversal if Sequence Number is used.


Required for credit cards if provided during the authorization. This field is filled in for a credit card reversal if Sequence Number is used.

Terminal Type Required for credit cards if provided during the authorization. This field is filled in for a credit card reversal if Sequence Number is used.





Terminal Capability Required for credit cards if provided during the authorization. This field is filled in for a credit card reversal if Sequence Number is used.

POS Entry Mode Required for credit cards if provided during the authorization. This field is filled in for a credit card reversal if Sequence Number is used.


Required for purchasing cards only. This field is filled in for a credit card reversal if Sequence Number is used.

Tax Amount Required for purchasing cards only. This field is filled in for a credit card reversal if Sequence Number is used.


Required for purchasing cards only. This field is filled in for a credit card reversal if Sequence Number is used.

Ship To Zip Code Required for purchasing cards only. This field is filled in for a credit card reversal if Sequence Number is used.


Optional.








Required for credit cards. This field is filled in for a credit card reversal if Sequence Number is used.





Output







Ship to phone Optional.

Customer IP address

Optional.




Table 51 Reversal Output Fields

Field Comments

Merchant ID

Account Number

Expiration Date

Amount

Card Type

Sequence Number

Approval Code



Return Code Message




Transaction Date

Transaction Time

Validation Code


Response Indicator

Returned ACI

Requested ACI

POS Mode Code



Order Number

Card Present Flag

Terminal Capability

Terminal Type

POS Entry Mode


ECommerce Type


Tax Amount

Ship To Zip Code



User Defined 1

User Defined 2

User Defined 3

User Defined 4

User Defined 5

Table 51 Reversal Output Fields (Continued)

Field Comments


Chapter 3 CPM API Function Requirements Return

Return

Input

User Source Name

Table 51 Reversal Output Fields (Continued)

Field Comments

Table 52 Return Input Requirements



Account Number Either Account Number and Expiration Date, or Track 1 Data, or Track 2 Data is required.

Card Type Required.

Expiration Date Required.

Amount Required.



Optional For the FTPS and FDMS North gateways, set this field to B to indicate a credit for a bill payment. See the field’s description in Table 6 on page 28 for more information.

Track 1 Data Either Account Number and Expiration Date, or Track 1 Data, or Track 2 Data is required.



Track 2 Data Either Account Number and Expiration Date, or Track 1 Data, or Track 2 Data is required.

For PIN-based debit returns with NOVA, you must provide the Track 2 Data. See PIN-based Debit Cards on page 63 for more information.

PIN Block Required for PIN-based debit returns with NOVA. See PIN-based Debit Cards on page 63 for more information.

Key Sequence Number

Required for PIN-based debit returns with NOVA. See PIN-based Debit Cards on page 63 for more information.


Required for PIN-based debit returns with NOVA. See PIN-based Debit Cards on page 63 for more information.

Last Record Number

Required for PIN-based debit returns with NOVA. See Using the Last Record Number with NOVA on page 64 for more information.



Optional.






Table 52 Return Input Requirements (Continued)







Ship To Zip Code Required for purchasing cards only.

Freight Amount Required for purchasing card level III only.

Duty Amount Required for purchasing card level III only.

Ship from Zip Code Required for purchasing card level III only.

Ship To Country Required for purchasing card level III only.


Required for purchasing card level III only.

VAT Tax Amount Required for purchasing card level III only.

VAT Tax Rate Required for purchasing card level III only.

Alternative Tax ID Required for purchasing card level III only.


Required for purchasing card level III only.


Required for purchasing card level III line item detail only.

Item Description Required for purchasing card level III line item detail only.

Item Product Code Required for purchasing card level III line item detail only.

Item Quantity Required for purchasing card level III line item detail only.







Item Tax Amount Required for purchasing card level III line item detail only.

Item Tax Rate Required for purchasing card level III line item detail only.

Item Total Amount Required for purchasing card level III line item detail only.



Item Commodity Code


Item Unit Cost Required for purchasing card level III line item detail only.





Item Tax Applied Required for purchasing card level III line item detail only.

Item Tax Exempt Required for purchasing card level III line item detail only.












Optional.


Optional.


Optional.









Ship to Address 1 Optional.

Ship to Address 2 Optional.

Ship to City Optional.

Ship to State Optional.

Ship to Phone Optional.

Customer IP Address

Optional.

Customer Email Optional.





Output

Table 53 Return Output Fields

Field Comments

Merchant ID

Account Number

Expiration Date

Amount

Card Type

Sequence Number


Last Record Number Returned for PIN-based debit returns with NOVA. See Using the Last Record Number with NOVA on page 64.

Return Code Message

Transaction Date

Transaction Time

User Defined 1

User Defined 2

User Defined 3

User Defined 4

User Defined 5

User Source Name

Track 1 Data

Track 2 Data




Chapter 3 CPM API Function Requirements Void

Void

Input

Output

Manual AuthorizationImportant Make sure to read Manual Authorization on page 11 for importantinformation about how to process transactions that require a Manual Authoriza-tion.

Table 54 Void Input Requirements



Sequence Number Required.



Table 55 Void Output Fields

Field Comments

Merchant ID

Sequence Number

Session ID

Return Code Message


Chapter 3 CPM API Function Requirements Lookup

Input

Output

Lookup

Input

Table 56 Manual Authorization Input Requirements




Approval Code Required.

Session ID Required if transaction security it enabled.


Table 57 Manual Authorization Output Fields

Field Comments

Merchant ID

Sequence Number

Approval Code

Table 58 Lookup Input Requirements





Output


Account Number Optional.



Amount Optional.


Tax Amount Optional.








Session ID Optional. Set the session identifier with the Set Session ID function in the CPM API. See the appropriate language in Chapter 7, Environment and Implementation, on page 184 for more information.

Table 58 Lookup Input Requirements (Continued)


Table 59 Lookup Output Fields

Field Comments

Merchant ID

ECommerce Type



Account Number

Expiration Date

Amount



Card Type

Tax Amount


Sequence Number

Approval Code



Return Code Message


Transaction Date

Transaction Time

Validation Code

Response Indicator

Returned ACI

Requested ACI

POS Mode Code



Address Match

Zip Match

Order Number

Card Present Flag

Table 59 Lookup Output Fields (Continued)

Field Comments




Terminal Capability

Terminal Type

POS Entry Mode

Ship To Zip Code


User Defined 1

User Defined 2

User Defined 3

User Defined 4

User Defined 5

User Source Name

Track 1 Data

Track 2 Data




Address Field

Zip Code

Table 59 Lookup Output Fields (Continued)

Field Comments


Chapter 3 CPM API Function Requirements BIN Lookup

BIN Lookup

Input

Output

Table 60 BIN Lookup Input Requirements



Account Number Required.

BIN Table Required. See

Session ID Optional. Set the session identifier with the Set Session ID function in the CPM API. See the appropriate language in Chapter 7, Environment and Implementation, on page 184 for more information.

Table 61 BIN Lookup Output Fields

Field Comments

Merchant ID

Account Number

BIN Information


Chapter 3 CPM API Function Requirements ACH Verify

ACH Verify

Input

Table 62 ACH Verify Input Requirements



Bank Account Number

Required.

Bank ID Required.


Amount Optional. Set to 0 when sending production transactions.

Account Type Optional.


Optional.








Customer Name Optional.


Chapter 3 CPM API Function Requirements ACH Verify

Output






Optional.

Table 62 ACH Verify Input Requirements (Continued)


Table 63 ACH Verify Output Requirements

Field Comments

Merchant ID

Bank Account Number

Bank ID

Order Number

Amount

Account Type


User Defined 1

User Defined 2

User Defined 3

User Defined 4

User Defined 5

Verification Result

Sequence Number

Return Code Message

Transaction Date


Chapter 3 CPM API Function Requirements ACH Deposit

ACH Deposit

Input

Transaction Time

Approval Code



Customer Name



Table 63 ACH Verify Output Requirements (Continued)

Field Comments

Table 64 ACH Deposit Input Requirements



Bank Account Number

Required.

Bank ID Required.


Amount Required.

Account Type Required.


Optional.


Chapter 3 CPM API Function Requirements ACH Deposit

Output






Customer Name Required.

Sequence Number Optional.


Set the session identifier with the Set Session ID function in the CPM API. Refer to the appropriate language in the Environment and Implementation section in this guide for more information.






Optional.

Table 64 ACH Deposit Input Requirements (Continued)


Table 65 ACH Deposit Output Requirements

Field Comments

Merchant ID

Bank Account Number

Bank ID

Order Number

Amount

Account Type


Chapter 3 CPM API Function Requirements ACH Refund

ACH Refund

Input


User Defined 1

User Defined 2

User Defined 3

User Defined 4

User Defined 5

Sequence Number

Return Code Message

Transaction Date

Transaction Time

Customer Name



Table 65 ACH Deposit Output Requirements (Continued)

Field Comments

Table 66 ACH Refund Input Requirements

Field POS Field requirement Comments


Bank Account Number

Required.

Bank ID Required.




Amount Required.

Account Type Required.


Optional.







Sequence Number Optional.








Optional.

Table 66 ACH Refund Input Requirements (Continued)

Field POS Field requirement Comments



Output

Table 67 ACH Refund Output Requirements

Field Comments

Merchant ID

Bank Account Number

Bank ID

Order Number

Amount

Account Type


User Defined 1

User Defined 2

User Defined 3

User Defined 4

User Defined 5

Sequence Number

Return Code Message

Transaction Date

Transaction Time

Customer Name




Chapter 3 CPM API Function Requirements ACH Void

ACH Void

Input

Output

Table 68 ACH Void Input Requirements






Table 69 ACH Void Output Requirements

Field Comments

Merchant ID

Bank Account Number

Bank ID

Order Number

Amount

Account Type


User Defined 1

User Defined 2

User Defined 3

User Defined 4


Chapter 3 CPM API Function Requirements ACH Lookup

ACH Lookup

Input

User Defined 5

Sequence Number

Return Code Message

Transaction Date

Transaction Time

Customer Name



Table 69 ACH Void Output Requirements (Continued)

Field Comments

Table 70 ACH Lookup Input Requirements







Chapter 3 CPM API Function Requirements ACH Lookup

Output

Table 71 ACH Lookup Output Requirements

Field Comments

Merchant ID

Bank Account Number

Bank ID

Order Number

Amount

Account Type


User Defined 1

User Defined 2

User Defined 3

User Defined 4

User Defined 5

Verification Result

Sequence Number

Return Code Message

Transaction Date

Transaction Time

Approval Code



Customer Name




Chapter 3 CPM API Function Requirements Direct Debit Validate

Direct Debit Validate

Input

Table 72 Direct Debit Validate Input Requirements



Bank Country Code Required.

Bank Account Number

Required.

Bank Sort Code Required for Austria, Germany, France, and the U.K.

RIB Code Optional and used for France only.

Customer Name Optional.


Amount Required. Set to 0 when sending production transactions.


Optional.







Chapter 3 CPM API Function Requirements Direct Debit Validate

Output



Table 72 Direct Debit Validate Input Requirements (Continued)


Table 73 Direct Debit Validate Output Requirements

Field Comments

Merchant ID

Bank Country Code

Bank Account Number

Bank Sort Code

RIB Code

Customer Name

Order Number

Amount

Verification Result


User Defined 1

User Defined 2

User Defined 3

User Defined 4

User Defined 5

Sequence Number

Return Code Message

Transaction Date

Transaction Time


Chapter 3 CPM API Function Requirements Direct Debit Deposit

Direct Debit Deposit

Input

Approval Code



Table 73 Direct Debit Validate Output Requirements (Continued)

Field Comments

Table 74 Direct Debit Deposit Input Requirements




Bank Account Number

Required.





Amount Required.


Chapter 3 CPM API Function Requirements Direct Debit Deposit

Output


Optional.








Table 74 Direct Debit Deposit Input Requirements (Continued)


Table 75 Direct Debit Deposit Output Requirements

Field Comments

Merchant ID

Bank Country Code

Bank Account Number

Bank Sort Code

RIB Code

Customer Name

Order Number

Amount


User Defined 1

User Defined 2

User Defined 3


Chapter 3 CPM API Function Requirements Direct Debit Refund

Direct Debit Refund

Input

User Defined 4

User Defined 5

Sequence Number

Return Code Message

Transaction Date

Transaction Time

Table 75 Direct Debit Deposit Output Requirements (Continued)

Field Comments

Table 76 Direct Debit Refund Input Requirements




Bank Account Number

Required.





Chapter 3 CPM API Function Requirements Direct Debit Refund

Output


Amount Required.


Optional.








Table 76 Direct Debit Refund Input Requirements (Continued)


Table 77 Direct Debit Refund Output Requirements

Field Comments

Merchant ID

Bank Country Code

Bank Account Number

Bank Sort Code

RIB Code

Customer Name

Order Number


Chapter 3 CPM API Function Requirements Direct Debit Void

Direct Debit Void

Input

Amount


User Defined 1

User Defined 2

User Defined 3

User Defined 4

User Defined 5

Sequence Number

Return Code Message

Transaction Date

Transaction Time

Table 77 Direct Debit Refund Output Requirements (Continued)

Field Comments

Table 78 Direct Debit Void Input Requirements







Chapter 3 CPM API Function Requirements Direct Debit Void

Output

Table 79 Direct Debit Void Output Requirements

Field Comments

Merchant ID

Bank Country Code

Bank Account Number

Bank Sort Code

RIB Code

Customer Name

Order Number

Amount


User Defined 1

User Defined 2

User Defined 3

User Defined 4

User Defined 5

Sequence Number

Return Code Message

Transaction Date

Transaction Time


Chapter 3 CPM API Function Requirements Direct Debit Lookup

Direct Debit Lookup

Input

Output

Table 80 Direct Debit Lookup Input Requirements






Table 81 Direct Debit Lookup Output Requirements

Field Comments

Merchant ID

Bank Country Code

Bank Account Number

Bank Sort Code

RIB Code

Customer Name

Order Number

Amount


User Defined 1

User Defined 2

User Defined 3


Chapter 3 CPM API Function Requirements Admin Command

Admin Command

Input

User Defined 4

User Defined 5

Verification Result

Sequence Number

Return Code Message

Transaction Date

Transaction Time

Approval Code



Table 81 Direct Debit Lookup Output Requirements (Continued)

Field Comments

Table 82 Admin Command Input Requirements


Merchant ID Required. Your merchant ID used to identify yourself within the CPM system. Required for all transaction types.

Admin Command String

Required.


Chapter 3 CPM API Function Requirements Begin Session

Note The Admin Command transaction does not have output fields.

Begin Session

Input

Merchant List Optional. List of merchant names to settle. For example, you might have several variations of merchant name that you use, each for a different product line within your business, and you want to settle only some of them.

Gateway List Optional.

Start Date Optional.

End Date Optional.

Table 82 Admin Command Input Requirements (Continued)


Table 83 Begin Session Input Requirements



Username Required.

Password Required.


Chapter 3 CPM API Function Requirements End Session

Output

End Session

Input

Table 84 Begin Session Output Fields

Field Comments

Merchant ID

Session ID

Username

Password

Return Code Message

Table 85 End Session Input Requirements



Username Optional.

Password Optional.

Session ID Required. Set the session identifier with the Set Session ID function in the CPM API. Refer to the appropriate language in the Environment and Implementation section in this guide for more information.


Chapter 3 CPM API Function Requirements End Session

Output

Table 86 End Session Output Fields

Field Comments

Merchant ID

Username

Password

Return Code Message


Chapter 4

CPM API Output Codes

This chapter explains the outputs you can receive from the CPM API.

You can receive the following result codes from a transaction:

• Transaction Response code — Details the success or failure of the completion of the function. This code is from the API call.

• Authorization Response code — Details if the authorization was approved or denied. This code is only received for authorization, reversal, and authorize and capture functions.

• Address Verification Response code — Details the results of the Address Verification Service performed for an authorization.

• Cardholder Verification Value — Details the results of the Cardholder Authentication Verification check for an authorization.

Transaction Response CodeThe Transaction Response code is the first value to examine after the completion of a transaction. The Run Transaction function returns the transaction response code.

Table 87 Transaction Response Codes

Code Description

0 Transaction was successful.

Does not indicate authorization is approved. Indicates transaction communicated from the client, through the CPM server, to the credit card issuing bank processor, and back.

Any value other than 0

Transaction failed due to an error during processing.


Chapter 4 CPM API Output Codes Authorization Response Code

Authorization Response CodeThe Authorization Response code details the success or failure of an authorization, and is for authorization, reversal, and authorization and capture functions. The Authorization Response contains two fields.

The first Authorization Response field is the Authorization Result code field. This field contains the processor-independent results of the transaction, and is only for authorization and reversal functions.

The second field is the Processor Authorization Result code. This field is the response code returned by the processor. The CPM Server provides this field to assist in possible transaction processing problems. Do not, however, place any dependencies on the field because changing processors and the integration code could be difficult.

Address Verification Service CodeThe Address Verification Service (AVS) code fields tell the merchant the results of the verification of the cardholder’s address and postal code. The CPM Server fields, Address Match, and ZIP Match, tell the merchant if the fields match the information in the issuing bank’s AVS database or not.

Note The results of the address verification do not impact the results of an autho-rization. If a credit card is valid but the address verification information is wrong,

Table 88 Authorization Result Codes

Code Description

A Approval — authorization is approved.

C Call — voice authorization is required. Call the processor.

D Decline — authorization was declined. Check the Authorization Response Message or Processor Authorization Response code for details.

E Error — a processing error has occurred. Check the Authorization Response Message or Processor Authorization Response code for details.

P Pick Up Card — the credit card is problematic. Remove the credit card from the cardholder. Check the Authorization Response Message or Processor Authorization Response code for details.

X Expired Card — the credit card has expired.


Chapter 4 CPM API Output Codes Address Verification Service Code

the authorization is still processed. The merchants must determine if they want toaccept or reject the authorization based on the address verification results.

Visa RED Regulations for AVSVisa is implementing RED (Re-Engineering Disputes) regulations that affect chargebacks and chargeback processing. Starting in Spring 2004, Visa will only permit representments for fraud if:

• You send full AVS information, which consists of the address and the postal code, with both the Authorization request and the Capture request. Remember that if you supply the Authorization’s sequence number with the Capture request, CPM automatically retrieves the AVS information that you supplied from the CPM database and sends it with the Capture.

• You receive a full AVS match, which is indicated by Visa codes I1 or I3. Transactions with an AVS match for postal code only, which is indicated by Visa code I4, will not be eligible for representment.

• You can provide an itemized bill with shipping information

CyberSource strongly encourages you to pursue full AVS authorization both to combat fraud and to effectively manage chargeback losses.

Important If you process on Paymentech's New Hampshire gateway, supplyingthe customer’s first name and last name prompts CyberSource software to sendboth the address and postal code information to Paymentech with the Capture. Ifyou do not supply the customer’s name, CyberSource sends only the postal code toPaymentech with the Capture.

Address Match

Table 89 Address Verification Service Codes

Code Description

N No match.

R Invalid AVS response from card issuer or address verification data contains EDIT ERROR.

X Service unavailable/not applicable


Chapter 4 CPM API Output Codes Card Verification Value Codes

ZIP Match

Card Verification Value CodesThe Card Verification Value (CVV) Result Code field tells the merchant the results of the CVV check. The field contains the direct response from the processor.

Note Table 91 lists the common CVV codes returned by the CPM-supported pay-ment processors. Processors can change the list of CVV codes they return withoutnotice. See your processor’s specification for the most up-to-date list of CVV codesthey return.

Y Match

Table 89 Address Verification Service Codes (Continued)

Code Description

Table 90 Address Verification Service Codes

Code Description

N No match.

R Invalid AVS response from card issuer or address verification data contains EDIT ERROR.

X Service unavailable/not applicable

Y Match

Table 91 Processor CVV Code Descriptions

Processor Code Meaning Definition

M Match The code given matches the code in the database.

N No Match The code given does not match the code in the database.

S Merchant did not provide

The code should be on the card but the merchant indicated it was not.


Chapter 4 CPM API Output Codes Card Verification Value Codes

I, P, U Unknown/Service unavailable

CVV/CVV2/CVC/CID is either not available or not applicable to this transaction.

Table 91 Processor CVV Code Descriptions (Continued)

Processor Code Meaning Definition


Chapter 5

CPM API Identifiers

This chapters explains two types of CPM API identifiers — transaction type identifiers and field identifiers.

Transaction Type IdentifiersWhen running a CPM API transaction function, you must provide a transaction type identifier. The supported identifiers are in the CPM Server header files — lcc.h for C/C++ and lcc.bas for VB/ActiveX, and lcc.java for Java — and listed in Table 92.

Table 92 CPM API Transaction Type Identifiers

Numerical Equivalent

Identifier Transaction

100 ID_AUTHORIZATION Authorization

101 ID_REVERSAL Reversal

102 ID_CAPTURE Capture

103 ID_RETURN Return

104 ID_AUTH_AND_CAPTURE Authorization and Capture

105 ID_MANUAL_AUTHORIZATION Manual Authorization

106 ID_VOID_TRANSACTION Void Transaction

108 ID_ACH_VERIFY ACH Verify

109 ID_ACH_DEPOSIT ACH Deposit

110 ID_ACH_REFUND ACH Refund

111 ID_ACH_VOID ACH Void

112 ID_ACH_LOOKUP ACH Lookup

113 ID_EUDD_VALIDATE Direct Debit Validate

114 ID_EUDD_DEPOSIT Direct Debit Deposit


Chapter 5 CPM API Identifiers CPM API Field Identifiers

CPM API Field IdentifiersIn order to create a transaction, you must set the fields required by the transaction. The fields are set through a single function call, Set Value. This function uses an ID, provided as an argument, to determine which field to set. You can use field identifiers to retrieve response fields in a similar manner. Common field identifiers are in the CPM Server header files — lcc.h for C/C++, lcc.bas for VB/ActiveX, and lcc.java for Java — and listed in Table 93. Different field identifiers may be required by different Gateways.

115 ID_EUDD_REFUND Direct Debit Refund

116 ID_EUDD_VOID Direct Debit Void

117 ID_EUDD_LOOKUP Direct Debit Lookup

120 ID_PREDIAL Predial

121 ID_LOOKUP Lookup

122 ID_BIN_LOOKUP BIN Lookup

130 ID_ADMIN_COMMAND Admin Command

150 ID_BEGIN_SESSION Begin Session

151 ID_END_SESSION End Session

Table 92 CPM API Transaction Type Identifiers (Continued)


Identifier Transaction

Table 93 CPM API Field Identifiers


Identifier Field

1 ID_ADMIN_COMMAND_STRING Admin Command String

2 ID_MERCHANT_LIST Merchant List

3 ID_GATEWAY_LIST Gateway List

4 ID_START_DATE Start Date

5 ID_END_DATE End Date

6 ID_BIN_TABLE BIN Table

51 ID_MERCHANT_ID Merchant ID



100 ID_MERCHANT_NAME Merchant Name for ID lookup

101 ID_ACCOUNT_NUMBER Account Number

102 ID_EXPIRATION_DATE Expiration Date

103 ID_AMOUNT Transaction Amount

104 ID_CARD_TYPE Card Type

105 ID_SEQUENCE_NUMBER Sequence Number

106 ID_APPROVAL_CODE Approval Code

107 ID_AUTH_RESPONSE_CODE Authorization Response Code

108 ID_AUTH_RESPONSE_MESSAGE Authorization Response Message

109 ID_RETURN_CODE_MESSAGE Return Code Message

110 ID_BANK_ACCOUNT_NUMBER Bank Account Number

111 ID_BANK_ID Bank ID

112 ID_ACCOUNT_TYPE Account Type

113 ID_VERIFICATION_RESULT Verification Result

114 ID_PROCESSOR_RESPONSE_CODE


115 ID_PROCESSOR_RESPONSE_MESSAGE


120 ID_TRANSACTION_ID Transaction ID

121 ID_TRANSACTION_DATE Transaction Date

122 ID_TRANSACTION_TIME Transaction Time

123 ID_VALIDIATION_CODE Validation Code

124 ID_ORIGINAL_AMOUNT Original Amount

125 ID_RESPONSE_INDICATOR Response Indicator

126 ID_RETURNED_ACI Returned ACI

127 ID_REQUESTED_ACI Requested ACI

128 ID_POS_MODE_CODE POS Mode Code

129 ID_MARKET_SPECIFIC_INDICATOR Market Specific Indicator

Table 93 CPM API Field Identifiers (Continued)


Identifier Field



130 ID_RETRIEVAL_REFERENCE_NUMBER


131 ID_ACCOUNT_DATA_SOURCE Account Data Source

132 ID_CARD_HOLDER_ID Card Holder ID

133 ID_AUTHORIZATION_SOURCE_CODE


134 ID_CURRENT_AMOUNT Current Transaction Amount

135 ID_TRANS_ATTRIBUTE Transaction Attribute

136 ID_CURRENT_TAX_AMOUNT Current Tax Amount

137 ID_LOOKUP_TRANSACTION_TYPE Lookup Transaction Type

138 ID_CASH_BACK_AMOUNT Cash Back Amount

139 ID_BIN_INFORMATION BIN Information

140 ID_ADDRESS_MATCH Address Match

141 ID_ZIP_MATCH Zip Match

142 ID_AVS_LEVEL AVS Level

150 ID_ORDER_NUMBER Order Number

151 ID_CUSTOMER_STREET Street Number, Street Name

152 ID_CUSTOMER_ZIP Zip Code

155 ID_PURCHASE_CARD_ORDER_NUMBER


156 ID_TAX_AMOUNT Tax Amount

157 ID_COMMERCIAL_CARD_TYPE Commercial Card Type

158 ID_SHIP_TO_ZIP_CODE Ship To Zip Code

159 ID_MERCHANT_PRODUCT_SKU Merchant Product SKU

165 ID_CVV CVV

166 ID_CVV_RESULT CVV Result

167 ID_CVV_INDICATOR CVV Indicator

170 ID_CUSTOMER_NAME Customer Name

171 ID_CUSTOMER_PHONE Customer Phone Number



Identifier Field



172 ID_CUSTOMER_CITY Customer City

173 ID_CUSTOMER_STATE Customer State

174 ID_CUSTOMER_COUNTRY Customer Country

175 ID_CUSTOMER_LASTNAME Customer Lastname

176 ID_CUSTOMER_FIRSTNAME Customer Firstname

177 ID_CUSTOMER_HOSTNAME Customer Hostname

178 ID_CUSTOMER_ANI Automatic Number Identification

179 ID_CUSTOMER_INFORMATION_ID Customer Information Identifier

190 ID_MERCHANT_BILLING_NAME Merchant Billing Name

191 ID_MERCHANT_BILLING_STATE Merchant Billing State

192 ID_MERCHANT_BILLING_LOCATION


200 ID_USER_SEQUENCE_NUMBER User Sequence Number

201 ID_USER_DEFINED_1 User Defined 1





222 ID_RESERVED_1 Reserved - Do not use

223 ID_RESERVED_2 Reserved - Do not use

250 ID_TRACK_1_DATA Track 1 Data

251 ID_TRACK_2_DATA Track 2 Data

252 ID_PIN_BLOCK PIN Block

253 ID_KEY_SEQUENCE Key Sequence Number

254 ID_TERMINAL_FEE Terminal Fee

2100 ID_LAST_RECORD_NUMBER Last Record Number

296 ID_USER_SOURCE_NAME User Source Name

300 ID_E_COMMERCE_TYPE ECommerce Type



Identifier Field



301 ID_CAVV CAVV

302 ID_XID Transaction ID

303 ID_HTTP_BROWSER_TYPE HTTP Browser Type

304 ID_CAVV_RESULT CAVV Result

350 ID_CARD_PRESENT_FLAG Card Present Flag

351 ID_TERMINAL_CAPABILITY Terminal Capability

352 ID_TERMINAL_TYPE Terminal Type

353 ID_POS_ENTRY_MODE POS Entry Mode

354 ID_CUSTOMER_PRESENT_FLAG Customer Present Flag

360 ID_REMAINING_BALANCE Remaining balance

400 ID_PROCESSOR_AVS_RESULT Processor AVS Result

401 ID_PROCESSOR_AUTH_RESPONSE_CODE


450 ID_USERNAME Username for Begin Session

451 ID_PASSWORD Password for Begin Session

460 ID_SHIP_TO_ADDRESS_1 Ship to address1

461 ID_SHIP_TO_ADDRESS_2 Ship to address 2

462 ID_SHIP_TO_CITY Ship to city

463 ID_SHIP _TO_STATE Ship to state

464 ID_SHIP_TO_PHONE Ship to phone number

465 ID_CUSTOMER_IP_ADDRESS Customer IP address

466 ID_CUSTOMER_EMAIL Customer email address

467 ID_UCAF_INDICATOR UCAF Indicator

471 ID_SHIP_TO_COUNTRY Ship to country

500 ID_FREIGHT_AMOUNT Freight amount

501 ID_DUTY_AMOUNT Duty amount

503 ID_SHIP_FROM_ZIP_CODE Ship from zip code

504 ID_DISCOUNT_AMOUNT_APPLIED Discount amount applied



Identifier Field



505 ID_VAT_TAX_AMOUNT VAT tax amount

506 ID_VAT_TAX_RATE VAT tax rate

507 ID_ALTERNATIVE_TAX_ID Alternative tax ID

508 ID_ALTERNATIVE_TAX_AMOUNT Alternative tax amount

509 ID_LINE_ITEM_DETAIL_COUNT Line item detail count

600 ID_GECC_PROMOTIONAL_PLAN Promotional Plan

601 ID_GECC_PROMOTIONAL_END_DATE


602 ID_GECC_SALE_TYPE Sale Type

603 ID_GECC_LINE_ITEM_1 Line item 1







610 ID_GECC_MICROFICHE_SEQUENCE_NUM


611 ID_GECC_PLAN_NUMBER Plan Number

650 ID_BENEFICIAL_CREDIT_PLAN Credit Plan

651 ID_BENEFICIAL_DEPARTMENT_CODE

Department Codes

652 ID_BENEFICIAL_SKU_NUMBER SKU Number

653 ID_BENEFICIAL_ITEM_DESCRIPTION

Item Description

654 ID_BENEFICIAL_STORE_NUMBER Store Number

700 ID_CARD_START_DATE Card Start Date

701 ID_CARD_ISSUE_NUMBER Card Issue Number

Shares same numeric equivalent with Raw ECI field.



Identifier Field



701 ID_RAW_ECI Raw ECI

800 ID_HOTEL_FOLIO_NUMBER Hotel folio number

801 ID_RENTAL_AGREEMENT_NUMBER

Rental agreement number

802 ID_CHECK_IN_DATE Check in date

803 ID_CHECK_OUT_DATE Check out date

804 ID_PICK_UP_DATE Pick up date

805 ID_DROP_OFF_DATE Drop off date

806 ID_EXTRA_CHARGES_INDICATOR Extra charges indicator

807 ID_NO_SHOW_INDICATOR No show indicator

808 ID_RETURN_CITY Return city

809 ID_RETURN_STATE Return state

810 ID_RETURN_LOCATION_ID Return location ID

811 ID_CHARGE_TYPE Charge Type

812 ID_STAY_DURATION Duration Of Stay

813 ID_ROOM_RATE Room Rate

814 ID_PROGRAM_CODE Special Program Code

815 ID_FOOD_AMOUNT Food Amount

816 ID_BEVERAGE_AMOUNT Beverage Amount

817 ID_TIP1_AMOUNT Tip 1 Amount

818 ID_TIP2_AMOUNT Tip 2 Amount

900 ID_AMEX_RETAIL_INFO Amex Retail Info

Shares same numeric equivalent with TAA1 field.



Identifier Field



900 ID_TAA1 Transaction Advice Addendum 1. Used for:

• Paymentech New Hampshire American Express purchasing cards

• American Express Phoenix Level II purchasing cards and non-Level II cards

901 ID_TAA2 See description for ID_TAA1 above.



904 ID_TAA1_AMOUNT Transaction Advice Addendum Amount 1




908 ID_TAA1_QTY Transaction Advice Addendum Quantity 1




912 ID_RETAIL_DEPT_NAME Retail Department Name

913 ID_RETAIL_ITEM1_DESCRIPTION Retail Item 1 Description







Identifier Field




919 ID_RETAIL_ITEM1_AMOUNT Retail Item 1 Amount





924 ID_RETAIL_ITEM6_AMOUNT Retail Item 6 Amount.

925 ID_RETAIL_ITEM1_QTY Retail Item 1 Quantity.






1012 ID_SHIP_TO_FIRSTNAME First name of person receiving the shipment.

1013 ID_SHIP_TO_LASTNAME Last name of person receiving the shipment.

1039 ID_RECUR_ADVICE_CODE Recurring payment advice code returned by Paymentech New Hampshire only for recurring MasterCard transactions.

2000 ID_EUDD_BANK_SORT_CODE Bank’s sort code; used for direct debits.

2001 ID_EUDD_BANK_COUNTRY_CODE Country code of country where bank is located; used for direct debits.

2002 ID_EUDD_RIB_CODE Bank’s RIB code; used for direct debits in France.

3000 ID_QHP_AMOUNT Qualified health benefit (IIAS) amount of the transaction.

3001 ID_RX_AMOUNT Prescription drug portion of the QHP amount.

3002 ID_VISION_AMOUNT Vision portion of the QHP amount.



Identifier Field



3003 ID_CLINIC_OTHER_AMOUNT Clinic/Other portion of the QHP amount.

3004 ID_DENTAL_AMOUNT Dental portion of the QHP amount.

3005 ID_PARTIAL_AUTH_FLAG Partial redemption indicator. Allows for transaction approval if the QHP amount is greater than the remaining balance on the card.

10000 ID_ITEM_DESCRIPTION Item description

10001 to 10999

ID_ITEM_DESCRIPTIONn Item description, where 0 < n < 1000.

11000 ID_ITEM_PRODUCT_CODE Item product code

11001 to 11999

ID_ITEM_PRODUCT_CODEn Item product code, where 0 < n < 1000.

12000 ID_ITEM_QUANTITY Item quantity

12001 to 12999

ID_ITEM_QUANTITYn Item quantity, where 0 < n < 1000

13000 ID_ITEM_UNIT_OF_MEASURE Item unit of measure

13001 to 13999

ID_ITEM_UNIT_OF_MEASUREn Item unit of measure, where 0 < n < 1000

14000 ID_ITEM_TAX_AMOUNT Item tax amount

14001 to 14999

ID_ITEM_TAX_AMOUNTn Item tax amount, where 0 < n < 1000

15000 ID_ITEM_TAX_RATE Item tax rate

15001 to 15999

ID_ITEM_TAX_RATEn Item tax rate, where 0 < n < 1000

16000 ID_ITEM_TOTAL_AMOUNT Item total amount

16001 to 16999

ID_ITEM_TOTAL_AMOUNTn Item total amount, where 0 < n < 1000

17000 ID_ITEM_DISCOUNT_AMOUNT Item discount amount

17001 to 17999

ID_ITEM_DISCOUNT_AMOUNTn Item discount amount, where 0 < n < 1000

18000 ID_ITEM_COMMODITY_CODE Item commodity code



Identifier Field



18001 to 18999

ID_ITEM_COMMODITY_CODEn Item commodity code, where 0 < n < 1000

19000 ID_ITEM_UNIT_COST Item unit cost

19001 to 19999

ID_ITEM_UNIT_COSTn Item unit cost, where 0 < n < 1000

20000 ID_ITEM_DISCOUNT_INDICATOR Item discount indicator

20001 to 20999

ID_ITEM_DISCOUNT_INDICATORn Item discount indicator, where 0 < n < 1000

21000 ID_ITEM_TAX_TYPE_APPLIED Item tax type applied

21001 to 21999

ID_ITEM_TAX_TYPE_APPLIEDn Item tax type applied, where 0 < n < 1000

22000 ID_ITEM_TAX_APPLIED Item tax applied

22001 to 22999

ID_ITEM_TAX_APPLIEDn Item tax applied, where 0 < n < 1000

23000 ID_ITEM_TAX_EXEMPT Item tax exempt

23001 to 23999

ID_ITEM_TAX_EXEMPTn Item tax exempt, where 0 < n < 1000

24000 ID_ITEM_RETURN_INDICATOR Item return indicator

24001 to 24999

ID_ITEM_RETURN_INDICATORn Item return indicator, where 0 < n < 1000



Identifier Field


Chapter 6

CPM Error Identifiers

This chapters explains the CPM API error identifiers. See the CPM Messages and Processor Codes Guide for more detailed information about the errors identifiers.

Error DescriptionsThe Run Transaction function returns a value corresponding to one of the error identifiers. The error identifiers are in the CPM Server header files — lcc.h for C/C++ and lcc.bas for VB/ActiveX and lcc.java for Java — and are listed in Table 94.

Note It may be necessary in the integration or the point of sale to convert the CPMAPI numerical ID and message error text into meaningful terms for customers ormerchant representatives.

See the CPM Messages and Processor Codes Guide for more information.

Table 94 Error Identifier Descriptions

Numerical ID

Text message Description

-114 ERR_MISSING_CONNECTION_INFO

Connection information was not specified.

-113 ERR_MERCHANT_NOT_SPECIFIED No merchant name specified.

-112 ERR_CONFIG_BAD_ENTRY Bad formatted entry in configuration file.

-111 ERR_CONFIG_LOOKUP_FAILED Could not find merchant in configuration file.

-110 ERR_CONFIG_OPEN_FAILED Failed to open configuration file.

-105 ERR_OPEN_DEBUG_FILE Failed to open lcc_test.txt.

-104 ERR_VALUE_TOO_LARGE Value too large for input buffer.


Chapter 6 CPM Error Identifiers Error Descriptions

-103 ERR_VALUE_NOT_FOUND Value ID not set.

-102 ERR_CONNECTION_INVALID Invalid Connection Handle.

-101 ERR_INVALID_HANDLE Invalid Transaction Handle.

-100 ERR_NOT_INITIALIZED CPM API Not Initialized.

-20 ERR_SSL_GENERAL General SSL error.

-19 ERR_SSL_NEG SSL negotiation error.

-18 ERR_SSL_LIB_INIT Failed to load SSL modules.

-17 ERR_ENCRYPTION_FAILED Encryption failed.

-16 ERR_SOCK_READ Error reading from socket.

-15 ERR_SOCK_WRITE Error writing to socket.

-14 ERR_SOCK_CONN_REFUSED Connection refused.

-13 ERR_SOCK_CONNECT Failed to connect to server.

-12 ERR_SOCK_CREATE Failed to create socket.

-10 ERR_SOCK_LIB_INIT Failed to start winsock.

0 ERR_SUCCESS The transaction was successful. This is a global CPM API success message.

11 ERR_NOT_ACCEPTING_TX Payment server is not accepting transactions.

13 ERR_INVALID_FIELD_25_NO_MAP Unable to map to 2.5 error code.

30 ERR_TRANSACTION_TYPE Incorrect transaction type.

101 ERR_INVALID_FIELD Missing or invalid field.

102 ERR_FIELD_TOO_LONG Field too long.

107 ERR_BATCH_GROUP_DRAFT_ID_EXISTS

Batch in the POS-port device is mission.

109 ERR_OUT_OF_MEMORY_BUFFERS The memory in the POS-port is full.

110 ERR_OUT_OF_MEMORY_HEAP The memory in the POS-port is full.

135 ERR_COULD_NOT_CONNECT_PROCESSOR

Could not connect to the processor’s network.

Table 94 Error Identifier Descriptions (Continued)

Numerical ID




136 ERR_TIME_OUT Too much time between the transmission and receiving of data, the connection was dropped.

137 ERR_UNIDENTIFIABLE Unable to identify error. Contact CPM Product Support for more information.

138 ERR_INVALID_FIELD_VALUE The data for the field is either too large or too small.

139 ERR_INVALID_DATA_TYPE The data for the field does not match the field’s data type.

141 ERR_INVALID_RECORD_SEQUENCE

Invalid sequence number.

142 ERR_INVALID_MERCHANT_CONFIGURATION

The merchant configuration is invalid on the Server.

143 ERR_CC_MOP_MISMATCH The credit card number does not match the credit card type.

144 ERR_INVALID_MOP_FOR_DIVISION The merchant does not accept this credit card type.

145 ERR_INVALID_TRANSACTION_TYPE

The transaction is not supported by the processor.

146 ERR_DUPLICATE_PURCHASE _IDENTIFER

The purchase ID is already in use.

200 ERR_UNKNOWN Unknown error.

230 ERR_LOOKUP_NO_RECORDS_FOUND

No records found with lookup.

231 ERR_MULTIPLE_RECORDS_FOUND

Multiple records found with lookup.

232 ERR_VOID_FAILED_TX_SETTLED The void function failed because the transaction has already settled.

233 ERR_VOID_FAILED_TX_NOT_FOUND

Cannot find the transaction to void.

234 ERR_SEQUENCE_NUMBER_LOOKUP_TIMEOUT

Database timeout on sequence number lookup.

235 ERR_HTTP_SSL_COMMUNICATIONS_FAILURE

As error status other than 200 from RBS Worldpay SSL and Vital.


Numerical ID




236 ERR_LOOKUP_FIELD_NOT_SET No lookup fields set.

237 ERR_LOOKUP_ENCRYPTED_ACCOUNT_NUMBER

Lookup with an encrypted account number is not allowed.

1000 ERR_SERVICE_NEED_TCB_PRIV The CPM Server needs to have Act as Operating System rights.

1001 ERR_INVALID_USERNAME_PASSWORD

An invalid username or password was entered.

1002 ERR_SESSION_INVALID The session ID specified is invalid.

1003 ERR_SESSION_TIMEOUT The session has timed out.

1004 ERR_SESSION_SOURCE_INVALID Invalid session ID.

1005 ERR_INVALID_MERCHANT_ID Could not find merchant ID on the server.

1006 ERR_SESSION_ACCESS_DENIED Access denied.

1007 ERR_CREATE_SESSION_FAILURE Could not create a user session.

1008 ERR_SESSION_AMOUNT_LIMIT_REACHED

Access denied. The total batch amount has reached or exceded the limit.

1009 ERR_SESSION_RETURN_AMOUNT_LIMIT_REACHED

Access denied. The total return amount has reached or exceeded the limit.

1010 ERR_LICENSE_KEY_VIOLATION The invalid license key for this client.

1011 ERR_DATABASE_LOG_FAILURE The transaction was not added to the database.

1012 ERR_DUPLICATE_TRANSACTION_CHECK

The transaction is already in the database.

1015 ERR_VOID_TX_FAILURE Cannot void transaction that has already settled.

1016 ERR_NO_LPC_AVAILABLE No Gateway available to handle transactions for this merchant.

1017 ERR_LPC_NOT_ENABLED The Gateway for this merchant is not enabled.

1018 ERR_TX_NOT_VOIDABLE Can only void Captures, Authorize and Captures, and Returns.


Numerical ID




1019 ERR_INVALID_MERCHANT_STATE_AUTH

Merchant state must be open (OPN) to do transactions.


Numerical ID



Chapter 7

Environment and Implementation

This explains CPM port usage, and environment and implementation of CPM for the following API platforms:

• ActiveX

• Batch

• C

• Java

CPM Port UsageCPM uses the ports listed in Table 95 for processing transactions and administrating the CPM Server.

Note You can change the port settings to meet the requirements of your systemenvironment.

Table 95 CPM Port Usage

Port Usage

1530 The CPM Server uses this port to send and receive transactions through the API. If SSL encryption is not enabled, the ActiveX, C, and Java APIs use this port. If SSL encryption is enabled, the only ActiveX and C APIs use this port.

1531 The CPM Server typically uses this port to send and receive transactions through the Java API with SSL encryption enabled.

28882 The CPM Administration Client uses this port to administer the CPM Server.

28883 The CPM Service Control Manager (Windows) or cpm_manager (Unix) uses this port.


Chapter 7 Environment and Implementation ActiveX

ActiveXThe CPM ActiveX control is an ATL COM (Component Object Model) object. The properties and methods are implemented through the IUknown and IDispatch interfaces. This feature allows integration with Visual Basic, Visual Basic Scripts, Visual C++, and J++ and distribution as described in the Microsoft DNA model.

These ActiveX functions allow the developer to create, execute, and examine transactions. See Chapter 5, CPM API Identifiers, on page 167 and Chapter 6, CPM Error Identifiers, on page 179 for more information on the transaction type identifiers, field identifiers, and error identifiers.

Merchant InformationThe ActiveX control provides three ways to specify merchant information:

• Configuration file

• Environment variable

• Registry

Configuration FileYou can create your own configuration file or use the default configuration file, lcc_client.cf, which was called lcc.cf in early versions of CPM. The default location for the configuration file is the working directory.

The function SetConfigFile is used to specify the path and filename of the configuration file. If you do not use this function, then the API looks at the path and filename specified by the environment variable LCC_CLIENT_CONF. If the environment variable is not defined, then the API looks for the merchant information in the Windows Registry. If the information is not specified in the Registry, the API looks for the default configuration file in the working directory. The API returns an error if it cannot locate the merchant information using any of these methods.

Configuration File FormatThe format of the file is much like an .ini file. The sections are denoted by brackets ([]), and information underneath those sections are simple key=value pairs.

The client configuration file stores the Merchant Identifier, CPM Server TCP/IP Address, CPM Server TCP/IP Port, and SSL Encryption Scheme underneath each merchant name section.



[Merchant Name]

MerchantID=Merchant ID

Server Address=IP Address of CPM Server

Server Port=Port on which the CPM Server is listening

Encryption=Encryption Scheme (0 default, 1 SSL)

Example

[Demonstration Merchant]

MerchantID=demo

Server Address=localhost

Server Port=1530

Encryption=0

Server Port and IP AddressThe API allows you to set the CPM Server TCP/IP port and TCP/IP address. Use these commands with the merchant object. See Sample Code on page 194 for more information.

RegistryThe API allows you to set merchant information in the Windows registry.

Environment Set UpMake sure you set the following environment settings. Refer to your compiler documentation for more information.

• Include lcc.bas (VB) or lcc.inc (C)

• Include ATLPayment 1.0 Type Library

• Include lccx.dll

The ActiveX API was compiled for Windows 2000 operating system with Intel processors.

BindingYou can bind operations in two ways: early binding and late binding. Early binding allows binding of the control to occur when you compile the API and is the preferred method. Late binding allows binding of the control to occur when the API executes.



Early Binding

To bind the interfaces in the control, include the following declarations in the .bas or .frm modules.

Public payment As LCCPayment

Public merchant As Merchant

Public merchantinfo As LCCStoreList

After the declarations are included in the modules, you can explicitly call the modules as shown below.

Set merchant = New Merchant

Set payment = New LCCPayment

Set merchantinfo = New LCCStoreList

Properly clean up memory associated with the objects with the statements below.

If Not merchant Is Nothing Then Set merchant = Nothing

If Not payment Is Nothing Then Set payment = Nothing

If Not merchantinfo Is Nothing Then Set merchantinfo = Nothing

Late Binding

To bind the interfaces in the control include the following statements.

Set merchant = CreateObject("LCC.Merchant")

Set merchantinfo = CreateObject("LCC.MerchantList")

Set payment = CreateObject("LCC.Payment")

Properly clean up memory associated with the objects with the statements below.

If Not merchant Is Nothing Then Set merchant = Nothing

If Not payment Is Nothing Then Set payment = Nothing

If Not merchantinfo Is Nothing Then Set merchantinfo = Nothing

Class DetailsThis section describes the classes.

Merchant Class

.MerchantName

This property gets/sets the merchant’s name.



.MerchantID

This property gets/sets the merchant’s ID.

.ServerPort

This property gets/sets the merchant’s server port.

.ServerIP

This property gets/sets the merchant’s server IP address.

.Encryption

This property gets/sets the merchant’s mode of encryption.

LCCStoreList Class

.Load

This method loads all the merchants in the merchant list.

Inputs

Outputs

.AddMerchant(pdispMerchant As Object)

This method adds a new merchant to the list.

Inputs

Outputs

.GetMerchantCount() as Long

This method retrieves the number of merchants in the list.

None

None

(Object) merchant object to add

None



Inputs

Outputs

.GetNextMerchant(Restart As Long, objMerchant As Object)

This method loads the next merchant in the list.

Inputs

Outputs

.RemoveMerchant(strMerchant as String)

This method deletes a merchant from the list.

Inputs

Outputs

.UpdateMerchant(objMerchant As Object)

This method adds a new merchant to the list.

Inputs

None

(Long) number of merchants in the list

(Long) start from beginning of store list if non-zero; otherwise, next merchant

(Object) merchant object

None

(String) name of merchant to remove

None

(Object) edited merchant information



Outputs

.Save()

This method commits the changes made to the list.

Inputs

Outputs

LCCPayment Class

.SetConfigFile(sConfigFile As String) As Integer

This method sets the path and filename of the merchant configuration file. The configuration file is used to look up merchant and server information based on an input merchant name. See Merchant Information on page 185 for more information.

Inputs

Output

.OpenConnection(sServer As String, nPort As Long, nEncryption As Long) As Long

This method establishes a persistent connection to the CPM Server that allows the transmission of multiple transactions over one connection. This method may increase processing time especially if you are using SSL encryption.

After you perform the .OpenConnection method and it is successful, perform the .SetConnectionHandle method to allow for the usage of the persistent connection. See .SetConnectionHandle(hConnection As Long) As Integer on page 191.

None

None

None

(String) full path to the API configuration file

(Integer) 0 if successful; an identifier corresponding to an error otherwise



Inputs

Outputs

.SetConnectionInformation(sServer As String, nPort As Long, nEncryption As Long) As Integer

This method sets the connection information for the specified transaction at run time. This method overrides the settings in the configuration file.

Inputs

Outputs

.SetConnectionHandle(hConnection As Long) As Integer

This method sets a handle corresponding to the specified connection. Other functions use this handle to manipulate the transaction.

Inputs

Outputs

(String) network address of the connection socket

(Long) port of the CPM Server application, usually 1530

(Long) type of encryption; 0 is the default, 1 is for SSL

(Long) connection handle if successful (>=0); an identifier corresponding to an error otherwise (<0)


(Long) port of the CPM Server application, usually 1530

(Long) type of encryption; 0 is the default, 1 is for SSL


(Long) the handle of the transaction




.CloseConnection(hConnection As Long) As Integer

This method closes a connection to the CPM Server that was opened with the OpenConnection function.

Inputs

Output

.GetSessionId () As Long

This method retrieves the session ID for a transaction. The session ID is used when the CPM Server is configured to use security.

Inputs

Outputs

.SetSessionId(SessionID As Long) As Integer

This method sets the session ID for a transaction. You must use this function when the CPM Server is configured to use security.

Inputs

Outputs

(Long) connection handle of an existing connection


None

(Long) the session ID

(Long) the session ID




.SetValue(FieldId As Long, Value As String) As Integer

This method sets the value of a field for a transaction.

Inputs

Outputs

.GetValue(FieldId As Long) As String

This method retrieves a field's value for a transaction.

Inputs

Outputs

.RunTransaction(TransactionTypeID As Long) As Long

This method executes a transaction. Use GetValue to retrieve the returned fields.

Inputs

Outputs

.ClearValues()

This method removes all the values associated with an open transaction.

Inputs

(Long) identifier of the field to set

(String) the value to set the field to


(Long) identifier of the field to set

(String) field value

(Long) transaction type identifier; for example, ID_AUTHORIZATION

(Long) 0 if successful; an identifier corresponding to an error otherwise

None



Outputs

Sample CodeNote The sample code below was compiled using Microsoft's Visual Studio com-piler, version 6.

'Program Name:ActiveX Sample'Date: September 3, 2001'Description:This Sample shows you how to run each of the transactions.'Requirements:You must have the LCCX.dll and the Atl.dll registered for our object to' work properly. If you installed with our installation program, it should' be done automatically.

Option Explicit

Public LCCPayment As LCCPayment

Const mstServerAddress As String = "localhost"

Dim mlngSessionID As LongDim mobjLCCPayment As ObjectDim mobjLCCMerchant As ObjectDim mobjLCCMerchantList As ObjectDim mlngSessionStatus As LongDim mstResult As String

Private Sub cmdACHFill_Click()

cboMerchant.Text = cboMerchant.List(0)txtAccount.Text = "Change Me"txtAmount.Text = "Change Me"txtBankID.Text = "Change Me"txtAccountType.Text = "Change Me"txtCustomerName.Text = "Change Me"

End Sub

Private Sub cmdClear_Click()

cboMerchant.Text = ""

txtAccount.Text = ""txtAmount.Text = ""txtCardType.Text = ""txtExpiration.Text = ""txtTax.Text = ""

None



txtBankID.Text = ""txtAccountType.Text = ""txtCustomerName.Text = ""txtZip.Text = ""txtUsername.Text = ""txtPassword.Text = ""

txtSequence.Text = "(null)"txtApproval.Text = "(null)"txtResponse.Text = "(null)"txtReturnCodeMsg.Text = "(null)"txtReturnCode.Text = "(null)"txtProcResponseCode.Text = "(null"txtZipMatch.Text = "(null)"txtAuthResponseCode.Text = "(null)"txtRetRefNumber.Text = "(null)"

End Sub

Private Sub cmdCreditFill_Click()

cboMerchant.Text = cboMerchant.List(0)txtAccount.Text = "Change Me"txtExpiration.Text = "Change Me"txtAmount.Text = "Change Me"txtCardType.Text = "Change Me"

End Sub

Private Sub Form_Load()

Dim iMerchants As IntegerDim x As Integer

'Early binding method - The following string needed to be added to the module'for early binding to be active: Public LCCPayment As LCCPaymentSet mobjLCCPayment = New LCCPayment

'Late Binding method' Set mobjLCCPayment = CreateObject("LCC.Payment") Set mobjLCCMerchant = CreateObject("LCC.Merchant") Set mobjLCCMerchantList = CreateObject("LCC.MerchantList")

'This will allow you to populate your form with the Merchants stored in the registry. cboMerchant.Clear

mobjLCCMerchantList.Load iMerchants = mobjLCCMerchantList.GetMerchantCount For x = 1 To iMerchants If (x = 1) Then mobjLCCMerchantList.GetNextMerchant True, mobjLCCMerchant Else mobjLCCMerchantList.GetNextMerchant False, mobjLCCMerchant End If



cboMerchant.AddItem mobjLCCMerchant.MerchantName Next 'You can set these fields for te Merchant object and then you can Add, Update, or Remove'the merchant information to the registry.' LCCMerchant.MerchantName = cboMerchant' LCCMerchant.ServerPort = 1530' LCCMerchant.ServerIP = "127.0.0.1"' LCCMerchant.Encryption = 0' LCCMerchant.MerchantID = cboMerchant

'' LCCMerchantList.AddMerchant LCCMerchant' LCCMerchantList.UpdateMerchant LCCMerchant' LCCMerchantList.RemoveMerchant cboMerchant 'You must save after you make these changes. At this point the registry changes will be 'made.' LCCMerchantList.Save

End Sub

Private Sub cmdAuth_Click() 'The authorization sample is much more indepth than the other transactions. If you want 'to know what a basic auth resembles, please refer to the verify. Dim lngHandle As Long Dim i As Integer

'Early binding method - requires additional code elsewhere i.e moduleSet mobjLCCPayment = New LCCPayment With mobjLCCPayment .ClearValues 'Although it is not necessary to set the session id for single threaded applications,'you may need to in order to do more complicated programs. If mlngSessionID <> 0 Then .SetSessionId (mlngSessionID)

'Here is where you SetValue the fields that are required and any additional fields that 'you want. .SetValue ID_MERCHANT_NAME, cboMerchant' .SetValue ID_MERCHANT_ID, cboMerchant .SetValue ID_ACCOUNT_NUMBER, txtAccount.Text .SetValue ID_CARD_TYPE, txtCardType.Text .SetValue ID_EXPIRATION_DATE, txtExpiration.Text .SetValue ID_AMOUNT, txtAmount.Text .SetValue ID_CUSTOMER_ZIP, txtZip.Text 'Level III Purchasing Card Group .SetValue ID_LINE_ITEM_DETAIL_COUNT, "1" .SetValue ID_FREIGHT_AMOUNT, "20" .SetValue ID_DUTY_AMOUNT, "21"



.SetValue ID_SHIP_FROM_ZIP_CODE, "63123" .SetValue ID_DISCOUNT_AMOUNT_APPLIED, "10" .SetValue ID_VAT_TAX_AMOUNT, "12" .SetValue ID_VAT_TAX_RATE, "10" .SetValue ID_ALTERNATIVE_TAX_ID, "12" .SetValue ID_ALTERNATIVE_TAX_AMOUNT, "10" 'In order to add an additional LineItem increment i i = 0 Do Until i = 1 'You can set up to 1000 items'Level III Purchasing Card Line Item Detail Group .SetValue ID_ITEM_DESCRIPTION + i, "Screw Drivers" .SetValue ID_ITEM_PRODUCT_CODE + i, "abc123" .SetValue ID_ITEM_QUANTITY + i, "5" .SetValue ID_ITEM_UNIT_OF_MEASURE + i, "10" .SetValue ID_ITEM_TAX_AMOUNT + i, "10" .SetValue ID_ITEM_TAX_RATE + i, "11" .SetValue ID_ITEM_TOTAL_AMOUNT + i, "10" .SetValue ID_ITEM_DISCOUNT_AMOUNT + i, "10" .SetValue ID_ITEM_COMMODITY_CODE + i, "1345" .SetValue ID_ITEM_UNIT_COST + i, "15" .SetValue ID_ITEM_DISCOUNT_INDICATOR + i, "3" .SetValue ID_ITEM_TAX_TYPE_APPLIED + i, "G" .SetValue ID_ITEM_TAX_APPLIED + i, "1" .SetValue ID_ITEM_TAX_EXEMPT + i, "N" i = i + 1 Loop 'Opening a connection, this is not required to run a transaction, but may be useful if'you want to send many transactions over one connection.' lngHandle = .OpenConnection(mstServerAddress, 1530, 0) 'One of the three options of notifying the API of the location of the server is to'the SetConnection Information. If you want to hard code the connection information.'You must have either Merchant name or Merchant ID set. Merchant ID overules Merchant'Name if both are set.' .SetConnectionInformation mstServerAddress, 1530, 0 'Another option is the Configuration File.'If you want to use a configuration file, you must provide a path to the text file that 'you create.'You may include network names and/or shared drives. You cannot have the Merchant ID 'set.'The format of the text file is located in the our documentation.' .SetConfigFile "c:\conf.txt"

'If Neither of those methods are used, it will you the information stored in the'registry. You should insert this information through the Merchant Information'Editor installed with the installation program. 'You can use the Connection handle in order to not have to Set the Connection information'in the future.' .SetConnectionHandle (lngHandle)



'Run the transaction and pull the Result. The mstResult is the return code.'The ideal is "0"'There is a list of the other return codes in the CyberSource documentation. mstResult = .RunTransaction(ID_AUTHORIZATION) txtReturnCodeMsg = .GetValue(ID_RETURN_CODE_MESSAGE) txtReturnCode = mstResult 'Closing a connection, this is not required to run a transaction' .CloseConnection (lngHandle) If (mstResult = 0) Then'You can GetValue any of the output fields listed in the documentation for this 'transaction type.'You would then base your business decisions on the values that are returned. txtSequence = .GetValue(ID_SEQUENCE_NUMBER) txtApproval = .GetValue(ID_APPROVAL_CODE) txtResponse = .GetValue(ID_AUTH_RESPONSE_MESSAGE) txtAuthResponseCode = .GetValue(ID_AUTH_RESPONSE_CODE) txtZipMatch = .GetValue(ID_ZIP_MATCH) txtProcResponseCode = .GetValue(ID_PROCESSOR_AUTH_RESPONSE_CODE) txtRetRefNumber.Text = .GetValue(ID_RETRIEVAL_REFERENCE_NUMBER) End If

End With 'mobjLCCPayment

'Clean up memory If Not mobjLCCPayment Is Nothing Then Set mobjLCCPayment = Nothing

End Sub

Private Sub cmdManualAuth_Click()

'A manual authorization will not result in a new record, but it will alter the'original authorzation. This should only be done on authorizations. Dim lngHandle As Long Set mobjLCCPayment = New LCCPayment With mobjLCCPayment .ClearValues If mlngSessionID <> 0 Then .SetSessionId (mlngSessionID) .SetValue ID_MERCHANT_NAME, cboMerchant .SetValue ID_SEQUENCE_NUMBER, txtSequence.Text

'Setting any additional values will overwrite existing data pulled from the original 'transaction .SetValue ID_APPROVAL_CODE, txtApproval.Text mstResult = .RunTransaction(ID_MANUAL_AUTHORIZATION) txtReturnCodeMsg = .GetValue(ID_RETURN_CODE_MESSAGE) txtReturnCode = mstResult



If (mstResult = 0) Then txtSequence = mobjLCCPayment.GetValue(ID_SEQUENCE_NUMBER) txtApproval = mobjLCCPayment.GetValue(ID_APPROVAL_CODE) txtResponse = mobjLCCPayment.GetValue(ID_AUTH_RESPONSE_MESSAGE) txtAuthResponseCode = mobjLCCPayment.GetValue(ID_AUTH_RESPONSE_CODE) End If


If Not mobjLCCPayment Is Nothing Then Set mobjLCCPayment = Nothing End Sub

Private Sub cmdReversal_Click()

'A Reversal changes the hold on the Authorization to the amount you provide to the Reversal. Dim lngHandle As Long Set mobjLCCPayment = New LCCPayment

With mobjLCCPayment .ClearValues If mlngSessionID <> 0 Then .SetSessionId (mlngSessionID) .SetValue ID_MERCHANT_NAME, cboMerchant .SetValue ID_SEQUENCE_NUMBER, txtSequence.Text

'A reversal should result in a lesser amount than the original authorization. Therefore,'you should set the amount field. .SetValue ID_AMOUNT, "0" mstResult = .RunTransaction(ID_REVERSAL) txtReturnCodeMsg = .GetValue(ID_RETURN_CODE_MESSAGE) txtReturnCode = mstResult If (mstResult = 0) Then txtSequence = mobjLCCPayment.GetValue(ID_SEQUENCE_NUMBER) txtApproval = mobjLCCPayment.GetValue(ID_APPROVAL_CODE) txtResponse = mobjLCCPayment.GetValue(ID_AUTH_RESPONSE_MESSAGE) txtAuthResponseCode = mobjLCCPayment.GetValue(ID_AUTH_RESPONSE_CODE) End If


If Not mobjLCCPayment Is Nothing Then Set mobjLCCPayment = Nothing

End Sub

Private Sub cmdCapture_Click()

Dim lngHandle As Long



Set mobjLCCPayment = New LCCPayment

With mobjLCCPayment .ClearValues .SetValue ID_MERCHANT_NAME, cboMerchant If mlngSessionID <> 0 Then .SetSessionId (mlngSessionID) If Len(txtSequence.Text) = 15 Or Len(txtSequence.Text) = 12 Then 'It is HIGHLY recommended that you simply provide the sequence number of a previous transaction and the Merchant Name. .SetValue ID_SEQUENCE_NUMBER, txtSequence.Text 'The date and time fields are necessary in order to get a better transaction rate. Otherwise, it will default to the 'authorization date and time. The default may be necessary for certain business structures. .SetValue ID_TRANSACTION_DATE, "121212" .SetValue ID_TRANSACTION_TIME, "101010" Else 'Here is where you SetValue the fields that are required and any additional fields that you want. 'Again, we HIGHLY recommend using a sequence number of a previous transaction when possible.' .SetValue ID_MERCHANT_ID, cboMerchant .SetValue ID_ACCOUNT_NUMBER, txtAccount.Text .SetValue ID_CARD_TYPE, txtCardType.Text .SetValue ID_EXPIRATION_DATE, txtExpiration.Text .SetValue ID_AMOUNT, txtAmount.Text .SetValue ID_CURRENT_AMOUNT, txtAmount.Text .SetValue ID_TRANSACTION_DATE, "121212" .SetValue ID_TRANSACTION_TIME, "101010" End If'Setting any additional values will overwrite existing data pulled from the original transaction'If you call for a verbal authorization, you can set the Approval Code here so that the Capture will settle.' .SetValue ID_APPROVAL_CODE, txtApproval.Text mstResult = .RunTransaction(ID_CAPTURE) txtReturnCodeMsg = .GetValue(ID_RETURN_CODE_MESSAGE) txtReturnCode = mstResult If (mstResult = 0) Then txtSequence = mobjLCCPayment.GetValue(ID_SEQUENCE_NUMBER) txtApproval = mobjLCCPayment.GetValue(ID_APPROVAL_CODE) txtResponse = mobjLCCPayment.GetValue(ID_AUTH_RESPONSE_MESSAGE) End If



End Sub

Private Sub cmdLookup_Click()



Dim lngHandle As Long Set mobjLCCPayment = New LCCPayment With mobjLCCPayment .ClearValues If mlngSessionID <> 0 Then .SetSessionId (mlngSessionID) .SetValue ID_MERCHANT_NAME, cboMerchant If Len(txtSequence.Text) = 0 Then .SetValue ID_RETRIEVAL_REFERENCE_NUMBER, txtRetRefNumber.Text Else .SetValue ID_SEQUENCE_NUMBER, txtSequence.Text End If

mstResult = .RunTransaction(ID_LOOKUP) txtReturnCodeMsg = .GetValue(ID_RETURN_CODE_MESSAGE) txtReturnCode = mstResult If (mstResult = 0) Then txtSequence = .GetValue(ID_SEQUENCE_NUMBER) txtApproval = .GetValue(ID_APPROVAL_CODE) txtResponse = .GetValue(ID_AUTH_RESPONSE_MESSAGE) txtAccount.Text = .GetValue(ID_ACCOUNT_NUMBER) txtAmount.Text = .GetValue(ID_AMOUNT) txtCardType.Text = .GetValue(ID_CARD_TYPE) txtExpiration.Text = .GetValue(ID_EXPIRATION_DATE) txtTax.Text = .GetValue(ID_TAX_AMOUNT) txtRetRefNumber.Text = .GetValue(ID_RETRIEVAL_REFERENCE_NUMBER) txtProcResponseCode = .GetValue(ID_PROCESSOR_AUTH_RESPONSE_CODE) End If

End With 'mobjLCCPayment If Not mobjLCCPayment Is Nothing Then Set mobjLCCPayment = Nothing End Sub

Private Sub cmdReturn_Click() Dim lngHandle As Long Set mobjLCCPayment = New LCCPayment

With mobjLCCPayment .ClearValues .SetValue ID_MERCHANT_NAME, cboMerchant If mlngSessionID <> 0 Then .SetSessionId (mlngSessionID) If Len(txtSequence.Text) = 15 Or Len(txtSequence.Text) = 12 Then 'It is best practice to simply provide the sequence number of a previous transaction and the Merchant Name.



.SetValue ID_SEQUENCE_NUMBER, txtSequence.Text Else 'Here is where you SetValue the fields that are required and any additional fields that you want.' .SetValue ID_MERCHANT_ID, cboMerchant .SetValue ID_ACCOUNT_NUMBER, txtAccount.Text .SetValue ID_CARD_TYPE, txtCardType.Text .SetValue ID_EXPIRATION_DATE, txtExpiration.Text .SetValue ID_AMOUNT, txtAmount.Text .SetValue ID_CURRENT_AMOUNT, txtAmount.Text End If

mstResult = .RunTransaction(ID_RETURN) txtReturnCodeMsg = .GetValue(ID_RETURN_CODE_MESSAGE) txtReturnCode = mstResult If (mstResult = 0) Then txtSequence = mobjLCCPayment.GetValue(ID_SEQUENCE_NUMBER) txtApproval = mobjLCCPayment.GetValue(ID_APPROVAL_CODE) txtResponse = mobjLCCPayment.GetValue(ID_AUTH_RESPONSE_MESSAGE) End If



End Sub

Private Sub cmdVoid_Click()

Dim lngHandle As Long Set mobjLCCPayment = New LCCPayment

With mobjLCCPayment .ClearValues If mlngSessionID <> 0 Then .SetSessionId (mlngSessionID) .SetValue ID_MERCHANT_NAME, cboMerchant

'Can only run a void on a transaction that hasn't settled. Otherwise you will receive an error. .SetValue ID_SEQUENCE_NUMBER, txtSequence.Text

mstResult = .RunTransaction(ID_VOID_TRANSACTION) txtReturnCodeMsg = .GetValue(ID_RETURN_CODE_MESSAGE) txtReturnCode = mstResult If (mstResult = 0) Then txtSequence = mobjLCCPayment.GetValue(ID_SEQUENCE_NUMBER) txtApproval = mobjLCCPayment.GetValue(ID_APPROVAL_CODE) txtResponse = mobjLCCPayment.GetValue(ID_AUTH_RESPONSE_MESSAGE) End If




If Not mobjLCCPayment Is Nothing Then Set mobjLCCPayment = Nothing End Sub

Private Sub cmdPredial_Click() Dim lngHandle As Long Set mobjLCCPayment = New LCCPayment

With mobjLCCPayment .ClearValues If mlngSessionID <> 0 Then .SetSessionId (mlngSessionID) .SetValue ID_MERCHANT_NAME, cboMerchant mstResult = .RunTransaction(ID_PREDIAL) txtReturnCodeMsg = .GetValue(ID_RETURN_CODE_MESSAGE) txtReturnCode = mstResult



End Sub

Private Sub cmdAuthCapture_Click() Dim lngHandle As Long Set mobjLCCPayment = New LCCPayment

With mobjLCCPayment .ClearValues If mlngSessionID <> 0 Then .SetSessionId (mlngSessionID) .SetValue ID_MERCHANT_NAME, cboMerchant' .SetValue ID_MERCHANT_ID, cboMerchant.Text .SetValue ID_ACCOUNT_NUMBER, txtAccount .SetValue ID_CARD_TYPE, txtCardType.Text .SetValue ID_EXPIRATION_DATE, txtExpiration .SetValue ID_AMOUNT, txtAmount mstResult = .RunTransaction(ID_AUTH_AND_CAPTURE) txtReturnCodeMsg = .GetValue(ID_RETURN_CODE_MESSAGE) txtReturnCode = mstResult If (mstResult = 0) Then txtSequence = .GetValue(ID_SEQUENCE_NUMBER) txtApproval = .GetValue(ID_APPROVAL_CODE) txtResponse = .GetValue(ID_AUTH_RESPONSE_MESSAGE) txtAuthResponseCode = .GetValue(ID_AUTH_RESPONSE_CODE) txtZipMatch = .GetValue(ID_ZIP_MATCH) txtProcResponseCode = .GetValue(ID_PROCESSOR_AUTH_RESPONSE_CODE)



txtRetRefNumber.Text = .GetValue(ID_RETRIEVAL_REFERENCE_NUMBER) End IfEnd With 'mobjLCCPayment


End Sub

Private Sub cmdACHVerify_Click()


'Verify amount must always be $0 txtAmount.Text = "0" With mobjLCCPayment .ClearValues If mlngSessionID <> 0 Then .SetSessionId (mlngSessionID)

.SetValue ID_MERCHANT_NAME, cboMerchant' .SetValue ID_MERCHANT_ID, cboMerchant.Text .SetValue ID_BANK_ACCOUNT_NUMBER, txtAccount.Text .SetValue ID_BANK_ID, txtBankID.Text .SetValue ID_ACCOUNT_TYPE, txtAccountType.Text .SetValue ID_AMOUNT, txtAmount.Text .SetValue ID_CUSTOMER_NAME, txtCustomerName.Text mstResult = .RunTransaction(ID_ACH_VERIFY) txtReturnCodeMsg = .GetValue(ID_RETURN_CODE_MESSAGE) txtReturnCode = mstResult If (mstResult = 0) Then txtSequence = .GetValue(ID_SEQUENCE_NUMBER) txtAuthResponseCode = .GetValue(ID_VERIFICATION_RESULT) txtProcResponseCode = .GetValue(ID_PROCESSOR_RESPONSE_CODE) End If



End Sub

Private Sub cmdACHDeposit_Click() Dim lngHandle As Long Set mobjLCCPayment = New LCCPayment '



With mobjLCCPayment .ClearValues .SetValue ID_MERCHANT_NAME, cboMerchant If mlngSessionID <> 0 Then .SetSessionId (mlngSessionID) If Len(txtSequence.Text) = 15 Or Len(txtSequence.Text) = 12 Then 'It is best practice to simply provide the sequence number of a previous transaction and the Merchant Name. .SetValue ID_SEQUENCE_NUMBER, txtSequence.Text .SetValue ID_AMOUNT, txtAmount.Text Else 'Here is where you SetValue the fields that are required and any additional fields that you want. .SetValue ID_BANK_ACCOUNT_NUMBER, txtAccount.Text .SetValue ID_BANK_ID, txtBankID.Text .SetValue ID_ACCOUNT_TYPE, txtAccountType.Text .SetValue ID_AMOUNT, txtAmount.Text .SetValue ID_CUSTOMER_NAME, txtCustomerName.Text End If mstResult = .RunTransaction(ID_ACH_DEPOSIT) txtReturnCodeMsg = .GetValue(ID_RETURN_CODE_MESSAGE) txtReturnCode = mstResult If (mstResult = 0) Then txtSequence = .GetValue(ID_SEQUENCE_NUMBER) txtAuthResponseCode = .GetValue(ID_VERIFICATION_RESULT) End If



End Sub

Private Sub cmdACHLookup_Click()


With mobjLCCPayment .ClearValues If mlngSessionID <> 0 Then .SetSessionId (mlngSessionID)

.SetValue ID_MERCHANT_NAME, cboMerchant .SetValue ID_SEQUENCE_NUMBER, txtSequence.Text mstResult = .RunTransaction(ID_ACH_LOOKUP) txtReturnCodeMsg = .GetValue(ID_RETURN_CODE_MESSAGE) txtReturnCode = mstResult If (mstResult = 0) Then



txtSequence = .GetValue(ID_SEQUENCE_NUMBER) txtAuthResponseCode = .GetValue(ID_VERIFICATION_RESULT) txtAccount.Text = .GetValue(ID_ACCOUNT_NUMBER) txtAmount.Text = .GetValue(ID_AMOUNT) txtBankID.Text = .GetValue(ID_BANK_ID) txtAccountType.Text = .GetValue(ID_ACCOUNT_TYPE) txtCustomerName.Text = .GetValue(ID_CUSTOMER_NAME) End If



End Sub

Private Sub cmdACHRefund_Click()


With mobjLCCPayment .ClearValues .SetValue ID_MERCHANT_NAME, cboMerchant If mlngSessionID <> 0 Then .SetSessionId (mlngSessionID) If Len(txtSequence.Text) = 15 Or Len(txtSequence.Text) = 12 Then 'It is best practice to simply provide the sequence number of a previous transaction and the Merchant Name. .SetValue ID_SEQUENCE_NUMBER, txtSequence.Text Else 'Here is where you SetValue the fields that are required and any additional fields that you want. .SetValue ID_BANK_ACCOUNT_NUMBER, txtAccount.Text .SetValue ID_BANK_ID, txtBankID.Text .SetValue ID_ACCOUNT_TYPE, txtAccountType.Text .SetValue ID_AMOUNT, txtAmount.Text .SetValue ID_CUSTOMER_NAME, txtCustomerName.Text End If mstResult = .RunTransaction(ID_ACH_REFUND) txtReturnCodeMsg = .GetValue(ID_RETURN_CODE_MESSAGE) txtReturnCode = mstResult If (mstResult = 0) Then txtSequence = .GetValue(ID_SEQUENCE_NUMBER) txtAuthResponseCode = .GetValue(ID_VERIFICATION_RESULT) End If



End Sub



Private Sub cmdACHVoid_Click()


With mobjLCCPayment .ClearValues If mlngSessionID <> 0 Then .SetSessionId (mlngSessionID)

.SetValue ID_MERCHANT_NAME, cboMerchant .SetValue ID_SEQUENCE_NUMBER, txtSequence.Text mstResult = .RunTransaction(ID_ACH_VOID) txtReturnCodeMsg = .GetValue(ID_RETURN_CODE_MESSAGE) txtReturnCode = mstResult If (mstResult = 0) Then txtSequence = .GetValue(ID_SEQUENCE_NUMBER) txtAuthResponseCode = .GetValue(ID_VERIFICATION_RESULT) End If



End Sub

Private Sub cmdExit_Click()

End

End Sub

Private Sub cmdBeginSession_Click()

Call cmdEndSession_Click Set mobjLCCPayment = New LCCPayment

With mobjLCCPayment'The following is to enable CPM security support. This is only'necessary when User Authentication Enabled in the Admin Client 'You should always clear values before setting you values for a RunTransaction. .ClearValues .SetValue ID_MERCHANT_NAME, cboMerchant.List(0) .SetValue ID_USERNAME, txtUsername.Text .SetValue ID_PASSWORD, txtPassword.Text mlngSessionStatus = .RunTransaction(ID_BEGIN_SESSION) txtReturnCodeMsg = .GetValue(ID_RETURN_CODE_MESSAGE) txtReturnCode = mlngSessionStatus


Chapter 7 Environment and Implementation Batch API

If mlngSessionStatus = 0 Then mlngSessionID = .GetSessionId Else MsgBox "Error Identifier: " & mlngSessionStatus, vbCritical, "Security Login Failed" End End If'Now that you have ran a Begin Session, you do not have to store the Session ID. It will'Remain in memory for this object until it has been dormant for the amount of time you'have set in the Admin Client even if you run a ClearValues on the object. In order to'release a session ID, you must run an End Session as shown in the cmdExit subroutine.


End Sub

Private Sub cmdEndSession_Click()

Set mobjLCCPayment = New LCCPayment

With mobjLCCPayment 'The following is to release the security session ID If mlngSessionID <> 0 Then .ClearValues .SetSessionId (mlngSessionID) .SetValue ID_MERCHANT_NAME, cboMerchant mlngSessionStatus = .RunTransaction(ID_END_SESSION) txtReturnCodeMsg = .GetValue(ID_RETURN_CODE_MESSAGE) txtReturnCode = mlngSessionStatus If Not mobjLCCPayment Is Nothing Then Set mobjLCCPayment = Nothing End If End With 'mobjLCCPaymentEnd Sub

Batch APIThe CPM Batch Processor Interface is an optional component that takes files containing transactions from legacy transaction processing systems and sends each transaction to the CPM Server. A single line in the batch file of fixed formatted fields represents each transaction.



You can send the following transaction types to the CPM Server through the batch interface:

• Authorization

• Capture

• Authorize and Capture

• Line Item Detail

• Void

• Reversal

• Return

• Lookup

• Predial

• Begin Session

• End Session

You can send several different transaction types to the CPM Server through the batch interface. Each line of the batch file represents a single transaction. Three configuration files define the fields for the transaction types. The input files need only the fields required for the credit card function. The output files supply all output information as well as a copy of the input fields.

Configuration Files

Merchant InformationThe Batch API provides three ways to specify merchant information:

• Environment variable

• Registry (for Windows systems)

• Configuration file

To locate the merchant information, the API first looks at the path and filename specified by the environment variable LCC_CLIENT_CONF. If the environment variable is not defined, then the API looks for the merchant information in the Windows Registry. If the information is not specified in the Registry, the API looks for the default configuration file



in the working directory. The API returns an error if it cannot locate the merchant information using any of these methods.

You can create your own configuration file or use the default configuration file, lcc_client.cf, which was called lcc.cf in early versions of CPM. The default location for the configuration file is the working directory.

Configuration File Format

The format of the file is much like an .ini file. The sections are denoted by brackets ([]), and information underneath those sections are simple key=value pairs.

The client configuration file stores the Merchant Identifier, CPM Server TCP/IP Address, CPM Server TCP/IP Port, and SSL Encryption Scheme underneath each merchant name section.

[Merchant Name]

MerchantID=Merchant ID




Example

[Demonstration Merchant]

MerchantID=demo


Server Port=1530

Encryption=0

LCC_BATCH.CFG FileThe lcc_batch.cfg file defines the input and output fields for each transaction record. The transactions are denoted by brackets ([]), and information underneath the transactions are simple key=value lists.

Note If you are processing Purchasing Card Level III transactions, enter the lineitem record prior to the transaction record.

The Begin Session and End Session transactions do not have outputs.



LCC_BATCH_IDS.CFG FileThe lcc_batch_ids.cfg file pairs the field names defined in the lcc_batch.cfg file with API field identifiers. The lcc_batch_ids.cfg file defines what API fields can be used by the Batch API.

Note Each field listed in the lcc_batch.cfg file must have an API field identifierdefined in the lcc_batch_ids.cfg file.

LCC_BATCH_LENGTHS.CFG FileThe lcc_batch_lengths.cfg file allows you to define the length of each input field. If a field length is set to an amount greater than that allowed by the CPM API, the CPM Server generates the error 102 ERR_FIELD_TOO_LONG and places the transaction in the .err file.

Note Each field listed in the lcc_batch.cfg file must have a length defined in thelcc_batch_lengths.cfg file.

Input File DescriptionThe input file consists of fixed format records, one record per line, and one transaction per record. The first three characters of each line hold a number that identifies the transaction type. See Table 96 for a list of the numbers and corresponding transaction types. If a field is unused, fill that field with spaces. Left justify all fields and fill any unused portion with spaces. The carriage return is used as the delimiter between records.

All amount fields formatted in the CPM API are 12 characters in length with a format of DDDDDDDDDDCC. Do not include any formatting characters. For example, enter $25.67 as 2567, followed by eight spaces.

If CPM Server security is enabled, send a Begin Session transaction to log into the CPM Server and obtain a session identifier. Send an End Session transaction to log out of the CPM Server.

Table 96 lists the transaction types and corresponding numbers used in the input file.

Table 96 Transaction Types

Credit Card Functions

100 ID_AUTHORIZATION

101 ID_REVERSAL



Implementing Purchase Card Level III UsageIf you are processing Purchasing Card Level III transactions, enter the line item information, which is transaction type identifier 999, immediately preceding the transaction information.

LCC_BATCH_LAYOUT.TXT FileThe lcc_batch_layout.txt file provides the record layout for each transaction type defined in lcc_batch.cfg. The file lists the input and output fields for each transaction, the starting position of each field, and the field length.

To generate the lcc_batch_layout.txt file:

1 At the command prompt, change to the CPM/lcc_batch subdirectory. For example: C:\>cd CPM\lcc_batch

2 Enter the following command.

lcc_batch -layout

102 ID_CAPTURE

103 ID_RETURN

104 ID_AUTH_AND_CAPTURE

105 ID_MANUAL_AUTHORIZATION

106 ID_VOID_TRANSACTION

Electronic Fund Transfer Functions

108 ID_ACH_VERIFY

109 ID_ACH_DEPOSIT

110 ID_ACH_REFUND

111 ID_ACH_VOID

Security Functions

150 ID_BEGIN_SESSION

151 ID_END_SESSION

Other

999 Purchase Card Level III line item detail

Table 96 Transaction Types (Continued)



Running the Batch Input File:

1 At the command prompt, change to the CPM/lcc_batch subdirectory. For example, C:\>cd CPM\lcc_batch

2 Enter the following command.

lcc_batch <batch input file name>

The batch processor begins processing the transactions. For each transaction a period (.) appears on the screen and three output files are generated.

Output Files

Approval Output File

The approval output file, *. app, lists all the transactions in the batch file that were approved.

Decline Output File

The decline output, *.den, file lists all the transactions in the batch file that were not approved.

Error Output File

The error output file, *.err, lists all the transactions in the batch file that were not processed because of errors.

Working With Output FilesIf you intend to run another batch input file of the same name, all three output files will have the same name and will overwrite the output files from the previous session. Move the output files to a different directory or rename the *. app, *.den, and the *.err from the previous session. CyberSource recommends that you establish naming conventions for your batch input and batch output files to maintain batch file organization.

Sample Code

LCC_BATCH.CFG File[Authorization]

Input=merchant_name, card_type, account_number, expiration_date, amount

Output= merchant_name, account_number, expiration_date, amount, sequence_number, auth_response_code, auth_response_message, approval_code



[Capture]

Input = merchant_name, sequence_number, amount


[Auth_And_Capture]

Input = merchant_name, card_type, account_number, expiration_date, amount


[Reversal]

Input = merchant_name, sequence_number, amount


[Return]

Input = merchant_name, account_number, expiration_date, amount


[Manual_Authorization]

Input = merchant_name, sequence_number, approval_code


[Void_Transaction]

Input = merchant_name, sequence_number




[Lookup]

Input = merchant_name, sequence_number


[Predial]

Input = merchant_name

Output= merchant_name, return_code_message

[Begin_Session]

Input = merchant_name, username, password

[End_Session]

Input = merchant_name

[Line_Item_Detail]

Input = item_description, item_product_code, item_quantity, item_total_amount

Output = item_description, item_product_code, item_total_amount

LCC_BATCH_IDS.CFG Filemerchant_name=100

account_number=101

expiration_date=102

amount=103

card_type=104

sequence_number=105



approval_code=106

auth_response_code=107

auth_response_message=108

return_code_message=109

transaction_id=120

transaction_date=121

transaction_time=122

validation_code=123

original_amount=124

response_indicator=125

returned_aci=126

requested_aci=127

pos_mode_code=128

market_specific_indicator=129

retrieval_reference_number=130

account_data_source=131

card_holder_id=132

authorization_source_code=133

current_amount=134

trans_attribute=135

current_tax_amount=136

address_match=140

zip_match=141

order_number=150

customer_street=151

customer_zip=152

purchase_card_order_number=155

tax_amount=156

commercial_card_type=157

ship_to_zip_code=158

cvv=165

cvv_result=166

customer_name=170

customer_phone=171

customer_city=172

customer_state=173

merchant_billing_name=190

merchant_billing_state=191

merchant_billing_location=192

user_sequence_number=200

user_defined_1=201



user_defined_2=202

user_defined_3=203

user_defined_4=204

user_defined_5=205

user_source_name=296

reserved_1=222

reserved_2=223

track_1_data=250

track_2_data=251

e_commerce_type=300

card_present_flag=350

terminal_capability=351

terminal_type=352

pos_entry_mode=353

customer_present_flag=354

remaining_balance=360

processor_avs_result=400

processor_auth_response_code=401

username=450

password=451

ship_to_address_1=460


ship_to_city=462

ship_to_state=463

ship_to_phone=464

customer_ip_address=465

customer_email=466

freight_amount=500

duty_amount=501

ship_from_zip_code=503

discount_amount_applied=504

vat_tax_amount=505

vat_tax_rate=506

alternative_tax_id=507

alternative_tax_amount=508

qhp_amount=3000

rx_amount=3001

vision_amount=3002

clinic_other_amount=3003

dental_amount=3004

partial_auth_flag=3005



item_description=10000

item_product_code=11000

item_quantity=12000

item_unit_of_measure=13000

item_tax_amount=14000

item_tax_rate=15000

item_total_amount=16000

item_discount_amount=17000

item_commodity_code=18000

item_unit_cost=19000

item_discount_indicator=20000

item_tax_type_applied=21000

item_tax_applied=22000

item_tax_exempt=23000

LCC_BATCH_LENGTHS.CFG Filemerchant_id=32

merchant_name=32

account_number=28

expiration_date=4

amount=12

card_type=4

sequence_number=15

approval_code=9

auth_response_code=1

auth_response_message=20

return_code_message=40

transaction_id=15

transaction_date=6

transaction_time=6

validation_code=4

original_amount=12

response_indicator=2

returned_aci=1

requested_aci=1

pos_mode_code=2

market_specific_indicator=2

retrieval_reference_number=12

account_data_source=1

card_holder_id=1



authorization_source_code=1

current_amount=12

trans_attribute=2

current_tax_amount=12

address_match=1

zip_match=1

order_number=25

customer_street=20

customer_zip=9

purchase_card_order_number=16

tax_amount=12

commercial_card_type=2

ship_to_zip_code=9

cvv=4

cvv_result=4

customer_name=26

customer_phone=14

customer_city=20

customer_state=2

merchant_billing_name=25

merchant_billing_state=2

merchant_billing_location=13

user_sequence_number=50

user_defined_1=50

user_defined_2=50

user_defined_3=50

user_defined_4=50

user_defined_5=50

user_source_name=31

reserved_1=50

reserved_2=50

track_1_data=76

track_2_data=37

e_commerce_type=2

card_present_flag=1

terminal_capability=1

terminal_type=1

pos_entry_mode=1

customer_present_flag=1

remaining_balance=12

processor_avs_result=3



processor_auth_response_code=4

username=31

password=12



ship_to_city=20

ship_to_state=2

ship_to_phone=14

customer_ip_address=30

customer_email=50

freight_amount=20

duty_amount=20

ship_from_zip_code=9

discount_amount_applied=20

vat_tax_amount=20

vat_tax_rate=20

alternative_tax_id=20

alternative_tax_amount=20

qhp_amount=12

rx_amount=12

vision_amount=12

clinic_other_amount=12

dental_amount=12

partial_auth_flag=1

line_item_detail_count=3

item_description=15

item_product_code=6

item_quantity=4

item_unit_of_measure=12

item_tax_amount=12

item_tax_rate=5

item_total_amount=12

item_discount_amount=12

item_commodity_code=12

item_unit_cost=12

item_discount_indicator=1

item_tax_type_applied=4

item_tax_applied=1

item_tax_exempt=1



LCC_BATCH_LAYOUT.TXT FileAUTH_AND_CAPTURE

INPUT:

transaction_type 1 3

merchant_name 4 32

account_number 36 28

expiration_date 64 4

amount 68 12

OUTPUT:


merchant_name 4 32



amount 68 12

sequence_number 80 15

auth_response_code 95 1

auth_response_message 96 20

approval_code 116 9

AUTHORIZATION

INPUT:


merchant_name 4 32



amount 68 12

OUTPUT:


merchant_name 4 32



amount 68 12






approval_code 116 9

BEGIN_SESSION

INPUT:


merchant_name 4 32

username 36 31

password 67 12

CAPTURE

INPUT:


merchant_name 4 32


amount 51 12

OUTPUT:


merchant_name 4 32



amount 68 12




approval_code 116 9

END_SESSION

INPUT:


merchant_name 4 32



LINE_ITEM_DETAIL

INPUT:


item_description 4 35

item_product_code 39 12

item_quantity 51 12

item_total_amount 63 12

OUTPUT:


item_description 4 35

item_product_code 39 12

item_total_amount 51 12

LOOKUP

INPUT:


merchant_name 4 32


OUTPUT:


merchant_name 4 32



amount 68 12




approval_code 116 9



MANUAL_AUTHORIZATION

INPUT:


merchant_name 4 32


approval_code 51 9

OUTPUT:


merchant_name 4 32



amount 68 12




approval_code 116 9

PREDIAL

INPUT:


merchant_name 4 32

OUTPUT:


merchant_name 4 32

return_code_message 36 40

RETURN

INPUT:


merchant_name 4 32





amount 68 12

OUTPUT:


merchant_name 4 32



amount 68 12




approval_code 116 9

REVERSAL

INPUT:


merchant_name 4 32


amount 51 12

OUTPUT:


merchant_name 4 32



amount 68 12




approval_code 116 9

VOID_TRANSACTION

INPUT:



Chapter 7 Environment and Implementation C API (Solaris, Win32 dll)

merchant_name 4 32


OUTPUT:


merchant_name 4 32



amount 68 12




approval_code 116 9

Sample Input File999Notebook 1212124 100 3300

999Pencil 31313112 25 2500

100Paymentech 002 5454545454545454 0103100

108Paymentech 96358965412 042000314 CJohn Golden

104Paymentech 002 5454545454545454 0103100

C API (Solaris, Win32 dll)

C SolarisThe C Solaris consists of a transaction interface and a class. The transaction interface, lcc.h, contains the constants for the transaction type identifiers, field identifiers, and error identifiers. See Chapter 5, CPM API Identifiers, on page 167 and Chapter 6, CPM Error Identifiers, on page 179 for more information on the transaction type identifiers, field identifiers, and error identifiers. The class contains a set of functions that allows the developer to create, execute, and examine transactions.

The Solaris API was compiled for Solaris 5.8 operating system with SPARC processors. The example Makefile, located on the CPM CD, is for Sun's Workshop Forte C compiler, version 6 update 1.



C Win32 dllThe C Win32 dll consists of a transaction interface and a class. The transaction interface, lcc.dll, contains the constants for the transaction type identifiers, field identifiers, and error identifiers. See Chapter 5, CPM API Identifiers, on page 167 and Chapter 6, CPM Error Identifiers, on page 179 for more information on the transaction type identifiers, field identifiers, and error identifiers. The class contains a set of functions that allows the developer to create, execute, and examine transactions.

The Win C API was compiled for Windows 2000 operating system with Intel processors.

Merchant InformationMost API calls are in the context of a merchant who is the originator of the transaction. You may indicate the merchant by either a merchant name or a merchant ID. The merchant ID is always the field that is ultimately passed to the CPM server. The API allows you to either send in the merchant ID directly, or supply a merchant name which is translated to the merchant ID through a local ID lookup through either the Windows registry, if running in a Windows environment, or a configuration file.

Configuration FileYou might need to change a parameter, such as the server IP or the merchant ID. If you have hard-coded these values in your software, then changes will be difficult. The client configuration file allows you to specify the merchant ID and CPM server location in a manner that can be changed without recompiling your client. You can use this method of abstraction, or you can implement your own, depending on your business needs and environment.

The configuration file is only used if needed. If you specify merchants by using the merchant name, then the API will attempt to look up the merchant ID in the configuration file. If you specify merchants directly by merchant ID, then the API will not attempt to consult the configuration file. You will also need to set the connection parameters—server IP, server port, encryption type—directly as well.

For best performance for most work, code your programs to use merchant IDs and explicitly set the connections. However, if you choose to use this route, take steps to avoid hard-coding the data to keep your programs more maintainable.



Configuration File LocationYou can create your own configuration file or use the default configuration file, lcc_client.cf, which was called lcc.cf in early versions of CPM. The default location for the configuration file is the working directory.

C Win API

The function LCC_SetConfigFile is used to specify the path and filename of the configuration file. If you do not use this function, then the API looks at the path and filename specified by the environment variable LCC_CLIENT_CONF. If the environment variable is not defined, then the API looks for the merchant information in the Windows Registry. If the information is not specified in the Registry, the API looks for the default configuration file in the working directory. The API returns an error if it cannot locate the merchant information using any of these methods.

C Solaris API

The function LCC_SetConfigFile is used to specify the path and filename of the configuration file. If you do not use this function, then the API looks at the path and filename specified by the environment variable LCC_CLIENT_CONF. If the environment variable is not defined, then the API looks for the merchant information in the working directory. The API returns an error if it cannot locate the merchant information using any of these methods.

Configuration File Format

The format of the file is much like an .ini file. The sections are denoted by brackets ([]), and information underneath those sections are simple key=value pairs.

The client configuration file stores the Merchant Identifier, Server Address, Server Port, and encryption scheme underneath each merchant name section.

[Merchant Name]

MerchantID=Merchant Id




Example

[Demonstration Store]

MerchantId=demo


Server Port=1530

Encryption=1



User SecurityCPM provides facilities to perform name/password validation on transactions submitted to the server. On the server side, you enable validation by defining CPM users and setting the “Require Username and Password” switch. See Server Properties.

On the client side, you obtain the username and password from the user of your client application and then open a “session” by passing the username and password to the CPM server using special transaction types designated for that purpose.

In some applications the username and password represent another computer application and not an end user. In those cases, create a special user on the server for this purpose, and code that name and password into your client application in a configurable fashion.

Environment Set Up

C SolarisMake sure you set the following environment settings. Please refer to your compiler documentation for more information.

• Include the lcc.h file

• Link to the liblcc.a, liblcc.solaris.so and libssl.a file

C Win32 dllMake sure you set the following environment settings. Please refer to your compiler documentation for more information.

• Include the lcc.h file

• Link to the lcc.lib file

Function DetailThis section describes the C API class and functions.

int LCC_Startup()

The function initializes the CPM API. You must call this function before performing any other API calls.



Inputs

Outputs

int LCC_Shutdown()

This function clears resources allocated with LCC_Startup.

Inputs

Outputs

int LCC_SetConfigFile(const char *sConfigFileName)

This function sets the path and name of the merchant configuration file. The configuration file is used to look up merchant and server information based on an input merchant name. See Merchant Information on page 227 for information.

Inputs

Outputs

long LCC_OpenConnection(const char *sServerAddress, int nPort, int nEncryp-tion)

This function establishes a persistent connection to the CPM Server that allows the transmission of multiple transactions over one connection. This function will decrease processing time especially if you are using SSL encryption. The typical order of function calls is the following. All error processing has been omitted for clarity:

• hConnection=LCC_OpenConnection(sServerIP, iPort, iEncryption)

• hTransaction=LCC_OpenTransaction()

None

(int) 0 if successful; otherwise an identifier corresponding to an error

None

(int) 0 if successful; an identifier corresponding to an error otherwise

(char *) full path to the API configuration file




• LCC_SetConnectionHandle(hTransaction_hConnection)

Note The parameters to this function overrides any server settings specified for themerchant in the configuration file or registry. Do not use the configuration file orregistry to define merchant information.

Note Keep the connection open for a sequence of transactions, but not perma-nently. The longer you design the connection to be open the more you will have topay attention to server actions which may break the connection, such as an admin-istrator taking the server out of service momentarily for maintenance.

Inputs

Outputs

int LCC_CloseConnection(long hConnectionHandle)

This function closes a connection to the CPM Server that was opened with the OpenConnection function.

Inputs

Outputs

int LCC_SetConnectionInformation(long hTransaction, const char *sServerAd-dress, int nPort, int nEncryption)

This function sets the connection information for the specified transaction at run time. This function overrides the settings in the configuration file. See Merchant Information on page 227 for more information.

(const char *) network address of the connection socket; for example, 10.2.3.88

(int) port of the CPM Server application; typically 1530

(int) type of encryption; 0 is for non-SSL (default), 1 is for SSL

(long) connection handle if successful (>=0); an identifier corresponding to an error otherwise (<0)

(long) connection handle of an existing connection




Inputs

Outputs

int LCC_SetConnectionHandle(long hTransaction, long hConnection)

This function is used to bind a connection handle to a transaction. See long LCC_OpenConnection(const char *sServerAddress, int nPort, int nEncryption) on page 230. As a programmer, you have a choice to either open connections explicitly and then bind them to the transaction, or let LCC_RunTransaction open and close a connection for you.

Inputs

Outputs

long LCC_OpenTransaction()

This function creates a transaction object and returns a unique transaction handle.

Note If LCC_OpenTransaction returns a handle, then you should free that handleusing LCC_CloseTransaction. Otherwise you will see memory leaks.

Inputs

(long) the handle of the transaction

(const char *) network address of the connection socket

(int) port of the CPM Server application

(int) type of encryption; 0 is the default, 1 is for SSL



(long) the connection handle


None



Outputs

int LCC_CloseTransaction(long hTransaction)

This function closes the handle corresponding to the specified transaction.

Inputs

Outputs

long LCC_RunTransaction(long hTransaction, long nTransactionId)

This function sends a transaction to the CPM Server for execution.

Note Use LCC_OpenTransaction to create the transaction handle.

Use LCC_SetValue to set the transaction fields.

Inputs

Outputs

int LCC_SetSessionId(long hTransaction, long nSessionId)

This function sets the session ID for a transaction. You must use this function when the CPM Server is configured to use security. See User Security on page 229 and Sample Code on page 238 for more information.

(long) a unique handle assigned to the new transaction if >=0, an identity corresponding to an error if <0.



(long) the handle of the transaction to be run

(long) the identifier for the transaction type. See Table 92, “CPM API Transaction Type Identifiers,” on page 167 for more information.

(long) 0 if successful; an identifier corresponding to an error otherwise



Inputs

Outputs

int LCC_GetSessionId(long hTransaction, long* val)

This function is used to get the session handle returned from the previous BeginSession transaction. The session ID is used when the CPM Server is configured to use security. See User Security on page 229 and Sample Code on page 238 for more information.

Inputs

Outputs

int LCC_SetValue(long hTransaction, long nFieldId, const char* sValue)

This function sets the value of a field for a transaction.

Inputs

Outputs

int LCC_GetValue(long hTransaction, long nFieldId, char* pValue, int cbValue)

This function retrieves a field's value for a transaction.


(long) the session ID



(long*) the session ID


(long) handle corresponding to the transaction

(long) identifier of the field to set

(const char *) the value to set the field to




Inputs

Outputs

const char *LCC_GetValuePtr(long hTransaction, long nFieldId)

This function retrieves a pointer value to a field’s value for a transaction.

Inputs

Outputs

int LCC_GetValueLength(long hTransaction, long nFieldId)

This function returns the length of a field's value for a transaction.

Inputs

Outputs


(long) identifier of the field to get

(char *) buffer that the value will be copied to

(int) length of the buffer



(long) identifier of the field to get

(const char *) a pointer to the value if successful; an identifier corresponding to an error otherwise


(long) identifier of the field length to get

(int) the length of the field's value; an identifier corresponding to an error otherwise



int LCC_ClearValues(long hTransaction)

This function removes all the values associated with an open transaction. It is legitimate to reuse a transaction object to run multiple transaction as in the following:

OpenTransaction() //create the transaction object

SetValue(...) //set the fields (multiple SetValue calls)

RunTransaction(...) //run the first transaction

ClearValues(...) //erase all of the values

SetValues(...) //set the fields for the second transaction

RunTransactions(...)

CloseTransaction(...) //destroy the transaction object

However, this will not result in any appreciable efficiency gains. Operational efficiency comes from establishing a persistent connection to CPM. See long LCC_OpenConnection(const char *sServerAddress, int nPort, int nEncryption) on page 230. In the example above, each RunTransaction call will create and destroy its own temporary connections.

Inputs

Outputs

int LCC_DumpValues(long hTransaction)

This function dumps all the values associated with the specified transaction into lcc_test.txt and is useful for debugging purposes.

Note The output file will contain all values, including credit cards. Do not use thisfunction in production.

Inputs






Outputs

int LCC_PrintValues(long hTransaction)

This function operates the same as DumpValues, but sends output directly to STDOUT.

Inputs

Outputs

(int) 1 if successful; 0 or ERR_OPEN_DEBUG_FILE if unsuccessful


(int) 1 if successful; 0 if unsuccessful



Sample Code /** lcc_demo.c** This program demonstrates the features of the LCC C API. It contains* two examples. The first example shows the basics of the API. The second* example shows how to set up a fully-featured connection to the CPM server.** Assumptions:* 1) CPM Server - The server needs to be configured with a gateway that* can accept MasterCard transactions* 2) Merchant - A merchant needs to be defined for that gateway. The merchant* ID needs to match that defined below.* 3) User - A user needs to be defined who can perform authorizations and* captures for the merchant.** Usage:* lcc_demo [optional switches]

* -axx.xx.xx.xx - specified an IP address for the CPM server* default is “localhost”* -ssl - turns on the ssl test* -mmerchantid - merchant id to use for transactions* default is “demo”* -uusername - user id to use for transaction session* -ppassword - user password** Program Outputs* This program prints to stdout** Copyright (c) 2002, CyberSource Corporation*/

/* CPM Server Settings*/#define MY_SERVER_IP “localhost”#define MY_PORT 1530

/* Merchant Settings This setting needs to refer to a merchant defined on the CPM server.*/#define MY_MERCHANT_ID “demo”

/* Security Settings USERNAME/PASSWORD needs to point to a user defined in the CPM server ‘Security’ tab. This user needs to have permissions to run AUTHS and CAPTURES on the above-defined merchant.*/#define MY_USERNAME “charley”#define MY_PASSWORD “demo”

/* Necessary header files and function declarations. */#include “lcc.h”#include “stdio.h”#include <string.h>#include <stdlib.h>



void SimpleAuthDemo(char *sMerchantID, char *sServerIP, int fUseSSL);void SessionDemo(char *sMerchantID, char *sServerIP, int fUseSSL,

char *sUserName, char *sPassword);

int main (int argc, char* argv[]){

char *sMerchantID = MY_MERCHANT_ID;char *sServerIP = MY_SERVER_IP;char *sUserName = MY_USERNAME;char *sPassword = MY_PASSWORD;int fUseSSL = 0;

/* Parse the command line arguments. The code recognizes the set of switches listed in the program header comments. The check against ‘\0’ is to validate that the user passed in at least something.*/

while (--argc) {if (argv[argc][0] == ‘-’ && argv[argc][2] != ‘\0’) {

switch (argv[argc][1]) {case ‘m’:

sMerchantID = &argv[argc][2];break;

case ‘a’:sServerIP = &argv[argc][2];break;

case ‘s’:fUseSSL = 1;break;

case ‘u’:sUserName = &argv[argc][2];break;

case ‘p’:sPassword = &argv[argc][2];break;

default:printf(“Invalid switch %c - ignored\n”, argv[argc][1]);break;

}}else {

printf(“Usage: lcc_demo -ssl -a10.2.3.84 -mdemo\n”);return 0;

}}

printf(“Testing against CPM server at %s using merchant %s\n”, sServerIP, sMerchantID);

/* This function performs a single auth*/SimpleAuthDemo(sMerchantID, sServerIP, fUseSSL);

/* This function demonstrates the usage of the persistent connection for efficiency. It also establishes a user session to authenticate the client that is logging into the CPM server.



*/SessionDemo(sMerchantID, sServerIP, fUseSSL, sUserName, sPassword);

printf(“\nTest completed\n”);return 0;

}

/** SimpleAuthDemo - Demonstrates a credit card authorization using a config* file and a minimum number of the CPM API. This test will fail if the server* is set up to require username/password. Toggle that server feature in* the server properties dialog to see the effect.* * Inputs:* sMerchantID - merchant ID to use* sServerIP - IP address of the CPM server* fUseSSL - 1 - use SSL encryption* 0 - use default encryption** Outputs:* Prints all function and transaction responses to stdout*/

void SimpleAuthDemo(char *sMerchantID, char *sServerIP, int fUseSSL){

int nRet;/* function return value */long hTransaction;/* transaction handle or error value */

/* Initialize the CPM API */printf(“\nSimple Auth Demo\n”);nRet = LCC_Startup();printf(“The return value for LCC_Startup is: %i\n”,nRet);if (nRet != 0) {

return;}

/* LCC_OpenTransaction opens a unique transaction handle. A negative number indicates an error.*/hTransaction = LCC_OpenTransaction();printf(“The return handle for LCC_OpenTransaction is: %ld\n”,hTransaction);

if (hTransaction >= 0) {

/* There are three ways to set the connection settings: from the registry, from a file, or directly from program arguments. These examples use the ‘direct’ approach. Each approach has its value however. Consult the API documentation for more information.

*/nRet = LCC_SetConnectionInformation(hTransaction, sServerIP,MY_PORT, fUseSSL); printf(“The return value for LCC_SetConnectionInfo is: %ld\n”,nRet);

/* Set the field values for a simple $1.00 authorization. Note, the function LCC_SetValue can return ERR_NOT_INITIALIZED or ERR_INVALID_

HANDLE but typically the return values can safely be ignored.



*/LCC_SetValue(hTransaction,ID_MERCHANT_ID,sMerchantID);LCC_SetValue(hTransaction,ID_ACCOUNT_NUMBER,”5454545454545454”);LCC_SetValue(hTransaction,ID_EXPIRATION_DATE,”1212”);LCC_SetValue(hTransaction,ID_CARD_TYPE,”002”);LCC_SetValue(hTransaction,ID_AMOUNT,”100”);

/* LCC_RunTransaction sends a transaction to the CPM server for execution.

*/nRet = LCC_RunTransaction(hTransaction,ID_AUTHORIZATION);printf(“The return value for LCC_RunTransaction is: %ld\n”,nRet);

/* LCC_PrintValues prints the values for a transaction. This is useful for debugging and demonstration. See also LCC_

DumpValues(). In your production application you will use the LCC_GetValue family of functions to retrieve results.

*/LCC_PrintValues(hTransaction);

/* Cleanup. */nRet = LCC_CloseTransaction(hTransaction);printf(“The return value for LCC_CloseTransaction is: %i\n”,nRet);

}nRet = LCC_Shutdown();printf(“The return value for LCC_Shutdown is: %i\n”,nRet);

return;}

/** SessionDemo - Demonstrates a credit card authorization and follow-on* bill using an efficient, persistent, CPM connection. Also demonstrates the

* use of the BeginSession and EndSession functions

* * Inputs:* sMerchantID - merchant ID to use* sServerIP - IP address of the CPM server* fUseSSL - 1 - use SSL encryption* 0 - use default encryption* sUserName - username to use for security* sPassword - password to use for security.** Outputs:* Prints transaction responses to stdout. For brevity, function responses *

are included only if they are non-zero.*/

#define SEQNUMLEN 16void SessionDemo(char *sMerchantID, char *sServerIP, int fUseSSL,

char *sUserName, char *sPassword){

int nRet;/* function return value */long hTransaction;/* transaction handle or error value */long hConnection;



long hSession;char sSeqNum[SEQNUMLEN];

/* Initialize the CPM API. If this call succeeds then you need to make sure to call LCC_Shutdown later.*/printf(“\nSecure Demo\n”);nRet = LCC_Startup();if (nRet != 0) {

printf(“The return value for LCC_Startup is: %i\n”,nRet);return;

}

/* Establish a persistent connection to a CPM server. This is a three step process of: Open the connection

Open the transaction Bind the connection and transaction A persistent connection is especially critical when using SSL. The SSL handshake happens at the connection level. You will have to do the extra coding to keep the connection around, including handling errors that may occur if the connection is lost, the benefit is that you will only see a small decrease in performance (<10%) for SSL instead of an vary large (>200%) decrease if you create the SSL connection for each transaction.*/

hConnection = LCC_OpenConnection(sServerIP,MY_PORT,fUseSSL);if (hConnection < 0) {

printf(“The return handle for LCC_OpenConnection is: %ld\n”, hConnection);

}else {

hTransaction = LCC_OpenTransaction();if (hTransaction < 0) {

printf(“The return handle for LCC_OpenTransaction is: %ld\n”,hTransaction);

}else{

nRet = LCC_SetConnectionHandle(hTransaction,hConnection);if (nRet != 0) {

printf(“The return handle for LCC_SetConnectionHandle is: %ld\n”,hTransaction);

}

/* First Transaction - Begin Session Begin a secure session, e.g., log into the server. This is

through the OpenTransaction API using a special transactiontype which returns a persistent session id.

*/printf(“\nBegin Session Transaction\n”);

LCC_SetValue(hTransaction,ID_MERCHANT_ID,sMerchantID);LCC_SetValue(hTransaction,ID_USERNAME,sUserName);LCC_SetValue(hTransaction,ID_PASSWORD,sPassword);nRet = LCC_RunTransaction(hTransaction,ID_BEGIN_SESSION);



if (nRet != 0) {printf(“The return value for LCC_RunTransaction is: %d\n”,nRet);

}nRet = LCC_GetSessionId(hTransaction, &hSession);if (nRet != 0) {

printf(“The return value for LCC_GetSessionID is: %d\n”,nRet);}printf(“Session Id=%ld\n”, hSession);LCC_PrintValues(hTransaction);

/* Second Transaction - Authorization. Now that we have established our session, run a sample

transaction. Note 1: The SetSession API call is used to bind the session to

this transaction. Note 2: Since we are using a persistent connection and only one transaction object, we need to clear the values from the

previous transaction before reusing the object. Note 3: These three API calls will return errors only if the API

is not initialized. Thus the error returns are ignored since that error would have been caught earlier.

*/printf(“\nAuth Transaction\n”);

LCC_ClearValues(hTransaction);LCC_SetSessionId(hTransaction, hSession);LCC_SetValue(hTransaction,ID_MERCHANT_ID,sMerchantID);LCC_SetValue(hTransaction,ID_ACCOUNT_NUMBER,”5454545454545454”);LCC_SetValue(hTransaction,ID_EXPIRATION_DATE,”1212”);LCC_SetValue(hTransaction,ID_CARD_TYPE,”002”);LCC_SetValue(hTransaction,ID_AMOUNT,”100”);

/* Run the authorization and get the returned sequence number for use in the follow-on capture. It’s very important to check the error return where you’re using a persistent connection.

*/nRet = LCC_RunTransaction(hTransaction,ID_AUTHORIZATION);if (nRet != 0) {

printf(“The return handle for LCC_RunTransaction is: %ld\n”,nRet);

}LCC_PrintValues(hTransaction);

nRet = LCC_GetValue(hTransaction,ID_SEQUENCE_NUMBER,sSeqNum,SEQNUMLEN);

if (nRet != 0) {printf(“The return value for LCC_GetValue is: %d\n”,nRet);

}

/* Third Transaction - Follow-on capture. This transaction uses the sequence number from the auth.*/printf(“\nCapture Transaction\n”);

LCC_ClearValues(hTransaction);LCC_SetSessionId(hTransaction, hSession);



LCC_SetValue(hTransaction,ID_MERCHANT_ID,sMerchantID);LCC_SetValue(hTransaction,ID_SEQUENCE_NUMBER,sSeqNum);

nRet = LCC_RunTransaction(hTransaction,ID_CAPTURE);if (nRet != 0) {

printf(“The return value for LCC_RunTransaction is: %d\n”,nRet);

}LCC_PrintValues(hTransaction);

/* Fourth Transaction - End Session End the secure session, again, with a special transaction type.*/printf(“\nEnd Session Transaction\n”);

LCC_ClearValues(hTransaction);LCC_SetSessionId(hTransaction, hSession);LCC_SetValue(hTransaction,ID_MERCHANT_ID,sMerchantID);nRet = LCC_RunTransaction(hTransaction,ID_END_SESSION);if (nRet != 0) {

printf(“The return value for LCC_RunTransaction is: %d\n”,nRet);

}LCC_PrintValues(hTransaction);LCC_CloseTransaction(hTransaction);

}

/* Connection and API Cleanup. Call CloseCOnnection if OpenConnection succeeded. Call Shutdown if Startup succeeded.*/nRet = LCC_CloseConnection(hConnection);if (nRet != 0) {

printf(“The return value for LCC_CloseConnection is: %i\n”,nRet);}

}nRet = LCC_Shutdown();if (nRet != 0) {

printf(“The return value for LCC_Shutdown is: %i\n”,nRet);}

return;}


Chapter 7 Environment and Implementation Java (API)

Java (API)The Java API consists of a transaction interface and a class. The transaction interface, lcc.japi.LCC, contains the constants for the transaction type identifiers, field identifiers, and error identifiers. See Chapter 5, CPM API Identifiers, on page 167 and Chapter 6, CPM Error Identifiers, on page 179 for more information on the transaction type identifiers, field identifiers, and error identifiers. The class lcc.japi.LCCTransaction contains a set of methods that allows the developer to create, execute, and examine transactions.

Merchant InformationThe Java API uses a configuration file to specify merchant information.

You can create your own configuration file or use the default configuration file, lcc_client.cf, which was previously called lcc.cf in early versions of CPM. The default location for the configuration file is the working directory.

The function SetConfigFile is used to specify the path and filename of the configuration file. If you do not use this function, then the API looks for the default configuration file in the working directory. The API returns an error if it cannot locate the merchant information using either of these methods.

Configuration File FormatThe format of the file is much like an .ini file. The sections are denoted by brackets ([]), and information underneath those sections are simple key=value pairs.

The client configuration file stores the Merchant Identifier, Server Address, Server Port, and encryption scheme underneath each merchant name section.

[Merchant Name]

MerchantId=Merchant Id




Example 1[Demonstration Store]

MerchantId=demo


Server Port=1530



Encryption=0

Example 2[Demonstration Store]

MerchantId=demo


Server Port=1531

Encryption=1

Server Port and IP AddressThe Java API allows you to set merchant name, merchant ID, merchant server port, IP address, and encryption method using SetValue and SetConnectionInformation.

For example, to set the demonstration store without SSL encryption, enter the following commands:

obj.SetValue(LCC.ID_MERCHANT_ID, "demo");

obj.SetConnectionInformation("123.45.67.89", 1530, 0);

To set the demonstration store with SSL encryption, enter the following commands.

obj.SetValue(LCC.ID_MERCHANT_ID, "demo");

obj.SetConnectionInformation("123.45.67.89", 1531, 1);

Note You can change the port settings to meet the requirements of your systemenvironment.

Environment SettingsMake sure you set the following environment settings. Please refer to your compiler documentation for more information.

• Import lcc.japi.* in the source code

• Include a reference to the lcc.jar file in the CLASSPATH environment variable:

On Windows systems, this .jar file is in the Client APIs\Java API subdirectory of the path that CPM was installed to. This subdirectory is typically C:\Program Files\CyberSource\PaymentManager\Client APIs\Java API.

For example:

CLASSPATH=C:\Program Files\CyberSource\PaymentManager\Client APIs\Java API\lcc.jar



On Solaris systems, this .jar file is found in the Client_APIs/Java_API subdirectory of the path that CPM was installed to. This subdirectory is typically /opt/cybersource/payment_manager50/Client_APIs/Java_API.

For example:

CLASSPATH=/opt/cybersource/payment_manager50/Client_APIs/Java_API/lcc.jar

Security Policy FilesThe CPM Java SDK that is available with CPM 5.5.5 and later is built on Java 1.4.2. To use this version or later of the Java SDK, you must update the security policy files that Java uses.

For All Java SDK Users: Updating the Security Policy FilesIf you are using the new Java SDK either with or without SSL, you must update the security policy files that Java uses in order to accommodate strong encryption. This is because the SDK uses the JCE implementation of the Blowfish encryption algorithm whether or not SSL is used, and the key size that this algorithm uses is larger than the size allowed by the default Java security policy files.

Note The CPM installation CD includes the security policy files used for Java 1.4.2from Sun Microsystems®. Sun posts the latest version of the policy files for down-load on their Web site. If you are using a Java implementation from a supplier otherthan Sun, check with the supplier to make sure you have the appropriate securitypolicy files for strong encryption.

For Windows

For Windows users, if you use the installer to install the SDK, the Install Shield Wizard automatically updates these security policy files for you. If you do not use the installer, you need to update the files manually using the following procedure:

1 Go to the Client APIs\Java API directory on the CPM installation CD and locate the following files:

local_policy.jarUS_export_policy.jar


http://www.sun.com

http://www.sun.com

http://www.sun.com


2 Replace the following existing files in your Java installation with the files from the previous step:

<Java Home Directory>\<jre>\lib\security\local_policy.jar <Java Home Directory>\<jre>\lib\security\US_export_policy.jar

You have updated the security policy files for strong encryption.

For Solaris

For Solaris users, you need to update the files manually using the following procedure:

1 Go to the cybersource/payment_manager/server directory and locate the following files:

local_policy.jarUS_export_policy.jar

2 Replace the following existing files in your Java installation with the files from the previous step:

$(JAVA_HOME)/lib/security/local_policy.jar $(JAVA_HOME)/lib/security/US_export_policy.jar

You have updated the security policy files for strong encryption.

For Users of Previous Versions of the Java SDKThe previous versions of the CPM Java SDK used EccpressoAll.jar and SSLPlus.jar. The new Java SDK does not use these files; if you switch to use the new Java SDK you can remove references to those .jar files from your classpath.

Method DetailsThis section describes the methods of the Java class LCCTransaction.

LCCTransaction()

This is the constructor.

Inputs

void SetSessionId(int nSessionID)

This method sets the session ID for a transaction. You must use this method when the CPM Server is configured to use security.

None



Inputs

Outputs

int OpenConnection(String sServerAddress, int nPort, int nEncryption)

This method establishes a persistent connection to the CPM Server that allows the transmission of multiple transactions over one connection. This method may decrease processing time especially if you are using SSL encryption.

Inputs

Output

int SetConnectionInformation(String sServerAddress, int nPort, int nEncryp-tion)

This method sets the connection information for the specified transaction at run time. This method overrides the settings in the configuration file.

Inputs

Outputs

(int) the session ID

None











int GetSessionId()

This method retrieves the session ID for a transaction. The session ID is used when the CPM Server is configured to use security.

Inputs

Outputs

void SetValue(int nFieldId, String sValue)

This method sets the value of a field for a transaction.

Inputs

Outputs

String GetValue(int nFieldId)

This method retrieves a field's value for a transaction.

Inputs

Outputs

int GetValueLength(int nFieldId)

This method returns the length of a field's value for a transaction.

None

(int) the session ID

(int) identifier of the field to set

(String) the value to set the field to

None

(int) identifier of the field of the value to return

(String) field value



Inputs

Outputs

void ClearValues()

This method clears the values for a transaction. The session identifier is not reset.

Inputs

Outputs

int RunTransaction(int nTransactionTypeId)

This method executes a transaction. Use GetValue to retrieve the returned fields.

Inputs

Outputs

void SetConfigFile(String sConfigFileName)

This method sets the path and filename of the merchant configuration file. The configuration file is used to look up merchant and server information based on an input merchant name. See Merchant Information on page 245 for more information.

Inputs

(int) identifier of the field length to get

(int) the length of the field's value; an identifier corresponding to an error otherwise

None

None

(int) transaction type identifier; for example, LCC.ID_AUTHORIZATION

(int) 0 if successful; otherwise an identifier corresponding to an error

(String) path to the merchant configuration file



Outputs

void CloseConnection()

This method closes a connection to the CPM Server that was opened with the OpenConnection method.

Inputs

Output

void DumpFields

This method dumps all the values associated with the specified transaction into lcc_test.txt.

Inputs

Outputs

void PrintFields()

This method prints all the field/value pairs set by SetValue or by the CPM Server after a RunTransaction.

Inputs

Outputs

None

None

None

None

None

None

None



Sample CodeNote The sample code below was compiled using Sun's JDK 1.3 compiler andjsse1.0.1 add-on. Setting the CLASSPATH is accomplished by the compile.cmdnow. The compile.cmd and run.cmd files used to compile and run this samplecode are included on the CPM CD.

/** LCCExample.java** This program demonstrates the features of the LCC Java API. It contains* two examples. The first example shows the basics of the API. The second* example shows how to set up a fully-featured connection to the CPM server.** Assumptions:* 1) CPM Server - The server needs to be configured with a gateway that* can accept MasterCard transactions.* 2) Merchant - A merchant needs to be defined for that gateway. The * merchant ID needs to match that defined below.* 3) User - A user needs to be defined who can perform authorizations and* captures for the merchant.** Usage:* java lcc_demo [optional switches]

* -axx.xx.xx.xx - specified an IP address for the CPM server* default is "localhost"* -ssl - turns on the ssl test* -mmerchantid - merchant id to use for transactions* default is "demo"* -uusername - user id to use for transaction session* -ppassword - user password** Program Outputs* This program prints to stdout** Copyright (c) 2002, CyberSource Corporation*/

import java.text.MessageFormat;

// Import the CyberSource JAVA LCC Packageimport lcc.japi.*;

public class LCCExample{ // Default CPM Server Settings static final String MY_SERVER_IP = "127.0.0.1"; static final int MY_REGULAR_PORT = 1530;



static final int MY_SSL_PORT = 1531;

// Default Merchant Setting // This setting needs to refer to a merchant defined on the CPM server. static final String MY_MERCHANT_ID = "demo";

// Default Security Settings // The username needs to point to a user defined in the CPM Server // 'Security' tab. This user needs to have permissions to run AUTHs and

// CAPTUREs on the above-defined merchant. static final String MY_USERNAME = "demo"; static final String MY_PASSWORD = "demo";

// Default SSL Setting static final int USE_SSL = 0;

// initialize settings with their default values static String merchantID = MY_MERCHANT_ID; static String serverIP = MY_SERVER_IP; static int serverPort = MY_REGULAR_PORT; static String userName = MY_USERNAME; static String password = MY_PASSWORD; static int useSSL = USE_SSL;

public static void main( String[] args ) { // Parse the command line arguments. The code recognizes the set of // switches listed in the program header comments. for (int i = 0; i < args.length; ++i) { if (args[i].charAt(0) == '-' && args[i].length() > 2) { switch (args[i].charAt(1)) { case 'm': merchantID = args[i].substring( 2 ); break; case 'a': serverIP = args[i].substring( 2 ); break; case 's': useSSL = 1; serverPort = MY_SSL_PORT; break; case 'u': userName = args[i].substring( 2 );; break; case 'p': password = args[i].substring( 2 ); break; default: System.out.println( MessageFormat.format(



"Invalid switch {0} ignored", new Object[] { new Character( args[i].charAt(1) ) } ) ); } } else { System.out.println( "Sample Usage: java lcc_demo -ssl -a10.2.3.84 -mdemo\n" ); return; } }

System.out.println( MessageFormat.format( "Testing against CPM server at {0} using merchant {1}", new Object[] { serverIP, merchantID } ) );

// This method performs a single auth simpleAuthDemo();

// This method demonstrates the usage of the persistent connection for // efficiency. It also establishes a user session to authenticate the // client that is logging into the CPM server. sessionDemo(); }

/* * SimpleAuthDemo - Demonstrates a credit card authorization using a * config file and a minumum number of the CPM API. This test will fail if * the server is set up to require username/password. Toggle that server * feature in the server properties dialog to see the effect. * * Uses the following data members: * serverIP - IP address of the CPM server * serverPort - port number to connect to * useSSL - 1 - use SSL encryption * 0 - use default encryption * merchantID - merchant ID to use * * Outputs: * Prints all function and transaction responses to stdout */ static void simpleAuthDemo() { int ret;

// Create an LCCTransaction instance LCCTransaction trans = new LCCTransaction();

// There are three ways to set the connection settings: from the // registry, from a file, or directly from program arguments. These // examples use the 'direct' approach. Each approach has its value



// however. Consult the API documentation for more information. ret = trans.SetConnectionInformation( serverIP, serverPort, useSSL ); System.out.println( "The return value for SetConnectionInformation is: " + ret );

// Set the field values for a simple $1.00 authorization. trans.SetValue( LCC.ID_MERCHANT_ID, merchantID ); trans.SetValue( LCC.ID_ACCOUNT_NUMBER, "5454545454545454" ); trans.SetValue( LCC.ID_EXPIRATION_DATE, "1212" ); trans.SetValue( LCC.ID_CARD_TYPE, "002" ); trans.SetValue( LCC.ID_AMOUNT, "100" );

// RunTransaction sends a transaction to the CPM server for execution. ret = trans.RunTransaction( LCC.ID_AUTHORIZATION ); System.out.println( "The return value for RunTransaction is: " + ret );

// PrintFields prints the values for a transaction. This is useful for // debugging and demonstration. In your production application, you // will use GetValue to retrieve results. trans.PrintFields(); }

/* * sessionDemo - Demonstrates a credit card authorization and follow-on * bill using an efficient, persistent, CPM connection. Also demonstrates * the use of the BeginSession and EndSession functions. * * Uses the following data members: * serverIP - IP address of the CPM server * serverPort - port number to connect to * sUseSSL - 1 - use SSL encryption * 0 - use default encryption * merchantID - merchant ID to use * userName - username to use for security * password - password to use for security * * Outputs: * Prints transaction responses to stdout. For brevity, function * responses are included only if they are non-zero. */ static void sessionDemo() { int ret, sessionID; String seqNum;

// Create an LCCTransaction instance LCCTransaction trans = new LCCTransaction();

/* Establish a persistent connection to a CPM server by calling OpenConnection.

A persistent connection is especially critical when using SSL. The



SSL handshake happens at the connection level. You will have to do the extra coding to keep the connection around, including handling errors that may occur if the connection is lost. The benefit is that you will only see a small decrease in performance (<10%) for SSL instead of anvary large (>200%) decrease if you create the SSL

connection for each transaction. */ ret = trans.OpenConnection( serverIP, serverPort, useSSL ); if (ret != 0) { System.out.println( "The return value for OpenConnection is: " + ret ); return; }

/* First Transaction - Begin Session Begin a secure session, e.g., log into the server. This is through the RunTransaction API using a special transaction type which returns a persistent session id. */ System.out.println( "\nBegin Session Transaction" );

trans.SetValue( LCC.ID_MERCHANT_ID, merchantID ); trans.SetValue( LCC.ID_USERNAME, userName ); trans.SetValue( LCC.ID_PASSWORD, password );

ret = trans.RunTransaction( LCC.ID_BEGIN_SESSION ); if (ret != 0) { System.out.println( "The return value for RunTransaction is " + ret ); } sessionID = trans.GetSessionId(); System.out.println( "Session ID = " + sessionID ); trans.PrintFields();

/* Second Transaction - Authorization. Now that we have established our session, run a sample transaction. Note 1: The SetSessionId API call is used to bind the session to this transaction. Note 2: Since we are using a persistent connection and only one transaction object, we need to clear the values from the previous transaction before reusing the object. */ System.out.println( "\nAuth Transaction" );

trans.ClearValues(); trans.SetSessionId( sessionID ); trans.SetValue( LCC.ID_MERCHANT_ID, merchantID ); trans.SetValue( LCC.ID_ACCOUNT_NUMBER, "5454545454545454" ); trans.SetValue( LCC.ID_EXPIRATION_DATE, "1212" ); trans.SetValue( LCC.ID_CARD_TYPE, "002" ); trans.SetValue( LCC.ID_AMOUNT, "100" );



/* Run the authorization and get the returned sequence number for use in the follow-on capture. It's very important to check the error return where you're using a persistent connection. */ ret = trans.RunTransaction( LCC.ID_AUTHORIZATION ); if (ret != 0) { System.out.println( "The return value for RunTransaction is " + ret ); } trans.PrintFields();

seqNum = trans.GetValue( LCC.ID_SEQUENCE_NUMBER );

/* Third Transaction - Follow-on capture. This transaction uses the sequence number from the auth. */ System.out.println("\nCapture Transaction\n");

trans.ClearValues(); trans.SetSessionId( sessionID ); trans.SetValue( LCC.ID_MERCHANT_ID, merchantID ); trans.SetValue( LCC.ID_SEQUENCE_NUMBER, seqNum );

ret = trans.RunTransaction( LCC.ID_CAPTURE ); if (ret != 0) { System.out.println( "The return value for RunTransaction is "

+ ret ); } trans.PrintFields();

/* Fourth Transaction - End Session End the secure session, again, with a special transaction type. */ System.out.println("\nEnd Session Transaction\n");

trans.ClearValues(); trans.SetSessionId( sessionID ); trans.SetValue( LCC.ID_MERCHANT_ID, merchantID );

ret = trans.RunTransaction( LCC.ID_END_SESSION ); if (ret != 0) { System.out.println( "The return value for RunTransaction is "

+ ret ); } trans.PrintFields();

// Connection Cleanup trans.CloseConnection(); }}


Chapter 8

CPM Server Test Mode Emulation

This chapter explains the Test Gateway.

The Test Gateway returns specific Authorization Response Codes, Address Match Codes, and ZIP Match Codes for specific input value ranges.

Restrictions• Do not install two CPM Servers on the same computer.

• Do not use the CPM Server in test mode for load testing or statistics gathering.

Approval Codes

Table 97 Possible Authorization Response Code Return Values

Input Amount Code Description

0 to 100.00 A Approval

100.01 to 200.00 C Call

200.01 to 300.00 D Decline

300.01 to 400.00 P Pick up card

400.01 to 500.00 X Expired card

500.01 to 600.00 E Error

>600.00 Generates random approval responses.


Chapter 8 CPM Server Test Mode Emulation Address Match

Address Match

ZIP MatchThe Customer ZIP is a 9-digit postal code.

Table 98 Possible Address Match Return Values

Customer StreetAddress Match

Description

0 to 100 Y Match

101 to 200 N No match

201 to 300 X The service is unavailable

>300 Generates random address responses.

Table 99 Possible ZIP Match Return Values

Customer ZIP ZIP Match Description

00000-0000 to 10000-1000 Y Match

10000-1001 to 20000-2000 N No match

20000-2001 to 30000-3000 X The service is unavailable

>30000-3001 Generates random postal code responses.


Chapter 9

CPM Server Database Schema

The CyberSource Payment Manager (CPM) Database contains transaction information. As with any database, you should implement security precautions to prevent unauthorized access.

Refer to your database documentation for technical issues relating to the setup and use. The CPM Server uses the Open Database Connectivity (ODBC) standard which converts Structured Query Language (SQL) statements into the proprietary interface of your chosen database. This enables the CPM Server to work with many different databases such as Oracle and Microsoft SQL Server.

Sizing the CPM DatabaseWhen creating your database, CyberSource recommends that you start with a database one gigabyte in size. To estimate how much space you will need, run some typical transactions and measure how much database space the transactions use. Then factor in your expected transaction volume and how long you plan to retain the data.

Maintaining the CPM DatabaseWarning Only perform the Purge feature in CPM Database Utility on an activeCPM database during your lowest period of transaction activity. To purge oldtransaction information that has been reported, set the Aging and Volume param-eters in the Storage tab of the CPM Server properties. You must coordinate yourreporting practices prior to transaction purging.


Chapter 9 CPM Server Database Schema Maintaining the CPM Database

Managing the DatabaseGood database management practices include:

• Employing a database administrator — for establishing and maintaining the database environment for CPM software.

• Sizing the database — anticipate your transaction volume when establishing a CPM database.

• Monitoring database access activity — to develop maintenance schedules, identify peak and low database access times based on your transaction throughput.

• Monitoring database size — to develop record purging schedules, consider the amount of available hard drive space available.

• Scheduling database backups — backup copies of a database reduce the amount of lost data when a database problem occurs.

• Scheduling database purges — removing old records in a database monitors database size. Purging requires many CPU cycles from the database server and should be performed when access activity is low. No more than 10,000 records should be purged at one time.

• Planning for crisis and recovery — planning can reduce the amount of data lost and the time required to get the database back up and running if a hard drive fails, data corrupts, or other crises occur.

CPM RDBMS SupportTable 100 list the relational database management systems (RDBMS) that are supported for CPM:

Table 100 Supported RDBMSs

Operating System RDBMSs

Windows SQL 7

SQL2000

Oracle 8.1.x

Oracle 9i

Oracle DB2 7.x or later

Sybase 11.x

Sybase 12.5


Chapter 9 CPM Server Database Schema CPM Database Tables

Amount Field LengthThe CPM API limits the length of all amount fields to 12 characters.

The lengths of the amount fields in the CPM database are typically longer than the CPM API amount lengths. Do not alter any amount field in the CPM Server database.

CPM Database Tables

Security TablesThe following tables store security information, and are only listed and not further described for proprietary reasons:

• SEC_ALLOWED_MERCH

• SEC_ALLOWED_TX

• SEC_GROUP_MAP

• SEC_GROUPS

• SEC_SESSION

• SEC_USER

Solaris Oracle 8.1.x

Oracle 9i

Sybase 11.x

Sybase 12.5

Table 100 Supported RDBMSs



AGREEMENT TableDescription Associates an Agreement to a Gateway.

UsageInserts a record for every Agreement to Gateway association.

Constraints AGREEMENT_ID (primary key)

AGREEMENT_VALUES TableDescription Stores Agreement information.

Usage Inserts a record for every Agreement.

Constraints

• AGREEMENT_ID (primary key)

• ELEM_NAME (primary key))

Table 101 AGREEMENT Table Fields

FieldData Length and Type

Description

AGREEMENT_ID 32 (varchar) Primary Key. Agreement identifier.

GATEWAY_ID 32 (varchar) Gateway identifier.

Table 102 AGREEMENT_VALUES Table Fields


Description

AGREEMENT_ID 32 (varchar) Primary Key. Agreement identifier.

ELEM_NAME 32 (varchar) Primary Key. Name of Agreement element.

ELEM_VALUE 255 (varchar) Agreement element value.



CC_LINEITEM_DETAIL TableDescription Stores all Purchasing Card Level III data.

UsageInserts one or more rows for every Purchasing Card Level III transaction.

Constraints

• SEQUENCE_NUMBER (primary key)

• LINE_ITEM_NUMBER (primary key)

Table 103 CC_LINE_ITEM_DETAIL Table Fields


Description

SEQUENCE_NUMBER

15 (varchar) Primary Key. Transaction Sequence Number unique to each transaction.

LINE_ITEM_NUMBER

4 (varchar) Primary Key. Count of the line item number.

DESCRIPTION 35 (varchar) Text description of the item purchased.

PRODUCT_CODE 12 (varchar) Product code of the item purchased.

QUANTITY 12 (varchar) Number of units of the item purchased.

UNIT_OF_MEASURE

12 (varchar) Unit of measure of measure code for the item purchased.

TAX_AMOUNT 20 (varchar) Tax amount for item purchased.

TAX_RATE 20 (varchar) Tax rate applied to item purchased.

TOTAL_AMOUNT 20 (varchar) Total amount charged for item purchased.

DISCOUNT_AMOUNT

20 (varchar) Amount of discount applied to this line item.

COMMODITY_CODE

12 (varchar) Commodity code used to classify the item purchased.

UNIT_COST 20 (varchar) Unit cost of the item purchased.

TAX_TYPE_APPLIED

4 (varchar) Type of tax applied to the item purchased.

TAX_APPLIED 1 (varchar) Tax applied.

TAX_EXEMPT 1 (varchar) Tax exempt.

DISCOUNT_INDICATOR

1 (varchar) Indicates if a discount was applied to the item purchased.



CC_SETTLEMENT TableDescription Stores the results of batch settlement.

Usage Inserts a record for every batch, update with current batch status.

Constraints

• MERCHANT_ID (primary key)

• BATCH_ID (primary key)

RETURN_INDICATOR

1 (varchar) Indicates if the item is a return.

Table 103 CC_LINE_ITEM_DETAIL Table Fields (Continued)


Description

Table 104 CC_Settlement Table Fields


Description

SERVER_ID 4 (varchar) CPM Server ID. Used to identify unique CPM Servers when connected to the same database.

MERCHANT_ID 32 (varchar) Primary Key. Merchant for this batch.

BATCH_ID 12 (varchar) Primary Key. Number identifying batch sent for settlement.

LPC_TYPE 4 (varchar) Indicates what Gateway was used to connect to processor.

CURRENCY_CODE 3 (varchar) Indicates the national currency used by the merchant.

SETTLE_DATE_TIME 8 (Date Time) Date and time of batch settlement. The format is MM/DD/YY HHMMSS AM or PM.

BATCH_STATUS 4 (varchar) Current status of batch at any given time.

BATCH_RESPONSE_MSG

30 (varchar) Text message of batch response.

PROCESSOR_BATCH_ID

12 (varchar) Processor assigned batch identifier.



CC_TRANSACTION TableDescription Stores all credit card transaction information.

UsageInserts a record for every credit card transaction that communicates with the processor, updated with every response from the processor for online transactions.

ConstraintsSEQUENCE_NUMBER (primary key)

Indexes

• BATCH_ID

• DRAFT_ID

• SERVER_ID

• MERCHANT_ID

• TRANS_DATE_TIME

SUBMISSION_ID 12 (varchar) Unique number identifying a settlement submission. A submission is a group of related submission batches.

SALES_TRANSACTIONS

9 (numeric) Number of sales in a batch.

SALES_AMOUNT 9 (numeric) Amount of the sale. The format is DDDDDDDCC.

RETURN_TRANSACTIONS

9 (numeric) Number of returns in a batch.

RETURN_AMOUNT 9 (numeric) Amount of returned item. The format is DDDDDDDCC.

Table 104 CC_Settlement Table Fields (Continued)


Description



• ACCOUNT_NUMBER

• ACCOUNT_EXTENSION

Table 105 CC_TRANSACTION Table Fields


Description

TRANSACTION_CODE

3 (varchar) Indicates transaction type with three letter code. Possible values:

• 100: Authorization

• 101: Reversal

• 102: Capture

• 103: Return

• 104: Authorize and Capture

• 106: Void Transaction

SERVER_ID 4 (varchar) Identifier representing the CPM Server that issued the transaction. If multiple CPM Servers use one database, this number must be unique to each Server.

LPC_TYPE 4 (varchar) Type of Gateway used in the transaction.

MERCHANT_ID 32 (varchar) Merchant identifier associated with each transaction.

SEQUENCE_NUMBER

15 (varchar) Primary Key. Transaction Sequence Number unique to each transaction.

PARENT_SEQ_NUMBER

15 (varchar) The Sequence Number of the transaction’s parent. For example, a capture transaction’s Parent Sequence Number is the corresponding authorization transaction’s Sequence Number.

LCC_RETURN_CODE

4 (varchar) Return code from the CPM API.

LCC_RETURN_MSG

40 (varchar) Text Description of the return code from the CPM Server.



TRANSACTION_STATE

1 (varchar) Indicates transaction state. Possible values:

• B: Failed to Settle. The processor found a problem with the transaction. Refer to the BAD_FIELD_CODE and BAD_FIELD_DATA fields and the processor specification to identify the problem.

• C: Captured. The transaction has been captured. Capture, authorize and capture, and return transactions set this state.

• O: Open. The transaction has been sent to the processor and CPM Server received the processor response. Authorization and reversal transactions set this state.

• S: Settled. Reserved for future use.

• V: Void. The transaction has been voided. A void transaction sets this state.

TRANS_DATE_TIME

8 (Date Time) Time the transaction occurred. The format is MM/DD/YY HHMMSS AM or PM.

LOCAL_DATE_TIME

8 (Date Time) Time parameter in the API function, which may be different than current time. For example, a direct marketing capture should contain the date the product shipped. The format is MM/DD/YY HHMMSS AM or PM.

AUTH_RESP_CODE

1 (varchar) Indicates authorization response. Possible values:

• A: Approval

• C: Call

• D: Decline

• E: Error

• P: Pickup card

• X: Expired card

PROC_AUTH_RSP_CODE

4 (varchar) Processor dependent authorization response code.

AUTH_RESPONSE_MSG

20 (varchar) Processor dependent authorization response message.

APPROVAL_CODE

9 (varchar) Processor assigned approval code.

Table 105 CC_TRANSACTION Table Fields (Continued)


Description



CVV_RESPONSE_CODE

4 (varchar) Result of Card Verification Value (CVV) check. This field contain’s the processor’s raw response, which will typically be one of these:

• M: Match

• N: No match

• S: Merchant code was not on the card

• I, U, or P: Unknown/service unavailable

ACCOUNT_NUMBER

28 (varchar) Credit card number used in transaction.

ACCOUNT_EXTENSION

80 (varchar) Encrypted credit card information.

EXPIRATION_DATE

4 Date (MMYY) Month and year when credit card expires.

AUTH_CURRENCY

3 (varchar) Currency code used in authorization transaction.

SETTLE_CURRENCY

3 (varchar) Currency code used in settlement transaction.

CLEAR_CURRENCY

3 (varchar) Currency code used in clear transaction.

AUTH_COUNTRY 3 (varchar) Country code where authorization occurred.

SETTLE_COUNTRY

3 (varchar) Country code where settlement occurred.

CLEAR_COUNTRY

3 (varchar) Country code where clear occurred.



Description



AMOUNT 16 (numeric) Amount for the transaction without tax. The format is DDDDDDDDDDDDCCCC.

For authorization, the amount to authorize.

For returns, the amount to give back.

For captures, the amount to settle.

For reversals, the new amount to be authorized, which must be less than the current authorized amount.

For incrementals, the new amount to be authorized and added to the original authorized amount.

Note Do not use a decimal point in the transaction amount.

ORIGINAL_AMOUNT

16 (numeric) The amount authorized in the first authorization. The format is DDDDDDDDDDDDCCCC.


CURRENT_AMOUNT

16 (numeric) The current amount authorized after any subsequent functions with a transaction. The original authorization's field is updated after any transactions acting on it. The format is DDDDDDDDDDDDCCCC.


CURRENT_TAX_AMOUNT

16 (numeric) The current tax amount authorized after any subsequent function. The format is DDDDDDDDDDDDCCCC.


ORDER_NUMBER 25 (varchar) Order Number assigned by the merchant.


MERCH_BILL_NAME

25 (varchar) Merchant’s Name.

MERCH_BILL_LOC

13 (varchar) Merchant’s Location. Can be by city.



Description



MERCH_BILL_STATE

2 (varchar) Merchant’s location by state.

BATCH_ID 12 (varchar) Identification number given to batch by the CPM Server.

DRAFT_ID 8 (varchar) Identification number given to draft in batch by the CPM Server.

CARD_TYPE 4 (varchar)

Note The API data input size is three characters.

Card type.

CyberSource strongly recommends that you send the card type even if it is optional for your processor. Omitting the card type can cause the transaction to be processed with the wrong card type.

Possible values:

• 000: Other

• 001: Visa

• 002: MasterCard

• 003: American Express

• 004: Discover

• 005: Diners Club

• 006: Carte Blanche

• 007: Japanese Credit Bank

• 008: Optima

• 009: Maestro (Switch/Solo)

• 010: GE Capital

• 011: GECC

• 012: Beneficial

• 013: Citibank Encryption Program

• 022: Liz Claiborne

• 029: Debit—PIN-based or PIN-less

• 030: NYCE

• 031: Pulse

• 032: Star

CUSTOMER_NAME

26 (varchar) Provided for storing additional customer information.



Description



CUSTOMER_PHONE


CUSTOMER_STREET


CUSTOMER_CITY 20 (varchar) Provided for storing additional customer information.

CUSTOMER_STATE


CUSTOMER_COUNTRY


CUSTOMER_ZIP 9 (varchar) Provided for storing additional customer information.

CUSTOMER_EMAIL


CUSTOMER_IP_ADDR


ADDRESS_MATCH

1 (varchar) One letter AVS result indicator. Possible values:

• Y: Match

• N: No match


• R: Invalid AVS response from card issuer or address verification data contain EDIT ERROR.

ZIP_MATCH 1 (varchar) One letter AVS result indicator. Possible values:

• Y: Match

• N: No match


• R: Invalid AVS response from card issuer or address verification data contain EDIT ERROR.

PROC_AVS_RESULT

3 (varchar) AVS result information. Code is processor dependent.



Description



ACCT_DATA_SOURCE

1 (varchar) Account data source. Detail transaction information.

RET_REFERENCE_NUM

12 (varchar) Retrieval reference number.

CARDHOLDER_ID_CODE

1 (varchar) Cardholder ID Code. Embossed on card.

AUTH_SOURCE_CODE

1 (varchar) Authorization source code.

TRANSACTION_ID

15 (varchar) Transaction ID number.

VALIDATION_CODE

4 (varchar) Processor dependent validation code. Refer to processor specifications for reference.

POS_MODE_CODE

2 (varchar) Type of point-of-sale device used initiating transaction. Detail transaction information.

MARKET_SPEC_IND

2 (varchar) Market specific indicator. Detail transaction information.

RETURNED_ACI 1 (varchar) The value of the returned transaction’s Custom Payment Services qualification status.

REQUESTED_ACI 1 (varchar) The value of the requested transaction’s Custom Payment Services qualification status.

RESPONSE_INDICATOR

2 (varchar) Details information about this transaction.

TRANS_ATTRIBUTE

2 (varchar) Whether reversal was sent or not for an authroization. The corresponding API field, ID_TRANS_ATTRIBUTE, accepts only one character field length. Possible values:

• 0: Reversal not sent

• 1: Reversal sent



Description



E_COMMERCE_TYPE

2 (varchar) Electronic commerce flag for Web transactions. Possible values:

• null: Not a Web transaction. At the point of sale, if not a Web transaction, this field should be empty.

• 01: Not secure. Channel encryption was not used between the browser and Web server.

• 02: Secure. Channel encryption was used between the browser and Web server.

• 03: Successful Verified by Visa transaction.

• 04: Verified by Visa transaction was attempted but not authenticated.

• 05: MasterCard SecureCode or Maestro (Switch/Solo) SecureCode transaction.

RECUR_TRANS_NUMBER

2 (varchar) Recurring transaction information.

RECUR_TRANS_COUNT

2 (varchar) Recurring transaction information.

USER_DEFINED_1

50 (varchar) User defined field.

USER_DEFINED_2


USER_DEFINED_3


USER_DEFINED_4


USER_DEFINED_5


USER_SEQUENCE_NUM


USER_SOURCE_NAME


RESERVED_1 50 (varchar) CPM Reserved field. Do not use.

RESERVED_2 50 (varchar) CPM Reserved field. Do not use.



Description



SOURCE_IP_ADDRESS

15 (varchar) Requested transaction source Internet Protocol Address.

TAX_AMOUNT 16 (numeric) Tax amount added to order. The format is DDDDDDDDDDDDCCCC.


P_CARD_ORDER_NUM

16 (varchar) Purchasing card Information.

COM_CARD_TYPE

2 (varchar) Commercial card type. Possible values:

• 00: Not a commercial card

• 01: Purchasing card

• 02: Corporate card

• 03: Business card

• 04: Unknown

FRAUD_REASON_CODE

6 (varchar) Reserved for use by CPM.

FRAUD_SCORE 4 (varchar) Reserved for use by CPM.

FRAUD_RESP_CODE

255 (varchar) Reserved for use by CPM.

SHIP_TO_ADDRESS_1

20 (varchar) The street address to where the product is shipped.

SHIP_TO_ADDRESS_2

20 (varchar) The street address to where the product is shipped.

SHIP_TO_CITY 20 (varchar) The city to where the product is shipped.

SHIP_TO_STATE 2 (varchar) The state to where the product is shipped.

SHIP_TO_PHONE 14 (varchar) The phone number of the location to where the product is shipped.

SHIP_TO_ZIP_CODE

9 (varchar) The postal code of the location to where the product is shipped.

SHIP_FROM_ZIP_CODE

9 (varchar) The postal code of the location from where the product is shipped.

FREIGHT_AMOUNT

20 (varchar) Total freight or shipping and handling charges.



Description



DUTY_AMOUNT 20 (varchar) Total of any import or export duties for the transaction.

LINE_ITEM_COUNT

4 (varchar) The number of line item detail records in this purchase.

DISCOUNT_AMOUNT

20 (varchar) Total amount of the discount applied to the merchant for the transaction.

VAT_TAX_AMOUNT

20 (varchar) VAT or other tax included in the transaction.

VAT_TAX_RATE 20 (varchar) Rate of VAT or other tax.

ALT_TAX_ID 20 (varchar) Tax identifier for the alternate tax included in the transaction.

ALT_TAX_AMOUNT

20 (varchar) Total amount of the alternate tax included in the transaction.

CARD_PRESENT_FLAG

1 (varchar) Whether card is present or not. Possible values:

• 0: Card is not present (call center or IVR)

• 1: Card is present (retail POS)

• 2: Unknown

TERM_CAPABILITY

1 (varchar) POS terminal capability. Possible values:

• 0: Unknown

• 1: Terminal has a magnetic stripe reader and manual entry capabilities

• 2: Magnetic stripe reader

• 3: No magnetic stripe reader

• 4: Contactless chip read capability

• 5: Contactless magnetic stripe read capability

TERMINAL_TYPE 1 (varchar) POS terminal type used in transaction. Possible values:

• 0: Unknown

• 1: Standalone, credit card terminal

• 2: Electronic cash register/POS system

• 3: Unattended device



Description



POS_ENTRY_MODE

1 (varchar) Entry method of credit card information into POS terminal used in transaction. Possible values:

• 0: Unknown



• 3: Credit card number manually keyed in to POS terminal

• 4: Read from contactless M/chip or Visa smart card

• 5: Contactless mobile commerce

• 6: Read from contactless chip magnetic strip

CUST_PRESENT_FLAG

1 (varchar) Indicates if the cardholder is present at the time of the transaction. Possible values:

• 0: Customer present

• 1: Customer not present

• 2: Recurring

• 3: Deferred

• 4: Telephone transaction

• 6: Debt transaction

• 7: Billing installment

BAD_FIELD_CODE

3 (varchar) Failed settlement information. A field contains incorrect data in the transaction.

BAD_FIELD_DATA 30 (varchar) Failed settlement information. Incorrect data in the field of the transaction causing failed settlement.

CARD_START_DATE

4 (varchar) Maestro (Switch/Solo) card starting date. The format is MMYY.

CARD_ISSUE_NUMBER

2 (varchar) Maestro (Switch/Solo) credit card number. Do not include spaces or dashes.

CAVV 40 (varchar) Cardholder Authentication Verification Value.

XID 40 (varchar Transaction ID.



Description



SHIP_TO_COUNTRY

2 (varchar) The country code of the location to where the product is shipped.

POS_DATA_CODE 12 (varchar) Point of Service Data Code. This value is a series of codes that identify terminal capability, security data, and specific conditions at the time of a transaction. The POS data code consists of 12 positions:

• Position 1: Card Input Capability

• Position 2: Cardholder Authentication Capability

• Position 3: Card Capture Capability

• Position 4: Operating Environment

• Position 5: Cardholder Present

• Position 6: Card Present

• Position 7: Card Data Input Mode

• Position 8: Cardmember Authentication Method

• Position 9: Cardmember Authentication Entity

• Position 10: Card Data Output Capability

• Position 11: Terminal Output Capability

• Position 12: PIN Capture Capability

RECUR_ADVICE_CODE

2 (varchar) Recurring payment advice code returned by Paymentech New Hampshire only for recurring MasterCard transactions. Possible values:

• 01: New account information available. Obtain new account information.

• 02: Try again later. Recycle transaction in 72 hours.

• 03: Do not try again. Obtain another type of payment from the customer.

• 21: Recurring payment cancellation.

CARD_LEVEL_RESULT

2 (varchar) Visa card level result. This value indicates the type of Visa card that was used for the transaction.



Description



DB_STATUS TableDescription Stores the total transactions and the oldest transaction in the database.

Usage Counts transactions by unit of measure.

EFT_TRANSACTION TableDescription Stores ACH transaction information.

UsageInsert a record for every ACH transaction function, update with response from the processor. This table is populated for every CPM API ACH function except ACH lookup. In addition to the field in the Electronic fund transfer API writing to this table, other fields from the following CPM API groups write to this table:

• Base group

• Extended information group

• PS2000 group

• Billing information group

• User defined fields group

Constraints SEQUENCE_NUMBER (primary key)

QHP_AMOUNT 16 (numeric) Qualified health benefit amount of the transaction.



Description

Table 106 DB_STATUS Table Fields


Description

TOTAL_TRANSACTIONS

8 (numeric) Records total number of transaction in database.

OLDEST_TRANSACTION

8 (numeric) Records oldest transaction stored in CPM Server database.



Indexes

• BATCH_ID

• DRAFT_ID

• MERCHANT_ID

• BANK_ID

• SERVER_ID

• TRANS_DATE_TIME

• BANK_ACCT_NUM

Table 107 EFT_TRANSACTION Table Fields


Description

SERVER_ID 4 (varchar) The CPM Server ID used in this transaction.

TRANSACTION_CODE

3 (varchar) ACH transaction code

LCC_RETURN_CODE

4 (varchar) CPM API return code.

LCC_RETURN_MSG

40 (varchar) CPM API return message.

BATCH_ID 12 (varchar) Indicates which settlement batch contains this transaction.

DRAFT_ID 8 (varchar) Draft identifier.

MERCHANT_ID 32 (varchar) Merchant identifier used in this transaction.

TRANSACTION_STATE

1 (varchar) Transaction state.

TRANS_DATE_TIME

9 (Date Time) Date and time of transaction.

BANK_ACCT_NUM

17 (varchar) The bank account number in which to credit or debit funds.

BANK_ID 9 (varchar) The transit routing number of the bank holding the target account. This field is also known as the ABA number or RDFI number.



ORDER_NUMBER 25 (varchar) Order number for this transaction.


ACCOUNT_TYPE 1 (varchar) Type of bank account used in this transaction. Check the financial processor specification for the proper variables used for this field. These values are set at the POS.

AMOUNT 16 (numeric) Transaction amount.

VERIFICATION_RESULT

1 (varchar) CPM independent field detailing the result of the verification for this transaction. Possible values:

• A: Verification successful

• D: Verification rejected

APPROVAL_CODE

9 (varchar) Financial processor approval code.

PROC_RSP_CODE

4 (varchar) Financial processor dependent result of the verification.

PROC_RSP_MSG 20 (varchar) Processor response message.

USER_SEQ_NUMBER

40 (varchar) User sequence number.

USER_DEFINED_1


USER_DEFINED_2


USER_DEFINED_3


USER_DEFINED_4


USER_DEFINED_5


SEQUENCE_NUMBER

15 (varchar) Transaction Sequence Number unique to each transaction. Primary key.

Table 107 EFT_TRANSACTION Table Fields (Continued)


Description



GATEWAY TableDescription Stores the Gateway identifier.

UsageInserts a record for each Gateway.

Constraints GATEWAY_ID (primary key)

BAD_FIELD_CODE

3 (varchar) Code from financial processor indicating ACH transaction failed during settlement.

BAD_FIELD_DATA 30 (varchar) Data indicating bad field causing failed settlement.

MERCH_BILL_NAME

25 (varchar) Merchant billing name.

MERCH_BILL_LOC

13 (varchar) Merchant billing location.

CUSTOMER_NAME


BANK_SORT_CODE

10 (varchar) Bank’s sort code; used for direct debits.

BANK_COUNTRY_CODE

2 (varchar) Country code of country where bank is located; used for direct debits.

RIB_CODE 2 (varchar) Bank’s RIB code; used for direct debits in France.

Table 107 EFT_TRANSACTION Table Fields (Continued)


Description

Table 108 GATEWAY Table Fields


Description

GATEWAY_ID 32 (varchar) Primary key. Gateway identifier.



GATEWAY_VALUES TableDescription Stores Gateway information.

UsageInserts a records for each Gateway value.

Constraints

• GATEWAY_ID (primary key)

• SERVER_ID (primary key)

• ELEM_NAME (primary key)

HBC_TRANSACTION TableDescription Stores sub-amount values related to health benefit card transactions.

Usage Inserts a record for every health benefit card transaction.


GATEWAY_VALUES Table Fields


Description

GATEWAY_ID 32 (varchar) Primary key. Gateway identifier.

SERVER_ID 32 (varchar) Primary key. CPM Server identifier.

ELEM_NAME 32 (varchar) Primary key. Gateway element name.

ELEM_VALUE 255 (varchar) Gateway element value.

Table 109 HBC_TRANSACTION Table Fields


Description

SEQUENCE_NUMBER

15 (varchar) Primary key.

RX_AMOUNT 16 (numeric) Prescription drug portion of the QHP amount.

VISION_AMOUNT 16 (numeric) Vision portion of the QHP amount.

CLINIC_OTHER_AMOUNT

16 (numeric) Clinic/Other portion of the QHP amount.



HR_TRANSACTION TableDescription Stores hotel and car rental information.

UsageInserts a records for each hotel or car rental value.


DENTAL_AMOUNT

16 (numeric) Dental portion of the QHP amount.

Table 109 HBC_TRANSACTION Table Fields (Continued)


Description

Table 110 HR_TRANSACTION Table Fields


Description

SEQUENCE_NUMBER

15 (varchar) Transaction Sequence Number unique to each transaction. Primary key.

FOLIO_NUMBER 10 (varchar) Primary key. Hotel folio number.

AGREEMENT_NUMBER

9 (varchar) Primary key. Rental agreement number.

CHECK_IN_DATE 8 (varchar) Primary key. Gateway element name.

CHECK_OUT_DATE

8 (varchar) Gateway element value.

PICK_UP_DATE 8 (varchar) Pickup date.

DROP_OFF_DATE 8 (varchar) Dropoff date.

EXTRA_CHARGES_INDICATOR

8 (varchar) Extra charges indicator.

NO_SHOW_INDICATOR

8 (varchar) No show indicator.

RETURN_CITY 8 (varchar) Return city.

RETURN_STATE 18 (varchar) Return state.

RETURN_LOCATION_ID

10 (varchar) Return location ID.



CHARGE_TYPE 1 (numerical) Type of charge. Possible values:

• 1: Lodging

• 2: Restaurant

• 3: Gift shop/other

STAY_DURATION 2 (varchar) Number of nights cardholder stays at hotel.

ROOM_RATE 5 (varchar) Room rate of last night’s stay. The format is NNN.NN.

PROGRAM_CODE 1 (numerical) Special program code. Possible values:

• 1: Intentionally not used.

• 2: Assured reservation/no show.

• 3: CARDeposit. Cardholder’s account number charged for an advance deposit

• 4: Delayed charge.

• 5: Express Service. Assured reservation made against the cardholder’s account number.

• 6: Assured reservation.

FOOD_AMOUNT 8 (varchar) Total cost of food and food/beverage. The format is NNNNNN.NN.

BEVERAGE_AMOUNT

8 (varchar) Total cost of beverages if broken out separately on charge. The format is NNNNNN.NN.

TIP1_AMOUNT 8 (varchar) Employee tip if on charge. The format is NNNNNN.NN.

TIP2_AMOUNT 8 (varchar) Second employee tip if on charge. The format is NNNNNN.NN.

Table 110 HR_TRANSACTION Table Fields (Continued)


Description



MERCHANT TableDescription Associates the Merchant ID to the display name.

Usage Inserts a record for each Merchant ID.

MERCHANT_AGREEMENT TableDescription Associates the Merchant ID to an Agreement and Agreement type.

UsageInserts a record for each Merchant ID and Agreement type association.

Constraints


• AGREEMENT_TYPE (primary key)

Table 111 MERCHANT Table Fields


Description

MERCHANT_ID 32 (varchar) Primary key. Merchant identifier.

DISPLAY_NAME 64 (varchar) Merchant name.

STATE 3 (varchar) Merchant location state.

Table 112 MERCHANT_AGREEMENT Table Fields


Description


AGREEMENT_TYPE

32 (varchar) Primary key. Agreement type.

AGREEMENT_ID 32 (varchar) Agreement identifier.



MERCHANT_VALUES TableDescription Stores Merchant information.

UsageInserts a record for each merchant element.

Constraints


• ELEM_NAME (primary key)

PLCARD_BENEFICIAL TableDescription Stores transaction information for the Beneficial private label credit card.

UsageInsert a record for every transaction using the Beneficial private label card, update with response from processor.


Table 113 MERCHANT_VALUES Table Fields


Description


ELEM_NAME 32 (varchar) Merchant element name.

ELEM_VALUE 255 (varchar) Merchant element value.

Table 114 PLCARD_BENEFICIAL Table Fields


Description

SEQUENCE_NUMBER

15 (varchar) Primary Key. CPM sequence number associated with a Beneficial private label card transaction

CREDIT_PLAN 5 (varchar) This field’s use is defined by the merchant and Beneficial.

DEPARTMENT_CODE

4 (varchar) This field’s use is defined by the merchant and Beneficial.



PLCARD_GECC TableDescription Stores transaction information for the General Electric Capitol Corporation (GECC) private label credit card.

UsageInsert a record for every transaction using the GECC private label credit card, update with response from processor.


SKU_NUMBER 9 (varchar) The Stock Keeping Unit (SKU) number associated with the transaction based on the merchant’s unique SKU schema.

ITEM_DESCRIPTION

40 (varchar) Description of item associated with the transaction. Defined by merchant.

STORE_NUMBER 5 (varchar) This field’s use is defined by the merchant and Beneficial.

Table 114 PLCARD_BENEFICIAL Table Fields


Description

Table 115 PLCARD_GECC Table Fields


Description

SEQUENCE_NUMBER

15 (varchar) Primary Key. CPM sequence number associated with a GECC private label card transaction.

PROMOTIONAL_PLAN

1 (varchar) This field is defined by GECC.

PROMO_END_DATE

4 (varchar) This field is defined by GECC.

SALE_TYPE 1 (varchar) This field is defined by GECC.

LINE_ITEM_1 4 (varchar) GECC private card line item detail. Defined by GECC.





PX_MESSAGE TableDescription Stores warning/error messages generated.

Usage Inserts one record for every message.





MICROFICHE_SEQ_NUM

8 (varchar Microfiche sequence number associated with the transaction.

PLAN_NUMBER 5 (varchar) This field is defined by GECC.

Table 115 PLCARD_GECC Table Fields


Description

Table 116 PX_MESSAGE Table Fields


Description

SERVER_ID 4 (varchar) CPM Server Identification Number.

DATE_TIME 8 (Date Time) Date and time of message. The format is MM/DD/YY HHMMSS AM or PM.

CODE 5 (varchar) Error Code.

MESSAGE 200 (varchar) Server Message.



SETTLEMENT_LOCK TableDescription Keeps multiple servers from settling the same batch simultaneously.

UsageInserts one row for every merchant being settled and deletes the row upon completion of the settlement for that merchant.

Constraints MERCHANT_ID (primary key)

TAA_RETAIL_TRANSACTION TableDescription Stores the retail Transaction Advice Addendum fields for American Express retail transactions.

UsageInserts a record for each TAA retail transaction.


Table 117 SETTLEMENT_LOCK Table Fields


Description

SERVER_ID 4 (varchar) CPM Server ID. Used to identify unique CPM Servers when connected to the same database.

MERCHANT_ID 32 (varchar) Primary Key. Merchant holding the lock.

BATCH_ID 12 (varchar) Number identifying batch sent for settlement.

LPC_TYPE 4 (varchar) Indicates what Gateway was used to connect to processor.

DATE_TIME 8 (Date Time) The date and time the lock was placed on the merchant. The format is MM/DD/YY HHMMSS AM or PM.

Table 118 TAA_RETAIL_TRANSACTION Table Fields


Description

SEQUENCE_NUMBER

15 (varchar) Primary Key.

DEPT_NAME 40 (varchar) Department name where the transaction took place.



ITEM1_DESCRIPTION

19 (varchar) Description of retail item 1.

ITEM2_DESCRIPTION


ITEM3_DESCRIPTION


ITEM4_DESCRIPTION


ITEM5_DESCRIPTION


ITEM6_DESCRIPTION


ITEM1_QTY 3 (varchar) Quantity purchased of retail item 1.






ITEM1_AMOUNT 12 (varchar) Unit cost of retail item 1.






Table 118 TAA_RETAIL_TRANSACTION Table Fields (Continued)


Description



TAA_TRANSACTION TableDescription Stores Transaction Advice Addendum fields for American Express purchasing cards for the American Express Phoenix and Paymentech New Hampshire gateways.

UsageInserts a record for each TAA transaction.


Table 119 TAA_TRANSACTION Table Fields


Description

SEQUENCE_NUMBER

15 (varchar) Primary Key.

TAA1 40 (varchar) Transaction Advice Addendum field. Used for:

• Paymentech New Hampshire American Express purchasing cards.

• American Express Phoenix Level II purchasing cards and non-Level II cards.

TAA2 40 (varchar) See description for TAA1.



TAA1_QTY 3 (varchar) The quantity purchased for the Transaction Advice Addendum 1 field.




TAA1_AMOUNT 12 (varchar) The unit cost for the Transaction Advice Addendum 1 field.






TID_POOL TableDescription Stores Terminal IDs and Last Record Numbers for use with the NOVA Debit Controller and the NOVA Debit gateway. See the CPM NOVA Debit Controller Administration Guide.

UsageInserts a record for each Terminal ID.

Table 120 TID_POOL Table Fields


Description

MERCHANT_ID 20 (varchar) Identifies the merchant store that the TERMINAL_ID belongs to. It consists of the bank number and the Agreements Settings Terminal ID. This value cannot be NULL.

TERMINAL_ID Integer Last 2 digits of the Terminal ID. This value is combined with the MERCHANT_ID to create a NOVA Terminal ID. This value must be unique and cannot be NULL.

LAST_RECORD_NUMBER

Integer The next Last Record Number for the TERMINAL_ID. This value cannot be NULL.

Note This counter automatically rolls over to zero after it reaches the value of maximum.sequence.number in the tidcontroller.properties file.

STATUS Integer Status of the TERMINAL_ID. Possible values:

• 0: Available,

• 1: In Use.

This value cannot be NULL.

LAST_USED_TIME

Datetime Date-timestamp for the last time the TERMINAL_ID was used.


Chapter 9 CPM Server Database Schema Database Field and CPM API Field Mapping

Database Field and CPM API Field MappingThis section shows how to map CPM database fields to CPM API fields.

CC_TRANSACTION Table

Table 121 CC_TRANSACTION Fields and CPM API Fields Mapping

Database Field CPM API Field

MERCHANT_ID ID_MERCHANT_ID

SEQUENCE_NUMBER ID_SEQUENCE_NUMBER

AUTH_RESP_CODE ID_AUTH_RESPONSE_CODE

PROC_AUTH_RSP_CODE ID_PROCESSOR_AUTH_RESPONSE_CODE

AUTH_RESPONSE_MSG ID_AUTH_RESPONSE_MESSAGE

APPROVAL_CODE ID_APPROVAL_CODE

ACCOUNT_NUMBER ID_ACCOUNT_NUMBER

EXPIRATION_DATE ID_EXPIRATION_DATE

AMOUNT ID_AMOUNT

ORIGINAL_AMOUNT ID_ORIGINAL_AMOUNT

TRANS_DATE_TIME ID_TRANSACTION_DATE

TRANS_DATE_TIME ID_TRANSACTION_TIME

CURRENT_AMOUNT ID_CURRENT_AMOUNT

ORDER_NUMBER ID_ORDER_NUMBER

MERCH_BILL_NAME ID_MERCHANT_BILLING_NAME

MERCH_BIL_LOC ID_MERCHANT_BILLING_LOCATION

MERCH_BILL_STATE ID_MERCHANT_BILLING_STATE

CARD_TYPE ID_CARD_TYPE

CUSTOMER_NAME ID_CUSTOMER_NAME

CUSTOMER_PHONE ID_CUSTOMER_PHONE

CUSTOMER_STREET ID_CUSTOMER_STREET

CUSTOMER_CITY ID_CUSTOMER_CITY



CUSTOMER_STATE ID_CUSTOMER_STATE

CUSTOMER_COUNTRY ID_CUSTOMER_COUNTRY

CUSTOMER_ZIP ID_CUSTOMER_ZIP

CUSTOMER_EMAIL ID_CUSTOMER_EMAIL

CUSTOMER_IP_ADDR ID_CUSTOMER_IP_ADDRESS

ADDRESS_MATCH ID_ADDRESS_MATCH

ZIP_MATCH ID_ZIP_MATCH

PROC_AVS_RESULT ID_PROCESSOR_AVS_RESULT

ACCT_DATA_SOURCE ID_ACCOUNT_DATA_SOURCE

RET_REFERENCE_NUM ID_RETRIEVAL_REFERENCE_NUMBER

CARDHOLDER_ID_CODE ID_CARD_HOLDER_ID

AUTH_SOURCE_CODE ID_AUTHORIZATION_SOURCE_CODE

TRANSACTION_ID ID_TRANSACTION_ID

VALIDATION_CODE ID_VALIDATION_CODE

POS_MODE_CODE ID_POS_MODE_CODE

MARKET_SPEC_IND ID_MARKET_SPECIFIC_INDICATOR

RETURNED_ACI ID_RETURNED_ACI

REQUESTED_ACI ID_REQUESTED_ACI

RESPONSE_INDICATOR ID_RESPONSE_INDICATOR

TRANS_ATTRIBUTE ID_TRANS_ATTRIBUTE

E_COMMERCE_TYPE ID_E_COMMERCE_TYPE

USER_DEFINED_1 ID_USER_DEFINED_1





USER_SEQUENCE_NUM ID_USER_SEQUENCE_NUMBER

USER_SOURCE_NAME ID_USER_SOURCE_NAME

Table 121 CC_TRANSACTION Fields and CPM API Fields Mapping (Continued)




RESERVED_1 ID_RESERVED_1

RESERVED_2 ID_RESERVED_2

TAX_AMOUNT ID_TAX_AMOUNT

P_CARD_ORDER_NUM ID_PURCHASE_CARD_ORDER_NUMBER

COM_CARD_TYPE ID_COMMERCIAL_CARD_TYPE

SHIP_TO_ADDRESS_1 ID_SHIP_TO_ADDRESS_1

SHIP_TO_ADDRESS_2 ID_SHIP_TO_ADDRESS_2

SHIP_TO_CITY ID_SHIP_TO_CITY

SHIP_TO_STATE ID_SHIP_TO_STATE

SHIP_TO_PHONE ID_SHIP_TO_PHONE

SHIP_TO_ZIP_CODE ID_SHIP_TO_ZIP_CODE

SHIP_FROM_ZIP_CODE ID_SHIP_FROM_ZIP_CODE

SHIP_TO_COUNTRY ID_SHIP_TO_COUNTRY

FREIGHT_AMOUNT ID_FREIGHT_AMOUNT

DUTY_AMOUNT ID_DUTY_AMOUNT

LINE_ITEM_COUNT ID_LINE_ITEM_DETAIL_COUNT

DISCOUNT_AMOUNT ID_DISCOUNT_AMOUNT_APPLIED

VAT_TAX_AMOUNT ID_VAT_TAX_AMOUNT

VAT_TAX_RATE ID_VAT_TAX_RATE

ALT_TAX_ID ID_ALTERNATIVE_TAX_ID

ALT_TAX_AMOUNT ID_ALTERNATIVE_TAX_AMOUNT

CARD_PRESENT_FLAG ID_CARD_PRESENT_FLAG

TERM_CAPABILITY ID_TERMINAL_CAPABILITY

TERMINAL_TYPE ID_TERMINAL_TYPE

POS_ENTRY_MODE ID_POS_ENTRY_MODE

CUST_PRESENT_FLAG ID_CUSTOMER_PRESENT_FLAG

RECUR_ADVICE_CODE ID_RECUR_ADVICE_CODE

POS_DATA_CODE ID_POS_DATA_CODE

Table 121 CC_TRANSACTION Fields and CPM API Fields Mapping (Continued)




CC_LINEITEM_DETAIL Table

EFT_TRANSACTION Table

Table 122 CC_LINEITEM_DETAIL Fields and CPM API Fields Mapping



DESCRIPTION ID_ITEM_DESCRIPTION

PRODUCT_CODE ID_ITEM_PRODUCT_CODE

QUANTITY ID_ITEM_QUANTITY

UNIT_OF_MEASURE ID_ITEM_UNIT_OF_MEASURE

TAX_AMOUNT ID_ITEM_TAX_AMOUNT

TOTAL_AMOUNT ID_ITEM_TOTAL_AMOUNT

DISCOUNT_AMOUNT ID_ITEM_DISCOUNT_AMOUNT

COMMODITY_CODE ID_ITEM_COMMODITY_CODE

UNIT_COST ID_ITEM_UNIT_COST

TAX_TYPE_APPLIED ID_ITEM_TAX_TYPE_APPLIED

TAX_APPLIED ID_ITEM_TAX_APPLIED

TAX_EXEMPT ID_ITEM_TAX_EXEMPT

DISCOUNT_INDICATOR ID_ITEM_DISCOUNT_INDICATOR

Table 123 EFT_TRANSACTION Fields and CPM API Fields Mapping


TRANSACTION_CODE ID_TRANSACTION_ID

LCC_RETURN_MSG ID_RETURN_CODE_MESSAGE

TRANS_DATE_TIME ID_TRANSATION_DATE

TRANS_DATE_TIME ID_TRANSACTION_TIME

BANK_ACCT_NUM ID_BANK_ACCOUNT_NUMBER

BANK_ID ID_BANK_ID



PLCARD_BENEFICIAL Table

ACCOUNT_TYPE ID_ACCOUNT_TYPE

VERIFICATION_RESULT ID_VERIFICATION_RESULT

PROC_RSP_CODE ID_PROCESSOR_RESPONSE_CODE

PROC_RSP_MSG ID_PROCESSOR_RESPONSE_MESSAGE

MERCHANT_ID ID_MERCHANT_ID

ORDER_NUMBER ID_ORDR_NUMBER_ID

AMOUNT ID_AMOUNT_ID

APPROVAL_CODE ID_APPROVAL_CODE

USER_SEQ_NUMBER ID_USER_SEQUENCE_NUMBER







MERCH_BILL_NAME ID_MERCHANT_BILLING_NAME

MERCH_BILL_LOC ID_MERCHANT_BILLING_LOCATION

CUSTOMER_NAME ID_CUSTOMER_NAME

Table 123 EFT_TRANSACTION Fields and CPM API Fields Mapping (Continued)


Table 124 PLCARD_BENEFICIAL Fields and CPM API Fields Mapping



CREDIT_PLAN ID_BENEFICIAL_CREDIT_PLAN

DEPARTMENT_CODE ID_BENEFICIAL_DEPARTMENT_CODE

SKU_NUMBER ID_BENEFICIAL_SKU_NUMBER



PLCARD_GECC Table

ITEM_DESCRIPTION ID_BENEFICIAL_ITEM_DESCRIPTION

STORE_NUMBER ID_BENEFICIAL_STORE_NUMBER

Table 124 PLCARD_BENEFICIAL Fields and CPM API Fields Mapping (Continued)


Table 125 PLCARD_GECC Fields and CPM API Fields Mapping



PROMOTION_PLAN ID_GECC_PROMOTIONAL_PLAN

PROMO_END_DATE ID_GECC_PROMOTIONAL_END_DATE

SALE_TYPE ID_GECC_SALE_TYPE

LINE_ITEM_1 ID_GECC_LINE_ITEM_1







MICROFICHE_SEQ_NUM ID_GECC_MICROFICHE_SEQUENCE_NUM

PLAN_NUMBER ID_GECC_PLAN_NUMBER



HR_TRANSACTION Table

Table 126 HR_TRANSACTION Table and CPM API Field Mapping



FOLIO_NUMBER ID_HOTEL_FOLIO_NUMBER

AGREEMENT_NUMBER ID_RENTAL_AGREEMENT_NUMBER

CHECK_IN_DATE ID_CHECK_IN_DATE

CHECK_OUT_DATE ID_CHECK_OUT_DATE

PICK_UP_DATE ID_PICK_UP_DATE

DROP_OFF_DATE ID_DROP_OFF_DATE

EXTRA_CHARGES_INDICATOR ID_EXTRA_CHARGES_INDICATOR

NO_SHOW_INDICATOR ID_NO_SHOW_INDICATOR

RETURN_CITY ID_RETURN_CITY

RETURN_STATE ID_RETURN_STATE

RETURN_LOCATION_ID ID_RETURN_LOCATION_ID

CHARGE_TYPE ID_CHARGE_TYPE

STAY_DURATION ID_DURATION_OF_STAY

ROOM_RATE ID_ROOM_RATE

PROGRAM_CODE ID_SPECIAL_PROGRAM_CODE

FOOD_AMOUNT ID_FOOD_AMOUNT

BEVERAGE_AMOUNT ID_BEVERAGE_AMOUNT

TIP1_AMOUNT ID_TIP_1_AMOUNT

TIP2_AMOUNT ID_TIP_2_AMOUNT



TAA_RETAIL_TRANSACTION Table

Table 127 TAA_RETAIL_TRANSACTION Fields and CPM API Fields Mapping


DEPT_NAME ID_RETAIL_DEPT_NAME

ITEM1_DESCRIPTION ID_RETAIL_ITEM1_DESCRIPTION






ITEM1_QTY ID_RETAIL_ITEM1_QTY






ITEM1_AMOUNT ID_RETAIL_ITEM1_AMOUNT








TAA_TRANSACTION Table

Table 128 TAA_TRANSACTION Fields and CPM API Fields Mapping


TAA1 ID_TAA1

TAA2 ID_TAA2

TAA3 ID_TAA3

TAA4 ID_TAA4

TAA1_QTY ID_TAA1_QTY




TAA1_AMOUNT ID_TAA1_AMOUNT





Index

AAAV+ 33ACH 20ACH Deposit 14, 141ACH Lookup 15, 147ACH Refund 14, 143ACH Verify 14, 139ACH Void 15, 146ActiveX 185address verification (AVS) 32, 39, 163address verification service

automated 33Enhanced 33plus 33standard 32

Admin Command 17, 75, 158American Express 52, 101, 114, 291, 293, 302, 303American Express retail TAA group 54Amex Retail Info 30APIs supported 5, 184Authorization 8, 84authorization response code 163Authorize and Capture 9, 106automated address verification plus 33automated AVS plus 33Automated Clearing House (ACH) 1, 13AVS 32, 39

automated 33Enhanced 33plus 33standard 32

Bbase group 23Batch API 208Begin Session 17, 159billing information group 50

BIN Lookup 12, 31, 138

CC AIX API 226Capture 8, 9, 11, 81, 93cash back amount 63CPM API 1, 229CPM API field identifiers 168CPM API Functions 7CPM reserved group 65CPM Server 28, 61, 82, 192, 208credit card 20, 209Credit card transactions 7CVV group 42

Ddatabase schema 261debit cards

BIN lookup 12PIN-based 63PIN-less 26returns 10reversal 10, 119

direct debits 15, 283dynamic merchant descriptors 50

EEcommerce group 44e-commerce type 44EFT 13electronic fund transfer group 70electronic funds transfer 13End Session 18, 160Enhanced address verification service 33Enhanced AVS 33extended customer information group 38


Index

extended information group 28

FFDMS South Debit 26, 63field identifiers 167files, security policy 247

Iidentifiers 167internet transaction data 48issuing bank 11, 51

Kkey sequence number 63

LLevel III purchasing card group 56Level III purchasing card line item detail group

57Lookup 11, 134

Mmagnetic track group 61Manual Authorization 8, 11, 133MasterCard SecureCode 8, 44merchant descriptors 50

Ppayer authentication 8, 44Paymentech Tampa 63PIN-based debit

BIN Lookup 12processing 63reversing 119

PIN-less debitBIN Lookup 12processing 26reversing 119

Predial 18private label card group 68processor specific response group 67PS/2000 group 37

purchasing card group 51, 52, 101, 114, 291, 293, 302, 303

Rretail 21, 291, 302retail TAA group 54Return 10, 127Reversal 8, 9, 28, 81, 119

SSecureCode 44security 2, 4, 17, 192, 233, 248security group 67security policy files 247Sequence Number 28, 81settlement 9, 17, 75soft descriptors 50standard AVS 32

TTAA 52, 101, 114, 291, 293, 302, 303terminal fee 63terminal setup group 40transaction response code 162

Uuser defined group 61

VVerified by Visa 8, 44Visual Basic (VB) 4Void 10


cybersource payment manager™ 6 - online credit...

Documents