Card-Present Processing Using the Simple Order API

Transcription

1 Title Page Card-Present Processing Using the Simple Order API Supplement to Credit Card Services Using the Simple Order API May 2015 CyberSource Corporation HQ P.O. Box 8999 San Francisco, CA Phone:

2 CyberSource Contact Information 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 2015 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 be 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 of Payment, CyberSource Payment Manager, CyberSource Risk Manager, CyberSource Decision Manager, CyberSource Connect, Authorize.Net, and echeck.net are trademarks and/or service marks of CyberSource Corporation. All other brands and product names are trademarks or registered trademarks of their respective owners. 2

3 Contents CONTENTS Recent Revisions to This Document 5 About This Guide 6 Audience and Purpose 6 Conventions 6 Related Documentation 7 Customer Support 7 Chapter 1 Introduction to Card-Present Transactions 8 Supported Processors 8 Prerequisites 9 Chapter 2 Optional Features 10 Europay, MasterCard, Visa (EMV) 10 EMV Cards and Cardholder Verification Methods (CVMs) 11 EMV Transactions 11 Encryption 12 Payment Network Tokenization 15 Appendix A API Fields 16 XML Schema Versions 16 Formatting Restrictions 17 Data Type Definitions 17 P2PE Request Fields (Recommended) 18 EMV Request Fields 19 Clear Text Request Fields 22 General Card-Present Request Fields 23 Reply Fields 38 Card-Present Processing Using the Simple Order API May

4 Contents Appendix B Examples 39 Name-Value Pair Examples 39 Sale Using Swiped Track Data 39 Sale Using Keyed Data 40 Sale Using EMV Technology with a Contact Read 41 Sale Using EMV Technology with a Contactless Read 42 Authorization Using Point-to-Point Encryption 43 XML Examples 44 Sale Using Swiped Track Data 44 Sale Using Keyed Data 46 Sale Using EMV Technology with a Contact Read 48 Sale Using EMV Technology with a Contactless Read 50 Authorization Using Point-to-Point Encryption 52 Card-Present Processing Using the Simple Order API May

5 Recent Revisions to This Document REVISIONS Release May 2015 April 2015 March 2015 December 2014 Changes All processors that support encryption: updated the information about devices and device reader data values. See "Encryption," page 12. FDC Nashville Global: added note that forced captures are not supported for EMV transactions. See "Europay, MasterCard, Visa (EMV)," page 10. All processors that support encryption: updated the device reader data in "Encryption," page 12. FDC Nashville Global: added support for EMV. See "Europay, MasterCard, Visa (EMV)," page 10. TSYS Acquiring Solutions: added support for the pos_catlevel field for transactions from mobile devices. See "General Card-Present Request Fields," page 23. All processors that support encryption: Updated the device reader data in "Encryption," page 12. Updated the description of the pos_encodingmethod field in "P2PE Request Fields (Recommended)," page 18. All processors: changed the retail and retail POS terminology to card present. All processors that support encryption: Added a transaction flow diagram. See "Encryption," page 12. Updated the device reader data in "Encryption," page 12. Added P2PE examples. See "Authorization Using Point-to-Point Encryption," page 43 (NVP), and "Authorization Using Point-to-Point Encryption," page 52 (XML). JCN Gateway: added salesslipnumber reply field in Table 13, "Reply Fields," on page 38. May 2014 April 2014 CyberSource through VisaNet: added new possible values for the MasterCard payment initiation channel. See paymentinitiationchannel in "General Card- Present Request Fields," page 23. FDC Nashville Global: updated the pos_terminalid field and added the pos_ terminalidalternate field. See "General Card-Present Request Fields," page 23. All processors: moved the optional features into a new chapter. See Chapter 2, "Optional Features," on page 10. Card-Present Processing Using the Simple Order API May

