API Reference Guide August 2005

Transcription

1 CyberSource Payment Manager API Reference Guide August 2005

2 CyberSource Contact Information For questions about CyberSource Payment Manager, For general information about our company, products, and services, go to For sales questions about any CyberSource Service, or call or (toll-free in the United States). For support information about any CyberSource service, visit the Support Center at Copyright 2005 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 Legends For 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 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 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. Trademarks CyberSource, the Power Behind the Buy Button, 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. CPM API Reference Guide CyberSource Corporation August 2005 ii

3 Contents Documentation Changes... ix Chapter 1 Introduction...1 CPM API Basics...1 Generic Function Overview...1 Generic Flow Chart of Functions...1 Generic Function Detail...3 Start up...3 Shut down...3 Set configuration file...3 Open connection...3 Close connection...3 Open transaction...3 Close transaction...3 Set connection information...4 Run transaction...4 Set session ID...4 Get session ID...4 Set value...4 Get value...4 Get value length...4 Get value pointer...4 Clear values...5 Dump values...5 Print values...5 Compatibility...5 Supported Platforms...5 CPM API Operations...6 Credit Card and Debit Card Transactions...6 Authorization...6 Capture...7 Authorize and Capture...7 Reversal...8 Return...8 Void...8 Manual Authorization...9 Lookup...9 BIN Lookup...10 CPM API Reference Guide CyberSource Corporation August 2005 iii

4 Contents ACH Transactions...11 ACH Verify...11 ACH Deposit...11 ACH Refund...12 ACH Void...12 ACH Lookup...12 Generic CPM API Operations...12 Admin Command...12 Begin Session...13 End Session...13 Other functions...13 Using the API Operations...13 Building the CPM API Integration...15 Financial Processor Specifications...16 Using the API in a Retail Environment...16 Chapter 2 CPM API Groups...17 Base Group...17 PIN-less Debit Cards...21 Extended Information Group...23 BIN Lookup...26 Using the Amex Retail Info Field...26 Address Verification Service Group...27 Standard AVS...27 VISA RED Regulations for AVS...27 Enhanced AVS...28 Automated Address Verification Plus...29 Configuring the AVS Level...29 PS2000 Group...32 Extended Customer Information Group...33 Customer Name and AVS...33 Terminal Setup Group...35 Card Verification Value Group...37 ECommerce Group...39 Billing Group (Soft Descriptors)...40 Purchasing Card Group...42 Using the TAA1 Field with American Express Phoenix...43 Level III Purchasing Card Group...44 Level III Purchasing Card Line Item Detail Group...45 User Defined Group...47 Magnetic Track Group...47 PIN-based Debit Cards...48 CPM Reserved Group...50 Security Group...50 Processor Specific Response Group...51 Private Label Card Group...51 Electronic Fund Transfer Group...53 CPM API Reference Guide CyberSource Corporation August 2005 iv

5 Contents Switch Card Group...54 Hotel and Car Rental Group...54 Admin Command Group...57 API Input Notes...58 Amount Field...58 Authorization...59 Capture...59 Authorize and Capture...59 Reversal...60 Return...60 Void...61 Manual Authorization...61 Lookup...61 ACH Verify...62 ACH Deposit...62 ACH Refund...62 Sequence Number Field...63 Chapter 3 CPM API Function Requirements...65 Authorization...65 Input...65 Output...72 Capture...74 Input...74 Output...83 Authorize and Capture...85 Input...85 Output...93 Reversal...96 Input...96 Output Return Input Output Void Input Output Manual Authorization Input Output Lookup Input Output BIN Lookup Input Output ACH Verify CPM API Reference Guide CyberSource Corporation August 2005 v

6 Contents Input Output ACH Deposit Input Output ACH Refund Input Output ACH Void Input Output ACH Lookup Input Output Admin Command Input Begin Session Input Output End Session Input Output Chapter 4 CPM API Output Codes Transaction Response Code Authorization Response Code Address Verification Service Code VISA RED Regulations for AVS Address Match Zip Match Card Verification Value Codes Chapter 5 CPM API Field Identifiers Transaction Type Identifiers CPM API Field Identifiers Chapter 6 CPM Error Identifiers Error Descriptions Chapter 7 Environment and Implementation CPM Port Usage ActiveX Merchant Information CPM API Reference Guide CyberSource Corporation August 2005 vi

