Secure Acceptance Web Mobile: Field Mapping Guide

M: Mandatory O: Optional N/A: Not required

Request Fields

Field Information

Comparative value for other CyberSource Services

Which fields are needed for which service

Secure Acceptance Field Name

Collected in Web/Mobile

Data Type & Length

Permitted values

Comments

Links

Legacy HOP/SOP Field Names

SO API Field Names

Accept Payments

Accept Payments & Create a Payment Token

Create a Payment Token

Update a Payment Token

Make a token based payment

Set up a Recurring Billing series of payments

Decision Manager fraud protection

Payment Types

access_key

No

String (32)

{key generated in UBC}

See ' Creating a Security Key' section of Configuration Guide

Link

### Does not exist ###

### Does not exist ###

M

M

M

M

M

M

M

All

profile_id

No

String (7)

{string, created  in UBC}

See ' Creating a Web/Mobile Profile' section of Configuration Guide. Must be exactly 7 characters in length.

Link

### Does not exist ###

### Does not exist ###

M

M

M

M

M

M

M

All

signature

No

-

{Base64 Signature}

Generated using the signing method for the access_key field supplied.

-

### Does not exist ###

### Does not exist ###

M

M

M

M

M

M

M

All

signed_date_time

No

String (20)

{UTC Date & Time format}

Your system time must be accurate to avoid payment processing errors related to the signed_date_time field.

-

### Does not exist ###

### Does not exist ###

M

M

M

M

M

M

M

All

signed_field_names

No

Variable

{Comma separated list of signed field names}

The names of all fields submitted must be included in this field or the unsigned_field_names field. To avoid increasing PCI DSS scope, do not sign the card_number or card_cvn fields.

-

### Does not exist ###

### Does not exist ###

M

M

M

M

M

M

M

All

unsigned_field_names

No

Variable

{Comma separated list of unsigned field names}

Included any unsigned field names you submit with the request - e.g. card_number. Included 'unsigned_field_names' in the signed_field_names field.

-

### Does not exist ###

### Does not exist ###

M

M

M

M

M

M

M

All

transaction_uuid

No

String (50)

{Any}

You should generate a unique reference for each transaction. We recommend, but do not mandate, the uuid format.

Link

### Does not exist ###

### Does not exist ###

M

M

M

M

M

M

M

All

locale

No

String (5)

-

Specifies the language of the checkout experience. See 'Localization' section of the Configuration guide.

Link

### Does not exist ###

### Does not exist ###

M

M

M

M

M

M

M

All

transaction_type

No

String (60)

n authorization n sale n authorization,create_payment_token n sale,create_payment_token n authorization,update_payment_token n sale,update_payment_token n create_payment_token

In SA this is a Comma delimited string of requested services eg. transaction_type=authorization,sale In SOAPI this is a list of service named values with a true/false value eg. ccAuthService_run=true ccCaptureService_run=true

-

orderPage_transactionType

### Does not exist ###

M

M

M

M

M

M

M

All

amount

No

String (50)

.1234567890

Total amount for the order. Must be greater than or equal to zero. Where line item detail is provided, this value must equal the total amount of each line item multiplied by their quantity, and include the tax amount.

-

amount

purchaseTotals_grandTotalAmount

M

M

O

O

M

O

O

All

bill_payment

No

String (5)

true,false

True marks payment as a VISA Bill Payment, or in conjunction with the deb_indicator field, a VISA Debt Repayment.

Link

### Does not exist ###

ccAuthService_billPayment

O

O

N/A

N/A

O

N/A

N/A

Card

debt_indicator

No

String (5)

true,false

True marks payment as a VISA Debt Repayment, providing bill_payment field is also set to True.

Link

### Does not exist ###

debtIndicator

O

O

N/A

N/A

O

N/A

N/A

Card

bill_to_address_city

Yes

String (50)

-

Check which fields are required by your processor, and pass in or set to 'Required' in the EBC, as appropriate.

-

