General Card-Present Request Fields

API Fields : General Card-Present Request Fields

General Card-Present Request Fields

Table 7

General Card-Present Request Fields

Field

Description

Used By:
Required (R) or Optional (O)

Data Type & Length

billTo_city

Credit card billing city.

ccAuthService:

■

Chase Paymentech Solutions: optional.

■

TSYS Acquiring Solutions: required when ccAuthService_billPayment=true and pos_entryMode=keyed.

■

All other processors: not used.

String (50)

billTo_country

Credit card billing country. Use the two-character ISO Standard Country Codes.

ccAuthService:

■

Chase Paymentech Solutions: optional.

■

TSYS Acquiring Solutions: required when ccAuthService_billPayment=true and pos_entryMode=keyed.

■

All other processors: not used.

String (2)

billTo_email

Customer’s email address, including full domain name.
Format: name@host.domain

ccAuthService:

■

Chase Paymentech Solutions: optional.

■

TSYS Acquiring Solutions: required when ccAuthService_billPayment=true and pos_entryMode=keyed.

■

All other processors: not used.

String (255)

billTo_firstName

Customer’s first name. Value should match value on card.

ccAuthService:

■

Chase Paymentech Solutions: optional.

■

TSYS Acquiring Solutions: required when ccAuthService_billPayment=true and pos_entryMode=keyed.

■

All other processors: not used.

String (60)

billTo_lastName

Customer’s last name. Value should match value on card.

ccAuthService:

■

Chase Paymentech Solutions: optional.

■

RBS WorldPay Atlanta: optional.

■

TSYS Acquiring Solutions: required when ccAuthService_billPayment=true and pos_entryMode=keyed.

■

All other processors: not used.

String (60)

billTo_phoneNumber

Customer’s phone number. CyberSource recommends that you include the country code when order is from outside the U.S.

ccAuthService:

■

Chase Paymentech Solutions: optional.

■

TSYS Acquiring Solutions: optional.

■

All other processors: not used.

String (15)

billTo_postalCode

Postal code for billing address. Postal code must consist of 5 to 9 digits.

When the billing country is 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

ccAuthService:

■

FDMS Nashville: required if pos_entryMode=keyed and the address is in the U.S. or Canada. Optional if pos_entryMode=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_entryMode=keyed.

■

TSYS Acquiring Solutions: required when ccAuthService_billPayment=true and pos_entryMode=keyed.

■

All other processors: optional.

String (10)

billTo_state

Credit card billing state or province. Use State, Province, and Territory Codes for the United States and Canada.

ccAuthService:

■

Chase Paymentech Solutions: optional.

■

TSYS Acquiring Solutions: required when ccAuthService_billPayment=true and pos_entryMode=keyed.

■

All other processors: not used.

String (2)

billTo_street1

Credit card billing street address as it appears in credit card issuer’s records.

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.

ccAuthService:

■

FDMS Nashville: required if keyed; not used if swiped.

■

TSYS Acquiring Solutions: required when ccAuthService_billPayment=true and pos_entryMode=keyed.

■

All other processors: optional.

FDMS Nashville: String (20)

All other processors: String (60)

billTo_street2

Used for additional address information. For example:
Attention: Accounts Payable

FDMS Nashville:

billTo_street1 and billTo_street2 together cannot exceed 20 characters.

ccAuthService (O)

FDMS Nashville: String (20)

All other processors: String (60)

card_accountNumber

Customer’s credit card number.

ccAuthService:

■

FDMS Nashville: required.

■

All other processors: required if pos_entryMode=keyed.

FDMS Nashville: String with numbers only (19)

All other processors: String with numbers only (20)

card_cardType

Type of card to authorize. Possible values:

■

001: Visa

■

002: Mastercard

■

003: American Express

■

004: Discover

■

005: Diners Club

■

006: Carte Blanche

■

007: JCB

ccAuthService
(Required for Carte Blanche and JCB. Optional for other card types.)

Important
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.

String (3)

card_cvIndicator

Indicates whether a CVN code was sent. Possible values:

■

0 (default): CVN service not requested. CyberSource uses this default when you do not include card_cvNumber in the request.