6 About This Guide ABOUT GUIDE Audience and Purpose This guide is written for application developers who want to use the CyberSource Simple Order API to integrate credit card processing with card-present data into their order management system. Implementing the CyberSource credit card services requires software development skills. You must write code that uses the API request and reply fields to integrate the credit card services into your existing order management system. Conventions The following special statements are used in this document: Note A Note contains helpful suggestions or references to material not contained in this document. Important An Important statement contains information essential to successfully completing a task or learning a concept. The following text conventions are used in this document: Table 1 Text Conventions Convention Meaning boldface API field names API service names Graphical user interface elements that you must act upon monospace Code in examples or possible values for API fields Card-Present Processing Using the Simple Order API May

7 About This Guide Related Documentation Getting Started with CyberSource Advanced for the Simple Order API (PDF HTML) describes how to get started using the Simple Order API. Credit Card Services Using the Simple Order API (PDF HTML) describes how to integrate CyberSource payment processing services into your business. Refer to the Support Center for complete CyberSource technical documentation: Customer Support For support information about any CyberSource service, visit the Support Center: Card-Present Processing Using the Simple Order API May

8 Introduction to Card-Present Transactions CHAPTER 1 This addendum to Credit Card Services Using the Simple Order API describes cardpresent processing with CyberSource. Supported Processors CyberSource supports card-present credit card transactions for the processors shown in the following table. Table 2 Processors that CyberSource Supports for Card-Present Transactions Processor EMV Magnetic Stripe American Express Direct supports card-present processing only for merchants in the U.S. who are doing business in U.S. dollars. No Yes Chase Paymentech Solutions No Yes CyberSource through VisaNet No Yes FDC Nashville Global Yes Yes FDMS Nashville No Yes GPN No Yes Litle No Yes RBS WorldPay Atlanta No Yes TSYS Acquiring Solutions No Yes Card-Present Processing Using the Simple Order API May

9 Chapter 1 Introduction to Card-Present Transactions Prerequisites Before you start your implementation: Contact your acquirer to find out whether you are allowed to process card-present transactions. Find out from your acquirer and CyberSource Customer Support whether you must have a separate CyberSource merchant ID for your card-present transactions. Contact CyberSource Customer Support to have your account configured to process card-present transactions. For point-to-point encryption (P2PE), you must use an approved device. See "Encryption," page 12. Make sure that you are familiar with the CyberSource Simple Order API for processing e-commerce and mail order/telephone order (MOTO) transactions as described in Credit Card Services Using the Simple Order API. The request and reply fields for card-present transactions are very similar to the request and reply fields for e-commerce/moto transactions. Table 3 Card-Present Fields in Service Requests and Replies Service Request Authorization request Authorization reply Capture request Capture reply Description A card-present authorization request includes additional fields and several existing authorization request fields have different requirements when the request is for a card-present transaction. A card-present authorization reply includes the same fields that are included for an e-commerce/moto transaction. For all processors except CyberSource through VisaNet, a cardpresent capture request includes the same fields that are included for an e-commerce/moto transaction. For CyberSource through VisaNet: A card-present capture request for a restaurant transaction requires additional fields. See the tables of request fields in Appendix A, "API Fields," on page 16. For non-restaurant transactions, a card-present capture request includes the same fields that are included for an e-commerce/moto transaction. A card-present capture reply includes the same fields that are included for an e-commerce/moto transaction. Card-Present Processing Using the Simple Order API May

10 Optional Features CHAPTER 2 Europay, MasterCard, Visa (EMV) Services: Authorization Authorization reversal Capture Credit Processor: FDC Nashville Global Forced captures are not supported for EMV transactions. Note Card Types: Contact: American Express Diners Club Discover JCB MasterCard Visa Contactless: American Express ExpressPay Diners Club Discover JCB MasterCard PayPass Visa paywave Card-Present Processing Using the Simple Order API May