billTo_city

billTo_city

O

O

O

O

O

O

O

All

bill_to_address_country

Yes

String (2)

{2 letter ISO Country Code}

Check which fields are required by your processor, and pass in or set to 'Required' in the EBC, as appropriate. If US or CA entered, this restricts the bill_to_address_state field to certain Territory or Country codes.

Link

billTo_country

billTo_country

M

M

M

M

O

M

O

All

bill_to_address_line1

Yes

String (60)

-

Check which fields are required by your processor, and pass in or set to 'Required' in the EBC, as appropriate.

-

billTo_street1

billTo_street1

O

O

O

O

O

O

O

All

bill_to_address_line2

Yes

String (60)

-

Check which fields are required by your processor, and pass in or set to 'Required' in the EBC, as appropriate.

-

billTo_street2

billTo_street2

O

O

O

O

O

O

O

All

bill_to_address_postal_code

Yes

String (10)

-

Check which fields are required by your processor, and pass in or set to 'Required' in the EBC, as appropriate.

-

billTo_postalCode

billTo_postalCode

O

O

O

O

O

O

O

All

bill_to_address_state

Yes

{See notes}

{2 letter state code for US and CA, otherwise string 50}

Check which fields are required by your processor, and pass in or set to 'Required' in the EBC, as appropriate. String (2) when country is US or CA, otherwise String (50)

Link

billTo_state

billTo_state

O

O

O

O

O

O

O

All

bill_to_company_name

Yes

String (40)

-

Check which fields are required by your processor, and pass in or set to 'Required' in the EBC, as appropriate.

-

billTo_company

billTo_company

O

O

O

O

O

O

O

All

bill_to_email

Yes

String (255)

{must be a valid email address}

Check which fields are required by your processor, and pass in or set to 'Required' in the EBC, as appropriate.

-

billTo_email

billTo_email

O

O

O

O

O

O

O

All

bill_to_forename

Yes

String (60)

-

Check which fields are required by your processor, and pass in or set to 'Required' in the EBC, as appropriate.

-

billTo_firstName

billTo_firstName

O

O

O

O

O

O

O

All

bill_to_phone

Yes

String (15)

( ),+-.*#xX1234567890

Check which fields are required by your processor, and pass in or set to 'Required' in the EBC, as appropriate.

-

billTo_phoneNumber

billTo_phoneNumber

O

O

O

O

O

O

O

All

bill_to_surname

Yes

String (60)

-

Check which fields are required by your processor, and pass in or set to 'Required' in the EBC, as appropriate.

-

billTo_lastName

billTo_lastName

O

O

O

O

O

O

O

All

card_cvn

Yes

String (4)

-

Collected directly from cardholder during the checkout process. To minimize your PCI DSS scope, do not collect this information yourself.

-

card_cvNumber

card_cvNumber

M

M

M

O

O

M

O

Card

card_expiry_date

Yes

String (7)

-

Collected directly from cardholder during the checkout process. To minimize your PCI DSS scope, do not collect this information yourself. Replaces two separate fields in the legacy HOP/SOP and SOAPI.

-

card_expirationMonth,card_expirationYear

card_expirationMonth, card_expirationYear

M

M

M

O

O

M

O

Card

card_number

Yes

String (20)

-

Collected directly from cardholder during the checkout process. To minimize your PCI DSS scope, do not collect this information yourself.

-

card_accountNumber

card_accountNumber

M

M

M

O

O

M

O

Card

card_type

Yes

String (3)

001,002,003,004,005,006,007,014,021,024,031,033,034,035,036,037,042,043

Collected directly from cardholder during the checkout process.

Link

card_cardType

card_cardType

M

M

M

O

O

M

O

Card

company_tax_id

Yes

String (9)

-

Check which fields are required by your processor, and pass in or set to 'Required' in the EBC, as appropriate.

-

-

-

O

O

O

O

N/A

O

O

eCheck

driver_license_number

Yes

String (30)

-

