Card-Present Processing Using the SCMP API
Title Page
Card-Present Processing
Using the SCMP API
Supplement to Credit Card Services
Using the SCMP API
March 2015
CyberSource Corporation HQ | P.O. Box 8999 | San Francisco, CA 94128-8999 | Phone: 800-530-9095
CyberSource Contact Information
For general information about our company, products, and services, go to
http://www.cybersource.com.
For sales questions about any CyberSource Service, email sales@cybersource.com or
call 650-432-7350 or 888-330-2300 (toll free in the United States).
For support information about any CyberSource Service, visit the Support Center at
http://www.cybersource.com/support.
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
252.227-7013 and in similar clauses in the FAR and NASA FAR Supplement.
For civilian agencies. Use, reproduction, or disclosure is subject to restrictions set forth in subparagraphs (a)
through (d) of the Commercial Computer Software Restricted Rights clause at 52.227-19 and the limitations set
forth in CyberSource Corporation's standard commercial agreement for this software. Unpublished rights
reserved under the copyright laws of the United States.
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
CONTENTS
Contents
Recent Revisions to This Document
About This Guide
6
Audience and Purpose
Conventions
6
6
Related Documentation
Customer Support
Chapter 1
7
7
Introduction to Card-Present Transactions
Supported Processors
Prerequisites
Chapter 2
5
8
9
Optional Features
Encryption
10
10
Payment Network Tokenization
Appendix A API Fields
12
13
Formatting Restrictions
Data Type Definitions
13
14
P2PE Request-Level Fields (Recommended)
Clear Text Request-Level Fields
15
16
General Card-Present Request-Level Fields
General Card-Present Offer-Level Fields
Reply Field
8
17
30
31
Card-Present Processing Using the SCMP API | March 2015
3
Contents
Appendix B Examples
32
Sale Using Swiped Track Data
Sale Using Keyed Data
32
33
Authorization Using Point-to-Point Encryption
Card-Present Processing Using the SCMP API | March 2015
34
4
REVISIONS
Recent Revisions to This
Document
Release
Changes
March 2015
All processors that support encryption:
December 2014
Updated Table 4, "Card Readers and Device Reader Data," on page 11.
Updated the description of the pos_encoding_method field in "P2PE
Request-Level Fields (Recommended)," page 15.
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 10.
Updated Table 4, "Card Readers and Device Reader Data," on page 11.
Added P2PE examples. See "Authorization Using Point-to-Point
Encryption," page 34.
JCN Gateway: added sales_slip_number reply field in Table 9, "Reply Field,"
on page 31.
May 2014
CyberSource through VisaNet: added new possible values for the MasterCard
payment initiation channel. See payment_initiation_channel in "General
Card-Present Request-Level Fields," page 17.
FDC Nashville Global: updated the terminal_id field and added the terminal_
id_alternate field. See "General Card-Present Request-Level Fields,"
page 17.
April 2014
All processors: moved the optional features into a new chapter. See
Chapter 2, "Optional Features," on page 10.
February 2014
Chase Paymentech Solutions:
January 2014
The terminal_capability field is required. See "General Card-Present
Request-Level Fields," page 17.
When the terminal_id field is included in the request, the cat_level field is
required. See "General Card-Present Request-Level Fields," page 17.
CyberSource through VisaNet:
Removed the dynamic MCC field from this guide and added it to Credit
Card Services Using the SCMP API.
Card-Present Processing Using the SCMP API | March 2015
5
ABOUT GUIDE
About This Guide
Audience and Purpose
This guide is written for application developers who want to use the CyberSource SCMP
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:
A Note contains helpful suggestions or references to material not contained in
this document.
Note
An Important statement contains information essential to successfully
completing a task or learning a concept.
Important
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 SCMP API | March 2015
6
About This Guide
Related Documentation
Getting Started with CyberSource Advanced for the SCMP API (PDF | HTML)
describes how to get started using the SCMP API.
Credit Card Services Using the SCMP API (PDF | HTML) describes how to integrate
CyberSource payment processing services into your business.
Refer to the Support Center for complete CyberSource technical documentation:
http://www.cybersource.com/support_center/support_documentation
Customer Support
For support information about any CyberSource service, visit the Support Center:
http://www.cybersource.com/support
Card-Present Processing Using the SCMP API | March 2015
7
CHAPTER
Introduction to
Card-Present Transactions
1
This addendum to Credit Card Services Using the SCMP API describes card-present
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 cardpresent 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
No
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 SCMP API | March 2015
8
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 Table 4,
"Card Readers and Device Reader Data," on page 11.
Make sure that you are familiar with the CyberSource SCMP API for processing
e-commerce and mail order/telephone order (MOTO) transactions as described in
Credit Card Services Using the SCMP API. The request and reply fields for cardpresent 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
Description
Authorization request
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.
Authorization reply
A card-present authorization reply includes the same fields that
are included for an e-commerce/MOTO transaction.
Capture request
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:
Capture reply
A card-present capture request for a restaurant transaction
requires additional fields. See the tables of request-level fields
in Appendix A, "API Fields," on page 13.
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 SCMP API | March 2015
9
CHAPTER
Optional Features
2
Encryption
Services:
Authorization
Processor:
All processors that are supported for card-present transactions
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.
Card-Present Processing Using the SCMP API | March 2015
10
Chapter 2
Optional Features
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
information about the status of the transaction.
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 supports the card readers that are listed in the following table.
Table 4
Card Readers and Device Reader Data
Device
Base64 Value for pos_device_
reader_data
Hex Value for pos_device_reader_
data
IDTech (Shuttle, UniMag II,
M100, M130)
RklEPUlEVEVDSC5VbmlNYWcuQW
5kcm9pZC5TZGt2MQ==
4649443d4944544543482e556e694d616
72e416e64726f69642e53646b7631
Infinite Peripherals (Linea Pro 5,
Infinea Tab M, Infinea Tab 4)
RklEPUNPTU1PTi5FbmNyeXB0ZW
RUcmFja3MuU2RrdjE=
4649443d434f4d4d4f4e2e456e63727970
746564547261636b732e53646b7631
Ingenico (ISC250)
RklEPUNPTU1PTi5FbmNyeXB0ZW
RUcmFja3MuU2RrdjE=
4649443d434f4d4d4f4e2e456e63727970
746564547261636b732e53646b7631
You must use hardware injected with Visa Inc. 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 SCMP API | March 2015
11
Chapter 2
Optional Features
For a transaction that uses encryption, use the fields documented in "P2PE Request-Level
Fields (Recommended)," page 15. The following fields are specifically for encryption:
pos_device_reader_data
pos_encoding_method
pos_encryption_algorithm
pos_payment_data
For examples of P2PE requests and replies, see "Authorization Using Point-to-Point
Encryption," page 34.
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 Payment Network Tokenization Using the SCMP
API.
Card-Present Processing Using the SCMP API | March 2015
12
APPENDIX
API Fields
Important
A
When you send an authorization or capture request that includes card-present
data, you must include the basic fields required for every authorization or
capture request. For information about card-not-present fields required for
these requests, see Credit Card Services Using the SCMP API.
Formatting Restrictions
Unless otherwise noted, all fields are order and case insensitive and the fields accept
special characters such as @, #, and %.
Note
Values for request-level and offer-level fields must not contain carets (^) or
colons (:). However, they can contain embedded spaces and any other
printable characters. When you use more than one consecutive space,
CyberSource removes the extra spaces.
Card-Present Processing Using the SCMP API | March 2015
13
Appendix A
API Fields
Data Type Definitions
Data Type
Description
Date and time
Format is YYYY-MM-DDThhmmssZ, where:
T separates the date and the time
Z indicates Coordinated Universal Time (UTC), which is also known as
Greenwich Mean Time
Example: 2012-08-11T224757Z equals 10:47:57 P.M. on August 11, 2012
Decimal
Number that includes a decimal point
Examples: 23.45, -0.1, 4.0, 90809.0468
Integer
Whole number {..., -3, -2, -1, 0, 1, 2, 3, ...}
Nonnegative integer
Whole number greater than or equal to zero {0, 1, 2, 3, ...}
Positive integer
Whole number greater than zero {1, 2, 3, ...}
String
Sequence of letters, numbers, spaces, and special characters
Card-Present Processing Using the SCMP API | March 2015
14
Appendix A
API Fields
P2PE Request-Level Fields
(Recommended)
Table 5
P2PE Request-Level Fields (Recommended)
Field
Description
Used By:
Required (R)
or Optional (O)
Data Type
& Length
pos_device_reader_
data
Data that identifies the card reader. This data
enables CyberSource to parse the data that is
in the pos_payment_data field. For the
possible values, see Table 4, "Card Readers
and Device Reader Data," on page 11.
ics_auth (O)
String (512)
pos_encoding_method
Encoding method that was applied to the data
in the pos_device_reader_data and pos_
payment_data 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:
ics_auth (O)
String (6)
Base64
Hex
pos_encryption_
algorithm
Encryption algorithm that was used to encrypt
the data in the pos_payment_data field. Set
this field to TDES. See "Encryption," page 10.
ics_auth (O)
String (4)
pos_payment_data
Encrypted payment data from a card reader.
See "Encryption," page 10.
ics_auth (O)
String (2048)
Card-Present Processing Using the SCMP API | March 2015
15
Appendix A
API Fields
Clear Text Request-Level Fields
Table 6
Clear Text Request-Level Fields
Field
Description
Used By:
Required (R)
or Optional (O)
Data Type
& Length
pos_service_code
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.
ics_auth (O)
String (3)
ics_auth (Required if
pos_entry_
mode=swiped;
otherwise, not used)
String (119)
track_data
This field is supported only for MasterCard and
only for 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: %B4111111111111111^SMITH/
JOHN
^1612101976110000868000000?;41
11111111111111=16121019761186800000?
Card-Present Processing Using the SCMP API | March 2015
16
Appendix A
API Fields
General Card-Present
Request-Level Fields
Table 7
General Card-Present Request-Level Fields
Field
Description
Used By:
Required (R)
or Optional (O)
Data Type
& Length
bill_address1
Credit card billing street address as it appears
in credit card issuer’s records.
ics_auth:
FDMS
Nashville:
String (20)
FDMS Nashville:
When the street name is numeric, it must be
sent in numeric format. For example, if the
address is One First Street, it must be sent as
1 1st Street.
bill_address2
Used for additional address information. For
example:
Attention: Accounts Payable
FDMS Nashville:
Required if keyed;
Not used if swiped.
TSYS Acquiring
Solutions: Required
when bill_
payment=true and
pos_entry_
mode=keyed.
All other processors:
Optional
ics_auth (O)
Credit card billing city.
Card-Present Processing Using the SCMP API | March 2015
FDMS
Nashville:
String (20)
All other
processors:
String (60)
FDMS Nashville:
bill_address1 and bill_address2 together
cannot exceed 20 characters.
bill_city
All other
processors:
String (60)
ics_auth:
Chase Paymentech
Solutions: Optional.
Litle: Optional.
TSYS Acquiring
Solutions: Required
when bill_
payment=true and
pos_entry_
mode=keyed.
All other processors:
Not used.
String (50)
17
Appendix A
Table 7
API Fields
General Card-Present Request-Level Fields (Continued)
Field
Description
Used By:
Required (R)
or Optional (O)
Data Type
& Length
bill_country
Credit card billing country. Use the ISO
Standard Country Codes.
ics_auth:
String (2)
Chase Paymentech
Solutions: Optional.
Litle: Optional.
TSYS Acquiring
Solutions: Required
when bill_
payment=true
and pos_entry_
mode=keyed.
All other processors:
Not used.
ics_auth (O)
String (5)
ics_auth:
String (2)
bill_payment
Indicates payment for bill or payment towards
existing contractual loan. For information about
Visa Bill Payments and Visa Debt
Repayments, see Credit Card Services Using
the SCMP API.
Possible values:
bill_state
false (default): Not a bill payment or loan
payment.
true: Bill payment or loan payment.
Credit card billing state or province. Use the
State, Province, and Territory Codes for the
United States and Canada.
Card-Present Processing Using the SCMP API | March 2015
Chase Paymentech
Solutions: Optional.
Litle: Optional.
TSYS Acquiring
Solutions: Required
when bill_
payment=true
and pos_entry_
mode=keyed.
All other processors:
Not used.
18
Appendix A
Table 7
API Fields
General Card-Present Request-Level Fields (Continued)
Field
Description
Used By:
Required (R)
or Optional (O)
Data Type
& Length
bill_zip
Postal code for billing address. Postal code
must consist of 5 to 9 digits.
ics_auth:
String (10)
FDMS Nashville:
Required if pos_
entry_
mode=keyed and
the address is in the
U.S. or Canada.
Optional if pos_
entry_mode=
keyed and the
address is not in the
U.S. or Canada. Not
used if swiped.
RBS WorldPay
Atlanta: For best
card-present keyed
rates, send the postal
code if pos_entry_
mode=keyed.
TSYS Acquiring
Solutions: Required
when bill_
payment=true and
pos_entry_
mode=keyed.
All other processors:
Optional.
When the billing country is the U.S., the 9-digit
postal code must follow this format:
[5 digits][dash][4 digits]
Example: 12345-6789
When the billing country is Canada, the 6-digit
postal code must follow this format:
[alpha][numeric][alpha][space][numeric][alpha]
[numeric]
Example: A1B 2C3
card_present
Indicates whether the card is present at the
time of the card-present transaction. Possible
values:
N: Card is not present.
Y: Card is present.
Card-Present Processing Using the SCMP API | March 2015
ics_auth:
FDMS Nashville:
Not used.
All other processors:
Required.
String (1)
19
Appendix A
Table 7
API Fields
General Card-Present Request-Level Fields (Continued)
Field
Description
Used By:
Required (R)
or Optional (O)
Data Type
& Length
card_type
Type of card to authorize. Possible values:
String (3)
cat_level
currency
customer_cc_cv_
indicator
001: Visa
002: MasterCard
003: American Express
ics_auth
(Required for Carte
Blanche and JCB.
Optional for other card
types.)
004: Discover
Important
005: Diners Club
006: Carte Blanche
007: JCB
Type of cardholder activated terminal. Possible
values:
1: Automated dispensing machine
2: Self-service terminal
3: Limited amount terminal
4: In-flight commerce (IFC) terminal
5: Radio frequency device
6: Mobile acceptance terminal
Some processors do not support all possible
values.
Currency used for order. For possible values,
see the ISO Standard Currency Codes.
Indicates whether a CVN code was sent.
Possible values:
CyberSource strongly
recommends that you
send the card type even
when it is optional for
your processor and
card type. Omitting the
card type can cause the
transaction to be
processed with the
wrong card type.
ics_auth:
Chase Paymentech
Solutions: Required if
terminal_id is
included in the
request. Otherwise,
optional.
CyberSource through
VisaNet: Optional.
All other processors:
Not used.
ics_auth (R)
String (5)
ics_auth:
Nonnegative
integer (1)
FDMS Nashville:
Required for
American Express
cards. Otherwise,
optional.
TSYS Acquiring
Solutions: Optional if
pos_entry_
mode=keyed.
Otherwise, not used.
All other processors:
Optional.
0 (default): CVN service not requested.
CyberSource uses this default when you do
not include customer_cc_cv_number in
the request.
1 (default): CVN service requested and
supported. CyberSource uses this default
when you include customer_cc_cv_
number in the request.
2: CVN on credit card is illegible.
9: CVN not imprinted on credit card.
Card-Present Processing Using the SCMP API | March 2015
Nonnegative
integer (1)
20
Appendix A
Table 7
API Fields
General Card-Present Request-Level Fields (Continued)
Field
Description
Used By:
Required (R)
or Optional (O)
Data Type
& Length
customer_cc_cv_
number
CVN. See the CVN information in Credit Card
Services Using the SCMP API.
ics_auth:
Nonnegative
integer (4)
customer_cc_expmo
customer_cc_expyr
customer_cc_number
Two-digit month in which credit card expires.
Format: MM.
Possible values: 01 through 12. Leading 0 is
required.
Four-digit year in which credit card expires.
Format: YYYY.
Customer’s credit card number.
Card-Present Processing Using the SCMP API | March 2015
FDMS Nashville:
Required for
American Express or
if swiped. Otherwise,
optional.
TSYS Acquiring
Solutions: Optional if
pos_entry_
mode=keyed.
Otherwise, not used.
All other processors:
Optional.
ics_auth:
FDMS Nashville:
Required.
All other processors:
Required if pos_
entry_
mode=keyed.
ics_auth:
FDMS Nashville:
Required.
All other processors:
Required if pos_
entry_
mode=keyed.
ics_auth:
FDMS Nashville:
Required.
All other processors:
Required if pos_
entry_
mode=keyed.
String (2)
Nonnegative
integer (4)
FDMS
Nashville:
Nonnegative
integer (19)
All other
processors:
Nonnegative
integer (20)
21
Appendix A
Table 7
API Fields
General Card-Present Request-Level Fields (Continued)
Field
Description
Used By:
Required (R)
or Optional (O)
Data Type
& Length
customer_email
Customer’s email address, including full
domain name.
Format: name@host.domain
ics_auth:
String (255)
Chase Paymentech
Solutions: Optional.
Litle: Optional.
TSYS Acquiring
Solutions: Required
when bill_
payment=true
and pos_entry_
mode=keyed.
All other processors:
Not used.
ics_auth:
customer_firstname
Customer’s first name. Value should match
value on card.
Chase Paymentech
Solutions: Optional.
Litle: Optional.
TSYS Acquiring
Solutions: Required
when bill_
payment=true
and pos_entry_
mode=keyed.
All other processors:
Not used.
ics_auth:
String (60)
customer_lastname
Customer’s last name. Value should match
value on card.
Card-Present Processing Using the SCMP API | March 2015
Chase Paymentech
Solutions: Optional.
Litle: Optional.
RBS WorldPay
Atlanta: Optional.
TSYS Acquiring
Solutions: Required
when bill_
payment=true
and pos_entry_
mode=keyed.
All other processors:
Not used.
String (60)
22
Appendix A
Table 7
API Fields
General Card-Present Request-Level Fields (Continued)
Field
Description
Used By:
Required (R)
or Optional (O)
Data Type
& Length
customer_phone
Customer’s phone number. CyberSource
recommends that you include the country code
when order is from outside the U.S.
ics_auth:
String (15)
Chase Paymentech
Solutions: Optional.
Litle: Optional.
TSYS Acquiring
Solutions: Optional.
All other processors:
Not used.
ics_auth (R)
String (13)
ics_auth (O)
String (2)
ics_auth
(See description)
String (15)
ics_bill (O)
Numeric (12)
ics_auth (R)
String (255)
e_commerce_indicator
extended_credit_total_
count
grand_total_amount
gratuity_amount
Type of transaction. For a card-present
transaction, you must set this field to retail.
Number of months the cardholder can use to
pay for the purchase. You can use this field
when offering extended credit to a cardholder
at a retail location. The cardholder provides
this value. The issuer pays you for the
purchase in one payment, and then the
cardholder pays the issuer in the number of
monthly payments specified by this value.
This field is supported only for acquirers in
South Africa and only for CyberSource through
VisaNet.
Grand total for the order. You must include
either this field or offer0 and the offer-level
field amount. For information about offers and
grand totals, see Getting Started with
CyberSource Advanced for the SCMP API.
Gratuity or tip amount for restaurants when the
card is present. Allowed only when industry_
datatype=restaurant.
When your customer uses a debit card or
prepaid card, and you receive a partial
authorization, the payment networks
recommend that you do not submit a capture
amount that is higher than the authorized
amount. When the capture amount exceeds
the partial amount that was approved, the
issuer has chargeback rights for the excess
amount. For information about partial
authorizations, see Credit Card Services Using
the SCMP API.
Restaurant data is supported only for
CyberSource through VisaNet.
ics_applications
CyberSource services to process for the
request.
Card-Present Processing Using the SCMP API | March 2015
23
Appendix A
Table 7
API Fields
General Card-Present Request-Level Fields (Continued)
Field
Description
Used By:
Required (R)
or Optional (O)
Data Type
& Length
industry_datatype
Indicates whether the transaction includes
restaurant data. You must set this field to
restaurant in order for restaurant data to
be sent to the processor.
ics_bill
(Required for restaurant
transactions.)
String (10)
ics_auth (R)
ics_auth (R)
String (30)
String (50)
When this field is not set to restaurant or
is not included in the request, CyberSource
does not send restaurant data to the
processor.
Restaurant data is supported only for
CyberSource through VisaNet.
merchant_id
merchant_ref_number
Your CyberSource merchant ID.
Merchant-generated order reference or
tracking number. CyberSource recommends
that you send a unique value for each
transaction so that you can perform meaningful
searches for the transaction. For information
about tracking orders, see Getting Started with
CyberSource Advanced for the SCMP API.
FDC Nashville Global:
The value for this field must be numeric and
must be less than 9 digits. When you do not
send a valid value, CyberSource creates one
for you. However, the value is not returned to
you, so you cannot use the merchant
reference number to track the order.
Card-Present Processing Using the SCMP API | March 2015
24
Appendix A
Table 7
API Fields
General Card-Present Request-Level Fields (Continued)
Field
Description
Used By:
Required (R)
or Optional (O)
Data Type
& Length
payment_initiation_
channel
MasterCard-defined code that indicates how
the account information was obtained.
Possible values:
ics_auth (O)
String (2)
00 (default): Card
01: Removable secure element that is
personalized for use with a mobile phone
and controlled by the wireless service
provider; examples: subscriber identity
module (SIM), universal integrated circuit
card (UICC)
02: Key fob
03: Watch
04: Mobile tag
05: Wristband
06: Mobile phone case or sleeve
07: Mobile phone with a non-removable,
secure element that is controlled by the
wireless service provider
08: Removable secure element that is
personalized for use with a mobile phone
and not controlled by the wireless service
provider; example: memory card
09: Mobile phone with a non-removable,
secure element that is not controlled by the
wireless service provider
10: Removable secure element that is
personalized for use with a tablet or e-book
and is controlled by the wireless service
provider; examples: subscriber identity
module (SIM), universal integrated circuit
card (UICC)
11: Tablet or e-book with a non-removable,
secure element that is controlled by the
wireless service provider
12: Removable secure element that is
personalized for use with a tablet or e-book
and is not controlled by the wireless service
provider
13: Tablet or e-book with a non-removable,
secure element that is not controlled by the
wireless service provider
This field is supported only for MasterCard and
only for CyberSource through VisaNet.
Card-Present Processing Using the SCMP API | March 2015
25
Appendix A
Table 7
API Fields
General Card-Present Request-Level Fields (Continued)
Field
Description
Used By:
Required (R)
or Optional (O)
Data Type
& Length
pos_entry_mode
Method of entering credit card information into
the POS terminal. Possible values:
ics_auth (R)
String (11)
ics_auth
(Required if any
shipping address
information is included
in the request.
Otherwise, optional.)
ics_auth (O)
ics_auth
(Required if any
shipping address
information is included
in the request and
shipping to the U.S. or
Canada. Otherwise,
optional.)
ics_auth
(Required if any
shipping address
information is included
in the request.
Otherwise, optional.)
ics_auth (O)
String (60)
keyed: Manually keyed into POS terminal.
swiped: Read from credit card magnetic
ship_to_address1
stripe.
First line of shipping address.
ship_to_address2
ship_to_city
Second line of shipping address.
City of shipping address.
ship_to_country
Country of shipping address. Use the ISO
Standard Country Codes.
ship_to_firstname
First name of the person receiving the
shipment.
Last name of the person receiving the
shipment.
State or province to ship the product to. Use
the State, Province, and Territory Codes for the
United States and Canada.
ship_to_lastname
ship_to_state
Card-Present Processing Using the SCMP API | March 2015
String (60)
String (50)
String (2)
String (60)
ics_auth (O)
String (60)
ics_auth
(Required if any
shipping address
information is included
in the request and
shipping to the U.S. or
Canada. Otherwise,
optional.)
String (2)
26
Appendix A
Table 7
API Fields
General Card-Present Request-Level Fields (Continued)
Field
Description
Used By:
Required (R)
or Optional (O)
Data Type
& Length
ship_to_zip
Postal code for the shipping address. The
postal code must consist of 5 to 9 digits.
ics_auth
(Required if any
shipping address
information is included
in the request and
shipping to the U.S. or
Canada. Otherwise,
optional.)
String (10)
ics_auth:
Integer (1)
When the shipping country is the U.S., the
9-digit postal code must follow this format:
[5 digits][dash][4 digits]
Example: 12345-6789
terminal_capability
When the shipping country is Canada, the
6-digit postal code must follow this format:
[alpha][numeric][alpha][space][numeric][alpha]
[numeric]
Example: A1B 2C3
POS terminal’s capability. Possible values:
1: Terminal has a magnetic stripe reader
only.
American Express
Direct: Required.
2: Terminal has a magnetic stripe reader
and manual entry capability.
Chase Paymentech
Solutions: Required.
3: Terminal has manual entry capability
only.
CyberSource through
VisaNet: Optional.
FDC Nashville
Global: Required.
FDMS Nashville:
Required.
GPN: Not used.
Litle: Required.
RBS WorldPay
Atlanta: Optional.
TSYS Acquiring
Solutions: Optional.
Card-Present Processing Using the SCMP API | March 2015
27
Appendix A
Table 7
API Fields
General Card-Present Request-Level Fields (Continued)
Field
Description
Used By:
Required (R)
or Optional (O)
Data Type
& Length
terminal_id
Identifier for the terminal at your retail location.
You can define this value yourself, but consult
the processor for requirements.
ics_auth:
String (8)
CyberSource through VisaNet
A list of all possible values is stored in your
CyberSource account and the value you send
for this field is validated against the list each
time you include the field in your request.
When you do not include this field in your
request, CyberSource uses the default value
that is defined in your CyberSource account.
FDC Nashville Global
To have your account configured to support
this field, contact CyberSource Customer
Support. This value must be a value that FDC
Nashville Global issued to you.
Card-Present Processing Using the SCMP API | March 2015
American Express
Direct: Optional. If
not provided,
CyberSource uses
the value in your
CyberSource
account.
Chase Paymentech
Solutions: Optional. If
you include this field
in your request, you
must also include
cat_level.
CyberSource through
VisaNet: Optional.
FDC Nashville
Global: Optional. If
not provided,
CyberSource uses
the value in your
CyberSource
account.
FDMS Nashville:
CyberSource uses
the value in your
CyberSource
account.
GPN: Not used.
Litle: Not used.
RBS WorldPay
Atlanta: Not used.
TSYS Acquiring
Solutions: Not used.
28
Appendix A
Table 7
API Fields
General Card-Present Request-Level Fields (Continued)
Field
Description
Used By:
Required (R)
or Optional (O)
Data Type
& Length
terminal_id_alternate
Identifier for an alternate terminal at your retail
location. You define the value for this field.
ics_auth:
String (8)
This field is supported only for MasterCard
transactions on FDC Nashville Global. Use the
terminal_id field to identify the main terminal
at your retail location. If your retail location has
multiple terminals, use this terminal_id_
alternate field to identify the terminal used for
the transaction.
transaction_local_date_
time
This field is a pass-through, which means that
CyberSource does not check the value or
modify the value in any way before sending it
to the processor.
Date and time at your physical location.
FDC Nashville
Global: Optional for
MasterCard
transactions.
Otherwise, not used.
All other processors:
Not used.
ics_auth (O)
String (14)
Format: YYYYMMDDhhmmss, where:
YYYY = year
MM = month
DD = day
hh = hour
mm = minutes
ss = seconds
Card-Present Processing Using the SCMP API | March 2015
29
Appendix A
API Fields
General Card-Present Offer-Level
Fields
Table 8
General Card-Present Offer-Level Fields
Field
Description
Used By:
Required (R)
or Optional (O)
Data Type
& Length
amount
Per-item price of the product. You must include
either offer0 and this field or the request-level
field grand_total_amount in your request. The
value for this field cannot be negative. For
information about offers and grand totals, see
Getting Started with CyberSource Advanced for
the SCMP API.
ics_auth
(See description)
For GPN:
Decimal
(10)
All other
processors:
Decimal
(15)
You can include a decimal point (.) in the value
for this field, but you cannot include any other
special characters. CyberSource truncates the
amount to the correct number of decimal
places.
merchant_product_
sku
Product identifier code. Required when
product_code is not default or one of the
values related to shipping and/or handling.
ics_auth
(See description)
String (15)
product_code
Type of product. The value for this field is used
to identify the product category (electronic,
handling, physical, service, or shipping). The
default value is default. For a list of valid
values, see the information about product
codes in Credit Card Services Using the SCMP
API.
ics_auth (O)
String (30)
ics_auth
(See description)
String (30)
When the value for this field is not default or
one of the values related to shipping and/or
handling, the quantity, product_name, and
merchant_product_sku fields are required.
For information about offers and grand totals,
see Getting Started with CyberSource
Advanced for the SCMP API.
product_name
Required when product_code is not default
or one of the values related to shipping and/or
handling.
Card-Present Processing Using the SCMP API | March 2015
30
Appendix A
Table 8
API Fields
General Card-Present Offer-Level Fields (Continued)
Field
Description
Used By:
Required (R)
or Optional (O)
Data Type
& Length
quantity
Default is 1. Required when product_code is
not default or one of the values related to
shipping and/or handling.
ics_auth
(See description)
Nonnegativ
e integer
(10)
tax_amount
Total tax to apply to the product. This value
cannot be negative. The tax amount and the
offer amount must be in the same currency.
ics_auth (O)
Decimal
(15)
The tax amount field is additive. The following
example uses a two-exponent currency such as
USD:
1 You include the following offer lines in your
request:
offer0=amount:10.00^quantity:
1^tax_amount:0.80
offer1=amount:20.00^quantity:
1^tax_amount:1.60
2 The total amount authorized will be 32.40,
not 30.00 with 2.40 of tax included.
If you want to include tax_amount and also
request the ics_tax service, see Tax
Calculation Service Using the SCMP API.
Reply Field
Table 9
Reply Field
Field
Description
Returned By
Data Type
& Length
sales_slip_number
Transaction identifier that CyberSource
generates. You have the option of printing the
sales slip number on the receipt.
ics_auth
Integer (5)
This field is supported only for JCN Gateway.
Card-Present Processing Using the SCMP API | March 2015
31
APPENDIX
B
Examples
Sale Using Swiped Track Data
Example 1
Request Message: Sale Using Swiped Track Data
merchant_id=JanesPlants
merchant_ref_number=ABC123
currency=usd
grand_total_amount=75.00
pos_entry_mode=swiped
card_present=Y
terminal_capability=2
track_data=%B4111111111111111^SMITH/BETTY^16121200123456789012**XXX***
***?*;4111111111111111=16121200XXXX00000000?*
ics_applications=ics_auth,ics_bill
e_commerce_indicator=retail
Example 2
Reply Message: Sale Using Swiped Track Data
merchant_ref_number=ABC123
request_id=0305782650000167905080
ics_rcode=100
ics_rflag=SOK
ics_rmsg=Request was processed successfully.
currency=usd
auth_rcode=100
auth_rflag=SOK
auth_rmsg=Request was processed successfully.
auth_auth_amount=75.00
auth_auth_code=831000
auth_auth_avs=2
auth_auth_response=00
auth_trans_ref_no=1094820975023470
auth_payment_network_transaction_id=0412MCCNYJPWY
auth_card_category=J1
auth_card_group=0
bill_rcode=100
bill_rflag=SOK
bill_rmsg=Request was processed successfully.
bill_bill_amount=75.00
bill_trans_ref_no=1094820975023470
receipt_number=260371
Card-Present Processing Using the SCMP API | March 2015
32
Appendix B
Examples
Sale Using Keyed Data
Example 3
Request Message: Sale Using Keyed Data
merchant_id=JanesPlants
merchant_ref_number=ABC123
currency=usd
grand_total_amount=75.00
pos_entry_mode=keyed
card_present=Y
terminal_capability=2
customer_cc_number=4111111111111111
customer_cc_expmo=12
customer_cc_expyr=2016
card_type=001
ics_applications=ics_auth,ics_bill
e_commerce_indicator=retail
Example 4
Reply Message: Sale Using Keyed Data
merchant_ref_number=ABC123
request_id=0305782650000167905080
ics_rcode=100
ics_rflag=SOK
ics_rmsg=Request was processed successfully.
currency=usd
auth_rcode=100
auth_rflag=SOK
auth_rmsg=Request was processed successfully.
auth_auth_amount=75.00
auth_auth_code=831000
auth_auth_avs=2
auth_auth_response=00
auth_trans_ref_no=1094820975023470
auth_payment_network_transaction_id=0412MCCNYJPWY
auth_card_category=J1
auth_card_group=0
bill_rcode=100
bill_rflag=SOK
bill_rmsg=Request was processed successfully.
bill_bill_amount=75.00
bill_trans_ref_no=1094820975023470
receipt_number=260371
Card-Present Processing Using the SCMP API | March 2015
33
Appendix B
Examples
Authorization Using Point-to-Point
Encryption
Example 5
Request Message: Authorization Using Point-to-Point Encryption
e_commerce_indicator=retail
ics_applications=ics_auth
merchant_id=myMerchantID123
merchant_ref_number=9876
card_present=y
pos_device_reader_data=4649443D4944544543482E556E694D61672E416E64726F
69642E53646B7631
pos_encoding_method=Hex
pos_encryption_algorithm=TDES
pos_entry_mode=swiped
pos_payment_data=02d700801f3c20008383252a363031312a2a2a2a2a2a2a2a303030
395e46444d53202020202020202020202020202020202020202020205e323231322a
2a2a2a2a2a2a2a3f2a3b363031312a2a2a2a2a2a2a2a303030393d323231322a2a2a
2a2a2a2a2a3f2a7a75ad15d25217290c54b3d9d1c3868602136c68d339d52d984233
91f3e631511d548fff08b414feac9ff6c6dede8fb09bae870e4e32f6f462d6a75fa0
a178c3bd18d0d3ade21bc7a0ea687a2eef64551751e502d97cb98dc53ea55162cdfa
395431323439323830303762994901000001a000731a8003
terminal_capability=2
currency=USD
grand_total_amount=30.00
Example 6
Reply Message: Authorization Using Point-to-Point Encryption
ics_rcode=100
ics_rflag=SOK
ics_rmsg=Request was processed successfully.
auth_rcode=100
auth_rflag=SOK
auth_rmsg=Request was processed successfully.
auth_auth_amount=30.00
auth_auth_code=888888
auth_auth_avs=1
auth_auth_response=100
auth_trans_ref_no=64709061YTHMP2LF
merchant_ref_number=9876
currency=USD
request_id=3965463790780176056470
Card-Present Processing Using the SCMP API | March 2015
34
© Copyright 2024