11 Chapter 2 Optional Features EMV (Europay, MasterCard, Visa) is a global standard for exchanging information between chip cards and POS terminals. A chip card is a credit or debit card with an embedded microchip. A chip card also has a magnetic stripe on the back of the card, which can be used for a back-up transaction when the card s chip cannot be read. The EMV standards define the protocols for all levels of transmission between chip cards and chip card processing devices: physical, electrical, data, and application. EMV Cards and Cardholder Verification Methods (CVMs) FDC Nashville Global supports EMV cards that are chip-and-signature cards. For these cards, a signature is the only CVM. EMV Transactions Note When you use the Simple Order API in XML format, you must use version 1.86 or later of the XML schema to implement EMV. EMV transactions are more secure from fraud than are magnetic stripe transactions, which require a visual inspection of the card. Chip-and-PIN cards are more secure from fraud than chip-and-signature cards. When an EMV chip card is used in a POS environment, it generates a cryptogram that changes with each transaction. This dynamic authentication provides an extra layer of security for POS transactions. For an EMV transaction, use the fields documented in "EMV Request Fields," page 19. The following fields and values are specifically for EMV: Request fields: emvrequest_cardsequencenumber emvrequest_combinedtags Reply field: emvreply_combinedtags Values for pos_entrymode: contact: Read from direct contact with chip card. contactless: Read from a contactless interface using chip data. msd: Read from a contactless interface using magnetic stripe data (MSD). Values for pos_terminalcapability: 4: Terminal can read chip cards. 5: Terminal can read contactless chip cards. Card-Present Processing Using the Simple Order API May

12 Chapter 2 Optional Features Encryption Services: Authorization Processor: All processors that are supported for card-present transactions Note When you use the Simple Order API in XML format, you must use version 1.86 or later of the XML schema to use encryption. The following diagram illustrates the steps in a transaction that uses encryption. 1 You send authentication data to your mobile device management (MDM) application to ensure that the user and the device have the required permissions. Your MDM application sends authentication credentials to the device. 2 The card is keyed, swiped, or read. The device generates an encrypted payload and sends it to your server along with the authentication credentials that were created in Step 1. 3 Your server creates a request message and uses the CyberSource API to send the message to CyberSource. 4 CyberSource sends a reply message to your server. The message indicates whether the request succeeded or failed. 5 Your server processes the information in the reply message. The device displays the status of the transaction. Card-Present Processing Using the Simple Order API May

13 Chapter 2 Optional Features CyberSource provides Derived Unique Key Per Transaction (DUKPT) keys to device manufacturers which they inject into their card readers. To encrypt sensitive transaction data, the read heads on a CyberSource-supported card reader use DUKPT for key management along with the Triple Data Encryption Standard (3DES or TDES) algorithm for data encryption. When you use a card reader that encrypts sensitive transaction data, you can securely send transactions to CyberSource for decryption and processing. You can reduce your PCI scope with encryption that is implemented correctly. CyberSource natively supports encrypted output from ID Tech s Shuttle, UniMag II, SecureKey M100, SecureKey M130, and SREDKey devices. The following table indicates whether swiped entry and keyed entry are supported for each device. Table 4 Entry Modes Supported by ID Tech Devices ID Tech Device Swiped Entry Keyed Entry Shuttle Yes No UniMag II Yes No M100 No Yes M130 Yes Yes SREDKey Yes Yes The following tables provide the device reader data values for swiped and keyed entry for each device. Table 5 Device Reader Data Values for Swiped Entry for ID Tech Devices ID Tech Device Shuttle and UniMag II M130 and SREDKey Base64 Value for pos_devicereaderdata RklEPUlEVEVDSC5VbmlNYWcuQW5 kcm9pzc5tzgt2mq== RklEPUlEVEVDSC5TZWN1cmVLZXk utvnsllnka3yx Hex Value for pos_devicereaderdata d e556e694d61672e4 16e64726f69642e53646b D E B6 5792E4D53522E53646B7631 Table 6 Device Reader Data Values for Keyed Entry for ID Tech Devices ID Tech Device M100, M130, and SREDKey Base64 Value for pos_devicereaderdata RklEPUlEVEVDSC5TZWN1cmVLZXk uu2rrdje= Hex Value for pos_devicereaderdata D E B6 5792E53646B7631 Card-Present Processing Using the Simple Order API May