Check which fields are required by your processor, and pass in or set to 'Required' in the EBC, as appropriate.

-

-

-

O

O

O

O

N/A

O

O

eCheck

driver_license_state

Yes

String (2)

{See References}

Check which fields are required by your processor, and pass in or set to 'Required' in the EBC, as appropriate.

Link

-

-

O

O

O

O

N/A

O

O

eCheck

echeck_account_name

Yes

String (255)

-

The name on the customer's bank account. Check which fields are required by your processor, and pass in or set to 'Required' in the EBC, as appropriate.

-

-

-

O

O

O

O

N/A

O

O

eCheck

echeck_account_number

Yes

Non-negative integer (17)

-

Collected directly from cardholder during the checkout process. To minimize your exposure to payment data, do not collect this information yourself.

-

-

-

O

O

O

O

N/A

O

O

eCheck

echeck_account_type

Yes

String (1)

C,S,X

Check which fields are required by your processor, and pass in or set to 'Required' in the EBC, as appropriate. C: Checking S: Savings X: Corporate Checking (USD only)

-

-

-

O

O

O

O

N/A

O

O

eCheck

echeck_bank_name

Yes

String (50)

-

The name of the bank that holds the customer's account. Check which fields are required by your processor, and pass in or set to 'Required' in the EBC, as appropriate.

-

-

-

O

O

O

O

N/A

O

O

eCheck

echeck_check_number

Yes

Non-negative integer (8)

-

Check which fields are required by your processor, and pass in or set to 'Required' in the EBC, as appropriate.

-

-

-

O

O

O

O

N/A

O

O

eCheck

echeck_routing_number

Yes

Non-negative integer (9)

-

Collected directly from cardholder during the checkout process. To minimize your exposure to payment data, do not collect this information yourself.

-

-

-

O

O

O

O

N/A

O

O

eCheck

echeck_sec_code

Yes

String (3)

CCD,PPD,TEL,WEB

Check which fields are required by your processor, and pass in or set to 'Required' in the EBC, as appropriate. See implementation guide for definition of values.

Link

-

-

O

O

O

O

N/A

O

O

eCheck

reference_number

No

String (50)

-

This should be unique per transaction, for example the order number/reference generated by your system.

-

orderNumber

merchantReferenceCode

M

M

M

M

M

O

O

All

consumer_id

No

String (50)

-

A consumer ID you can set and store against a token.

-

billTo_customerID

billTo_customerID

N/A

O

O

O

O

O

O

All

currency

No

String (3)

{3 character ISO Currency Code}

Enure your processor(s) supports the currency you supply for the payment method selected.

Link

currency

purchaseTotals_currency

M

M

O

O

M

O

O

All

customer_cookies_accepted

No

String (5)

true,false

Used for Decision Manager risk profiling.

-

billTo_httpBrowserCookies Accepted

billTo_httpBrowserCookies Accepted

N/A

N/A

N/A

N/A

N/A

N/A

O

All

customer_gift_wrap

No

String (5)

true,false

Used for Decision Manager risk profiling.

-

invoiceHeader_isGift

invoiceHeader_isGift

N/A

N/A

N/A

N/A

N/A

N/A

O

All

customer_ip_address

No

String (15)

-

Must be a valid IP address.

-

billTo_ipAddress

billTo_ipAddress

N/A

N/A

N/A

N/A

N/A

N/A

O

All

date_of_birth

No

String (8)

{Use the format YYYYMMDD}

-

-

billTo_dateOfBirth

billTo_dateOfBirth

N/A

N/A

N/A

N/A

N/A

N/A

O

All

ignore_avs

No

String (5)

true,false

-

-

orderPage_ignoreAVS

businessRules_ignoreAVSResult

N/A

N/A

N/A

N/A

N/A

N/A

O

Card

ignore_cvn

No

String (5)

true,false

-

-

orderPage_ignoreCVN

businessRules_ignoreCVResult

N/A

N/A

N/A