■

1 (default): CVN service requested and supported. CyberSource uses this default when you include card_cvNumber in the request.

■

2: CVN on credit card is illegible.

■

9: CVN not imprinted on credit card.

ccAuthService:

■

FDMS Nashville: required for American Express; otherwise, optional.

■

TSYS Acquiring Solutions: optional if pos_entryMode=
keyed; otherwise, not used.

■

All other processors: optional.

String with numbers only (1)

card_cvNumber

CVN. See CVN information in Credit Card Services User Guide.

ccAuthService:

■

FDMS Nashville: required for American Express or if swiped; otherwise, optional.

■

TSYS Acquiring Solutions: optional if pos_entryMode=
keyed; otherwise, not used.

■

All other processors: optional.

String with numbers only (4)

card_expirationMonth

Two‑digit month in which credit card expires. Format: MM.
Possible values: 01 through 12. Leading 0 is required.

ccAuthService:

■

FDMS Nashville: required.

■

All other processors: required if pos_entryMode=keyed.1

String (2)

card_expirationYear

Four‑digit year in which credit card expires. Format: YYYY.

ccAuthService:

■

FDMS Nashville: required.

■

All other processors: required if pos_entryMode=keyed.1

String (4)

ccAuthService_billPayment

Indicates payment for bill or payment towards existing contractual loan. For information about Visa Bill Payments and Visa Debt Repayments, see Credit Card Services User Guide. Possible values:

■

true: Bill payment or loan payment.

■

false (default): Not a bill payment or loan payment.

ccAuthService (O)

String (5)

ccAuthService_commerceIndicator

Type of transaction. For a card-present transaction, you must set this field to retail.

ccAuthService (R)

String (13)

ccAuthService_run

Set to true to request credit card authorization.

ccAuthService (R)

String (255)

item_#_productCode

Type of product. This value 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 User Guide.

When this field is not set to default or one of the values related to shipping and/or handling, the item_#_quantity, item_#_productName, and item_#_productSKU fields are required. For information about items and grand totals, see Getting Started with CyberSource Essentials.

ccAuthService (O)

String (30)

item_#_productName

Required when item_#_productCode is not default or one of the values related to shipping and/or handling.

ccAuthService
(See description)

String (30)

item_#_productSKU

Product identifier code. Required when item_#_productCode is not default or one of the values related to shipping and/or handling.

ccAuthService
(See description)

String (15)

item_#_quantity

Default is 1. Required when item_#_productCode is not default or one of the values related to shipping and/or handling.

ccAuthService
(See description)

Integer (10)

item_#_taxAmount

Total tax to apply to the product. This value cannot be negative. The tax amount and the unit price must be in the same currency.

The tax amount field is additive. The following example uses a two-exponent currency such as USD:

1

You include the following items in your request:

item_0_unitPrice=10.00
item_0_quantity=1
item_0_taxAmount=0.80

item_1_unitPrice=20.00
item_1_quantity=1
item_1_taxAmount=1.60

2

The total amount authorized will be 32.40, not 30.00 with 2.40 of tax included.

ccAuthService (O)

String (15)

item_#_unitPrice

Per-item price of the product. You must include either this field or purchaseTotals_grandTotalAmount in your request. This value cannot be negative. For information about items and grand totals, see Getting Started with CyberSource Essentials.

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.

ccAuthService
(See description)

For GPN:
String (10)

All other processors: String (15)

merchantID

Your CyberSource merchant ID.

ccAuthService (R)

String (30)

merchantReferenceCode

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 Essentials.

FDC Nashville Global:

This value 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.

ccAuthService (R)

String (50)

pos_cardPresent

Indicates whether the card is present at the time of the transaction. Possible values:

■

N: Card is not present.

■

Y: Card is present.

ccAuthService:

■

FDMS Nashville: not used.

■

All other processors: required.

String (1)

pos_catLevel

Type of cardholder-activated terminal. Possible values:

■

1: Automated dispensing machine

■

2: Self-service terminal

■

3: Limited amount terminal

■

6: Mobile acceptance terminal