14 Chapter 2 Optional Features Perform the following steps to enable CyberSource to process the native output from ID Tech s Shuttle, UniMag II, M100, M130, and SREDKey devices: Step 1 Step 2 Step 3 Use the following command to instruct the device to output the data in USB human interface device (HID) mode: Command The device outputs the data as a hex ByteArray. Convert the hex ByteArray to a string representation of the hex ByteArray. For example, if a hex byte is A1, converting it to an ASCII string results in the asterisk character (*) but converting it to a string representation of the hex byte results in A1. Set the pos_paymentdata field to the string representation of the hex ByteArray. For all other devices, use the CyberSource Common Track Format ID to send encrypted data to CyberSource. To use the Common Track specification, you must receive track 1 or track 2 data from the device, reformat the data, and add redundancy checks. For a copy of the Common Track specification, contact your CyberSource account representative. The following table provides the device reader data values for the CyberSource Common Track Format ID. Table 7 Device Reader Data Values for CyberSource Common Track Format ID Format ID Common Track Base64 Value for pos_devicereaderdata RklEPUNPTU1PTi5FbmNyeXB0ZWR UcmFja3MuU2RrdjE= Hex Value for pos_devicereaderdata d434f4d4d4f4e2e456e b732e53646b7631 You must use hardware injected with Visa cryptography keys. If you have a specific device that you want to use and it is not in the table of supported devices, contact CyberSource Customer Support to learn whether your desired device can be injected with Visa Inc. cryptography keys and certified for use. Visa Inc. cryptography services work with DUKPT key management and 3DES encryption technologies. For security reasons, you cannot store CyberSource transaction credentials on a mobile device. You can store CyberSource transaction credentials in a secure manner on a file server or a workstation. CyberSource transaction credentials include your merchant ID, transaction security keys, and CyberSource certificates. For information about certificates and security keys, see Creating and Using Security Keys. To support this security requirement, point-of-sale (POS) devices that use the card encryption capabilities supported by CyberSource do not transact directly with CyberSource. Instead, POS devices use an application, an intermediate server, or device management software that transacts directly with CyberSource. Card-Present Processing Using the Simple Order API May

15 Chapter 2 Optional Features For a transaction that uses encryption, use the fields documented in "P2PE Request Fields (Recommended)," page 18. The following fields are specifically for encryption: pos_devicereaderdata pos_encodingmethod pos_encryptionalgorithm pos_paymentdata For examples of P2PE requests and replies, see: Name-value pair examples: "Authorization Using Point-to-Point Encryption," page 43 XML examples: "Authorization Using Point-to-Point Encryption," page 52 Payment Network Tokenization Payment network tokenization enables you to request a credit card authorization with a token instead of a primary account number (PAN). For information about adding payment network tokenization functionality to an order management system that already uses CyberSource credit card services, see the Payment Network Tokenization Using the Simple Order API. Card-Present Processing Using the Simple Order API May

16 API Fields APPENDIX A Important When you send an authorization, authorization reversal, capture, or credit request that includes card-present data, you must include the basic fields required for every authorization, authorization reversal, capture, or credit request. For information about card-not-present fields required for these requests, see Credit Card Services Using the Simple Order API. XML Schema Versions For general information about the XML schema versions, see Getting Started with CyberSource Advanced for the Simple Order API.The following table specifies the Simple Order API version to use for each processor for clear-text card-present transactions and card-present transactions that use point-to-point encryption (P2PE). Table 8 Simple Order API XML Schema Versions for Card-Present Transactions Processor Version for P2PE Transactions Version for Clear Text Transactions American Express Direct 1.86 or later 1.27 or later Chase Paymentech Solutions 1.86 or later 1.25 or later CyberSource through VisaNet 1.86 or later 1.69 or later FDC Nashville Global 1.86 or later 1.24 or later FDMS Nashville 1.86 or later 1.29 or later GPN 1.86 or later 1.26 or later Litle 1.86 or later 1.58 or later RBS WorldPay Atlanta 1.86 or later 1.48 or later TSYS Acquiring Solutions 1.86 or later 1.13 or later Card-Present Processing Using the Simple Order API May

