Level II and Level III Processing Using the Simple Order API

Transcription

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

2 Contact Information For general information about our company, products, and services, go to For sales questions about any Service, or call or (toll free in the United States). For support information about any Service, visit the Support Center at Copyright 2015 Corporation. All rights reserved. Corporation ("") furnishes this document and the software described in this document under the applicable agreement between the reader of this document ("You") and ("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. 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. 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 Corporation's standard commercial agreement for this software. Unpublished rights reserved under the copyright laws of the United States. Trademarks, The Power of Payment, Payment Manager, Risk Manager, Decision Manager, Connect, Authorize.Net, and echeck.net are trademarks and/or service marks of 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 6 About This Guide 7 Audience and Purpose 7 Conventions 7 Related Documentation 8 Customer Support 8 Chapter 1 Introduction to and Processing 9 Prerequisites 9 Supported Processors and Card Types 10 About and Data 11 and Data Processing 11 Requesting Captures and Credits with and Data 12 Using Decimals and Strings 15 Chapter 2 American Express Direct: 16 Order-Level Fields 17 Item-Level Fields 18 Chapter 3 Chase Paymentech Solutions: and 20 Processor Specification Used 20 Order-Level Fields 21 Item-Level Fields 25 Examples 29 and Processing Using the Simple Order API March

4 Contents Chapter 4 through VisaNet: and 31 Supported Acquirers 31 Order-Level Fields 32 Item-Level Fields 41 Chapter 5 FDC Compass: and 45 Processor Specification Used 45 Order-Level Fields 46 Item-Level Fields 50 Examples 54 Chapter 6 FDC Nashville Global: and 56 Processor Specification 56 Order-Level Fields 57 Item-Level Fields 63 Chapter 7 FDMS Nashville: 69 Order-Level Fields 70 Item-Level Fields 71 Chapter 8 FDMS South: 72 Order-Level Fields 72 Item-Level Fields 74 Chapter 9 GPN: and 76 Processor Specification 76 Order-Level Fields 77 Item-Level Fields 80 Chapter 10 Litle: and 83 Order-Level Fields 84 Item-Level Fields 88 and Processing Using the Simple Order API March

5 Contents Chapter 11 RBS WorldPay Atlanta: and 92 Processor Specification 92 Order-Level Fields 93 Item-Level Fields 97 Examples 100 Chapter 12 TSYS Acquiring Solutions: and 102 Processor Specification 102 Order-Level Fields 103 Item-Level Fields 108 Examples 111 Appendix A Codes for Units of Measurement 113 and Processing Using the Simple Order API March

6 Recent Revisions to This Document REVISIONS Release Changes March 2015 Added a note to the and Data Processing section. See page 11. January 2015 December 2014 through VisaNet: Added new request fields and updated existing request fields. See Chapter 4, " through VisaNet: and," on page 31. Added a note to the description of the taxable API field when it is used for RBS WorldPay Atlanta. This field is required for Visa and MasterCard transactions that involve Level II data even when item_#_taxamount is set to 0. See taxable, page 93. August 2014 through VisaNet: updated the list of supported acquirers. See Chapter 4, " through VisaNet: and," on page 31. July 2014 through VisaNet: updated the list of supported acquirers. See Chapter 4, " through VisaNet: and," on page 31. June 2014 through VisaNet: updated the list of supported acquirers. See Chapter 4, " through VisaNet: and," on page 31. and Processing Using the Simple Order API March

7 About This Guide ABOUT GUIDE Audience and Purpose This guide is written for application developers who want to use the Simple Order API to integrate credit card processing with or data into their order management system. Implementing the 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 with or data 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: Convention Meaning bold Field and service names in text; for example: Include the ics_applications field. Items that you are instructed to act upon; for example: Click Save. and Processing Using the Simple Order API March

8 About This Guide Convention Meaning monospace XML elements. Code examples and samples. Text that you enter in an API environment; for example: Set the davservice_run field to true. Related Documentation Getting Started with 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 payment processing services into your business. Refer to the Support Center for complete technical documentation: Customer Support For support information about any service, visit the Support Center: and Processing Using the Simple Order API March

9 Introduction to and Processing CHAPTER 1 This addendum to Credit Card Services Using the Simple Order API describes: processing for American Express, Visa, and MasterCard processing for Visa and MasterCard After this introductory chapter, there is a chapter for each processor that supports or. Important This document provides guidelines that indicate which fields are needed to obtain the best interchange rates. These guidelines are based on industry information. recommends that you contact your acquirer for the most current information because the payment card companies can change their requirements at any time. Prerequisites Prerequisites for Processing. To activate processing for American Express, contact American Express and Customer Support. Prerequisites for Processing. Check with your processor to determine whether you need to add processing to your contract or account setup. When you are ready to go live with processing, contact Customer Support to have your account configured to process data. If your account is not enabled, and you try to send live transactions, you will receive an error for invalid data. and Processing Using the Simple Order API March

10 Chapter 1 Introduction to and Processing Supported Processors and Card Types Table 1 Processor Supported Processors and Card Types Card Types Supported Card Types Supported American Express Direct American Express None Chase Paymentech Solutions Visa MasterCard American Express Visa MasterCard through VisaNet FDC Compass FDC Nashville Global FDMS Nashville FDMS South GPN Litle RBS WorldPay Atlanta TSYS Acquiring Solutions Visa MasterCard American Express Visa MasterCard American Express Visa MasterCard American Express Visa MasterCard Visa MasterCard Visa MasterCard Visa MasterCard American Express Visa MasterCard Visa MasterCard Visa MasterCard Visa MasterCard Visa MasterCard None None Visa MasterCard Visa MasterCard Visa MasterCard Visa MasterCard and Processing Using the Simple Order API March

11 Chapter 1 Introduction to and Processing About and Data cards, which are also called Type II cards, provide customers with additional information on their credit card statements about their purchases. cards enable customers to easily track the amount of sales tax they pay and to reconcile transactions with a unique customer code. There are two categories of cards: Business/corporate cards are given by businesses to employees for business-related expenses such as travel and entertainment or for corporate supplies and services. Purchase/procurement cards are used by businesses for expenses such as supplies and services. These cards are often used as replacements for purchase orders. Each processor supports a different set of fields. If your business is not in the United States, you must use additional fields. data can be provided for purchase cards, which are special credit cards that employees use to make purchases for their company. You provide additional detailed information the data about the purchase card order during the settlement process. The data is forwarded to the company that made the purchase, and it enables the company to manage its purchasing activities. and Data Processing Important Only submit level II and level III data for level II and level III cards, otherwise the transaction may fail and result in errors from your processor during clearing. recommends submitting level II data for only purchase/ procurement cards and level III data for only business/corporate cards. does not store the and data. Instead, it functions as a passthrough service for the data. If you request multiple partial captures or credits for a particular order, you must supply the and data in each request. and Processing Using the Simple Order API March

12 Chapter 1 Introduction to and Processing enforces only the minimal level of field validation to avoid interfering with the business policies between you and any company that purchases your services. Note temporarily disables your account s processing capability and contacts you if your transactions produce batching errors when the information is sent to the processor. If this happens, your request is not rejected, but you receive a field in the reply indicating that the information in the request has been ignored and not sent to the processor. For captures, the reply field is cccapturereply_purchasinglevel3enabled. For credits, the reply field is cccreditreply_purchasinglevel3enabled. The possible values for the reply field are: Y: the data was included in the request to the processor. N: the data was not included in the request to the processor. Requesting Captures and Credits with and Data To include data in a capture or credit request: Step 1 Step 2 Authorize a credit card payment. Capture the authorization. Include the following information in the capture request: data: see the chapter in this document for the processor you are using. Also see "Using Decimals and Strings," page 15. Important If you omit required fields from a request, the transaction does not result in an error. Instead, it is processed as a regular non- transaction. However, your processor could charge you penalties or increase your fees. Contact your processor to ensure you understand your processor s specific requirements for transactions. Basic fields required for every capture request. For more information, see Credit Card Services Using the Simple Order API. and Processing Using the Simple Order API March

13 Chapter 1 Introduction to and Processing Step 3 If necessary, credit the payment. Include the following information in the credit request: data: see the chapter in this document for the processor you are using. Also see "Using Decimals and Strings," page 15. Important If you omit required fields from a request, the transaction does not result in an error. Instead, it is processed as a regular non- transaction. However, your processor could charge you penalties or increase your fees. Contact your processor to ensure you understand your processor s specific requirements for transactions. RBS WorldPay Atlanta does not require data for credits. Note Basic fields required for every credit request. For more information, see Credit Card Services Using the Simple Order API. To include data in a capture or credit request: Step 1 Step 2 Authorize a credit card payment. recommends that for transactions you include the total order amount in the authorization request, even though it is not required. Doing so ensures that uses your total order amount and that the capture or credit request total amount matches the original authorization total amount. The field to use in the authorization request is purchasetotals_grandtotalamount. Capture the authorization. Include the following information in the capture request: and data: see the chapter in this document for the processor you are using. Also see "Using Decimals and Strings," page 15. Purchasing level field: the field name is cccaptureservice_purchasinglevel. Set this field to 3 to indicate that the request includes data. Basic fields required for every capture request. For more information, see Credit Card Services Using the Simple Order API. Step 3 Check the capture reply message. and Processing Using the Simple Order API March

14 Chapter 1 Introduction to and Processing The reply message includes a field that indicates whether sent the information to the processor. The field name is cccapturereply_purchasinglevel3enabled. The possible values are: Y: the account is enabled for transactions. The data was included in the request to the processor. N: the account is not enabled for transactions. The data was not included in the request to the processor. If your account is not enabled for data or if you did not include the purchasing level field in your request, does not include the data in the request sent to the processor. Step 4 If necessary, credit the payment. Include the following information in the credit request: and data: see the chapter in this document for the processor you are using. Also see "Using Decimals and Strings," page 15. RBS WorldPay Atlanta does not require data for credits. Note Purchasing level field: the field name is cccreditservice_purchasinglevel Set this field to 3 to indicate that the request includes data. Basic fields required for every credit request. For more information, see Credit Card Services Using the Simple Order API. Step 5 Check the capture reply message. The reply message includes a field that indicates whether sent the information to the processor. The field name is cccapturereply_purchasinglevel3enabled. The possible values are: Y: the account is enabled for transactions. The data was included in the request to the processor. N: the account is not enabled for transactions. The data was not included in the request to the processor. If your account is not enabled for data or if you did not include the purchasing level field in your request, does not include the data in the request sent to the processor. and Processing Using the Simple Order API March

15 Chapter 1 Introduction to and Processing Using Decimals and Strings uses decimal points in all amount and tax rate fields; does not use implied decimal points. For example, if the amount of the product being purchased is 29.95, set that field to For tax rates used with transactions, you need to include a decimal point in the value. For example, if a tax rate is 1%, you should set that field to For many of the fields described in this document, Visa and MasterCard permit different lengths for alphanumeric (string) input. accepts any length you provide. If the value you provide is longer than the payment card company permits, truncates the value, keeping the left-most portion of the value. If the value you provide is shorter than the payment card company requires, pads the field before sending it to the processor. and Processing Using the Simple Order API March

16 American Express Direct: CHAPTER 2 Note On American Express Direct, data is supported only for merchants in the U.S. who are doing business in U.S. dollars. Important This document provides guidelines that indicate which fields are needed to obtain the best interchange rates. These guidelines are based on industry information. recommends that you contact your acquirer for the most current information because the payment card companies can change their requirements at any time. Fields for amounts and tax rates use a string data type. However, you should include only numbers and a decimal point in those fields. Important When you send a capture or credit request with data, you must include the required fields for every capture or credit request. For information about the non-level-ii fields required for capture and credit requests, see Credit Card Services Using the Simple Order API. and Processing Using the Simple Order API March

17 Chapter 2 American Express Direct: Order-Level Fields Table 2 Order-Level Fields for American Express Direct American Express Direct &Length billto_firstname Requestor Name Requestor s first name. Include this value when the cardmember is not the person who ordered or purchased the product or service. American Express (O) String (See description) This field and billto_lastname together should not exceed 37 characters. billto_lastname Requestor Name Requestor s last name. Include this value when the cardmember is not the person who ordered or purchased the product or service. American Express (O) String (See description) This field and billto_firstname together should not exceed 37 characters. amexdatataa1 amexdatataa2 amexdatataa3 amexdatataa4 Charge 1 Charge 2 Charge 3 Charge 4 Four Transaction Advice Addendum fields. These fields are used to display descriptive information about a transaction on your customer s American Express card statement. If you are sending any TAA fields, start with amexdatataa1, then...taa2, and so on. Skipping a TAA field causes subsequent TAA fields to be ignored. American Express (O but recommended) String (40) Contact Customer Support if you plan to use these fields so that your account can be configured appropriately. userpo Cardmember Reference Number Value used by your customer to identify the order. This value is typically a purchase order number, cost center, or project number. American Express (O) String (17) and Processing Using the Simple Order API March

18 Chapter 2 American Express Direct: Table 2 Order-Level Fields for American Express Direct (Continued) American Express Direct &Length shipto_ postalcode Ship-to Postal Code Postal code for the shipping address. The postal code must consist of 5 to 9 digits. The postal code is required. You can provide the postal code by including shipto_postalcode in the request or by making sure the postal code is set for your account. American Express (See description) String (10) If the shipping country is the U.S., the 9- digit postal code must follow this format: [5 digits][dash][4 digits] Example: If the shipping country is Canada, the 6- digit postal code must follow this format: [alpha][numeric][alpha] [space][numeric][alpha] [numeric] Example: A1B 2C4 Item-Level Fields Table 3 Item-Level Fields for American Express Direct American Express Direct & Length item_#_ invoicenumber No corresponding American Express Direct field Field to support an invoice number for a transaction.you must specify the number of line items that will include an invoice number. By default, the first line item will include an invoice number field. The invoice number field can be included for up to 10 line items. American Express (O) String (23) and Processing Using the Simple Order API March

19 Chapter 2 American Express Direct: Table 3 Item-Level Fields for American Express Direct (Continued) American Express Direct & Length item_#_quantity Charge Item Quantity 1 Quantity of the product being purchased. The default value is 1. American Express (O but recommended) Nonnegative integer (3) item_#_ taxamount Total Tax Amount Total tax to apply to the product. adds all the item_#_ taxamount values to calculate the Total Tax Amount that is sent to the processor. American Express (R) Integer (12) The item_#_taxamount value cannot be negative. This field is additive. For example, if you send one item with unitprice of and taxamount of 0.80, and you send another item with unitprice of and taxamount of 1.60, the total amount authorized will be for 32.40, not with 2.40 of tax included. The item_#_taxamount and the item_#_unitprice must be in the same currency. If you want to include item_#_ taxamount and also request the taxservice service, see Tax Calculation Service Using the Simple Order API. item_#_unitprice Charge Item Amount 1 Per-item price of the product. This value cannot be negative. You can include a decimal point (.) in this field, but you cannot include any other special characters. The amount will be truncated at the request level to the correct number of decimal places. American Express (O but recommended) Integer (12) and Processing Using the Simple Order API March

20 Chase Paymentech Solutions: and CHAPTER 3 Important This document provides guidelines that indicate which fields are needed to obtain the best interchange rates. These guidelines are based on industry information. recommends that you contact your acquirer for the most current information because the payment card companies can change their requirements at any time. Fields for amounts and tax rates use a string data type. However, you should include only numbers and a decimal point in those fields.. Important When you send a capture or credit request with and/or data, you must include the required fields for every capture or credit request. For information about the non-level-ii and non-level-iii fields required for capture and credit requests, see Credit Card Services Using the Simple Order API. Processor Specification Used The specifications that used to implement processing for Chase Paymentech Solutions are: Paymentech s 120-Byte Technical Specification, Rev 2.0.0, December 8, 2003 Paymentech s 96-Byte and 120-Byte Batch Technical Specification Addendum, Rev , April 1, 2004 The records referenced are: Procurement Level 3 Visa: Order Level Record, Record #1, Record #2 Procurement Level 3 MasterCard: Order Level Record, Record #1, Record #2 and Processing Using the Simple Order API March

21 Chapter 3 Chase Paymentech Solutions: and Order-Level Fields Table 4 Order-Level Fields for Chase Paymentech Solutions Chase Paymentech Solutions &Length cccaptureservice_ purchasinglevel No corresponding Chase Paymentech Solutions field Flag that indicates the capture or credit request is for processing. Set to 3. See "Requesting Captures and Credits with and Data," page 12. Visa (R for captures; not used for credits) MasterCard (R for captures; not used for credits) String (1) cccreditservice_ purchasinglevel No corresponding Chase Paymentech Solutions field Flag that indicates the capture or credit request is for processing. Set to 3. See "Requesting Captures and Credits with and Data," page 12. Visa (R for credits; not used for captures) MasterCard (R for credits; not used for captures) String (1) amexdatataa1 amexdatataa2 amexdatataa3 amexdatataa4 TAA1 TAA2 TAA3 TAA4 Four Transaction Advice Addendum fields. These fields are used to display descriptive information about a transaction on your customer s American Express card statement. If you are sending any TAA fields, start with amexdatataa1, then...taa2, and so on. Skipping a TAA field causes subsequent TAA fields to be ignored. American Express (See description) String (40) Contact Customer Support if you plan to use these fields so that your account can be configured appropriately. The amexdatataa1 field is required for transactions for American Express cards for Chase Paymentech Solutions, but the other TAA fields are optional. However, if you are including the request ID (cccreditservice_capturerequestid) in a credit request, you are not required to include amexdatataa1. and Processing Using the Simple Order API March

22 Chapter 3 Chase Paymentech Solutions: and Table 4 Order-Level Fields for Chase Paymentech Solutions (Continued) Chase Paymentech Solutions &Length userpo Customer Reference Number Value used by your customer to identify the order. This value is typically a purchase order number. recommends that you do not populate the field with all zeros or nines. Visa (R for purchase/ procurement cards; otherwise O) String (25) MasterCard (R for purchase/ procurement cards; otherwise O) American Express (R for purchase/ procurement cards; otherwise O) Visa (R for purchase/ procurement cards; otherwise O) MasterCard (R for purchase/ procurement cards; otherwise O) othertax_ alternatetaxamount Alternate Tax Amount Total amount of alternate tax for the order. String (10) othertax_ alternatetaxid Alternate Tax ID Your tax ID number to use for the alternate tax amount. Required if you set Alternate Tax Amount to any value, including zero. You may send this field without sending Alternate Tax Amount. MasterCard (See description) String (15) othertax_ vattaxamount VAT/Tax Amount Total amount of VAT or other tax included in the order. String (13) and Processing Using the Simple Order API March

23 Chapter 3 Chase Paymentech Solutions: and Table 4 Order-Level Fields for Chase Paymentech Solutions (Continued) Chase Paymentech Solutions &Length othertax_ vattaxrate VAT/Tax Rate Rate of VAT or other tax for the order. Example: (=4%) String (4) Valid range: 0.01 to 0.99 (1% to 99%, with only whole percentage values accepted; values with additional decimal places will be truncated) purchasetotals_ discountamount Discount Amount Applied to Order Total discount applied to the order. For example: a discount off the order total. Visa (R for Level III interchange) String (13) purchasetotals_ dutyamount Duty Amount Total charges for any import or export duties included in the order. Visa (R for Level III interchange) MasterCard (R for interchange) Visa: String (13) MasterCard : String (10) purchasetotals_ freightamount Freight Amount Total freight or shipping and handling charges for the order. When you include this field in your request, you must also include purchasetotals_ grandtotalamount. Visa (R for Level III interchange) MasterCard (R for interchange) Visa: String (13) MasterCard : String (10) purchasetotals_ grandtotalamount No corresponding Chase Paymentech Solutions field Grand total for the entire capture or credit request. MasterCard (R) String (15) and Processing Using the Simple Order API March

24 Chapter 3 Chase Paymentech Solutions: and Table 4 Order-Level Fields for Chase Paymentech Solutions (Continued) Chase Paymentech Solutions &Length shipfrom_ postalcode Ship From ZIP/ Postal Code Postal code for the address from which the goods are shipped, which is used to determine nexus. The default is the postal code associated with your account. The postal code must consist of 5 to 9 digits. If the billing country is the U.S., the 9- digit postal code must follow this format: [5 digits][dash][4 digits] Example: MasterCard (R for best rate. Do not use all zeros or nines.) String (10) If the billing country is Canada, the 6- digit postal code must follow this format: [alpha][numeric][alpha] [space][numeric][alpha] [numeric] Example: A1B 2C4 shipto_country Destination Country Code Country to ship the product to. Use the two-character ISO Standard Country Codes. Visa (R for best rate) String (2) MasterCard (O but recommended) shipto_postalcode Destination ZIP/Postal Code Postal code for the shipping address. This is the same as shipfrom_ postalcode when your customer takes possession of the items at your location. The postal code must consist of 5 to 9 digits. If the shipping country is the U.S., the 9- digit postal code must follow this format: [5 digits][dash][4 digits] Example: Visa (R for best rate) MasterCard (R for best rate. Do not use all zeros or nines.) String (10) If the shipping country is Canada, the 6- digit postal code must follow this format: [alpha][numeric][alpha] [space][numeric][alpha] [numeric] Example: A1B 2C4 and Processing Using the Simple Order API March

25 Chapter 3 Chase Paymentech Solutions: and Item-Level Fields Important The maximum number of items you can have in a Chase Paymentech Solutions transaction is 98. If the number of items exceeds 98, Chase Paymentech Solutions rejects the batch. Table 5 Item-Level Fields for Chase Paymentech Solutions Chase Paymentech Solutions & Length item_#_ commoditycode Item Commodity Code Commodity code used to classify the item. Visa (R for Level III interchange) String (12) item_#_ discountamount Visa: Discount Amount for Line Item MasterCard: Discount Amount Discount applied to the item. Visa (R for Level III interchange) MasterCard (R for interchange) Visa: String (13) MasterCard: String (10) item_#_ discountindicator Discount Indicator Flag that indicates whether the amount is discounted. Possible values: Y: amount is discounted MasterCard (R for interchange) String (1) N: amount is not discounted If you do not provide a value but you set Discount Amount to a value greater than zero, then sets this field to Y. item_#_ grossnetindicator Gross/Net Indicator Flag that indicates whether the tax amount is included in the Line Item Total. Possible values: MasterCard (R) String (1) Y: item amount includes tax amount N: item amount does not include tax amount and Processing Using the Simple Order API March