N/A

N/A

N/A

O

Card

merchant_defined_data#

No

String (100)

-

# Represents a number from 1 to 100. The first four of these will be stored against the token, if the Create or Update Token services are being called. Up to 100 defined data fields can be stored against an individual transaction and/or used within the DM service. Do use these fields for Personally Identifying Information.

-

merchantDefinedData#

merchantDefinedData_mddField_#

O

O

O

O

O

O

O

All

merchant_secure_data#

No

String (100)

-

# Represents a number from 1 to 3. CyberSource encrypts this data before storing it in the database. Will be stored against a Token and/or an individual transaction, depending on the transaction_type.

-

### Does not exist ###

merchantSecureData_field#

O

O

O

O

O

O

O

All

merchant_secure_data4

No

String (2000)

-

The fourth Secure Data field has a larger length of 2,000 characters. See comments for previous fields.

-

### Does not exist ###

merchantSecureData_field4

O

O

O

O

O

O

O

All

override_custom_receipt_page

No

String (255)

{Must be a valid URL, including protocol, e.g. http://example.com/receipt}

Used in Secure Acceptance to allow merchants to override the URL of receipt page indicated in the UBC.

-

orderPage_receiptResponseURL

### Does not exist ###

O

O

O

O

O

N/A

N/A

All

payment_method

No

String (30)

card,echeck

Used to determine the payment method. If not provided, is assumed to be card.

-

paymentOption

### Does not exist ###

M

M

M

M

N/A

M

N/A

eCheck

returns_accepted

No

String (5)

true,false

Used for Decision Manager risk profiling.

-

invoiceHeader_returnsAccepted

invoiceHeader_returnsAccepted

N/A

N/A

N/A

N/A

N/A

N/A

O

All

ship_to_address_line1

Yes

String (60)

-

-

-

shipTo_street1

shipTo_street1

O

O

O

O

O

O

O

All

ship_to_address_line2

Yes

String (60)

-

-

-

shipTo_street2

shipTo_street2

O

O

O

O

O

O

O

All

ship_to_address_city

Yes

String (50)

-

-

-

shipTo_city

shipTo_city

O

O

O

O

O

O

O

All

ship_to_address_state

Yes

{See notes}

{2 letter state code for US and CA, otherwise string 50}

String (2) when country is US or CA, otherwise String (50)

-

shipTo_state

shipTo_state

O

O

O

O

O

O

O

All

ship_to_address_country

Yes

String (2)

{2 letter ISO Country Code}

Check which fields are required by your processor, and pass in or set to 'Required' in the EBC, as appropriate. If US or CA entered, this restricts the ship_to_address_state field to certain Territory or Country codes.

Link

shipTo_country

shipTo_country

O

O

O

O

O

O

O

All

ship_to_address_postal_code

Yes

String (10)

-

-

-

shipTo_postalCode

shipTo_postalCode

O

O

O

O

O

O

O

All

ship_to_company_name

Yes

String (40)

-

-

-

shipTo_company

shipTo_company

O

O

O

O

O

O

O

All

ship_to_forename

Yes

String (60)

-

-

-

shipTo_firstName

shipTo_firstName

O

O

O

O

O

O

O

All

ship_to_surname

Yes

String (60)

-

-

-

shipTo_lastName

shipTo_lastName

O

O

O

O

O

O

O

All

ship_to_phone

Yes

String (15)

( ),+-.*#xX1234567890

-

-

shipTo_phoneNumber

shipTo_phoneNumber

O

O

O

O

O

O

O

All

shipping_method

Yes

String (50)

sameday,oneday,twoday,threeday,lowcost,pickup,other,none

Used for Decision Manager risk profiling.

-

shipTo_shippingMethod

shipTo_shippingMethod

N/A

N/A

N/A

N/A

N/A

N/A

O

All

tax_amount

No

String (15)

.1234567890

Will display during the checkout experience, if enabled on the Payment Form section of the profile in the EBC. If line items are used, this should equal the sum of each line item's tax amount multiplied by quantity.

-

taxAmount

purchaseTotals_taxAmount

O

O

N/A

N/A

O

O

O

All

0

payment_token

No

-

-

Retrieves billing and shipping details stored against the token.

-

### Does not exist ###

recurringSubscriptionInfo_subscriptionID

N/A

N/A

N/A

M

M

N/A

N/A

All

allow_payment_token_update

No

String (5)

true,false

If true, allows the billing, shipping and payment details stored against a token to be updated. When used with One-click payment will display 'Edit' to the cardholder. If you wish to update details stored against the token without allowing the cardholder to edit, omit this value and use the transaction_type of 'Update payment type'

-

### Does not exist ###

### Does not exist ###

N/A

N/A

N/A

O

O

N/A

N/A

All

payment_token_comments

No

String (255)

-

Comments in this field are stored against the token, and displayed in the Subscription Detail report.

-

comments

comments

N/A

O

O

O

O

N/A

N/A

All

payment_token_title

No

String (60)

-

Comments in this field are stored against the token, and displayed in the Subscription Detail report.

-

subscription_title

subscription_title

N/A

O

O

O

O

N/A

N/A

All

recurring_amount

No

-

String (15)

-

-

recurringSubscriptionInfo_amount

recurringSubscriptionInfo_amount

N/A

N/A

N/A

N/A

N/A

M

N/A

All

recurring_frequency

No

String (20)

weekly,monthly,quarterly,annually,bi-weekly,semi-monthly,quad-weekly,semi-annually

weekly: once every seven days, commencing on the recurring_start_date. monthly: once every month, commencing on the recurring_start_date. Start date of 31st/30th/29th will lead to billings on the last day of shorter months. quarterly: Once every three months, see monthly for end of month billing date logic. annually: Once a year. bi-weekly: Once every 14 days. semi-monthly: Billed on the 1st and 15th of each month, regardless of start date specified. quad-weekly: Once every 28 days. semi-annually: Once every 6 months, see monthly for end of month billing date logic.

-

recurringSubscriptionInfo_frequency

recurringSubscriptionInfo_frequency

N/A

N/A

N/A

N/A

N/A

M

N/A

All

recurring_number_of_installments

No

String (3)

{any number between 1 and 156}

Optional field containing the number of installments, payments will cease once the number of installments specified has elapsed. This field cannot be used for an update to a subscription.

-

recurringSubscriptionInfo_numberOfPayments

recurringSubscriptionInfo_numberOfPayments

N/A

N/A

N/A

N/A

N/A

O

N/A

All

recurring_start_date

No

String (8)

{format YYYYMMDD}

If not populated or in the past, will default to tomorrows date.

-

recurringSubscriptionInfo_startDate

recurringSubscriptionInfo_startDate

N/A

N/A

N/A

N/A

N/A

O

N/A

All

device_fingerprint_id

No

String (88)

-

Equivalent to the session ID used in the Decision Manager Device Fingerprint code segments.

-

deviceFingerprintID

deviceFingerprintID

N/A

N/A

N/A

N/A

N/A

N/A

O

All

item_#_code

No

String (255)

l default l adult_content l coupon l electronic_good l electronic_software l gift_certificate l service l subscription l handling_only l service l shipping_and_handling l shipping_only l subscription

Indicates the type of good. # represents the line item number, starting at 0 with a maximum value of 49.

-

item_#_productCode

item_#_productCode

O

O

N/A

N/A

O

O

O

All

item_#_name

No

String (255)

-

# represents the line item number, starting at 0 with a maximum value of 49.

-

item_#_productName

item_#_productName

O

O

N/A

N/A

O

O

O

All

item_#_quantity

No

String (10)

{Positive integer}

Required if one of the following item codes is used: l adult_content l coupon l electronic_good l electronic_software l gift_certificate l service l subscription  # represents the line item number, starting at 0 with a maximum value of 49.

-

item_#_quantity

item_#_quantity

O

O

N/A

N/A

O

O

O

All

item_#_sku

No

String (255)

-

Your product identifier. Required if one of the following item codes is used: l adult_content l coupon l electronic_good l electronic_software l gift_certificate l service l subscription  # represents the line item number, starting at 0 with a maximum value of 49.

-

item_#_productSKU

item_#_productSKU

O

O

N/A

N/A

O

O

O

All

item_#_tax_amount

No

String (15)

{Positive integer}

Tax amount for the line item. Cannot be a negative number. Is the same currency as the total amount. # represents the line item number, starting at 0 with a maximum value of 49.

-

item_#_taxAmount

item_#_taxAmount

O

O

N/A

N/A

O

O

O

All

item_#_unit_price

No

String (15)

{Positive integer}

Per unit price for the item, cannot be a negative number.  # represents the line item number, starting at 0 with a maximum value of 49.

-

item_#_unitPrice

item_#_unitPrice

O

O

N/A

N/A

O

O

O

All

line_item_count

No

String (2)

{Sequential number from 0 to 49}

This is a required field if any item_#_* fields are used. Should equal the total number of line items included in the request.

-

lineItemCount

### Does not exist ###

O

O

N/A

N/A

O

O

O

All

journey_type

No

String (32)

-

Type of travel, such as: one way or round trip.

-

decisionManager_travelData_journeyType

decisionManagerTravelData_journeyType

N/A

N/A

N/A

N/A

N/A

N/A

O

All

complete_route

No

String (255)

-

Concatenation of individual travel legs in the format for example: SFO-JFK:JFK-LHR:LHR-CDG. Use this field or the journey_leg#_dest and _orig fields.

Link

decisionManager_travelData_completeRoute

decisionManager_travelData_completeRoute

N/A

N/A

N/A

N/A

N/A

N/A

O

All

journey_leg#_dest

No

String (3)

{See comments}

Airport code for the destination of the leg of the trip designated by the pound (#) symbol in the field name. This code is usually three digits long, for example: SFO = San Francisco. Do not use the colon (:) or the dash (-). See link for list of airport codes. Note In your request, send either the complete route or the individual legs (_leg#_orig and _leg#_dest). If you send all the fields, the complete route takes precedence over the individual legs.

Link

decisionManager_travelData_leg#_dest

decisionManager_travelData_leg_#_destination

N/A

N/A

N/A

N/A

N/A

N/A

O

All

journey_leg#_orig

No

String (3)

{See comments}

See above

Link

decisionManager_travelData_leg#_orig

decisionManager_travelData_leg_#_origin

N/A

N/A

N/A

N/A

N/A

N/A

O

All

departure_time

No

DateTime (25)

{See comments}

Departure date and time of the first leg of the trip. Use one of the following formats: n yyyy-MM-dd HH:mm z n yyyy-MM-dd hh:mm a z n yyyy-MM-dd hh:mma z HH = hour in 24-hour format hh = hour in 12-hour format a = am or pm (case insensitive) z = time zone of the departing flight, for example: If the airline is based in city A, but the flight departs from city B, z is the time zone of city B at the time of departure. Important For travel information, use GMT instead of UTC, or use the local time zone. Examples 2011-03-20 11:30 PM PDT 2011-03-20 11:30pm GMT 2011-03-20 11:30pm GMT-05:00 Eastern Standard Time: GMT-05:00 or EST Note When specifying an offset from GMT, the format must be exactly as specified in the example. Insert no spaces between the time zone and the offset.

-

decisionManager_travelData_departureDateTime

decisionManager_travelData_departureDateTime

N/A

N/A

N/A

N/A

N/A

N/A

O

All

skip_decision_manager

No

String (5)

true,false

Allows DM to be skipped on a per transaction basis, even if DM is enabled an profile level.

-

### Does not exist ###

decisionManager_enabled

N/A

N/A

N/A

N/A

N/A

N/A

O

All