7 Contents Configuration File Configuration File Format Server Port and IP Address Registry Environment Set Up Binding Class Details Merchant Class LCCStoreList Class LCCPayment Class Sample Code Batch API Configuration Files Merchant Information LCC_BATCH.CFG File LCC_BATCH_IDS.CFG File LCC_BATCH_LENGTHS.CFG File Input File Description Implementing Purchase Card Level III Usage LCC_BATCH_LAYOUT.TXT File Output Files Working With Output Files Sample Code C API (Solaris, Win32 dll) C Solaris C Win32 dll Merchant Information Configuration File Configuration File Location User Security Environment Set Up C Solaris C Win32 dll Function Detail Sample Code Java (API) Merchant Information Server Port and IP Address Environment Set Up Method Details Sample Code Chapter 8 CPM Server Test Mode Emulation Test Gateway Restrictions Approval codes Address Match CPM API Reference Guide CyberSource Corporation August 2005 vii

8 Contents Zip Code Match Chapter 9 CPM Server Database Schema Sizing the CPM Database Maintaining the CPM Database Managing the Database CPM RDMS Support Amount Field Length CPM Database Tables Security Tables AGREEMENT Table AGREEMENT_VALUES Table CC_LINEITEM_DETAIL Table CC_SETTLEMENT Table CC_TRANSACTION Table DB_STATUS Table EFT_TRANSACTION Table GATEWAY Table GATEWAY_VALUES Table HR_TRANSACTION Table MERCHANT Table MERCHANT_AGREEMENT Table MERCHANT_VALUES Table PLCARD_BENEFICIAL Table PLCARD_GECC Table PX_MESSAGE Table SETTLEMENT_LOCK Table TAA_TRANSACTION Table Database Field and CPM API Field Mapping CC_TRANSACTION Table CC_LINEITEM_DETAIL Table EFT_TRANSACTION Table PLCARD_BENEFICIAL Table PLCARD_GECC Table HR_TRANSACTION Table TAA_TRANSACTION Table Index CPM API Reference Guide CyberSource Corporation August 2005 viii

9 Documentation Changes The following changes were made to this guide since its last publication: Changed the version number to Added information about using the Market Specific Indicator field to indicate a bill payment with the MPS gateway. See the description of the field in Table 2 on page 23 for more information. CPM API Reference Guide CyberSource Corporation August 2005 ix

10 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 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 Overview The 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 Functions To 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 August