17 Appendix A API Fields Formatting Restrictions Unless otherwise noted, all field names are case sensitive and all fields accept special characters such #, and %. Note The values of the item_#_ fields must not contain carets (^) or colons (:) because these characters are reserved for use by the CyberSource services. Values for request-level and item-level fields must not contain new lines or carriage returns. However, they can contain embedded spaces and any other printable characters. CyberSource removes all leading and trailing spaces. Data Type Definitions For more information about these data types, see the World Wide Web Consortium (W3C) XML Schema Part 2: Datatypes specification. Data Type Description Integer Whole number {..., -3, -2, -1, 0, 1, 2, 3,...} String Sequence of letters, numbers, spaces, and special characters Card-Present Processing Using the Simple Order API May

18 Appendix A API Fields P2PE Request Fields (Recommended) Table 9 P2PE Request Fields Field Description Used By: Required (R) or Optional (O) Data Type & Length pos_devicereaderdata pos_encodingmethod pos_ encryptionalgorithm pos_paymentdata Data that identifies the card reader. This data enables CyberSource to parse the data that is in the pos_paymentdata field. For possible values, see "Encryption," page 12. Encoding method that was applied to the data in the pos_devicereaderdata and pos_ paymentdata fields. When sensitive data must be included in the authorization reply message that CyberSource sends you, CyberSource uses this encoding method to encrypt the sensitive data. Possible values: Base64 Hex Encryption algorithm that was used to encrypt the data in the pos_paymentdata field. Set this value to TDES. See "Encryption," page 12. Encrypted payment data from a card reader. See "Encryption," page 12. ccauthservice (O) String (512) ccauthservice (O) String (6) ccauthservice (O) String (4) ccauthservice (O) String (2048) Card-Present Processing Using the Simple Order API May

19 Appendix A API Fields EMV Request Fields Table 10 EMV Request Fields Field Description Used By: Required (R) or Optional (O) emvrequest_ cardsequencenumber Number assigned to a specific card when two or more cards are associated with the same primary account number. This value enables issuers to distinguish among multiple cards that are linked to the same account. This value can also act as a tracking tool when reissuing cards. When this value is available, it is provided by the chip reader. When the chip reader does not provide this value, do not include this field in your request. See "Europay, MasterCard, Visa (EMV)," page 10. ccauthservice (O) Data Type & Length String with numbers only (3) Card-Present Processing Using the Simple Order API May

20 Appendix A API Fields Table 10 EMV Request Fields (Continued) Field Description Used By: Required (R) or Optional (O) emvrequest_ combinedtags EMV data that is transmitted from the chip card to the issuer, and from the issuer to the chip card. The EMV data is in the tag-length-value format and includes chip card tags, terminal tags, and transaction detail tags. See "Europay, MasterCard, Visa (EMV)," page 10. For information about the individual tags, see the Application Specification section in the EMV 4.3 Specifications: Important The following tags contain sensitive information and must not be included in this field: 56: Track 1 equivalent data 57: Track 2 equivalent data 5A: Application PAN 5F20: Cardholder name 5F24: Application expiration date 99: Transaction PIN 9F0B: Cardholder name (extended) 9F1F: Track 1 discretionary data 9F20: Track 2 discretionary data ccauthservice (O) ccauthreversalservice (O) cccaptureservice (See description) cccreditservice (See description) Data Type & Length FDC Nashville Global: String (999) For information about the individual tags, see the Application Specification section in the EMV 4.3 Specifications: For captures, this field is required for contact EMV transactions. Otherwise, it is optional. For credits, this field is required for contact EMV stand-alone credits and contactless EMV stand-alone credits. Otherwise, it is optional. Important For contact EMV captures, contact EMV stand-alone credits, and contactless EMV stand-alone credits, you must include the following tags in this field. For all other types of EMV transactions, the following tags are optional. 95: Terminal verification results 9F10: Issuer application data 9F26: Application cryptogram Card-Present Processing Using the Simple Order API May

