cybersource payment manager™ 6.4...
Post on 20-Aug-2018
236 Views
Preview:
TRANSCRIPT
CyberSource Payment Manager™ 6.4 SP2API Reference Guide
May 2009
CPM API Reference Guide • CyberSource Corporation • May 2009 ii
CyberSource Contact Information
For questions about CyberSource Payment Manager, emailsoftware-support@cybersource.com.
For general information about our company, products, and services, go tohttp://www.cybersource.com.
For sales questions about any CyberSource Service, email sales@cybersource.com 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© 2009 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.
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 • May 2009 iii
Contents
CPM API Transactions ...................................................................................................................7Credit Card and Debit Card Transactions............................................................................7
Authorization ....................................................................................................................8Capture ...............................................................................................................................9Authorize and Capture ....................................................................................................9Reversal ............................................................................................................................10Return ...............................................................................................................................10Void...................................................................................................................................11Manual Authorization....................................................................................................11Lookup..............................................................................................................................12BIN 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 • May 2009 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 • May 2009 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 • May 2009 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 • May 2009 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 • May 2009 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 • May 2009 ix
Documentation Changes and Enhancements
The following table lists changes made in recent releases of this document:
Release Changes
6.4 SP2 • Updated the CPM version to 6.4 SP2.
• Added Account Verification transaction.
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.
6.2.5 • Updated the CPM version to 6.2.5.
• Updated gateway processor name: changed Midwest Payment Systems (MPS) to Fifth
Third Processing Solutions (FTPS).
6.2.4 • Updated the CPM version to 6.2.4.
• 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 • May 2009 x
Changes
6.2.3 • Updated the CPM version to 6.2.3.
• 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.
6.2.1 • Updated the CPM version to 6.2.1.
• 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 • May 2009 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 • May 2009 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.
CPM API Reference Guide • CyberSource Corporation • May 2009 2
Chapter 1 Introduction CPM API Basics
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.
CPM API Reference Guide • CyberSource Corporation • May 2009 3
Chapter 1 Introduction CPM API Basics
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.
CPM API Reference Guide • CyberSource Corporation • May 2009 4
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.
CPM API Reference Guide • CyberSource Corporation • May 2009 5
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
CPM API Reference Guide • CyberSource Corporation • May 2009 6
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
CPM API Reference Guide • CyberSource Corporation • May 2009 7
Chapter 1 Introduction CPM API Transactions
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.
Account Verification. Account Verification transactions are used to verify accounts without financially impacting the cardholder. Address Verification Service and Card Security Value can be verified along with the account number. Successful Account Verification transactions will return an Approved Authorization response.
Transactions are identified by submitting the following:
Transaction type=Authorization
Amount=$0
Customer present flag=2. This flag is valid only for MasterCard and MasterCard Diners transactions on Paymentech NH.
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.
CPM API Reference Guide • CyberSource Corporation • May 2009 8
Chapter 1 Introduction CPM API Transactions
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.
CPM API Reference Guide • CyberSource Corporation • May 2009 9
Chapter 1 Introduction CPM API Transactions
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.
CPM API Reference Guide • CyberSource Corporation • May 2009 10
Chapter 1 Introduction CPM API Transactions
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.
CPM API Reference Guide • CyberSource Corporation • May 2009 11
Chapter 1 Introduction CPM API Transactions
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.
• 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
CPM API Reference Guide • CyberSource Corporation • May 2009 12
Chapter 1 Introduction CPM API Transactions
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.
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.
CPM API Reference Guide • CyberSource Corporation • May 2009 13
Chapter 1 Introduction CPM API Transactions
Table 2 lists the transaction types you use with ACH transactions. The transaction types are described in the sections after the table.
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
Table 2 CPM ACH Transaction Types
Transaction Type Transaction Type ID
ACH Verify 108
ACH Deposit 109
ACH Refund 110
ACH Void 111
ACH Lookup 112
CPM API Reference Guide • CyberSource Corporation • May 2009 14
Chapter 1 Introduction CPM API Transactions
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 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.
CPM API Reference Guide • CyberSource Corporation • May 2009 15
Chapter 1 Introduction CPM API Transactions
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
Transaction Type Transaction Type ID
Validate 113
Deposit 114
Refund 115
Void 116
Lookup 117
CPM API Reference Guide • CyberSource Corporation • May 2009 16
Chapter 1 Introduction CPM API Transactions
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
Transaction Type Transaction Type ID
Admin Command 130
Begin Session 150
End Session 151
CPM API Reference Guide • CyberSource Corporation • May 2009 17
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.
CPM API Reference Guide • CyberSource Corporation • May 2009 18
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.
CPM API Reference Guide • CyberSource Corporation • May 2009 19
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.
CPM API Reference Guide • CyberSource Corporation • May 2009 20
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.
CPM API Reference Guide • CyberSource Corporation • May 2009 21
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
CPM API Reference Guide • CyberSource Corporation • May 2009 22
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
CPM API Reference Guide • CyberSource Corporation • May 2009 23
Chapter 2 CPM API Groups Base Group
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)
FieldNumeric Identifier
Description Length
CPM API Reference Guide • CyberSource Corporation • May 2009 24
Chapter 2 CPM API Groups Base Group
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
Table 5 Base Group Fields (Continued)
FieldNumeric Identifier
Description Length
CPM API Reference Guide • CyberSource Corporation • May 2009 25
Chapter 2 CPM API Groups Base Group
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
Table 5 Base Group Fields (Continued)
FieldNumeric Identifier
Description Length
CPM API Reference Guide • CyberSource Corporation • May 2009 26
Chapter 2 CPM API Groups Base Group
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.
CPM API Reference Guide • CyberSource Corporation • May 2009 27
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
FieldNumeric Identifier
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.
Note Do not include a decimal point in the transaction amount.
12
CPM API Reference Guide • CyberSource Corporation • May 2009 28
Chapter 2 CPM API Groups Extended Information Group
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)
FieldNumeric Identifier
Description Length
CPM API Reference Guide • CyberSource Corporation • May 2009 29
Chapter 2 CPM API Groups Extended Information Group
Current Amount 134 This field contains the amount authorized in the original authorization. Use this field only with Reversal functions. The format is DDDDDDDDDDCC.
Note Do not include a decimal point in the transaction amount.
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.
Note Do not include a decimal point in the transaction amount.
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
Table 6 Extended Information Group Fields (Continued)
FieldNumeric Identifier
Description Length
CPM API Reference Guide • CyberSource Corporation • May 2009 30
Chapter 2 CPM API Groups Extended Information Group
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
Table 6 Extended Information Group Fields (Continued)
FieldNumeric Identifier
Description Length
CPM API Reference Guide • CyberSource Corporation • May 2009 31
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
11-14 Numeric retail item code for item 2 Optional
15-18 Numeric retail item code for item 3 Optional
19-22 Numeric retail item code for item 4 Optional
23-26 Numeric retail item code for item 5 Optional
CPM API Reference Guide • CyberSource Corporation • May 2009 32
Chapter 2 CPM API Groups Address Verification Service Group
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.
CPM API Reference Guide • CyberSource Corporation • May 2009 33
Chapter 2 CPM API Groups Address Verification Service Group
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.
CPM API Reference Guide • CyberSource Corporation • May 2009 34
Chapter 2 CPM API Groups Address Verification Service Group
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
FieldNumeric Identifier
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
CPM API Reference Guide • CyberSource Corporation • May 2009 35
Chapter 2 CPM API Groups Address Verification Service Group
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.
• 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
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)
FieldNumeric Identifier
Description Length
CPM API Reference Guide • CyberSource Corporation • May 2009 36
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)
FieldNumeric Identifier
Description Length
Table 9 PS2000 Group Fields
FieldNumeric Identifier
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
CPM API Reference Guide • CyberSource Corporation • May 2009 37
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
FieldNumeric Identifier
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
CPM API Reference Guide • CyberSource Corporation • May 2009 38
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.
CPM API Reference Guide • CyberSource Corporation • May 2009 39
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
FieldNumeric Identifier
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
CPM API Reference Guide • CyberSource Corporation • May 2009 40
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)
• 2: Read from credit card magnetic track 2 (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)
FieldNumeric Identifier
Description Length
CPM API Reference Guide • CyberSource Corporation • May 2009 41
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
FieldNumeric Identifier
Description Length
CVV 165 The contents of the CVV. 3 (Visa, MasterCard, Discover)
4 (American Express)
CPM API Reference Guide • CyberSource Corporation • May 2009 42
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
FieldNumeric Identifier
Description Length
CPM API Reference Guide • CyberSource Corporation • May 2009 43
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
FieldNumeric Identifier
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
CPM API Reference Guide • CyberSource Corporation • May 2009 44
Chapter 2 CPM API Groups ECommerce Group
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)
FieldNumeric Identifier
Description Length
CPM API Reference Guide • CyberSource Corporation • May 2009 45
Chapter 2 CPM API Groups ECommerce Group
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
Table 13 ECommerce Group Fields (Continued)
FieldNumeric Identifier
Description Length
CPM API Reference Guide • CyberSource Corporation • May 2009 46
Chapter 2 CPM API Groups ECommerce Group
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
Table 13 ECommerce Group Fields (Continued)
FieldNumeric Identifier
Description Length
CPM API Reference Guide • CyberSource Corporation • May 2009 47
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
FieldNumeric Identifier
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
CPM API Reference Guide • CyberSource Corporation • May 2009 48
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)
FieldNumeric Identifier
Description Length
CPM API Reference Guide • CyberSource Corporation • May 2009 49
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
FieldNumeric Identifier
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>
• <7-character merchant name>*<14-character product description>
• <3-character merchant name>*<18-character product description>
25
Merchant Billing State
191 Merchant’s billing state. 2
CPM API Reference Guide • CyberSource Corporation • May 2009 50
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)
FieldNumeric Identifier
Description Length
CPM API Reference Guide • CyberSource Corporation • May 2009 51
Chapter 2 CPM API Groups Purchasing Card Group
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
FieldNumeric Identifier
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.
Note Do not include a decimal point in the transaction amount.
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
Merchant Product SKU
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
CPM API Reference Guide • CyberSource Corporation • May 2009 52
Chapter 2 CPM API Groups Purchasing Card Group
Transaction Advice Addendum 2
901 See description for Transaction Advice Addendum 1 field above.
40
Transaction Advice Addendum 3
902 See description for Transaction Advice Addendum 1 field above.
40
Transaction Advice Addendum 4
903 See description for Transaction Advice Addendum 1 field above.
40
Transaction Advice Addendum Amount 1
904 The unit cost for the Transaction Advice Addendum 1 field.
12
Transaction Advice Addendum Amount 2
905 The unit cost for the Transaction Advice Addendum 2 field.
12
Transaction Advice Addendum Amount 3
906 The unit cost for the Transaction Advice Addendum 3 field.
12
Transaction Advice Addendum Amount 4
907 The unit cost for the Transaction Advice Addendum 4 field.
12
Transaction Advice Addendum Quantity 1
908 The quantity purchased for the Transaction Advice Addendum 1 field.
3
Transaction Advice Addendum Quantity 2
909 The quantity purchased for the Transaction Advice Addendum 2 field.
3
Transaction Advice Addendum Quantity 3
910 The quantity purchased for the Transaction Advice Addendum 3 field.
3
Transaction Advice Addendum Quantity 4
911 The quantity purchased for the Transaction Advice Addendum 4 field.
3
Table 16 Purchasing Card Group Fields (Continued)
FieldNumeric Identifier
Description Length
CPM API Reference Guide • CyberSource Corporation • May 2009 53
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
FieldNumeric Identifier
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
Retail Item 2 Description
914 Description of retail item 2. 19
CPM API Reference Guide • CyberSource Corporation • May 2009 54
Chapter 2 CPM API Groups American Express Retail TAA Group
Retail Item 3 Description
915 Description of retail item 3. 19
Retail Item 4 Description
916 Description of retail item 4. 19
Retail Item 5 Description
917 Description of retail item 5. 19
Retail Item 6 Description
918 Description of retail item 6. 19
Retail Item 1 Amount
919 Unit cost of retail item 1. 12
Retail Item 2 Amount
920 Unit cost of retail item 2. 12
Retail Item 3 Amount
921 Unit cost of retail item 3. 12
Retail Item 4 Amount
922 Unit cost of retail item 4. 12
Retail Item 5 Amount
923 Unit cost of retail item 5. 12
Retail Item 6 Amount
924 Unit cost of retail item 6. 12
Retail Item 1 Quantity
925 Quantity purchased of retail item 1. 3
Retail Item 2 Quantity
926 Quantity purchased of retail item 2. 3
Retail Item 3 Quantity
927 Quantity purchased of retail item 3. 3
Retail Item 4 Quantity
928 Quantity purchased of retail item 4. 3
Retail Item 5 Quantity
929 Quantity purchased of retail item 5. 3
Retail Item 6 Quantity
930 Quantity purchased of retail item 6. 3
Table 17 American Express Retail TAA Group Fields (Continued)
FieldNumeric Identifier
Description Length
CPM API Reference Guide • CyberSource Corporation • May 2009 55
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
FieldNumeric Identifier
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
CPM API Reference Guide • CyberSource Corporation • May 2009 56
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)
FieldNumeric Identifier
Description Length
Table 19 Level III Purchasing Card Line Item Detail Group Fields
FieldNumeric Identifier
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
CPM API Reference Guide • CyberSource Corporation • May 2009 57
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)
FieldNumeric Identifier
Description Length
CPM API Reference Guide • CyberSource Corporation • May 2009 58
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
FieldNumeric Identifier
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
CPM API Reference Guide • CyberSource Corporation • May 2009 59
Chapter 2 CPM API Groups Pre-Paid Card Group
Table 21 Pre-Paidt Card Group Fields
FieldNumeric Identifier
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
CPM API Reference Guide • CyberSource Corporation • May 2009 60
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
FieldNumeric Identifier
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 Defined 2 202 Field usage defined by merchant. 50
User Defined 3 203 Field usage defined by merchant. 50
User Defined 4 204 Field usage defined by merchant. 50
User Defined 5 206 Field usage defined by merchant. 50
User Source Name
296 Field usage defined by merchant. 31
CPM API Reference Guide • CyberSource Corporation • May 2009 61
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
FieldNumeric Identifier
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
CPM API Reference Guide • CyberSource Corporation • May 2009 62
Chapter 2 CPM API Groups Magnetic Track Group
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.
CPM API Reference Guide • CyberSource Corporation • May 2009 63
Chapter 2 CPM API Groups Magnetic Track Group
• 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
CPM API Reference Guide • CyberSource Corporation • May 2009 64
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.
CPM API Reference Guide • CyberSource Corporation • May 2009 65
Chapter 2 CPM API Groups CPM Reserved Group
Table 24 Payment Server Reserved Group Fields
FieldNumeric Identifier
Description Length
Reserved 1 222 Reserved field. Do not use.
Reserved 2 223 Reserved field. Do not use.
CPM API Reference Guide • CyberSource Corporation • May 2009 66
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
FieldNumeric Identifier
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
FieldNumeric Identifier
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
CPM API Reference Guide • CyberSource Corporation • May 2009 67
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
FieldNumeric Identifier
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
Line item 2 604 GECC private card line item detail. Defined by GECC.
4
Line item 3 605 GECC private card line item detail. Defined by GECC.
4
Line item 4 606 GECC private card line item detail. Defined by GECC.
4
Line item 5 607 GECC private card line item detail. Defined by GECC.
4
Line item 6 608 GECC private card line item detail. Defined by GECC.
4
CPM API Reference Guide • CyberSource Corporation • May 2009 68
Chapter 2 CPM API Groups Private Label Card Group
Line item 7 609 GECC private card line item detail. Defined by GECC.
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)
FieldNumeric Identifier
Description Length
CPM API Reference Guide • CyberSource Corporation • May 2009 69
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
CPM API Reference Guide • CyberSource Corporation • May 2009 70
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
CPM API Reference Guide • CyberSource Corporation • May 2009 71
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
FieldNumeric Identifier
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
FieldNumeric Identifier
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
CPM API Reference Guide • CyberSource Corporation • May 2009 72
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)
FieldNumeric Identifier
Description Length
CPM API Reference Guide • CyberSource Corporation • May 2009 73
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)
FieldNumeric Identifier
Description Length
CPM API Reference Guide • CyberSource Corporation • May 2009 74
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
FieldNumeric Identifier
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
CPM API Reference Guide • CyberSource Corporation • May 2009 75
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
FieldNumeric Identifier
Description Length
CPM API Reference Guide • CyberSource Corporation • May 2009 76
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.
CPM API Reference Guide • CyberSource Corporation • May 2009 77
Chapter 2 CPM API Groups API Input Notes
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.
Capture - Copy this amount from the API if present or copy from the parent transaction if the SEQUENCE_NUMBER is provided.
CURRENT_AMOUNT Authorize - The purchase amount plus the tax amount. If this transaction is reversed, update this field from the Reversal Current_Amount field.
Capture - Copy this amount from the API if present or copy from the parent transaction if the SEQUENCE_NUMBER is provided.
TAX_AMOUNT Authorize - The tax amount from the API.
Capture - Copy this amount from the API if present or copy from the parent transaction if the SEQUENCE_NUMBER is provided.
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
CPM API Reference Guide • CyberSource Corporation • May 2009 78
Chapter 2 CPM API Groups API Input Notes
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.
ORIGINAL_AMOUNT Not used.
CURRENT_AMOUNT Not used.
TAX_AMOUNT Not used.
Table 36 Reversal Amount Field Usage
Field Name Usage
CPM API Reference Guide • CyberSource Corporation • May 2009 79
Chapter 2 CPM API Groups API Input Notes
Manual Authorization
Lookup
ACH Verify
Table 39 Manual Authorization Amount Field Usage
Field Name Usage
AMOUNT The purchase amount from the CPM API.
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
AMOUNT The purchase amount from the CPM API.
ORIGINAL_AMOUNT Not used.
CURRENT_AMOUNT Not used.
TAX_AMOUNT Not used.
CPM API Reference Guide • CyberSource Corporation • May 2009 80
Chapter 2 CPM API Groups API Input Notes
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
AMOUNT The purchase amount from the CPM API.
ORIGINAL_AMOUNT Not used.
CURRENT_AMOUNT Not used.
TAX_AMOUNT Not used.
Table 43 ACH Refund Amount Field Usage
Field Name Usage
AMOUNT The purchase amount from the CPM API.
ORIGINAL_AMOUNT Not used.
CURRENT_AMOUNT Not used.
TAX_AMOUNT Not used.
CPM API Reference Guide • CyberSource Corporation • May 2009 81
Chapter 2 CPM API Groups API Input Notes
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.
CPM API Reference Guide • CyberSource Corporation • May 2009 82
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
CPM API Reference Guide • CyberSource Corporation • May 2009 83
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.
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.
CPM API Reference Guide • CyberSource Corporation • May 2009 84
Chapter 3 CPM API Function Requirements Authorization
CVV Optional.
ECommerce Type Required for Web-based transactions.
Market Specific Indicator
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.
Track 2 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
Optional. Required to use Enhanced AVS with the American Express Phoenix gateway.
Customer Phone Optional.
Customer City Optional.
Customer State Optional.
Customer Country Optional.
Customer Hostname
Optional.
Table 44 Authorization Input Requirements (Continued)
Field POS Field Requirement Comments
CPM API Reference Guide • CyberSource Corporation • May 2009 85
Chapter 3 CPM API Function Requirements Authorization
Card Present Flag Optional.
Customer Present Flag
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.
Purchase Card Order Number
Required for purchasing cards only.
Tax Amount Required for purchasing cards only.
Commercial Card Type
Required for purchasing cards only.
Ship To Zip Code Required for purchasing cards. Also required to use AAV+ with the American Express Phoenix gateway.
Merchant Product SKU
Optional.
User Sequence Number
Optional.
Table 44 Authorization Input Requirements (Continued)
Field POS Field Requirement Comments
CPM API Reference Guide • CyberSource Corporation • May 2009 86
Chapter 3 CPM API Function Requirements Authorization
Merchant Billing Name
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.
Merchant Billing State
Optional.
Merchant Billing Location
Optional. See the important note on page 50 if Paymentech New Hampshire is your processor.
User Defined 1 Optional.
User Defined 2 Optional.
User Defined 3 Optional.
User Defined 4 Optional.
User Defined 5 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.
Table 44 Authorization Input Requirements (Continued)
Field POS Field Requirement Comments
CPM API Reference Guide • CyberSource Corporation • May 2009 87
Chapter 3 CPM API Function Requirements Authorization
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.
Discount Amount Applied
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.
Alternative Tax Amount
Required for purchasing card Level III only.
Line Item Detail Count
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 Unit of Measure
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.
Table 44 Authorization Input Requirements (Continued)
Field POS Field Requirement Comments
CPM API Reference Guide • CyberSource Corporation • May 2009 88
Chapter 3 CPM API Function Requirements Authorization
Item Total Amount Required for purchasing card Level III only.
Item Discount Amount
Required for purchasing card Level III only.
Item Commodity Code
Required for purchasing card Level III only.
Item Unit Cost Required for purchasing card Level III only.
Item Discount Indicator
Required for purchasing card Level III only.
Item Tax Type Applied
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.
Item Return Indicator
Required for purchasing card Level III only.
Promotional Plan Required for GECC private label card.
Promotional End Date
Required for GECC private label card.
Sale Type Required for GECC private label card.
Line item 1 Required for GECC private label card.
Line item 2 Required for GECC private label card.
Line item 3 Required for GECC private label card.
Line item 4 Required for GECC private label card.
Line item 5 Required for GECC private label card.
Line item 6 Required for GECC private label card.
Table 44 Authorization Input Requirements (Continued)
Field POS Field Requirement Comments
CPM API Reference Guide • CyberSource Corporation • May 2009 89
Chapter 3 CPM API Function Requirements Authorization
Line item 7 Required for GECC private label card.
Microfiche Sequence Number
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.
Table 44 Authorization Input Requirements (Continued)
Field POS Field Requirement Comments
CPM API Reference Guide • CyberSource Corporation • May 2009 90
Chapter 3 CPM API Function Requirements Authorization
Output
Table 45 Authorization Output Fields
Field Comments
Merchant ID
Account Number
Expiration Date
Amount
Card Type
Sequence Number
Approval Code
Authorization Response Message
Authorization Response Code
Return Code Message
Transaction Identifier
Transaction Date
Transaction Time
Validation Code
Response Indicator
Returned ACI
Requested ACI
POS Mode Code
Market Specific Indicator
Retrieval Reference Number
Account Data Source
Card Holder ID
Authorization Source Code
Address Match
Zip Match
CPM API Reference Guide • CyberSource Corporation • May 2009 91
Chapter 3 CPM API Function Requirements Authorization
Order Number
Card Present Flag
Terminal Capability
Terminal Type
POS Entry Mode
Customer Present Flag
CVV Result
ECommerce Type
Purchase Card Order Number
Tax Amount
Commercial Card Type
Ship To Zip Code
User Sequence Number
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
Processor AVS Result
Processor Authorization Response Code
Address Field
Table 45 Authorization Output Fields (Continued)
Field Comments
CPM API Reference Guide • CyberSource Corporation • May 2009 92
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
Field POS Field Requirement Comments
Merchant ID Required.
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.
Processor AVS Result
Required. This field is filled in if Sequence Number is used.
CPM API Reference Guide • CyberSource Corporation • May 2009 93
Chapter 3 CPM API Function Requirements Capture
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.
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.
Customer Street Optional. See Visa RED Regulations for AVS on page 33.
Customer Zip Optional. See Visa RED Regulations for AVS on page 33.
Customer Name Optional. See Visa RED Regulations for AVS on page 33.
Retrieval Reference Number
Required. This field is filled in if Sequence Number is used.
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)
Field POS Field Requirement Comments
CPM API Reference Guide • CyberSource Corporation • May 2009 94
Chapter 3 CPM API Function Requirements Capture
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.
Market Specific Indicator
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.
Authorization Source Code
Optional. This field is filled in if Sequence Number is used.
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.
CVV Result Required if CVV check was performed. This field is filled in if Sequence Number is used.
Table 46 Capture Input Requirements (Continued)
Field POS Field Requirement Comments
CPM API Reference Guide • CyberSource Corporation • May 2009 95
Chapter 3 CPM API Function Requirements Capture
Card Present Flag Optional. This field is filled in if Sequence Number is used.
Customer 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.
Purchase Card Order Number
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.
Commercial Card Type
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 Sequence Number
Optional. 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 Defined 2 Optional. This field is filled in if Sequence Number is used.
Table 46 Capture Input Requirements (Continued)
Field POS Field Requirement Comments
CPM API Reference Guide • CyberSource Corporation • May 2009 96
Chapter 3 CPM API Function Requirements Capture
User Defined 3 Optional. This field is filled in if Sequence Number is used.
User Defined 4 Optional. This field is filled in if Sequence Number is used.
User Defined 5 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.
Processor Authorization Response Code
Required. This field is filled in if Sequence Number is used.
Merchant Billing 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.
• In the same section, see the description of the Merchant Billing Name for the format requirements.
Merchant Billing State
Optional. This field is filled in if Sequence Number is used.
Merchant Billing Location
Optional. This field is filled in if Sequence Number is used.
See the important note on page 50 if Paymentech New Hampshire is your processor.
Session ID Required if transaction security is enabled.
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 address 1 Optional.
Ship to address 2 Optional.
Ship to city Optional.
Ship to state Optional.
Ship to phone Optional.
Table 46 Capture Input Requirements (Continued)
Field POS Field Requirement Comments
CPM API Reference Guide • CyberSource Corporation • May 2009 97
Chapter 3 CPM API Function Requirements Capture
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 only.
Discount Amount Applied
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.
Alternative Tax Amount
Required for purchasing card Level III only.
Line Item Detail Count
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 Unit of Measure
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.
Table 46 Capture Input Requirements (Continued)
Field POS Field Requirement Comments
CPM API Reference Guide • CyberSource Corporation • May 2009 98
Chapter 3 CPM API Function Requirements Capture
Item Total Amount Required for purchasing card Level III only.
Item Discount Amount
Required for purchasing card Level III only.
Item Commodity Code
Required for purchasing card Level III only.
Item Unit Cost Required for purchasing card Level III only.
Item Discount Indicator
Required for purchasing card Level III only.
Item Tax Type Applied
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.
Item Return Indicator
Required for purchasing card Level III only.
Promotional Plan Required for GECC private label card.
Promotional End Date
Required for GECC private label card.
Sale Type Required for GECC private label card.
Line item 1 Required for GECC private label card.
Line item 2 Required for GECC private label card.
Line item 3 Required for GECC private label card.
Line item 4 Required for GECC private label card.
Line item 5 Required for GECC private label card.
Line item 6 Required for GECC private label card.
Table 46 Capture Input Requirements (Continued)
Field POS Field Requirement Comments
CPM API Reference Guide • CyberSource Corporation • May 2009 99
Chapter 3 CPM API Function Requirements Capture
Line item 7 Required for GECC private label card.
Microfiche Sequence Number
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.
Hotel Folio Number Required for Hotel and car rental only.
Rental Agreement Number
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.
Extra Charges Indicator
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.
Table 46 Capture Input Requirements (Continued)
Field POS Field Requirement Comments
CPM API Reference Guide • CyberSource Corporation • May 2009 100
Chapter 3 CPM API Function Requirements Capture
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.
Special Program Code
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.
Tip 2 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.
Table 46 Capture Input Requirements (Continued)
Field POS Field Requirement Comments
CPM API Reference Guide • CyberSource Corporation • May 2009 101
Chapter 3 CPM API Function Requirements Capture
TAA4 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 Amount 3 See description for TAA Amount 1.
TAA Amount 4 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.
TAA Quantity 3 See description for TAA Quantity 1.
TAA Quantity 4 See description for TAA Quantity 1.
Retail Department Name
Optional for American Express retail transactions.
Retail Item 1 Description
Optional for American Express retail transactions.
Retail Item 2 Description
Optional for American Express retail transactions.
Retail Item 3 Description
Optional for American Express retail transactions.
Retail Item 4 Description
Optional for American Express retail transactions.
Retail Item 5 Description
Optional for American Express retail transactions.
Retail Item 6 Description
Optional for American Express retail transactions.
Retail Item 1 Amount
Optional for American Express retail transactions.
Table 46 Capture Input Requirements (Continued)
Field POS Field Requirement Comments
CPM API Reference Guide • CyberSource Corporation • May 2009 102
Chapter 3 CPM API Function Requirements Capture
Retail Item 2 Amount
Optional for American Express retail transactions.
Retail Item 3 Amount
Optional for American Express retail transactions.
Retail Item 4 Amount
Optional for American Express retail transactions.
Retail Item 5 Amount
Optional for American Express retail transactions.
Retail Item 6 Amount
Optional for American Express retail transactions.
Retail Item 1 Quantity
Optional for American Express retail transactions.
Retail Item 2 Quantity
Optional for American Express retail transactions.
Retail Item 3 Quantity
Optional for American Express retail transactions.
Retail Item 4 Quantity
Optional for American Express retail transactions.
Retail Item 5 Quantity
Optional for American Express retail transactions.
Retail Item 6 Quantity
Optional for American Express retail transactions.
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.
Table 46 Capture Input Requirements (Continued)
Field POS Field Requirement Comments
CPM API Reference Guide • CyberSource Corporation • May 2009 103
Chapter 3 CPM API Function Requirements Capture
Output
Table 47 Capture Output Fields
Field Comments
Merchant ID
Account Number
Expiration Date
Amount
Original Transaction Amount
Card Type
Sequence Number
Approval Code
Authorization Response Code
Authorization Response Message
Return Code Message
Transaction Identifier
Transaction Date
Transaction Time
Response Indicator
Returned ACI
Requested ACI
POS Mode Code
Market Specific Indicator
Retrieval Reference Number
Address Match
Zip Match
Order Number
Card Present Flag
Terminal Capability
CPM API Reference Guide • CyberSource Corporation • May 2009 104
Chapter 3 CPM API Function Requirements Capture
Terminal Type
POS Entry Mode
Customer Present Flag
ECommerce Type
Purchase Card Order Number
Tax Amount
Commercial Card Type
Ship To Zip Code
User Sequence Number
User Defined 1
User Defined 2
User Defined 3
User Defined 4
User Defined 5
User Source Name
Track 1 Data
Track 2 Data
Username If using CPM Security
Password If using CPM Security
Processor AVS Result
Processor Authorization Response Code
Validation Code
Address Field
Zip Code
Hotel Folio Number
Rental Agreement Number
Check In Date
Table 47 Capture Output Fields (Continued)
Field Comments
CPM API Reference Guide • CyberSource Corporation • May 2009 105
Chapter 3 CPM API Function Requirements Authorize and Capture
Authorize and Capture
Input
Check Out Date
Pickup Date
Drop Off Date
Extra Charges Indicator
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
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 for credit cards but not debit cards.
Amount Required. For PIN-based debit transactions, the Amount should include the Cash Back Amount.
CPM API Reference Guide • CyberSource Corporation • May 2009 106
Chapter 3 CPM API Function Requirements Authorize and Capture
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.
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.
CVV Optional.
ECommerce Type Required for Web-based transactions.
Market Specific Indicator
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)
Field POS Field Requirement Comments
CPM API Reference Guide • CyberSource Corporation • May 2009 107
Chapter 3 CPM API Function Requirements Authorize and Capture
Track 1 Data Required for transactions where the card is swiped through a card reader.
Either Account Number and Expiration Date, or Track 1 Data, or Track 2 Data is required.
Track 2 Data Required for transactions where the card is swiped through a card reader.
Required specifically for PIN-based debits. See PIN-based Debit Cards on page 63.
Either Account Number and Expiration Date, or Track 1 Data, or Track 2 Data is required.
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 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
Optional. Required to use Enhanced AVS with the American Express Phoenix gateway.
Customer Phone Optional.
Table 48 Authorize and Capture Input Requirements (Continued)
Field POS Field Requirement Comments
CPM API Reference Guide • CyberSource Corporation • May 2009 108
Chapter 3 CPM API Function Requirements Authorize and Capture
Customer City Optional.
Customer State Optional.
Customer Country Optional.
Customer Hostname
Optional.
Card Present Flag Optional.
Customer Present Flag
Optional.
Terminal Type Optional.
Terminal Capability Optional.
POS Entry Mode Optional.
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.
HTTP Browser Type
Optional.
Purchase Card Order Number
Required for purchasing cards only.
Tax Amount Required for purchasing cards only.
Commercial Card Type
Required for purchasing cards only.
Ship To Zip Code Required for purchasing cards. Also required to use AAV+ with the American Express Phoenix gateway.
Merchant Product SKU
Optional.
Table 48 Authorize and Capture Input Requirements (Continued)
Field POS Field Requirement Comments
CPM API Reference Guide • CyberSource Corporation • May 2009 109
Chapter 3 CPM API Function Requirements Authorize and Capture
Merchant Billing Name
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.
Merchant Billing State
Optional.
Merchant Billing Location
Optional. See the important note on page 50 if Paymentech New Hampshire is your processor.
User Sequence Number
Optional.
User Defined 1 Optional.
User Defined 2 Optional.
User Defined 3 Optional.
User Defined 4 Optional.
User Defined 5 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 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 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.
Table 48 Authorize and Capture Input Requirements (Continued)
Field POS Field Requirement Comments
CPM API Reference Guide • CyberSource Corporation • May 2009 110
Chapter 3 CPM API Function Requirements Authorize and Capture
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.
Discount Amount Applied
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.
Alternative Tax Amount
Required for purchasing card Level III only.
Line Item Detail Count
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 Unit of Measure
Required for purchasing card Level III only.
Item Tax Amount Required for purchasing card Level III only.
Table 48 Authorize and Capture Input Requirements (Continued)
Field POS Field Requirement Comments
CPM API Reference Guide • CyberSource Corporation • May 2009 111
Chapter 3 CPM API Function Requirements Authorize and Capture
Item Tax Rate Required for purchasing card Level III only.
Item Total Amount Required for purchasing card Level III only.
Item Discount Amount
Required for purchasing card Level III only.
Item Commodity Code
Required for purchasing card Level III only.
Item Unit Cost Required for purchasing card Level III only.
Item Discount Indicator
Required for purchasing card Level III only.
Item Tax Type Applied
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.
Item Return Indicator
Required for purchasing card Level III only.
Promotional Plan Required for GECC private label card.
Promotional End Date
Required for GECC private label card.
Sale Type Required for GECC private label card.
Line item 1 Required for GECC private label card.
Line item 2 Required for GECC private label card.
Line item 3 Required for GECC private label card.
Line item 4 Required for GECC private label card.
Line item 5 Required for GECC private label card.
Table 48 Authorize and Capture Input Requirements (Continued)
Field POS Field Requirement Comments
CPM API Reference Guide • CyberSource Corporation • May 2009 112
Chapter 3 CPM API Function Requirements Authorize and Capture
Line item 6 Required for GECC private label card.
Line item 7 Required for GECC private label card.
Microfiche Sequence Number
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.
Hotel Folio Number Required for Hotel and car rental only.
Rental Agreement Number
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.
Extra Charges Indicator
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.
Table 48 Authorize and Capture Input Requirements (Continued)
Field POS Field Requirement Comments
CPM API Reference Guide • CyberSource Corporation • May 2009 113
Chapter 3 CPM API Function Requirements Authorize and Capture
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.
Special Program Code
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.
Tip 2 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.
Table 48 Authorize and Capture Input Requirements (Continued)
Field POS Field Requirement Comments
CPM API Reference Guide • CyberSource Corporation • May 2009 114
Chapter 3 CPM API Function Requirements Authorize and Capture
TAA3 See description for TAA2.
TAA4 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 Amount 3 See description for TAA Amount 1.
TAA Amount 4 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.
TAA Quantity 3 See description for TAA Quantity 1.
TAA Quantity 4 See description for TAA Quantity 1.
Retail Department Name
Optional for American Express retail transactions.
Retail Item 1 Description
Optional for American Express retail transactions.
Retail Item 2 Description
Optional for American Express retail transactions.
Retail Item 3 Description
Optional for American Express retail transactions.
Retail Item 4 Description
Optional for American Express retail transactions.
Retail Item 5 Description
Optional for American Express retail transactions.
Retail Item 6 Description
Optional for American Express retail transactions.
Retail Item 1 Amount
Optional for American Express retail transactions.
Table 48 Authorize and Capture Input Requirements (Continued)
Field POS Field Requirement Comments
CPM API Reference Guide • CyberSource Corporation • May 2009 115
Chapter 3 CPM API Function Requirements Authorize and Capture
Retail Item 2 Amount
Optional for American Express retail transactions.
Retail Item 3 Amount
Optional for American Express retail transactions.
Retail Item 4 Amount
Optional for American Express retail transactions.
Retail Item 5 Amount
Optional for American Express retail transactions.
Retail Item 6 Amount
Optional for American Express retail transactions.
Retail Item 1 Quantity
Optional for American Express retail transactions.
Retail Item 2 Quantity
Optional for American Express retail transactions.
Retail Item 3 Quantity
Optional for American Express retail transactions.
Retail Item 4 Quantity
Optional for American Express retail transactions.
Retail Item 5 Quantity
Optional for American Express retail transactions.
Retail Item 6 Quantity
Optional for American Express retail transactions.
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.
Table 48 Authorize and Capture Input Requirements (Continued)
Field POS Field Requirement Comments
CPM API Reference Guide • CyberSource Corporation • May 2009 116
Chapter 3 CPM API Function Requirements Authorize and Capture
Output
Table 49 Authorize and Capture Output Fields
Field Comments
Merchant ID
Authorization Source Code
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.
Authorization Response Code
Authorization Response Message
Return Code Message
Transaction Identifier
Transaction Date
Transaction Time
Validation Code
Response Indicator
Returned ACI
Requested ACI
POS Mode Code
Market Specific Indicator
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
CPM API Reference Guide • CyberSource Corporation • May 2009 117
Chapter 3 CPM API Function Requirements Authorize and Capture
Card Holder ID
Order Number
Card Present Flag
Terminal Capability
Terminal Type
POS Entry Mode
Customer Present Flag
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
Purchase Card Order Number
Tax Amount
Commercial Card Type
Ship To Zip Code
User Defined 1
User Defined 2
User Defined 3
User Defined 4
User Defined 5
User Sequence Number
User Source Name
Processor AVS Result
Processor Authorization Response Code
Table 49 Authorize and Capture Output Fields (Continued)
Field Comments
CPM API Reference Guide • CyberSource Corporation • May 2009 118
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
Rental Agreement Number
Check In Date
Check Out Date
Pickup Date
Drop Off Date
Extra Charges Indicator
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
CPM API Reference Guide • CyberSource Corporation • May 2009 119
Chapter 3 CPM API Function Requirements Reversal
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
Field POS Field Requirement Comments
Merchant ID Required.
Account Number Required. This field is filled in for a credit card reversal if Sequence Number is used.
Either Account Number and Expiration Date, or Track 1 Data, or Track 2 Data is required.
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.
Either Account Number and Expiration Date, or Track 1 Data, or Track 2 Data is required.
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.
CPM API Reference Guide • CyberSource Corporation • May 2009 120
Chapter 3 CPM API Function Requirements Reversal
Processor AVS Result
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.
Retrieval Reference Number
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.
Either Account Number and Expiration Date, or Track 1 Data, or Track 2 Data is required.
Track 2 Data Required for credit card transactions where the card is swiped through a card reader.
Also required for PIN-based debit transactions.
Either Account Number and Expiration Date, or Track 1 Data, or Track 2 Data is required.
PIN Block Required for PIN-based debit transactions.
Key Sequence Number
Required for PIN-based debit transactions.
Table 50 Reversal Input Requirements (Continued)
Field POS Field Requirement Comments
CPM API Reference Guide • CyberSource Corporation • May 2009 121
Chapter 3 CPM API Function Requirements Reversal
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.
Table 50 Reversal Input Requirements (Continued)
Field POS Field Requirement Comments
CPM API Reference Guide • CyberSource Corporation • May 2009 122
Chapter 3 CPM API Function Requirements Reversal
Market Specific 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.
Account Data Source
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.
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.
Authorization Source 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.
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.
Customer 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.
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.
Table 50 Reversal Input Requirements (Continued)
Field POS Field Requirement Comments
CPM API Reference Guide • CyberSource Corporation • May 2009 123
Chapter 3 CPM API Function Requirements Reversal
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.
Purchase Card Order Number
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.
Commercial Card Type
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.
User Sequence Number
Optional.
User Defined 1 Optional.
User Defined 2 Optional.
User Defined 3 Optional.
User Defined 4 Optional.
User Defined 5 Optional.
User Source Name Optional.
Processor Authorization Response Code
Required for credit cards. This field is filled in for a credit card reversal if Sequence Number is used.
Table 50 Reversal Input Requirements (Continued)
Field POS Field Requirement Comments
CPM API Reference Guide • CyberSource Corporation • May 2009 124
Chapter 3 CPM API Function Requirements Reversal
Output
Session ID Required if transaction security is enabled.
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.
Ship to address 2 Optional.
Ship to city Optional.
Ship to state Optional.
Ship to phone Optional.
Customer IP address
Optional.
Customer email Optional.
Table 50 Reversal Input Requirements (Continued)
Field POS Field Requirement Comments
Table 51 Reversal Output Fields
Field Comments
Merchant ID
Account Number
Expiration Date
Amount
Card Type
Sequence Number
Approval Code
Authorization Response Code
Authorization Response Message
Return Code Message
CPM API Reference Guide • CyberSource Corporation • May 2009 125
Chapter 3 CPM API Function Requirements Reversal
Transaction Identifier
Transaction Date
Transaction Time
Validation Code
Original Transaction Amount
Response Indicator
Returned ACI
Requested ACI
POS Mode Code
Market Specific Indicator
Retrieval Reference Number
Order Number
Card Present Flag
Terminal Capability
Terminal Type
POS Entry Mode
Customer Present Flag
ECommerce Type
Purchase Card Order Number
Tax Amount
Ship To Zip Code
Commercial Card Type
User Sequence Number
User Defined 1
User Defined 2
User Defined 3
User Defined 4
User Defined 5
Table 51 Reversal Output Fields (Continued)
Field Comments
CPM API Reference Guide • CyberSource Corporation • May 2009 126
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
Field POS Field Requirement Comments
Merchant ID Required.
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.
ECommerce Type Required for Web-based transactions.
Market Specific Indicator
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.
CPM API Reference Guide • CyberSource Corporation • May 2009 127
Chapter 3 CPM API Function Requirements Return
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.
Retrieval Reference Number
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.
Card Present Flag Optional.
Customer Present Flag
Optional.
Terminal Type Optional.
Terminal Capability Optional.
POS Entry Mode Optional.
Purchase Card Order Number
Required for purchasing cards only.
Table 52 Return Input Requirements (Continued)
Field POS Field Requirement Comments
CPM API Reference Guide • CyberSource Corporation • May 2009 128
Chapter 3 CPM API Function Requirements Return
Tax Amount Required for purchasing cards only.
Commercial Card Type
Required for purchasing cards only.
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.
Discount Amount Applied
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.
Alternative Tax Amount
Required for purchasing card level III only.
Line Item Detail Count
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.
Table 52 Return Input Requirements (Continued)
Field POS Field Requirement Comments
CPM API Reference Guide • CyberSource Corporation • May 2009 129
Chapter 3 CPM API Function Requirements Return
Item Unit of Measure
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 Discount Amount
Required for purchasing card level III line item detail only.
Item Commodity Code
Required for purchasing card level III line item detail only.
Item Unit Cost Required for purchasing card level III line item detail only.
Item Discount Indicator
Required for purchasing card level III line item detail only.
Item Tax Type Applied
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.
Item Return Indicator
Required for purchasing card level III line item detail only.
Table 52 Return Input Requirements (Continued)
Field POS Field Requirement Comments
CPM API Reference Guide • CyberSource Corporation • May 2009 130
Chapter 3 CPM API Function Requirements Return
Merchant Billing Name
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.
Merchant Billing State
Optional.
Merchant Billing Location
Optional.
User Sequence Number
Optional.
User Defined 1 Optional.
User Defined 2 Optional.
User Defined 3 Optional.
User Defined 4 Optional.
User Defined 5 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 the appropriate language in Chapter 7, Environment and Implementation, on page 184 for more information.
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.
Table 52 Return Input Requirements (Continued)
Field POS Field Requirement Comments
CPM API Reference Guide • CyberSource Corporation • May 2009 131
Chapter 3 CPM API Function Requirements Return
Output
Table 53 Return Output Fields
Field Comments
Merchant ID
Account Number
Expiration Date
Amount
Card Type
Sequence Number
User 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
Username If using CPM Security
Password If using CPM Security
CPM API Reference Guide • CyberSource Corporation • May 2009 132
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
Field POS Field Requirement Comments
Merchant ID Required.
Sequence Number Required.
Session ID Required if transaction security is enabled.
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 55 Void Output Fields
Field Comments
Merchant ID
Sequence Number
Session ID
Return Code Message
CPM API Reference Guide • CyberSource Corporation • May 2009 133
Chapter 3 CPM API Function Requirements Lookup
Input
Output
Lookup
Input
Table 56 Manual Authorization Input Requirements
Field POS Field Requirement Comments
Merchant ID Required.
Sequence Number Required.
Approval Code Required.
Session ID Required if transaction security it enabled.
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 57 Manual Authorization Output Fields
Field Comments
Merchant ID
Sequence Number
Approval Code
Table 58 Lookup Input Requirements
Field POS Field Requirement Comments
Merchant ID Required.
CPM API Reference Guide • CyberSource Corporation • May 2009 134
Chapter 3 CPM API Function Requirements Lookup
Output
Sequence Number Required.
Account Number Optional.
Transaction Identifier
Optional. This field is filled in if Sequence Number is used.
Amount Optional.
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.
Tax Amount Optional.
User Defined 1 Optional.
User Defined 2 Optional.
User Defined 3 Optional.
User Defined 4 Optional.
User Defined 5 Optional.
Retrieval Reference Number
Optional. This field is filled in if Sequence Number is used.
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)
Field POS Field Requirement Comments
Table 59 Lookup Output Fields
Field Comments
Merchant ID
ECommerce Type
CPM API Reference Guide • CyberSource Corporation • May 2009 135
Chapter 3 CPM API Function Requirements Lookup
Account Number
Expiration Date
Amount
Original Transaction Amount
Purchase Card Order Number
Card Type
Tax Amount
Commercial Card Type
Sequence Number
Approval Code
Authorization Response Code
Authorization Response Message
Return Code Message
Transaction Identifier
Transaction Date
Transaction Time
Validation Code
Response Indicator
Returned ACI
Requested ACI
POS Mode Code
Market Specific Indicator
Retrieval Reference Number
Address Match
Zip Match
Order Number
Card Present Flag
Table 59 Lookup Output Fields (Continued)
Field Comments
CPM API Reference Guide • CyberSource Corporation • May 2009 136
Chapter 3 CPM API Function Requirements Lookup
Customer Present Flag
Terminal Capability
Terminal Type
POS Entry Mode
Ship To Zip Code
User Sequence Number
User Defined 1
User Defined 2
User Defined 3
User Defined 4
User Defined 5
User Source Name
Track 1 Data
Track 2 Data
Username If using CPM Security
Password If using CPM Security
Processor Authorization Response Code
Address Field
Zip Code
Table 59 Lookup Output Fields (Continued)
Field Comments
CPM API Reference Guide • CyberSource Corporation • May 2009 137
Chapter 3 CPM API Function Requirements BIN Lookup
BIN Lookup
Input
Output
Table 60 BIN Lookup Input Requirements
Field POS Field Requirement Comments
Merchant ID Required.
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
CPM API Reference Guide • CyberSource Corporation • May 2009 138
Chapter 3 CPM API Function Requirements ACH Verify
ACH Verify
Input
Table 62 ACH Verify Input Requirements
Field POS Field Requirement Comments
Merchant ID Required.
Bank Account Number
Required.
Bank ID Required.
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.
Amount Optional. Set to 0 when sending production transactions.
Account Type Optional.
User Sequence Number
Optional.
User Defined 1 Optional.
User Defined 2 Optional.
User Defined 3 Optional.
User Defined 4 Optional.
User Defined 5 Optional.
Session ID Required if transaction security is enabled.
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.
Customer Name Optional.
CPM API Reference Guide • CyberSource Corporation • May 2009 139
Chapter 3 CPM API Function Requirements ACH Verify
Output
Merchant Billing Name
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.
Merchant Billing Location
Optional.
Table 62 ACH Verify Input Requirements (Continued)
Field POS Field Requirement Comments
Table 63 ACH Verify Output Requirements
Field Comments
Merchant ID
Bank Account Number
Bank ID
Order Number
Amount
Account Type
User Sequence Number
User Defined 1
User Defined 2
User Defined 3
User Defined 4
User Defined 5
Verification Result
Sequence Number
Return Code Message
Transaction Date
CPM API Reference Guide • CyberSource Corporation • May 2009 140
Chapter 3 CPM API Function Requirements ACH Deposit
ACH Deposit
Input
Transaction Time
Approval Code
Processor Response Code
Processor Response Message
Customer Name
Merchant Billing Name
Merchant Billing Location
Table 63 ACH Verify Output Requirements (Continued)
Field Comments
Table 64 ACH Deposit Input Requirements
Field POS Field Requirement Comments
Merchant ID Required.
Bank Account Number
Required.
Bank ID Required.
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.
Amount Required.
Account Type Required.
User Sequence Number
Optional.
CPM API Reference Guide • CyberSource Corporation • May 2009 141
Chapter 3 CPM API Function Requirements ACH Deposit
Output
User Defined 1 Optional.
User Defined 2 Optional.
User Defined 3 Optional.
User Defined 4 Optional.
User Defined 5 Optional.
Customer Name Required.
Sequence Number Optional.
Session ID Required if transaction security is enabled.
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.
Merchant Billing Name
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.
Merchant Billing Location
Optional.
Table 64 ACH Deposit Input Requirements (Continued)
Field POS Field Requirement Comments
Table 65 ACH Deposit Output Requirements
Field Comments
Merchant ID
Bank Account Number
Bank ID
Order Number
Amount
Account Type
CPM API Reference Guide • CyberSource Corporation • May 2009 142
Chapter 3 CPM API Function Requirements ACH Refund
ACH Refund
Input
User Sequence Number
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
Merchant Billing Name
Merchant Billing Location
Table 65 ACH Deposit Output Requirements (Continued)
Field Comments
Table 66 ACH Refund Input Requirements
Field POS Field requirement Comments
Merchant ID Required.
Bank Account Number
Required.
Bank ID Required.
CPM API Reference Guide • CyberSource Corporation • May 2009 143
Chapter 3 CPM API Function Requirements ACH Refund
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.
Amount Required.
Account Type Required.
User Sequence Number
Optional.
User Defined 1 Optional.
User Defined 2 Optional.
User Defined 3 Optional.
User Defined 4 Optional.
User Defined 5 Optional.
Customer Name Required.
Sequence Number Optional.
Session ID Required if transaction security is enabled.
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.
Merchant Billing Name
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.
Merchant Billing Location
Optional.
Table 66 ACH Refund Input Requirements (Continued)
Field POS Field requirement Comments
CPM API Reference Guide • CyberSource Corporation • May 2009 144
Chapter 3 CPM API Function Requirements ACH Refund
Output
Table 67 ACH Refund Output Requirements
Field Comments
Merchant ID
Bank Account Number
Bank ID
Order Number
Amount
Account Type
User Sequence Number
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
Merchant Billing Name
Merchant Billing Location
CPM API Reference Guide • CyberSource Corporation • May 2009 145
Chapter 3 CPM API Function Requirements ACH Void
ACH Void
Input
Output
Table 68 ACH Void Input Requirements
Field POS Field Requirement Comments
Merchant ID Required.
Sequence Number Required.
Session ID Required if transaction security is enabled.
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.
Table 69 ACH Void Output Requirements
Field Comments
Merchant ID
Bank Account Number
Bank ID
Order Number
Amount
Account Type
User Sequence Number
User Defined 1
User Defined 2
User Defined 3
User Defined 4
CPM API Reference Guide • CyberSource Corporation • May 2009 146
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
Merchant Billing Name
Merchant Billing Location
Table 69 ACH Void Output Requirements (Continued)
Field Comments
Table 70 ACH Lookup Input Requirements
Field POS Field Requirement Comments
Merchant ID Required.
Sequence Number Required.
Session ID Required if transaction security is enabled.
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.
CPM API Reference Guide • CyberSource Corporation • May 2009 147
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 Sequence Number
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
Processor Response Code
Processor Response Message
Customer Name
Merchant Billing Name
Merchant Billing Location
CPM API Reference Guide • CyberSource Corporation • May 2009 148
Chapter 3 CPM API Function Requirements Direct Debit Validate
Direct Debit Validate
Input
Table 72 Direct Debit Validate Input Requirements
Field POS Field Requirement Comments
Merchant ID Required.
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.
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.
Amount Required. Set to 0 when sending production transactions.
User Sequence Number
Optional.
User Defined 1 Optional.
User Defined 2 Optional.
User Defined 3 Optional.
User Defined 4 Optional.
User Defined 5 Optional.
CPM API Reference Guide • CyberSource Corporation • May 2009 149
Chapter 3 CPM API Function Requirements Direct Debit Validate
Output
Session ID Required if transaction security is enabled.
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 72 Direct Debit Validate Input Requirements (Continued)
Field POS Field Requirement Comments
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 Sequence Number
User Defined 1
User Defined 2
User Defined 3
User Defined 4
User Defined 5
Sequence Number
Return Code Message
Transaction Date
Transaction Time
CPM API Reference Guide • CyberSource Corporation • May 2009 150
Chapter 3 CPM API Function Requirements Direct Debit Deposit
Direct Debit Deposit
Input
Approval Code
Processor Response Code
Processor Response Message
Table 73 Direct Debit Validate Output Requirements (Continued)
Field Comments
Table 74 Direct Debit Deposit Input Requirements
Field POS Field Requirement Comments
Merchant ID Required.
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 Required.
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.
Amount Required.
CPM API Reference Guide • CyberSource Corporation • May 2009 151
Chapter 3 CPM API Function Requirements Direct Debit Deposit
Output
User Sequence Number
Optional.
User Defined 1 Optional.
User Defined 2 Optional.
User Defined 3 Optional.
User Defined 4 Optional.
User Defined 5 Optional.
Session ID Required if transaction security is enabled.
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 74 Direct Debit Deposit Input Requirements (Continued)
Field POS Field Requirement Comments
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 Sequence Number
User Defined 1
User Defined 2
User Defined 3
CPM API Reference Guide • CyberSource Corporation • May 2009 152
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
Field POS Field Requirement Comments
Merchant ID Required.
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 Required.
CPM API Reference Guide • CyberSource Corporation • May 2009 153
Chapter 3 CPM API Function Requirements Direct Debit Refund
Output
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.
Amount Required.
User Sequence Number
Optional.
User Defined 1 Optional.
User Defined 2 Optional.
User Defined 3 Optional.
User Defined 4 Optional.
User Defined 5 Optional.
Session ID Required if transaction security is enabled.
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 76 Direct Debit Refund Input Requirements (Continued)
Field POS Field Requirement Comments
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
CPM API Reference Guide • CyberSource Corporation • May 2009 154
Chapter 3 CPM API Function Requirements Direct Debit Void
Direct Debit Void
Input
Amount
User Sequence Number
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
Field POS Field Requirement Comments
Merchant ID Required.
Sequence Number Required.
Session ID Required if transaction security is enabled.
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.
CPM API Reference Guide • CyberSource Corporation • May 2009 155
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 Sequence Number
User Defined 1
User Defined 2
User Defined 3
User Defined 4
User Defined 5
Sequence Number
Return Code Message
Transaction Date
Transaction Time
CPM API Reference Guide • CyberSource Corporation • May 2009 156
Chapter 3 CPM API Function Requirements Direct Debit Lookup
Direct Debit Lookup
Input
Output
Table 80 Direct Debit Lookup Input Requirements
Field POS Field Requirement Comments
Merchant ID Required.
Sequence Number Required.
Session ID Required if transaction security is enabled.
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 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 Sequence Number
User Defined 1
User Defined 2
User Defined 3
CPM API Reference Guide • CyberSource Corporation • May 2009 157
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
Processor Response Code
Processor Response Message
Table 81 Direct Debit Lookup Output Requirements (Continued)
Field Comments
Table 82 Admin Command Input Requirements
Field POS Field Requirement Comments
Merchant ID Required. Your merchant ID used to identify yourself within the CPM system. Required for all transaction types.
Admin Command String
Required.
CPM API Reference Guide • CyberSource Corporation • May 2009 158
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)
Field POS Field Requirement Comments
Table 83 Begin Session Input Requirements
Field POS Field Requirement Comments
Merchant ID Required.
Username Required.
Password Required.
CPM API Reference Guide • CyberSource Corporation • May 2009 159
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
Field POS Field Requirement Comments
Merchant ID Required.
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.
CPM API Reference Guide • CyberSource Corporation • May 2009 160
Chapter 3 CPM API Function Requirements End Session
Output
Table 86 End Session Output Fields
Field Comments
Merchant ID
Username
Password
Return Code Message
CPM API Reference Guide • CyberSource Corporation • May 2009 161
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.
CPM API Reference Guide • CyberSource Corporation • May 2009 162
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.
CPM API Reference Guide • CyberSource Corporation • May 2009 163
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
CPM API Reference Guide • CyberSource Corporation • May 2009 164
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.
CPM API Reference Guide • CyberSource Corporation • May 2009 165
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
CPM API Reference Guide • CyberSource Corporation • May 2009 166
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
CPM API Reference Guide • CyberSource Corporation • May 2009 167
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)
Numerical Equivalent
Identifier Transaction
Table 93 CPM API Field Identifiers
Numerical Equivalent
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
CPM API Reference Guide • CyberSource Corporation • May 2009 168
Chapter 5 CPM API Identifiers CPM API Field Identifiers
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
Processor Response Code
115 ID_PROCESSOR_RESPONSE_MESSAGE
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)
Numerical Equivalent
Identifier Field
CPM API Reference Guide • CyberSource Corporation • May 2009 169
Chapter 5 CPM API Identifiers CPM API Field Identifiers
130 ID_RETRIEVAL_REFERENCE_NUMBER
Retrieval Reference Number
131 ID_ACCOUNT_DATA_SOURCE Account Data Source
132 ID_CARD_HOLDER_ID Card Holder ID
133 ID_AUTHORIZATION_SOURCE_CODE
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
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
Table 93 CPM API Field Identifiers (Continued)
Numerical Equivalent
Identifier Field
CPM API Reference Guide • CyberSource Corporation • May 2009 170
Chapter 5 CPM API Identifiers CPM API Field Identifiers
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
Merchant Billing Location
200 ID_USER_SEQUENCE_NUMBER User Sequence Number
201 ID_USER_DEFINED_1 User Defined 1
202 ID_USER_DEFINED_2 User Defined 2
203 ID_USER_DEFINED_3 User Defined 3
204 ID_USER_DEFINED_4 User Defined 4
205 ID_USER_DEFINED_5 User Defined 5
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
Table 93 CPM API Field Identifiers (Continued)
Numerical Equivalent
Identifier Field
CPM API Reference Guide • CyberSource Corporation • May 2009 171
Chapter 5 CPM API Identifiers CPM API Field Identifiers
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
Processor Authorization 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
Table 93 CPM API Field Identifiers (Continued)
Numerical Equivalent
Identifier Field
CPM API Reference Guide • CyberSource Corporation • May 2009 172
Chapter 5 CPM API Identifiers CPM API Field Identifiers
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
Promotional End Date
602 ID_GECC_SALE_TYPE Sale Type
603 ID_GECC_LINE_ITEM_1 Line item 1
604 ID_GECC_LINE_ITEM_2 Line item 2
605 ID_GECC_LINE_ITEM_3 Line item 3
606 ID_GECC_LINE_ITEM_4 Line item 4
607 ID_GECC_LINE_ITEM_5 Line item 5
608 ID_GECC_LINE_ITEM_6 Line item 6
609 ID_GECC_LINE_ITEM_7 Line item 7
610 ID_GECC_MICROFICHE_SEQUENCE_NUM
Microfiche Sequence Number
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.
Table 93 CPM API Field Identifiers (Continued)
Numerical Equivalent
Identifier Field
CPM API Reference Guide • CyberSource Corporation • May 2009 173
Chapter 5 CPM API Identifiers CPM API Field Identifiers
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.
Table 93 CPM API Field Identifiers (Continued)
Numerical Equivalent
Identifier Field
CPM API Reference Guide • CyberSource Corporation • May 2009 174
Chapter 5 CPM API Identifiers CPM API Field Identifiers
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.
902 ID_TAA3 See description for ID_TAA1 above.
903 ID_TAA4 See description for ID_TAA1 above.
904 ID_TAA1_AMOUNT Transaction Advice Addendum Amount 1
905 ID_TAA2_AMOUNT Transaction Advice Addendum Amount 2
906 ID_TAA3_AMOUNT Transaction Advice Addendum Amount 3
907 ID_TAA4_AMOUNT Transaction Advice Addendum Amount 4
908 ID_TAA1_QTY Transaction Advice Addendum Quantity 1
909 ID_TAA2_QTY Transaction Advice Addendum Quantity 2
910 ID_TAA3_QTY Transaction Advice Addendum Quantity 3
911 ID_TAA4_QTY Transaction Advice Addendum Quantity 4
912 ID_RETAIL_DEPT_NAME Retail Department Name
913 ID_RETAIL_ITEM1_DESCRIPTION Retail Item 1 Description
914 ID_RETAIL_ITEM2_DESCRIPTION Retail Item 2 Description
915 ID_RETAIL_ITEM3_DESCRIPTION Retail Item 3 Description
916 ID_RETAIL_ITEM4_DESCRIPTION Retail Item 4 Description
917 ID_RETAIL_ITEM5_DESCRIPTION Retail Item 5 Description
Table 93 CPM API Field Identifiers (Continued)
Numerical Equivalent
Identifier Field
CPM API Reference Guide • CyberSource Corporation • May 2009 175
Chapter 5 CPM API Identifiers CPM API Field Identifiers
918 ID_RETAIL_ITEM6_DESCRIPTION Retail Item 6 Description
919 ID_RETAIL_ITEM1_AMOUNT Retail Item 1 Amount
920 ID_RETAIL_ITEM2_AMOUNT Retail Item 2 Amount
921 ID_RETAIL_ITEM3_AMOUNT Retail Item 3 Amount
922 ID_RETAIL_ITEM4_AMOUNT Retail Item 4 Amount
923 ID_RETAIL_ITEM5_AMOUNT Retail Item 5 Amount
924 ID_RETAIL_ITEM6_AMOUNT Retail Item 6 Amount.
925 ID_RETAIL_ITEM1_QTY Retail Item 1 Quantity.
926 ID_RETAIL_ITEM2_QTY Retail Item 2 Quantity.
927 ID_RETAIL_ITEM3_QTY Retail Item 3 Quantity.
928 ID_RETAIL_ITEM4_QTY Retail Item 4 Quantity.
929 ID_RETAIL_ITEM5_QTY Retail Item 5 Quantity.
930 ID_RETAIL_ITEM6_QTY Retail Item 6 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.
Table 93 CPM API Field Identifiers (Continued)
Numerical Equivalent
Identifier Field
CPM API Reference Guide • CyberSource Corporation • May 2009 176
Chapter 5 CPM API Identifiers CPM API Field Identifiers
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
Table 93 CPM API Field Identifiers (Continued)
Numerical Equivalent
Identifier Field
CPM API Reference Guide • CyberSource Corporation • May 2009 177
Chapter 5 CPM API Identifiers CPM API Field Identifiers
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
Table 93 CPM API Field Identifiers (Continued)
Numerical Equivalent
Identifier Field
CPM API Reference Guide • CyberSource Corporation • May 2009 178
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.
CPM API Reference Guide • CyberSource Corporation • May 2009 179
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
Text message Description
CPM API Reference Guide • CyberSource Corporation • May 2009 180
Chapter 6 CPM Error Identifiers Error Descriptions
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.
Table 94 Error Identifier Descriptions (Continued)
Numerical ID
Text message Description
CPM API Reference Guide • CyberSource Corporation • May 2009 181
Chapter 6 CPM Error Identifiers Error Descriptions
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.
Table 94 Error Identifier Descriptions (Continued)
Numerical ID
Text message Description
CPM API Reference Guide • CyberSource Corporation • May 2009 182
Chapter 6 CPM Error Identifiers Error Descriptions
1019 ERR_INVALID_MERCHANT_STATE_AUTH
Merchant state must be open (OPN) to do transactions.
Table 94 Error Identifier Descriptions (Continued)
Numerical ID
Text message Description
CPM API Reference Guide • CyberSource Corporation • May 2009 183
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.
CPM API Reference Guide • CyberSource Corporation • May 2009 184
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.
CPM API Reference Guide • CyberSource Corporation • May 2009 185
Chapter 7 Environment and Implementation ActiveX
[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.
CPM API Reference Guide • CyberSource Corporation • May 2009 186
Chapter 7 Environment and Implementation ActiveX
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.
CPM API Reference Guide • CyberSource Corporation • May 2009 187
Chapter 7 Environment and Implementation ActiveX
.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
CPM API Reference Guide • CyberSource Corporation • May 2009 188
Chapter 7 Environment and Implementation ActiveX
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
CPM API Reference Guide • CyberSource Corporation • May 2009 189
Chapter 7 Environment and Implementation ActiveX
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
CPM API Reference Guide • CyberSource Corporation • May 2009 190
Chapter 7 Environment and Implementation ActiveX
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)
(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
(Integer) 0 if successful; an identifier corresponding to an error otherwise
(Long) the handle of the transaction
(Integer) 0 if successful; an identifier corresponding to an error otherwise
CPM API Reference Guide • CyberSource Corporation • May 2009 191
Chapter 7 Environment and Implementation ActiveX
.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
(Integer) 0 if successful; an identifier corresponding to an error otherwise
None
(Long) the session ID
(Long) the session ID
(Integer) 0 if successful; an identifier corresponding to an error otherwise
CPM API Reference Guide • CyberSource Corporation • May 2009 192
Chapter 7 Environment and Implementation ActiveX
.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
(Integer) 0 if successful; an identifier corresponding to an error otherwise
(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
CPM API Reference Guide • CyberSource Corporation • May 2009 193
Chapter 7 Environment and Implementation ActiveX
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
CPM API Reference Guide • CyberSource Corporation • May 2009 194
Chapter 7 Environment and Implementation ActiveX
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
CPM API Reference Guide • CyberSource Corporation • May 2009 195
Chapter 7 Environment and Implementation ActiveX
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"
CPM API Reference Guide • CyberSource Corporation • May 2009 196
Chapter 7 Environment and Implementation ActiveX
.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)
CPM API Reference Guide • CyberSource Corporation • May 2009 197
Chapter 7 Environment and Implementation ActiveX
'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
CPM API Reference Guide • CyberSource Corporation • May 2009 198
Chapter 7 Environment and Implementation ActiveX
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
End With 'mobjLCCPayment
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
End With 'mobjLCCPayment
If Not mobjLCCPayment Is Nothing Then Set mobjLCCPayment = Nothing
End Sub
Private Sub cmdCapture_Click()
Dim lngHandle As Long
CPM API Reference Guide • CyberSource Corporation • May 2009 199
Chapter 7 Environment and Implementation ActiveX
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 With 'mobjLCCPayment
If Not mobjLCCPayment Is Nothing Then Set mobjLCCPayment = Nothing
End Sub
Private Sub cmdLookup_Click()
CPM API Reference Guide • CyberSource Corporation • May 2009 200
Chapter 7 Environment and Implementation ActiveX
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.
CPM API Reference Guide • CyberSource Corporation • May 2009 201
Chapter 7 Environment and Implementation ActiveX
.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 With 'mobjLCCPayment
If Not mobjLCCPayment Is Nothing Then Set mobjLCCPayment = Nothing
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
End With 'mobjLCCPayment
CPM API Reference Guide • CyberSource Corporation • May 2009 202
Chapter 7 Environment and Implementation ActiveX
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 With 'mobjLCCPayment
If Not mobjLCCPayment Is Nothing Then Set mobjLCCPayment = Nothing
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)
CPM API Reference Guide • CyberSource Corporation • May 2009 203
Chapter 7 Environment and Implementation ActiveX
txtRetRefNumber.Text = .GetValue(ID_RETRIEVAL_REFERENCE_NUMBER) End IfEnd With 'mobjLCCPayment
If Not mobjLCCPayment Is Nothing Then Set mobjLCCPayment = Nothing
End Sub
Private Sub cmdACHVerify_Click()
Dim lngHandle As Long Set mobjLCCPayment = New LCCPayment
'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 With 'mobjLCCPayment
If Not mobjLCCPayment Is Nothing Then Set mobjLCCPayment = Nothing
End Sub
Private Sub cmdACHDeposit_Click() Dim lngHandle As Long Set mobjLCCPayment = New LCCPayment '
CPM API Reference Guide • CyberSource Corporation • May 2009 204
Chapter 7 Environment and Implementation ActiveX
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 With 'mobjLCCPayment
If Not mobjLCCPayment Is Nothing Then Set mobjLCCPayment = Nothing
End Sub
Private Sub cmdACHLookup_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_SEQUENCE_NUMBER, txtSequence.Text mstResult = .RunTransaction(ID_ACH_LOOKUP) txtReturnCodeMsg = .GetValue(ID_RETURN_CODE_MESSAGE) txtReturnCode = mstResult If (mstResult = 0) Then
CPM API Reference Guide • CyberSource Corporation • May 2009 205
Chapter 7 Environment and Implementation ActiveX
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 With 'mobjLCCPayment
If Not mobjLCCPayment Is Nothing Then Set mobjLCCPayment = Nothing
End Sub
Private Sub cmdACHRefund_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_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 With 'mobjLCCPayment
If Not mobjLCCPayment Is Nothing Then Set mobjLCCPayment = Nothing
End Sub
CPM API Reference Guide • CyberSource Corporation • May 2009 206
Chapter 7 Environment and Implementation ActiveX
Private Sub cmdACHVoid_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_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 With 'mobjLCCPayment
If Not mobjLCCPayment Is Nothing Then Set mobjLCCPayment = Nothing
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
CPM API Reference Guide • CyberSource Corporation • May 2009 207
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 With 'mobjLCCPayment
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.
CPM API Reference Guide • CyberSource Corporation • May 2009 208
Chapter 7 Environment and Implementation Batch API
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
CPM API Reference Guide • CyberSource Corporation • May 2009 209
Chapter 7 Environment and Implementation Batch API
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
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
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.
CPM API Reference Guide • CyberSource Corporation • May 2009 210
Chapter 7 Environment and Implementation Batch API
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
CPM API Reference Guide • CyberSource Corporation • May 2009 211
Chapter 7 Environment and Implementation Batch API
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)
CPM API Reference Guide • CyberSource Corporation • May 2009 212
Chapter 7 Environment and Implementation Batch API
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
CPM API Reference Guide • CyberSource Corporation • May 2009 213
Chapter 7 Environment and Implementation Batch API
[Capture]
Input = merchant_name, sequence_number, amount
Output= merchant_name, account_number, expiration_date, amount, sequence_number, auth_response_code, auth_response_message, approval_code
[Auth_And_Capture]
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
[Reversal]
Input = merchant_name, sequence_number, amount
Output= merchant_name, account_number, expiration_date, amount, sequence_number, auth_response_code, auth_response_message, approval_code
[Return]
Input = merchant_name, account_number, expiration_date, amount
Output= merchant_name, account_number, expiration_date, amount, sequence_number, auth_response_code, auth_response_message, approval_code
[Manual_Authorization]
Input = merchant_name, sequence_number, approval_code
Output= merchant_name, account_number, expiration_date, amount, sequence_number, auth_response_code, auth_response_message, approval_code
[Void_Transaction]
Input = merchant_name, sequence_number
CPM API Reference Guide • CyberSource Corporation • May 2009 214
Chapter 7 Environment and Implementation Batch API
Output= merchant_name, account_number, expiration_date, amount, sequence_number, auth_response_code, auth_response_message, approval_code
[Lookup]
Input = merchant_name, sequence_number
Output= merchant_name, account_number, expiration_date, amount, sequence_number, auth_response_code, auth_response_message, approval_code
[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
CPM API Reference Guide • CyberSource Corporation • May 2009 215
Chapter 7 Environment and Implementation Batch API
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
CPM API Reference Guide • CyberSource Corporation • May 2009 216
Chapter 7 Environment and Implementation Batch API
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_address_2=461
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
CPM API Reference Guide • CyberSource Corporation • May 2009 217
Chapter 7 Environment and Implementation Batch API
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
CPM API Reference Guide • CyberSource Corporation • May 2009 218
Chapter 7 Environment and Implementation Batch API
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
CPM API Reference Guide • CyberSource Corporation • May 2009 219
Chapter 7 Environment and Implementation Batch API
processor_auth_response_code=4
username=31
password=12
ship_to_address_1=20
ship_to_address_2=20
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
CPM API Reference Guide • CyberSource Corporation • May 2009 220
Chapter 7 Environment and Implementation Batch API
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:
transaction_type 1 3
merchant_name 4 32
account_number 36 28
expiration_date 64 4
amount 68 12
sequence_number 80 15
auth_response_code 95 1
auth_response_message 96 20
approval_code 116 9
AUTHORIZATION
INPUT:
transaction_type 1 3
merchant_name 4 32
account_number 36 28
expiration_date 64 4
amount 68 12
OUTPUT:
transaction_type 1 3
merchant_name 4 32
account_number 36 28
expiration_date 64 4
amount 68 12
sequence_number 80 15
auth_response_code 95 1
CPM API Reference Guide • CyberSource Corporation • May 2009 221
Chapter 7 Environment and Implementation Batch API
auth_response_message 96 20
approval_code 116 9
BEGIN_SESSION
INPUT:
transaction_type 1 3
merchant_name 4 32
username 36 31
password 67 12
CAPTURE
INPUT:
transaction_type 1 3
merchant_name 4 32
sequence_number 36 15
amount 51 12
OUTPUT:
transaction_type 1 3
merchant_name 4 32
account_number 36 28
expiration_date 64 4
amount 68 12
sequence_number 80 15
auth_response_code 95 1
auth_response_message 96 20
approval_code 116 9
END_SESSION
INPUT:
transaction_type 1 3
merchant_name 4 32
CPM API Reference Guide • CyberSource Corporation • May 2009 222
Chapter 7 Environment and Implementation Batch API
LINE_ITEM_DETAIL
INPUT:
transaction_type 1 3
item_description 4 35
item_product_code 39 12
item_quantity 51 12
item_total_amount 63 12
OUTPUT:
transaction_type 1 3
item_description 4 35
item_product_code 39 12
item_total_amount 51 12
LOOKUP
INPUT:
transaction_type 1 3
merchant_name 4 32
sequence_number 36 15
OUTPUT:
transaction_type 1 3
merchant_name 4 32
account_number 36 28
expiration_date 64 4
amount 68 12
sequence_number 80 15
auth_response_code 95 1
auth_response_message 96 20
approval_code 116 9
CPM API Reference Guide • CyberSource Corporation • May 2009 223
Chapter 7 Environment and Implementation Batch API
MANUAL_AUTHORIZATION
INPUT:
transaction_type 1 3
merchant_name 4 32
sequence_number 36 15
approval_code 51 9
OUTPUT:
transaction_type 1 3
merchant_name 4 32
account_number 36 28
expiration_date 64 4
amount 68 12
sequence_number 80 15
auth_response_code 95 1
auth_response_message 96 20
approval_code 116 9
PREDIAL
INPUT:
transaction_type 1 3
merchant_name 4 32
OUTPUT:
transaction_type 1 3
merchant_name 4 32
return_code_message 36 40
RETURN
INPUT:
transaction_type 1 3
merchant_name 4 32
account_number 36 28
expiration_date 64 4
CPM API Reference Guide • CyberSource Corporation • May 2009 224
Chapter 7 Environment and Implementation Batch API
amount 68 12
OUTPUT:
transaction_type 1 3
merchant_name 4 32
account_number 36 28
expiration_date 64 4
amount 68 12
sequence_number 80 15
auth_response_code 95 1
auth_response_message 96 20
approval_code 116 9
REVERSAL
INPUT:
transaction_type 1 3
merchant_name 4 32
sequence_number 36 15
amount 51 12
OUTPUT:
transaction_type 1 3
merchant_name 4 32
account_number 36 28
expiration_date 64 4
amount 68 12
sequence_number 80 15
auth_response_code 95 1
auth_response_message 96 20
approval_code 116 9
VOID_TRANSACTION
INPUT:
transaction_type 1 3
CPM API Reference Guide • CyberSource Corporation • May 2009 225
Chapter 7 Environment and Implementation C API (Solaris, Win32 dll)
merchant_name 4 32
sequence_number 36 15
OUTPUT:
transaction_type 1 3
merchant_name 4 32
account_number 36 28
expiration_date 64 4
amount 68 12
sequence_number 80 15
auth_response_code 95 1
auth_response_message 96 20
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.
CPM API Reference Guide • CyberSource Corporation • May 2009 226
Chapter 7 Environment and Implementation C API (Solaris, Win32 dll)
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.
CPM API Reference Guide • CyberSource Corporation • May 2009 227
Chapter 7 Environment and Implementation C API (Solaris, Win32 dll)
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
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 Store]
MerchantId=demo
Server Address=localhost
Server Port=1530
Encryption=1
CPM API Reference Guide • CyberSource Corporation • May 2009 228
Chapter 7 Environment and Implementation C API (Solaris, Win32 dll)
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.
CPM API Reference Guide • CyberSource Corporation • May 2009 229
Chapter 7 Environment and Implementation C API (Solaris, Win32 dll)
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
(int) 0 if successful; an identifier corresponding to an error otherwise
CPM API Reference Guide • CyberSource Corporation • May 2009 230
Chapter 7 Environment and Implementation C API (Solaris, Win32 dll)
• 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 *sServerAddress, 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
(int) 0 if successful; an identifier corresponding to an error otherwise
CPM API Reference Guide • CyberSource Corporation • May 2009 231
Chapter 7 Environment and Implementation C API (Solaris, Win32 dll)
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
(int) 0 if successful; an identifier corresponding to an error otherwise
(long) the handle of the transaction
(long) the connection handle
(int) 0 if successful; an identifier corresponding to an error otherwise
None
CPM API Reference Guide • CyberSource Corporation • May 2009 232
Chapter 7 Environment and Implementation C API (Solaris, Win32 dll)
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
(int) 0 if successful; an identifier corresponding to an error otherwise
(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
CPM API Reference Guide • CyberSource Corporation • May 2009 233
Chapter 7 Environment and Implementation C API (Solaris, Win32 dll)
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 handle of the transaction
(long) the session ID
(int) 0 if successful; an identifier corresponding to an error otherwise
(long) the handle of the transaction
(long*) the session ID
(int) 0 if successful; an identifier corresponding to an error otherwise
(long) handle corresponding to the transaction
(long) identifier of the field to set
(const char *) the value to set the field to
(int) 0 if successful; an identifier corresponding to an error otherwise
CPM API Reference Guide • CyberSource Corporation • May 2009 234
Chapter 7 Environment and Implementation C API (Solaris, Win32 dll)
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) handle corresponding to the transaction
(long) identifier of the field to get
(char *) buffer that the value will be copied to
(int) length of the buffer
(int) 0 if successful; an identifier corresponding to an error otherwise
(long) handle corresponding to the transaction
(long) identifier of the field to get
(const char *) a pointer to the value if successful; an identifier corresponding to an error otherwise
(long) handle corresponding to the transaction
(long) identifier of the field length to get
(int) the length of the field's value; an identifier corresponding to an error otherwise
CPM API Reference Guide • CyberSource Corporation • May 2009 235
Chapter 7 Environment and Implementation C API (Solaris, Win32 dll)
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
(long) handle corresponding to the transaction
(int) 0 if successful; an identifier corresponding to an error otherwise
(long) handle corresponding to the transaction
CPM API Reference Guide • CyberSource Corporation • May 2009 236
Chapter 7 Environment and Implementation C API (Solaris, Win32 dll)
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
(long) handle corresponding to the transaction
(int) 1 if successful; 0 if unsuccessful
CPM API Reference Guide • CyberSource Corporation • May 2009 237
Chapter 7 Environment and Implementation C API (Solaris, Win32 dll)
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>
CPM API Reference Guide • CyberSource Corporation • May 2009 238
Chapter 7 Environment and Implementation C API (Solaris, Win32 dll)
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.
CPM API Reference Guide • CyberSource Corporation • May 2009 239
Chapter 7 Environment and Implementation C API (Solaris, Win32 dll)
*/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.
CPM API Reference Guide • CyberSource Corporation • May 2009 240
Chapter 7 Environment and Implementation C API (Solaris, Win32 dll)
*/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;
CPM API Reference Guide • CyberSource Corporation • May 2009 241
Chapter 7 Environment and Implementation C API (Solaris, Win32 dll)
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);
CPM API Reference Guide • CyberSource Corporation • May 2009 242
Chapter 7 Environment and Implementation C API (Solaris, Win32 dll)
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);
CPM API Reference Guide • CyberSource Corporation • May 2009 243
Chapter 7 Environment and Implementation C API (Solaris, Win32 dll)
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;}
CPM API Reference Guide • CyberSource Corporation • May 2009 244
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
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 1[Demonstration Store]
MerchantId=demo
Server Address=localhost
Server Port=1530
CPM API Reference Guide • CyberSource Corporation • May 2009 245
Chapter 7 Environment and Implementation Java (API)
Encryption=0
Example 2[Demonstration Store]
MerchantId=demo
Server Address=localhost
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
CPM API Reference Guide • CyberSource Corporation • May 2009 246
Chapter 7 Environment and Implementation Java (API)
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
CPM API Reference Guide • CyberSource Corporation • May 2009 247
Chapter 7 Environment and Implementation Java (API)
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
CPM API Reference Guide • CyberSource Corporation • May 2009 248
Chapter 7 Environment and Implementation Java (API)
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
(String) 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
(int) 0 if successful; an identifier corresponding to an error otherwise
(String) 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
(int) 0 if successful; an identifier corresponding to an error otherwise
CPM API Reference Guide • CyberSource Corporation • May 2009 249
Chapter 7 Environment and Implementation Java (API)
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
CPM API Reference Guide • CyberSource Corporation • May 2009 250
Chapter 7 Environment and Implementation Java (API)
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
CPM API Reference Guide • CyberSource Corporation • May 2009 251
Chapter 7 Environment and Implementation Java (API)
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
CPM API Reference Guide • CyberSource Corporation • May 2009 252
Chapter 7 Environment and Implementation Java (API)
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;
CPM API Reference Guide • CyberSource Corporation • May 2009 253
Chapter 7 Environment and Implementation Java (API)
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(
CPM API Reference Guide • CyberSource Corporation • May 2009 254
Chapter 7 Environment and Implementation Java (API)
"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
CPM API Reference Guide • CyberSource Corporation • May 2009 255
Chapter 7 Environment and Implementation Java (API)
// 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
CPM API Reference Guide • CyberSource Corporation • May 2009 256
Chapter 7 Environment and Implementation Java (API)
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" );
CPM API Reference Guide • CyberSource Corporation • May 2009 257
Chapter 7 Environment and Implementation Java (API)
/* 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(); }}
CPM API Reference Guide • CyberSource Corporation • May 2009 258
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.
CPM API Reference Guide • CyberSource Corporation • May 2009 259
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.
CPM API Reference Guide • CyberSource Corporation • May 2009 260
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.
CPM API Reference Guide • CyberSource Corporation • May 2009 261
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
CPM API Reference Guide • CyberSource Corporation • May 2009 262
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
CPM API Reference Guide • CyberSource Corporation • May 2009 263
Chapter 9 CPM Server Database Schema CPM Database Tables
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
FieldData Length and Type
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.
CPM API Reference Guide • CyberSource Corporation • May 2009 264
Chapter 9 CPM Server Database Schema CPM Database Tables
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
FieldData Length and Type
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.
CPM API Reference Guide • CyberSource Corporation • May 2009 265
Chapter 9 CPM Server Database Schema CPM Database Tables
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)
FieldData Length and Type
Description
Table 104 CC_Settlement Table Fields
FieldData Length and Type
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.
CPM API Reference Guide • CyberSource Corporation • May 2009 266
Chapter 9 CPM Server Database Schema CPM Database Tables
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)
FieldData Length and Type
Description
CPM API Reference Guide • CyberSource Corporation • May 2009 267
Chapter 9 CPM Server Database Schema CPM Database Tables
• ACCOUNT_NUMBER
• ACCOUNT_EXTENSION
Table 105 CC_TRANSACTION Table Fields
FieldData Length and Type
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.
CPM API Reference Guide • CyberSource Corporation • May 2009 268
Chapter 9 CPM Server Database Schema CPM Database Tables
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)
FieldData Length and Type
Description
CPM API Reference Guide • CyberSource Corporation • May 2009 269
Chapter 9 CPM Server Database Schema CPM Database Tables
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.
Table 105 CC_TRANSACTION Table Fields (Continued)
FieldData Length and Type
Description
CPM API Reference Guide • CyberSource Corporation • May 2009 270
Chapter 9 CPM Server Database Schema CPM Database Tables
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.
Note Do not use a decimal point in the transaction amount.
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.
Note Do not use a decimal point in the transaction amount.
CURRENT_TAX_AMOUNT
16 (numeric) The current tax amount authorized after any subsequent function. The format is DDDDDDDDDDDDCCCC.
Note Do not use a decimal point in the transaction amount.
ORDER_NUMBER 25 (varchar) Order Number assigned by the merchant.
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.
MERCH_BILL_NAME
25 (varchar) Merchant’s Name.
MERCH_BILL_LOC
13 (varchar) Merchant’s Location. Can be by city.
Table 105 CC_TRANSACTION Table Fields (Continued)
FieldData Length and Type
Description
CPM API Reference Guide • CyberSource Corporation • May 2009 271
Chapter 9 CPM Server Database Schema CPM Database Tables
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.
Table 105 CC_TRANSACTION Table Fields (Continued)
FieldData Length and Type
Description
CPM API Reference Guide • CyberSource Corporation • May 2009 272
Chapter 9 CPM Server Database Schema CPM Database Tables
CUSTOMER_PHONE
14 (varchar) Provided for storing additional customer information.
CUSTOMER_STREET
20 (varchar) Provided for storing additional customer information.
CUSTOMER_CITY 20 (varchar) Provided for storing additional customer information.
CUSTOMER_STATE
2 (varchar) Provided for storing additional customer information.
CUSTOMER_COUNTRY
2 (varchar) Provided for storing additional customer information.
CUSTOMER_ZIP 9 (varchar) Provided for storing additional customer information.
CUSTOMER_EMAIL
50 (varchar) Provided for storing additional customer information.
CUSTOMER_IP_ADDR
30 (varchar) Provided for storing additional customer information.
ADDRESS_MATCH
1 (varchar) One letter AVS result indicator. Possible values:
• Y: Match
• N: No match
• X: Service unavailable
• 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
• X: Service unavailable
• 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.
Table 105 CC_TRANSACTION Table Fields (Continued)
FieldData Length and Type
Description
CPM API Reference Guide • CyberSource Corporation • May 2009 273
Chapter 9 CPM Server Database Schema CPM Database Tables
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
Table 105 CC_TRANSACTION Table Fields (Continued)
FieldData Length and Type
Description
CPM API Reference Guide • CyberSource Corporation • May 2009 274
Chapter 9 CPM Server Database Schema CPM Database Tables
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
50 (varchar) User defined field.
USER_DEFINED_3
50 (varchar) User defined field.
USER_DEFINED_4
50 (varchar) User defined field.
USER_DEFINED_5
50 (varchar) User defined field.
USER_SEQUENCE_NUM
50 (varchar) User defined field.
USER_SOURCE_NAME
31 (varchar) User defined field.
RESERVED_1 50 (varchar) CPM Reserved field. Do not use.
RESERVED_2 50 (varchar) CPM Reserved field. Do not use.
Table 105 CC_TRANSACTION Table Fields (Continued)
FieldData Length and Type
Description
CPM API Reference Guide • CyberSource Corporation • May 2009 275
Chapter 9 CPM Server Database Schema CPM Database Tables
SOURCE_IP_ADDRESS
15 (varchar) Requested transaction source Internet Protocol Address.
TAX_AMOUNT 16 (numeric) Tax amount added to order. The format is DDDDDDDDDDDDCCCC.
Note Do not use a decimal point in the transaction amount.
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.
Table 105 CC_TRANSACTION Table Fields (Continued)
FieldData Length and Type
Description
CPM API Reference Guide • CyberSource Corporation • May 2009 276
Chapter 9 CPM Server Database Schema CPM Database Tables
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
Table 105 CC_TRANSACTION Table Fields (Continued)
FieldData Length and Type
Description
CPM API Reference Guide • CyberSource Corporation • May 2009 277
Chapter 9 CPM Server Database Schema CPM Database Tables
POS_ENTRY_MODE
1 (varchar) 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)
• 2: Read from credit card magnetic track 2 (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
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.
Table 105 CC_TRANSACTION Table Fields (Continued)
FieldData Length and Type
Description
CPM API Reference Guide • CyberSource Corporation • May 2009 278
Chapter 9 CPM Server Database Schema CPM Database Tables
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.
Table 105 CC_TRANSACTION Table Fields (Continued)
FieldData Length and Type
Description
CPM API Reference Guide • CyberSource Corporation • May 2009 279
Chapter 9 CPM Server Database Schema CPM Database Tables
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.
Table 105 CC_TRANSACTION Table Fields (Continued)
FieldData Length and Type
Description
Table 106 DB_STATUS Table Fields
FieldData Length and Type
Description
TOTAL_TRANSACTIONS
8 (numeric) Records total number of transaction in database.
OLDEST_TRANSACTION
8 (numeric) Records oldest transaction stored in CPM Server database.
CPM API Reference Guide • CyberSource Corporation • May 2009 280
Chapter 9 CPM Server Database Schema CPM Database Tables
Indexes
• BATCH_ID
• DRAFT_ID
• MERCHANT_ID
• BANK_ID
• SERVER_ID
• TRANS_DATE_TIME
• BANK_ACCT_NUM
Table 107 EFT_TRANSACTION Table Fields
FieldData Length and Type
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.
CPM API Reference Guide • CyberSource Corporation • May 2009 281
Chapter 9 CPM Server Database Schema CPM Database Tables
ORDER_NUMBER 25 (varchar) Order number for this transaction.
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.
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
50 (varchar) User defined field.
USER_DEFINED_2
50 (varchar) User defined field.
USER_DEFINED_3
50 (varchar) User defined field.
USER_DEFINED_4
50 (varchar) User defined field.
USER_DEFINED_5
50 (varchar) User defined field.
SEQUENCE_NUMBER
15 (varchar) Transaction Sequence Number unique to each transaction. Primary key.
Table 107 EFT_TRANSACTION Table Fields (Continued)
FieldData Length and Type
Description
CPM API Reference Guide • CyberSource Corporation • May 2009 282
Chapter 9 CPM Server Database Schema CPM Database Tables
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
26 (varchar) Provided for storing additional customer information.
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)
FieldData Length and Type
Description
Table 108 GATEWAY Table Fields
FieldData Length and Type
Description
GATEWAY_ID 32 (varchar) Primary key. Gateway identifier.
CPM API Reference Guide • CyberSource Corporation • May 2009 283
Chapter 9 CPM Server Database Schema CPM Database Tables
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.
Constraints SEQUENCE_NUMBER (primary key)
GATEWAY_VALUES Table Fields
FieldData Length and Type
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
FieldData Length and Type
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.
CPM API Reference Guide • CyberSource Corporation • May 2009 284
Chapter 9 CPM Server Database Schema CPM Database Tables
HR_TRANSACTION TableDescription Stores hotel and car rental information.
UsageInserts a records for each hotel or car rental value.
Constraints SEQUENCE_NUMBER (primary key)
DENTAL_AMOUNT
16 (numeric) Dental portion of the QHP amount.
Table 109 HBC_TRANSACTION Table Fields (Continued)
FieldData Length and Type
Description
Table 110 HR_TRANSACTION Table Fields
FieldData Length and Type
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.
CPM API Reference Guide • CyberSource Corporation • May 2009 285
Chapter 9 CPM Server Database Schema CPM Database Tables
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)
FieldData Length and Type
Description
CPM API Reference Guide • CyberSource Corporation • May 2009 286
Chapter 9 CPM Server Database Schema CPM Database Tables
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
• MERCHANT_ID (primary key)
• AGREEMENT_TYPE (primary key)
Table 111 MERCHANT Table Fields
FieldData Length and Type
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
FieldData Length and Type
Description
MERCHANT_ID 32 (varchar) Primary key. Merchant identifier.
AGREEMENT_TYPE
32 (varchar) Primary key. Agreement type.
AGREEMENT_ID 32 (varchar) Agreement identifier.
CPM API Reference Guide • CyberSource Corporation • May 2009 287
Chapter 9 CPM Server Database Schema CPM Database Tables
MERCHANT_VALUES TableDescription Stores Merchant information.
UsageInserts a record for each merchant element.
Constraints
• MERCHANT_ID (primary key)
• 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.
Constraints SEQUENCE_NUMBER (primary key)
Table 113 MERCHANT_VALUES Table Fields
FieldData Length and Type
Description
MERCHANT_ID 32 (varchar) Primary key. Merchant identifier.
ELEM_NAME 32 (varchar) Merchant element name.
ELEM_VALUE 255 (varchar) Merchant element value.
Table 114 PLCARD_BENEFICIAL Table Fields
FieldData Length and Type
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.
CPM API Reference Guide • CyberSource Corporation • May 2009 288
Chapter 9 CPM Server Database Schema CPM Database Tables
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.
Constraints SEQUENCE_NUMBER (primary key)
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
FieldData Length and Type
Description
Table 115 PLCARD_GECC Table Fields
FieldData Length and Type
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.
LINE_ITEM_2 4 (varchar) GECC private card line item detail. Defined by GECC.
LINE_ITEM_3 4 (varchar) GECC private card line item detail. Defined by GECC.
CPM API Reference Guide • CyberSource Corporation • May 2009 289
Chapter 9 CPM Server Database Schema CPM Database Tables
PX_MESSAGE TableDescription Stores warning/error messages generated.
Usage Inserts one record for every message.
LINE_ITEM_4 4 (varchar) GECC private card line item detail. Defined by GECC.
LINE_ITEM_5 4 (varchar) GECC private card line item detail. Defined by GECC.
LINE_ITEM_6 4 (varchar) GECC private card line item detail. Defined by GECC.
LINE_ITEM_7 4 (varchar) GECC private card line item detail. Defined by GECC.
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
FieldData Length and Type
Description
Table 116 PX_MESSAGE Table Fields
FieldData Length and Type
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.
CPM API Reference Guide • CyberSource Corporation • May 2009 290
Chapter 9 CPM Server Database Schema CPM Database Tables
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.
Constraints SEQUENCE_NUMBER (primary key)
Table 117 SETTLEMENT_LOCK Table Fields
FieldData Length and Type
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
FieldData Length and Type
Description
SEQUENCE_NUMBER
15 (varchar) Primary Key.
DEPT_NAME 40 (varchar) Department name where the transaction took place.
CPM API Reference Guide • CyberSource Corporation • May 2009 291
Chapter 9 CPM Server Database Schema CPM Database Tables
ITEM1_DESCRIPTION
19 (varchar) Description of retail item 1.
ITEM2_DESCRIPTION
19 (varchar) Description of retail item 2.
ITEM3_DESCRIPTION
19 (varchar) Description of retail item 3.
ITEM4_DESCRIPTION
19 (varchar) Description of retail item 4.
ITEM5_DESCRIPTION
19 (varchar) Description of retail item 5.
ITEM6_DESCRIPTION
19 (varchar) Description of retail item 6.
ITEM1_QTY 3 (varchar) Quantity purchased of retail item 1.
ITEM2_QTY 3 (varchar) Quantity purchased of retail item 2.
ITEM3_QTY 3 (varchar) Quantity purchased of retail item 3.
ITEM4_QTY 3 (varchar) Quantity purchased of retail item 4.
ITEM5_QTY 3 (varchar) Quantity purchased of retail item 5.
ITEM6_QTY 3 (varchar) Quantity purchased of retail item 6.
ITEM1_AMOUNT 12 (varchar) Unit cost of retail item 1.
ITEM2_AMOUNT 12 (varchar) Unit cost of retail item 2.
ITEM3_AMOUNT 12 (varchar) Unit cost of retail item 3.
ITEM4_AMOUNT 12 (varchar) Unit cost of retail item 4.
ITEM5_AMOUNT 12 (varchar) Unit cost of retail item 5.
ITEM6_AMOUNT 12 (varchar) Unit cost of retail item 6.
Table 118 TAA_RETAIL_TRANSACTION Table Fields (Continued)
FieldData Length and Type
Description
CPM API Reference Guide • CyberSource Corporation • May 2009 292
Chapter 9 CPM Server Database Schema CPM Database Tables
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.
Constraints SEQUENCE_NUMBER (primary key)
Table 119 TAA_TRANSACTION Table Fields
FieldData Length and Type
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.
TAA3 40 (varchar) See description for TAA1.
TAA4 40 (varchar) See description for TAA1.
TAA1_QTY 3 (varchar) The quantity purchased for the Transaction Advice Addendum 1 field.
TAA2_QTY 3 (varchar) The quantity purchased for the Transaction Advice Addendum 2 field.
TAA3_QTY 3 (varchar) The quantity purchased for the Transaction Advice Addendum 3 field.
TAA4_QTY 3 (varchar) The quantity purchased for the Transaction Advice Addendum 4 field.
TAA1_AMOUNT 12 (varchar) The unit cost for the Transaction Advice Addendum 1 field.
TAA2_AMOUNT 12 (varchar) The unit cost for the Transaction Advice Addendum 2 field.
TAA3_AMOUNT 12 (varchar) The unit cost for the Transaction Advice Addendum 3 field.
TAA4_AMOUNT 12 (varchar) The unit cost for the Transaction Advice Addendum 4 field.
CPM API Reference Guide • CyberSource Corporation • May 2009 293
Chapter 9 CPM Server Database Schema CPM Database Tables
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
FieldData Length and Type
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.
CPM API Reference Guide • CyberSource Corporation • May 2009 294
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
CPM API Reference Guide • CyberSource Corporation • May 2009 295
Chapter 9 CPM Server Database Schema Database Field and CPM API Field Mapping
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_DEFINED_2 ID_USER_DEFINED_2
USER_DEFINED_3 ID_USER_DEFINED_3
USER_DEFINED_4 ID_USER_DEFINED_4
USER_DEFINED_5 ID_USER_DEFINED_5
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)
Database Field CPM API Field
CPM API Reference Guide • CyberSource Corporation • May 2009 296
Chapter 9 CPM Server Database Schema Database Field and CPM API Field Mapping
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)
Database Field CPM API Field
CPM API Reference Guide • CyberSource Corporation • May 2009 297
Chapter 9 CPM Server Database Schema Database Field and CPM API Field Mapping
CC_LINEITEM_DETAIL Table
EFT_TRANSACTION Table
Table 122 CC_LINEITEM_DETAIL Fields and CPM API Fields Mapping
Database Field CPM API Field
SEQUENCE_NUMBER ID_SEQUENCE_NUMBER
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
Database Field CPM API Field
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
CPM API Reference Guide • CyberSource Corporation • May 2009 298
Chapter 9 CPM Server Database Schema Database Field and CPM API Field Mapping
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
USER_DEFINED_1 ID_USER_DEFINED_1
USER_DEFINED_2 ID_USER_DEFINED_2
USER_DEFINED_3 ID_USER_DEFINED_3
USER_DEFINED_4 ID_USER_DEFINED_4
USER_DEFINED_5 ID_USER_DEFINED_5
SEQUENCE_NUMBER ID_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)
Database Field CPM API Field
Table 124 PLCARD_BENEFICIAL Fields and CPM API Fields Mapping
Database Field CPM API Field
SEQUENCE_NUMBER ID_SEQUENCE_NUMBER
CREDIT_PLAN ID_BENEFICIAL_CREDIT_PLAN
DEPARTMENT_CODE ID_BENEFICIAL_DEPARTMENT_CODE
SKU_NUMBER ID_BENEFICIAL_SKU_NUMBER
CPM API Reference Guide • CyberSource Corporation • May 2009 299
Chapter 9 CPM Server Database Schema Database Field and CPM API Field Mapping
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)
Database Field CPM API Field
Table 125 PLCARD_GECC Fields and CPM API Fields Mapping
Database Field CPM API Field
SEQUENCE_NUMBER ID_SEQUENCE_NUMBER
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
LINE_ITEM_2 ID_GECC_LINE_ITEM_2
LINE_ITEM_3 ID_GECC_LINE_ITEM_3
LINE_ITEM_4 ID_GECC_LINE_ITEM_4
LINE_ITEM_5 ID_GECC_LINE_ITEM_5
LINE_ITEM_6 ID_GECC_LINE_ITEM_6
LINE_ITEM_7 ID_GECC_LINE_ITEM_7
MICROFICHE_SEQ_NUM ID_GECC_MICROFICHE_SEQUENCE_NUM
PLAN_NUMBER ID_GECC_PLAN_NUMBER
CPM API Reference Guide • CyberSource Corporation • May 2009 300
Chapter 9 CPM Server Database Schema Database Field and CPM API Field Mapping
HR_TRANSACTION Table
Table 126 HR_TRANSACTION Table and CPM API Field Mapping
Database Field CPM API Field
SEQUENCE_NUMBER ID_SEQUENCE_NUMBER
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
CPM API Reference Guide • CyberSource Corporation • May 2009 301
Chapter 9 CPM Server Database Schema Database Field and CPM API Field Mapping
TAA_RETAIL_TRANSACTION Table
Table 127 TAA_RETAIL_TRANSACTION Fields and CPM API Fields Mapping
Database Field CPM API Field
DEPT_NAME ID_RETAIL_DEPT_NAME
ITEM1_DESCRIPTION ID_RETAIL_ITEM1_DESCRIPTION
ITEM2_DESCRIPTION ID_RETAIL_ITEM2_DESCRIPTION
ITEM3_DESCRIPTION ID_RETAIL_ITEM3_DESCRIPTION
ITEM4_DESCRIPTION ID_RETAIL_ITEM4_DESCRIPTION
ITEM5_DESCRIPTION ID_RETAIL_ITEM5_DESCRIPTION
ITEM6_DESCRIPTION ID_RETAIL_ITEM6_DESCRIPTION
ITEM1_QTY ID_RETAIL_ITEM1_QTY
ITEM2_QTY ID_RETAIL_ITEM2_QTY
ITEM3_QTY ID_RETAIL_ITEM3_QTY
ITEM4_QTY ID_RETAIL_ITEM4_QTY
ITEM5_QTY ID_RETAIL_ITEM5_QTY
ITEM6_QTY ID_RETAIL_ITEM6_QTY
ITEM1_AMOUNT ID_RETAIL_ITEM1_AMOUNT
ITEM2_AMOUNT ID_RETAIL_ITEM2_AMOUNT
ITEM3_AMOUNT ID_RETAIL_ITEM3_AMOUNT
ITEM4_AMOUNT ID_RETAIL_ITEM4_AMOUNT
ITEM5_AMOUNT ID_RETAIL_ITEM5_AMOUNT
ITEM6_AMOUNT ID_RETAIL_ITEM6_AMOUNT
CPM API Reference Guide • CyberSource Corporation • May 2009 302
Chapter 9 CPM Server Database Schema Database Field and CPM API Field Mapping
TAA_TRANSACTION Table
Table 128 TAA_TRANSACTION Fields and CPM API Fields Mapping
Database Field CPM API Field
TAA1 ID_TAA1
TAA2 ID_TAA2
TAA3 ID_TAA3
TAA4 ID_TAA4
TAA1_QTY ID_TAA1_QTY
TAA2_QTY ID_TAA2_QTY
TAA3_QTY ID_TAA3_QTY
TAA4_QTY ID_TAA4_QTY
TAA1_AMOUNT ID_TAA1_AMOUNT
TAA2_AMOUNT ID_TAA2_AMOUNT
TAA3_AMOUNT ID_TAA3_AMOUNT
TAA4_AMOUNT ID_TAA4_AMOUNT
CPM API Reference Guide • CyberSource Corporation • May 2009 303
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
CPM API Reference Guide • CyberSource Corporation • May 2009 304
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 12, 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, 10, 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 11
CPM API Reference Guide • CyberSource Corporation • May 2009 305
top related