11 Chapter 1 Introduction CPM API Basics 2 Set the session identifier. (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. (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 August

12 Chapter 1 Introduction CPM API Basics Generic Function Detail Start up Initializes 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 down Terminates the CPM API. Call this function after performing all CPM API calls. This function is not used by ActiveX and Java. Set configuration file Enables the CPM API to read from the specified configuration file other than the default configuration file. Open connection This 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 connection This function closes a connection to the CPM Server that was opened with the Open Connection function. (optional) Open transaction Opens 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 transaction Closes the handle corresponding to the specified transaction. This function is not used by ActiveX and Java. CPM API Reference Guide CyberSource Corporation August

13 Chapter 1 Introduction CPM API Basics Set connection information This function sets the connection information for the specified transaction at run time. This function overrides the settings in the configuration file. Run transaction Sends a transaction to the CPM Server for execution. Set session ID Sets the session ID for a transaction. You must use this function when the CPM Server is configured to use security. (optional) Get session ID Retrieves the session ID for a transaction. The session ID is used when the CPM Server is configured to use security. (optional) Set value Sets the value of a field for a transaction. Get value Retrieves a field's value for a transaction. Get value length Returns the length of a field's value for a transaction. Get value pointer Retrieves the pointer value to a field's value for a transaction. Note This function is not supported for all programming languages, such as Visual Basic. CPM API Reference Guide CyberSource Corporation August

14 Chapter 1 Introduction Compatibility Clear values Removes all the values associated with an open transaction. Dump values Dumps all the values associated with the specified transaction into lcc_test.txt. Print values Prints all the values associated with the specified transaction to stdout. Compatibility Custom 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 Platforms The 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 supported, contact your sales representative. CPM API Reference Guide CyberSource Corporation August

15 Chapter 1 Introduction CPM API Operations CPM API Operations Credit Card and Debit Card Transactions Authorization You can use the Authorization transaction (transaction type 100) with either credit cards or debit cards. For Credit Cards. For 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 (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 (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 (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. For Debit Cards. For debit cards (either PIN-less or PIN-based), the Authorization transaction actually removes the funds from the customer s account, and the Capture transaction (type 102) settles the funds into your account. You can either use an individual Authorization immediately followed by an individual Capture, or use the bundled Authorization and Capture transaction type (type 104). You will typically use the bundled Authorization and Capture transaction type. Note that you cannot perform a credit with a debit card; if you need to refund the customer s money, provide the refund in cash. CPM API Reference Guide CyberSource Corporation August

16 Chapter 1 Introduction CPM API Operations Verified by Visa. Verified by Visa reduces the risk of unauthorized use of a credit cardholder account. Verified by Visa enables card issuers to verify a cardholder's identity through the use of a password, and provides results to you in real time during the checkout process. Verified by Visa, also known as Visa Payer Authentication Service (VPAS), reduces your exposure to fraud and disputes, and protects the cardholder from fraudulent use of their Visa credit card. Visa cardholders will go through the same online purchase process they currently use. After they have entered their Visa card number and hit the "BUY" button, their Visa 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, will trigger a daughter window to appear in the cardholder's browser. The cardholder is asked to enter a password to identify themselves to the issuing bank. Upon verification, the bank will issue a success message to you assuring you that they have authenticated the identity of the Visa cardholder, the purchase is completed, and a digitally signed receipt is stored for recordkeeping. The cardholder receives a message notifying them that their purchase has been approved. To use Verified by Visa with credit card transactions, send Verified by Visa data in the ecommerce group fields when you request an authorization. Capture The Capture transaction (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 Capture The Authorize and Capture transaction (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 helpful 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 primary 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 August

17 Chapter 1 Introduction CPM API Operations Reversal The Reversal (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 authorization has been settled, perform a Return (transaction type 103) to return the 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. Return The Return transaction (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. If you need to refund the customer s money, provide the refund in cash. Void The Void transaction (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 authorization has been settled, perform a Return transaction to return the money to the cardholder s account. CPM API Reference Guide CyberSource Corporation August

18 Chapter 1 Introduction CPM API Operations Do not use the Void transaction with debit cards. Manual Authorization You use the Manual Authorization transaction (transaction type 105) after receiving a call response from either an Authorization (transaction type 100) or an Authorization and Capture (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 Chapter 2, Sequence Number Field, on page 63. Do not use the Manual Authorization transaction with debit cards. Lookup A Lookup transaction (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. Sequence Number Account Number User Defined 1 Order Number Transaction ID User Defined 2 CPM API Reference Guide CyberSource Corporation August

19 Chapter 1 Introduction CPM API Operations Amount Retrieval Reference Number User Defined 3 Tax Amount User Sequence Number User Defined 4 Lookup Transaction Type User Defined 5 Note You cannot use the Account Number field to retrieve a transaction from an encrypted CPM database. BIN Lookup CPM 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 VISAbranded debit card for a tuition payment, you will want to know if you can process the card as a PIN-less debit card. These are the three steps to using BIN information: 1 Obtain the BIN information. 2 Create the BIN information database table. 3 Before processing a card, look up the card s BIN information from the database table. Obtaining the BIN Information. You first must obtain the BIN information from your payment processor or merchant bank. Each processor or merchant bank has a different format for the BIN information they provide. You receive this information in one or more files which you store locally. You then use CyberSource s Database Utility to load that information into a database table. You can then use CyberSource s BIN Lookup function to easily look up the BIN information for a particular card number. You must discuss with your processor or bank how you can determine from the BIN information they provide whether a card can be processed as a PIN-based or PIN-less debit card. The processor or bank may have specific business rules that you should follow when deciding whether to accept a card for a certain type of payment. When you receive the reply from CyberSource s BIN Lookup function, you must parse the reply for the information that you need to make that decision. 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. Once 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 CPM API Reference Guide CyberSource Corporation August

20 Chapter 1 Introduction CPM API Operations 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 (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 Transactions ACH 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. ACH Verify The ACH Verify transaction (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 Deposit The ACH Deposit transaction (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 CPM API Reference Guide CyberSource Corporation August

21 Chapter 1 Introduction CPM API Operations 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 Refund The ACH Refund transaction (transaction type 110) is processed as part of a settlement batch and is sent to the financial processor. The financial processor, when processing the ACH Refund transaction, takes funds from the merchant's account and places it in the customer s account. The settlement of a ACH refund transaction can only fail if there is syntactically incorrect information in the transaction. If insufficient funds exist to perform the transaction, the financial processor or acquiring bank calls the merchant directly. ACH Void An ACH Deposit or ACH Refund transaction can be voided (transaction type 111) in the CPM database as long as the transaction has not already be 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 Lookup The ACH Lookup transaction (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. Generic CPM API Operations Admin Command The Admin Command function (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. CPM API Reference Guide CyberSource Corporation August

22 Chapter 1 Introduction Using the API Operations Begin Session The Begin Session function (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 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 session identifier field in the transaction function is left NULL. End Session The End Session function (transaction type 151) logs a user out of the CPM Server by turning in their session ID. Other functions Other functions for working with the API are described in the Chapter 7, Environment and Implementation, on page 145. Using the API Operations To 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 ensures 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. CPM API Reference Guide CyberSource Corporation August

23 Chapter 1 Introduction Using the API Operations 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. 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. CPM API Reference Guide CyberSource Corporation August

24 Chapter 1 Introduction Building the CPM API Integration 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. Building the CPM API Integration The 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 17. Note Additional information and integration functionality, such as AVS and CVV, can help the merchant receive reduced interchange rates for credit card transactions. Contact your financial processor for more information on interchange reduction 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 ensures 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. CPM API Reference Guide CyberSource Corporation August

25 Chapter 1 Introduction Building the CPM API Integration Financial Processor Specifications This 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 ensure correct transaction billing. Using the API in a Retail Environment When 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 47 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 August

26 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 CPM API fields are divided into groups. The groups comprise API fields based on transaction type and credit card or ACH transaction function. Not all groups are necessary for a transaction. Each API field has an identifier listed in Chapter 5, CPM API Field Identifiers, on page 131. The tables below include each field s numeric identifier. Base Group The 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. We recommend all CPM API integrations include all fields in the base group. Table 1 Base Group Fields Field Numeric Identifier Description Length Merchant ID 51 Which CPM Merchant ID to use on the CPM Server. You set up your Merchant ID (or Merchant IDs; you may have multiple IDs) in the CPM Administration Client. This field is required with every transaction. 32 CPM API Reference Guide CyberSource Corporation August

27 Chapter 2 CPM API Groups Base Group Table 1 Base Group Fields (Continued) Field Numeric Identifier Description Length 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. Account Number 101 The credit card or debit card number. Do not include spaces or dashes. Expiration Date 102 The credit card expiration date for the function. Use the format MMYY. Amount 103 The amount for the transaction. Use the format DDDDDDDDDDCC. For the NOVA gateway, use format 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 (described in Table 2, which starts on page 23). no limit (7 for the NOVA gateway) CPM API Reference Guide CyberSource Corporation August

28 Chapter 2 CPM API Groups Base Group Table 1 Base Group Fields (Continued) Field Numeric Identifier Description Length 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 to help avoid any confusion caused by overlapping BIN ranges. This field can contain one of the following 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: Switch 010: GE Capital 011: GECC 012: Beneficial 013: Citibank Encryption Program 022: Liz Claiborne 029: Debit (either PIN-based or PIN-less) 3 CPM API Reference Guide CyberSource Corporation August

29 Chapter 2 CPM API Groups Base Group Table 1 Base Group Fields (Continued) Field Numeric Identifier Description Length Sequence Number 105 A unique number assigned to each transaction. The sequence number is updated with the output of every transaction. The sequence number provides an index to refer to the transaction and tracks the detail fields of an authorization. By inserting the sequence number of an authorization into the sequence number field of a reversal, capture, or void, the CPM Server looks up all detail fields of the authorization and copies them to the corresponding fields of the subsequent transaction. NOTE When performing a Capture or Reversal that references a manually authorized Authorization or combined Authorization and Capture, provide the sequence number for the original Authorization (the 100 transaction) or the Authorization and Capture (the 104 transaction), and NOT for the Manual Authorization (the 105 transaction). See Chapter 1, Manual Authorization, on page 9. See Sequence Number Field on page 63 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 PIN-based debit card transactions, if the request is approved, the field contains a reference number that you must print on the customer s receipt. 9 CPM API Reference Guide CyberSource Corporation August

30 Chapter 2 CPM API Groups Base Group Table 1 Base Group Fields (Continued) Field Numeric Identifier Description Length Authorization Response Code Authorization Response Message Return Code Message 107 A processor-independent response for all authorization requests. This field is only used for authorizations, reversals, and authorize and capture. The field can contain one of the following 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. 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. 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 PIN-less Debit Cards A 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. CPM API Reference Guide CyberSource Corporation August

31 Chapter 2 CPM API Groups Base Group Note PIN-less debit cards are different from PIN-based debit cards (see PIN-based Debit Cards on page 48). 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, and utilities, among others. This is the typical scenario: You are accepting a credit card for a combined Authorization and Capture transaction, and the card the customer presents is a VISA- or MasterCardbranded card that may be used in either a credit card or debit transaction. You use the CPM BIN Lookup transaction (described on page 26) to determine if the card can be used for PIN-less debit transactions and then process the card accordingly. Note that you must have a separate merchant ID for the FDMS South Debit gateway. When you process the card, make sure to specify the correct merchant ID associated with the gateway that you want to use (FDMS South Debit gateway or a credit card gateway). 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) 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 FDMS South 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 96. CPM API Reference Guide CyberSource Corporation August