21 Appendix A API Fields Table 10 pos_environment EMV Request Fields (Continued) Field Description Used By: Required (R) or Optional (O) Operating environment. Possible values: 0: No terminal used or unknown environment. 1: On merchant premises, attended. 2: On merchant premises, unattended, or cardholder terminal. Examples: oil, kiosks, self-checkout, home computer, mobile telephone, personal digital assistant (PDA). Cardholder terminal is supported only for MasterCard transactions on CyberSource through VisaNet. 3: Off merchant premises, attended. Examples: portable POS devices at trade shows, at service calls, or in taxis. 4: Off merchant premises, unattended, or cardholder terminal. Examples: vending machines, home computer, mobile telephone, PDA. Cardholder terminal is supported only for MasterCard transactions on CyberSource through VisaNet. 5: On premises of cardholder, unattended. 9: Unknown delivery mode. S: Electronic delivery of product. Examples: music, software, or etickets that are downloaded over the internet. T: Physical delivery of product. Examples: music or software that is delivered by mail or by a courier. This field is supported only for American Express Direct and CyberSource through VisaNet. CyberSource through VisaNet For MasterCard transactions, the only valid values are 2 and 4. Data Type & Length ccauthservice (O) String (1) Card-Present Processing Using the Simple Order API May

22 Appendix A API Fields Clear Text Request Fields Table 11 Clear Text Request Fields Field Description Used By: Required (R) or Optional (O) pos_servicecode MasterCard service code that is included in the track data. You can extract the service code from the track data and provide it in this API field. pos_trackdata This field is supported only for MasterCard and only on CyberSource through VisaNet. Card s track 1 and 2 data. For all processors except FDMS Nashville, this value consists of one of the following: Track 1 data Track 2 data Data for both tracks 1 and 2 For FDMS Nashville, this value consists of one of the following: Track 1 data Data for both tracks 1 and 2 Example: %B ^SMITH/ JOHN ^ ?; = ? Data Type & Length ics_auth (O) String (3) ccauthservice: FDC Nashville Global: Required if pos_entrymode= contact, contactless, msd, or swiped; otherwise, not used. All other processors: Required if pos_ entrymode= swiped; otherwise, not used. String (119) Card-Present Processing Using the Simple Order API May

23 Appendix A API Fields General Card-Present Request Fields Table 12 General Card-Present Request Fields Field Description Used By: Required (R) or Optional (O) billto_city Credit card billing city. ccauthservice: billto_country Credit card billing country. Use the twocharacter ISO Standard Country Codes. Chase Paymentech Solutions: Optional. Litle: Optional. TSYS Acquiring Solutions: Required when ccauthservice_ billpayment=true and pos_ entrymode=keyed. All other processors: Not used. ccauthservice: Chase Paymentech Solutions: Optional. Litle: Optional. Data Type & Length String (50) String (2) TSYS Acquiring Solutions: Required when ccauthservice_ billpayment=true and pos_ entrymode=keyed. All other processors: Not used. Card-Present Processing Using the Simple Order API May

24 Appendix A API Fields Table 12 billto_ billto_firstname General Card-Present Request Fields (Continued) Field Description Used By: Required (R) or Optional (O) Customer s address, including full domain name. Format: name@host.domain Customer s first name. Value should match value on card. ccauthservice: Chase Paymentech Solutions: Optional. Litle: Optional. TSYS Acquiring Solutions: Required when ccauthservice_ billpayment=true and pos_ entrymode=keyed. All other processors: Not used. ccauthservice: Chase Paymentech Solutions: Optional. Litle: Optional. Data Type & Length String (255) String (60) TSYS Acquiring Solutions: Required when ccauthservice_ billpayment=true and pos_ entrymode=keyed. All other processors: Not used. billto_lastname Customer s last name. Value should match value on card. ccauthservice: Chase Paymentech Solutions: Optional. String (60) Litle: Optional. RBS WorldPay Atlanta: Optional. TSYS Acquiring Solutions: Required when ccauthservice_ billpayment=true and pos_ entrymode=keyed. All other processors: Not used. Card-Present Processing Using the Simple Order API May