Chase Paymentech Solutions

Only values 1, 2, and 3 are supported.

GPN

Only value 6 is supported.

TSYS Acquiring Solutions

Only value 6 is supported.

ccAuthService:

■

Chase Paymentech Solutions: required if pos_terminalID is included in the request; otherwise, optional.

■

GPN: required.

■

TSYS Acquiring Solutions: required for transactions from mobile devices; otherwise, not used.

■

All other processors: not used.

Nonnegative integer (1)

pos_entryMode

Method of entering credit card information into the POS terminal. Possible values:

■

keyed: Manually keyed into POS terminal.

■

swiped: Read from credit card magnetic stripe.

ccAuthService (R)

String (11)

pos_terminalCapability

POS terminal’s capability. Possible values:

■

1: Terminal has a magnetic stripe reader only.

■

2: Terminal has a magnetic stripe reader and manual entry capability.

■

3: Terminal has manual entry capability only.

ccAuthService:

■

Chase Paymentech Solutions: required.

■

FDC Nashville Global: required.

■

FDMS Nashville: required.

■

GPN: optional.

■

RBS WorldPay Atlanta: optional.

■

TSYS Acquiring Solutions: optional.

Integer (1)

pos_terminalID

Identifier for the terminal at your retail location. You can define this value yourself, but consult the processor for requirements.

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.

ccAuthService:

■

Chase Paymentech Solutions: optional. If you include this field in your request, you must also include pos_catLevel.

■

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.

■

RBS WorldPay Atlanta: not used.

■

TSYS Acquiring Solutions: not used.

String (8)

pos_terminalIDAlternate

Identifier for an alternate terminal at your retail location. You define the value for this field.

This field is supported only for Mastercard transactions on FDC Nashville Global. Use the pos_terminalID field to identify the main terminal at your retail location. If your retail location has multiple terminals, use this pos_terminalIDAlternate field to identify the terminal used for the transaction.

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.

ccAuthService:

■

FDC Nashville Global: optional for Mastercard transactions; otherwise, not used.

■

All other processors: not used.

String (8)

purchaseTotals_currency

Currency used for order. For possible values, see ISO Standard Currency Codes.

ccAuthService (R)

String (5)

purchaseTotals_grandTotalAmount

Grand total for the order. You must include either this field or item_#_unitPrice in your request. For information about items and grand totals, see Getting Started with CyberSource Essentials.

ccAuthService
(See description)

String (15)

shipTo_city

City of shipping address.

ccAuthService (Required if any shipping address information is included in the request and shipping to the U.S. or Canada; otherwise, optional.)

String (50)

shipTo_country

Country of shipping address. Use the two-character ISO Standard Country Codes.

ccAuthService (Required if any shipping address information is included in the request; otherwise, optional.)

String (2)

shipTo_firstName

First name of the person receiving the shipment.

ccAuthService (O)

String (60)

shipTo_lastName

Last name of the person receiving the shipment.

ccAuthService (O)

String (60)

shipTo_postalCode

Postal code for the shipping address. The postal code must consist of 5 to 9 digits.

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

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

ccAuthService (Required if any shipping address information is included in the request and shipping to the U.S. or Canada; otherwise, optional.)

String (10)

shipTo_state

State or province to ship the product to. Use the State, Province, and Territory Codes for the United States and Canada.

ccAuthService (Required if any shipping address information is included in the request and shipping to the U.S. or Canada; otherwise, optional.)

String (2)

shipTo_street1

First line of shipping address.

ccAuthService (Required if any shipping address information is included in the request; otherwise, optional.)

String (60)

shipTo_street2

Second line of shipping address.

ccAuthService (O)

String (60)

transactionLocalDateTime

Date and time at your physical location.

Format: YYYYMMDDhhmmss, where
YYYY = year
MM = month
DD = day
hh = hour
mm = minutes
ss = seconds

ccAuthService (O)

String (14)

1 This field is optional if your CyberSource account is configured for relaxed requirements for address data and expiration date. See Relaxed Requirements for Address Data and Expiration Date. Important It is your responsibility to determine whether a field is required for the transaction you are requesting.