On This Page

Request Fields

To prevent data tampering, sign all request fields except for fields that contain data the customer is entering.
When signing fields in the request, create a comma-separated list of the fields. The sequence of the fields in the string is critical to the signature generation process. For example: 
bill_to_forename=john
bill_to_surname=doe
bill_to_email=jdoe@example.com
signed_field_names=bill_to_forename,bill_to_surname,bill_to_email
When generating the security signature, create a comma-separated name=value string of the POST fields that are included in the
signed_field_names
 field. The sequence of the fields in the string is critical to the signature generation process. For example:
  • bill_to_forename=john
  • bill_to_surname=doe
  • bill_to_email=jdoe@example.com
The string to sign is
bill_to_forename=john,bill_to_surname=doe,bill_to_email=jdoe@example.com
For information on the signature generation process, see the security script of the sample code for the scripting language you are using. See Scripting Language Samples.
The TC 33 Capture file contains information about the purchases and refunds that a merchant submits to
Cybersource
.
Visa Platform Connect
 creates the TC 33 Capture file at the end of the day and sends it to the merchant’s acquirer, who uses this information to facilitate end-of-day clearing processing with payment card companies.
access_key
Required for authentication with
Secure Acceptance
. See Security Keys.
To prevent data tampering, sign this field.
Used By & Required (R) or Optional (O):
 Required by the
Secure Acceptance
 application.
Data Type & Length:
 Alphanumeric String (32)
aggregator_id
Value that identifies you as a payment aggregator. Get this value from your processor.
Visa Platform Connect
:
 The value for this field corresponds to this data in the TC 33 capture file:
  • Record: CP01 TCR6
  • Position: 95-105
  • Field: Mastercard Payment Facilitator ID
FDC Compass
:
 This value must consist of uppercase characters.
Field Length:
  • American Express Direct: 20
  • Visa Platform Connect
    : 11
  • FDC Compass: 20
  • FDC Nashville Global: 15
Required/Optional:
  • American Express Direct: R for all aggregator transactions.
  • Visa Platform Connect
    : R for Mastercard aggregator authorizations; otherwise, not used.
  • FDC Compass: R for all aggregator transactions.
  • FDC Nashville Global: R for all aggregator transactions.
Used By & Required (R) or Optional (O):
authorization
 (See description)
Data Type & Length:
 String (See description)
allow_payment_token_update
Indicates whether the customer can update the billing, shipping, and payment information on the order review page. Possible values:
  • true
    : Customer can update details.
  • false
    : Customer cannot update details.
Used By & Required (R) or Optional (O):
update_payment_token
 (R)
Data Type & Length:
 Enumerated String (5)
amount
Total amount for the order. Must be greater than or equal to zero and must equal the total amount of each line item including the tax amount.
To prevent data tampering, sign this field.
Used By & Required (R) or Optional (O):
  • create_payment_token
     (R)
  • authorization
     or
    sale
     (R)
  • authorization,create_payment_token
     (R)
  • sale,create_payment_token
     (R)
  • update_payment_token
     (O)
Data Type & Length:
 Amount String (15)
auth_indicator
Flag that specifies the purpose of the authorization. Possible values:
  • 0
    : Preauthorization
  • 1
    : Final authorization
Mastercard requires European merchants to indicate whether the authorization is a final authorization or a preauthorization.
To set the default for this field, contact customer support.
Used By & Required (R) or Optional (O):
authorization
 (See description)
Data Type & Length:
 String (1)
auth_trans_ref_no
Transaction reference number. Identifier used for tracking a request through to the payment processor for reconciliation.
Used By & Required (R) or Optional (O):
authorization
 (See description)
Data Type & Length:
 String
  • China UnionPay: 12
  • TeleCheck: 50
  • Visa Platform Connect: 25
  • All other processors: 60
auth_type
Authorization type. Possible values:
  • AUTOCAPTURE
    : Automatic capture.
  • STANDARDCAPTURE
    : Standard capture.
  • verbal
    : Forced capture.
Asia, Middle East, and Africa Gateway; Cielo; Comercio Latino; and Cybersource Latin American Processing
:
 Set this field to
AUTOCAPTURE
 and include it in a bundled request to indicate that you are requesting an automatic capture. If your account is configured to enable automatic captures, set this field to
STANDARDCAPTURE
 and include it in a standard authorization or bundled request to indicate that you are overriding an automatic capture.
Used By & Required (R) or Optional (O):
  • authorization
     (See description)
  • capture
     (Required for a verbal authorization; otherwise, not used.)
Data Type & Length:
 Cielo, Comercio Latino, and Cybersource Latin American Processing: String (15)
All other processors: String (11)
bill_payment
Flag that indicates a payment for a bill or for an existing contractual loan. Visa provides a Bill Payment program that enables customers to use their Visa cards to pay their bills. Possible values:
  • true
    : Bill payment or loan payment.
  • false
     (default): Not a bill payment or loan payment.
Used By & Required (R) or Optional (O):
 Optional
Data Type & Length:
 Enumerated String (5)
bill_to_address_city
City in the billing address.
This value can be entered by your customer during the checkout process, or you can include this field in your request to
Secure Acceptance
. See Configuring Billing Information Fields.
Used By & Required (R) or Optional (O):
  • create_payment_token
     (R)
  • authorization
     or
    sale
     (R)
  • authorization,create_payment_token
     (R)
  • sale,create_payment_token
     (R)
  • update_payment_token
     (O)
Data Type & Length:
 AlphaNumericPunctuation String (50)
bill_to_address_country
Country code for the billing address. Use the two-character ISO country codes.
This value can be entered by your customer during the checkout process, or you can include this field in your request to
Secure Acceptance
. See Configuring Billing Information Fields.
Used By & Required (R) or Optional (O):
  • create_payment_token
     (R)
  • authorization
     or
    sale
     (R)
  • authorization,create_payment_token
     (R)
  • sale,create_payment_token
     (R)
  • update_payment_token
     (O)
Data Type & Length:
 Alpha String (2)
bill_to_address_line1
First line of the billing address.
On JCN Gateway, this field is required when the authorization or sale request includes
create_payment_token
 or
Decision Manager
.
This field is optional when requesting an authorization or a sale without
create_payment_token
 or
Decision Manager
.
This value can be entered by your customer during the checkout process, or you can include this field in your request to
Secure Acceptance
. See Configuring Billing Information Fields.
Used By & Required (R) or Optional (O):
  • create_payment_token
     (R)
  • authorization
     or
    sale
     (R)
  • authorization,create_payment_token
     (R)
  • sale,create_payment_token
     (R)
  • update_payment_token
     (O)
Data Type & Length:
AlphaNumericPunctuation
  • Visa Platform Connect
    : String (40)
  • Moneris: String (50)
  • Worldpay VAP: String (35)
  • All other processors: String (60)
bill_to_address_line2
Second line of the billing address.
This value can be entered by your customer during the checkout process, or you can include this field in your request to
Secure Acceptance
. See Configuring Billing Information Fields.
Used By & Required (R) or Optional (O):
 Optional
Data Type & Length:
AlphaNumericPunctuation
  • Visa Platform Connect
    : String (40)
  • Moneris: String (50)
  • Worldpay VAP: String (35)
  • All other processors: String (60)
bill_to_address_postal_code
Postal code for the billing address.
This field is required if
bill_to_address_country
 is U.S. or Canada. 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:
 A1B2C3. For the rest of the world countries, the maximum length is 10.
This value can be entered by your customer during the checkout process, or you can include this field in your request to
Secure Acceptance
. See Configuring Billing Information Fields.
Used By & Required (R) or Optional (O):
 See description.
Data Type & Length:
 AlphaNumericPunctuation (See description)
bill_to_address_state
State or province in the billing address.
For the U.S. and Canada, use the standard state, province, and territory codes.
This field is required if
bill_to_address_country
 is U.S. or Canada.
This value can be entered by your customer during the checkout process, or you can include this field in your request to
Secure Acceptance
. See Configuring Billing Information Fields.
Used By & Required (R) or Optional (O):
 See description.
Data Type & Length:
 AlphaNumericPunctuation String (20)
bill_to_company_name
Name of the customer's company.
This value can be entered by your customer during the checkout process, or you can include this field in your request to
Secure Acceptance
. See Configuring Billing Information Fields.
Used By & Required (R) or Optional (O):
 Optional
Data Type & Length:
 AlphaNumericPunctuation String (60)
bill_to_email
Customer email address, including the full domain name.
This value can be entered by your customer during the checkout process, or you can include this field in your request to
Secure Acceptance
. See Configuring Billing Information Fields.
Used By & Required (R) or Optional (O):
  • create_payment_token
     (R)
  • authorization
     or
    sale
     (R)
  • authorization,create_payment_token
     (R)
  • sale,create_payment_token
     (R)
  • update_payment_token
     (O)
Data Type & Length:
 Email String (255)
bill_to_forename
Customer first name. This name must be the same as the name on the card.
This value can be entered by your customer during the checkout process, or you can include this field in your request to
Secure Acceptance
. See Configuring Billing Information Fields.
Used By & Required (R) or Optional (O):
  • create_payment_token
     (R)
  • authorization
     or
    sale
     (R)
  • authorization,create_payment_token
     (R)
  • sale,create_payment_token
     (R)
  • update_payment_token
     (O)
Data Type & Length:
 AlphaNumericPunctuation String (60)
bill_to_phone
Customer phone number.
Cybersource
 recommends that you include the country code if the order is from outside the U.S.
This value can be entered by your customer during the checkout process, or you can include this field in your request to
Secure Acceptance
. See Configuring Billing Information Fields.
This field is optional for card payments.
For ACH payments, this field is required if your processor is Cybersource ACH Service or
TeleCheck
.
Used By & Required (R) or Optional (O):
 See description.
Data Type & Length:
 Phone String (6 to 15)
String (10) if using
TeleCheck
 for ACH payments.
bill_to_surname
Customer last name. This name must be the same as the name on the card.
This value can be entered by your customer during the checkout process, or you can include this field in your request to
Secure Acceptance
. See Configuring Billing Information Fields.
Used By & Required (R) or Optional (O):
  • create_payment_token
     (R)
  • authorization
     or
    sale
     (R)
  • authorization,create_payment_token
     (R)
  • sale,create_payment_token
     (R)
  • update_payment_token
     (O)
Data Type & Length:
 AlphaNumericPunctuation String (60)
card_cvn
Card verification number.
For American Express card types, the CVN must be 4 digits.
This field can be configured as required or optional. See Payment Method Configuration.
Used By & Required (R) or Optional (O):
 See description.
Data Type & Length:
 Numeric String (4)
card_expiry_date
Card expiration date.
Format: MM-yyyy
Used By & Required (R) or Optional (O):
  • create_payment_token
     (R)
  • authorization
     or
    sale
     (R)
  • authorization,create_payment_token
     (R)
  • sale,create_payment_token
     (R)
  • update_payment_token
     (O)
Data Type & Length:
 Date (a) String (7)
card_number
Card number.
Use only numeric values. Be sure to include valid and well-formed data for this field.
Used By & Required (R) or Optional (O):
  • create_payment_token
     (R)
  • authorization
     or
    sale
     (R)
  • authorization,create_payment_token
     (R)
  • sale,create_payment_token
     (R)
  • update_payment_token
     (O)
Data Type & Length:
 Numeric String (20)
card_type
Type of card to authorize. Possible values:
  • 001
    : Visa
  • 002
    : Mastercard
  • 003
    : American Express
  • 004
    : Discover
  • 005
    : Diners Club: cards starting with 54 or 55 are rejected.
  • 006
    : Carte Blanche
  • 007
    : JCB
  • 014
    : EnRoute
  • 021
    : JAL
  • 024
    : Maestro UK Domestic
  • 031
    : Delta
  • 033
    : Visa Electron
  • 034
    : Dankort
  • 036
    : Carte Bancaire
  • 037
    : Carta Si
  • 042
    : Maestro International
  • 043
    : GE Money UK card
  • 050
    : Hipercard (sale only)
  • 054
    : Elo
  • 062
    : China UnionPay
Used By & Required (R) or Optional (O):
  • create_payment_token
     (R)
  • authorization
     or
    sale
     (R)
  • authorization,create_payment_token
     (R)
  • sale,create_payment_token
     (R)
  • update_payment_token
     (O)
Data Type & Length:
 Enumerated String (3)
card_type_selection_indicator
Identifies whether the card type is the result of the default acquirer parameter settings or the selection of the cardholder. Possible values:
  • 0
    : Card type selected by default acquirer settings.
  • 1
    : Card type selected by cardholder.
This field is supported only on Credit Mutuel-CIC. The default value is
1
.
Used By & Required (R) or Optional (O):
authorization
 (O)
Data Type & Length:
 String (1)
company_tax_id
Company's tax identifier.
Contact your
TeleCheck
 representative to find out whether this field is required or optional.
This value can be entered by your customer during the checkout process, or you can include this field in your request to
Secure Acceptance
. See Configuring ACH Information Fields.
Used By & Required (R) or Optional (O):
  • sale
     (See description)
  • create_payment_token
     (See description)
  • sale,create_payment_token
     (See description)
  • update_payment_token
     (See description)
Data Type & Length:
 AlphaNumericPunctuation String (9)
complete_route
Concatenation of individual travel legs in the format, for example: SFO-JFK:JFK-LHR:LHR-CDG.
For a complete list of airport codes, see IATA's City Code Directory.
In your request, send either the complete route or the individual legs (
journey_leg#_orig
 and
journey_leg#_dest
). If you send all the fields, the value of
complete_route
 takes precedence over that of the
journey_leg#
 fields.
Used By & Required (R) or Optional (O):
 Optional
Data Type & Length:
 AlphaNumericPunctuation String (255)
conditions_accepted
Indicates whether the customer accepted the service fee amount. Possible values:
  • false
    : Customer did not accept.
  • true
    : Customer did accept.
Used By & Required (R) or Optional (O):
 Required when service fee is enabled for the profile. See Service Fees.
Data Type & Length:
 Enumerated String (5)
consumer_id
Identifier for the customer's account. This field is defined when you create a subscription.
Used By & Required (R) or Optional (O):
  • create_payment_token
     (O)
  • authorization,create_payment_token
     (O)
  • sale,create_payment_token
     (O)
  • update_payment_token
     (O)
Data Type & Length:
 AlphaNumericPunctuation String (100)
credential_stored_on_file
Indicates whether to associate the new network transaction ID with the payment token for future merchant-initiated transactions (MITs). Set this field to
true
 when you use a payment token for a cardholder-initiated transaction (CIT) and you plan to set up a new schedule of MITs using an existing payment token. This will ensure that the new network transaction ID is associated with the token. Possible values:
  • true
  • false
In Europe, enable Payer Authentication on Secure Acceptance and set the
payer_authentication_challenge_code
 field to
04
 on the initial cardholder-initiated transaction (CIT) to ensure compliance with Strong Customer Authentication (SCA) rules.
Used By & Required (R) or Optional (O):
 Optional
Data Type & Length:
 String (5)
cryptocurrency_purchase
Flag that specifies whether the payment is for the purchase of cryptocurrency.
This field is supported only for Visa transactions on Visa Platform Connect. Possible values:
  • true
    : Payment is for the purchase of cryptocurrency.
  • false
     (default): Payment is not for the purchase of cryptocurrency.
Used By & Required (R) or Optional (O):
 Optional
Data Type & Length:
 String (5)
currency
Currency used for the order. For the possible values, see the ISO currency codes.
To prevent data tampering, sign this field.
Used By & Required (R) or Optional (O):
  • create_payment_token
     (R)
  • authorization
     or
    sale
     (R)
  • authorization,create_payment_token
     (R)
  • sale,create_payment_token
     (R)
  • update_payment_token
     (O)
Data Type & Length:
 Alpha String (3)
customer_browser_color_depth
Indicates the bit depth of the color palette for displaying images, in bits per pixel.
Secure Acceptance
 automatically populates this field, but you can override it.
Used By & Required (R) or Optional (O):
 Optional
Data Type & Length:
 String (2)
customer_browser_java_enabled
Indicates the ability of the cardholder browser to execute Java. The value is returned from the
navigator.javaEnabled
 property.
Secure Acceptance
 automatically populates this field, but you can override it. Possible values:
  • true
  • false
Used By & Required (R) or Optional (O):
 Optional
Data Type & Length:
 String (5)
customer_browser_javascript_enabled
Indicates the ability of the cardholder browser to execute JavaScript. This value is available from the fingerprint details of the cardholder's browser.
Secure Acceptance
 automatically populates this field, but you can override it. Possible values:
  • true
  • false
Used By & Required (R) or Optional (O):
 Optional
Data Type & Length:
 String (5)
customer_browser_language
Indicates the browser language as defined in IETF BCP47.
Secure Acceptance
 automatically populates this field, but you can override it.
Used By & Required (R) or Optional (O):
 Optional
Data Type & Length:
 String (8)
customer_browser_screen_height
Total height of the customer's screen in pixels.
Secure Acceptance
 automatically populates this field, but you can override it.
Example:
 864
Used By & Required (R) or Optional (O):
 Optional
Data Type & Length:
 String (6)
customer_browser_screen_width
Total width of the customer's screen in pixels.
Secure Acceptance
 automatically populates this field, but you can override it.
Used By & Required (R) or Optional (O):
 Optional
Data Type & Length:
 String (6)
customer_browser_time_difference
Difference between UTC time and the cardholder browser local time, in minutes.
Secure Acceptance
 automatically populates this field, but you can override it.
Used By & Required (R) or Optional (O):
 Optional
Data Type & Length:
 String (5)
customer_cookies_accepted
Indicates whether the customer's browser accepts cookies. Possible values:
  • true
    : Customer browser accepts cookies.
  • false
    : Customer browser does not accept cookies.
Used By & Required (R) or Optional (O):
 Optional
Data Type & Length:
 Enumerated String (5)
customer_gift_wrap
Indicates whether the customer requested gift wrapping for this purchase. Possible values:
  • true
    : Customer requested gift wrapping.
  • false
    : Customer did not request gift wrapping.
Used By & Required (R) or Optional (O):
 Optional
Data Type & Length:
 Enumerated String (5)
customer_ip_address
Customer's IP address reported by your web server using socket information.
Used By & Required (R) or Optional (O):
 Optional
Data Type & Length:
 IP, IPv4: String (15) or IPv6: String (39)
date_of_birth
Date of birth of the customer. Use the format: yyyyMMDD.
This value can be entered by your customer during the checkout process, or you can include this field in your request to
Secure Acceptance
. See Configuring ACH Information Fields.
Used By & Required (R) or Optional (O):
 Optional
Data Type & Length:
 Date (b) String (8)
debt_indicator
Flag that indicates a payment for an existing contractual loan under the VISA Debt Repayment program. Contact your processor for details and requirements. Possible formats:
  • false
     (default): Not a loan payment.
  • true
    : Loan payment.
Used By & Required (R) or Optional (O):
 Optional
Data Type & Length:
 Enumerated String (5)
departure_time
Departure date and time of the first leg of the trip. Use one of these formats:
  • yyyy-MM-DD HH:mm z
  • yyyy-MM-DD hh:mm a z
  • yyyy-MM-DD hh:mma z
  • HH = 24-hour format
  • hh = 12-hour format
  • a = am or pm (case insensitive)
  • z = time zone of the departing flight.
Examples:
  • 2023-01-20 23:30 GMT
  • 2023-01-20 11:30 PM GMT
  • 2023-01-20 11:30pm GMT
Used By & Required (R) or Optional (O):
 Optional
Data Type & Length:
 Date (c) DateTime (29)
device_fingerprint_id
Field that contains the session ID for the fingerprint. The string can contain uppercase and lowercase letters, digits, and these special characters: hyphen (-) and underscore (_).
However, do not use the same uppercase and lowercase letters to indicate different session IDs.
The session ID must be unique for each merchant ID. You can use any string that you are already generating, such as an order number or web session ID.
The
Cybersource
-generated device fingerprint ID overrides the merchant-generated device fingerprint ID.
Used By & Required (R) or Optional (O):
 Optional
Data Type & Length:
 AlphaNumericPunctuation String (88)
driver_license_number
Driver's license number of the customer.
Contact your
TeleCheck
 representative to find out whether this field is required or optional. If you include this field in your request, then you must also include the
driver_license_state
 field.
This value can be entered by your customer during the checkout process, or you can include this field in your request to
Secure Acceptance
. See Configuring ACH Information Fields.
Used By & Required (R) or Optional (O):
  • sale
     (See description)
  • create_payment_token
     (See description)
  • sale,create_payment_token
     (See description)
  • update_payment_token
     (See description)
Data Type & Length:
 Alphanumeric String (30)
driver_license_state
State or province where the customer's driver's license was issued.
For the U.S. and Canada, use the standard state, province, and territory codes.
Contact your
TeleCheck
 representative to find out whether this field is required or optional.
This value can be entered by your customer during the checkout process, or you can include this field in your request to
Secure Acceptance
. See Configuring ACH Information Fields.
Used By & Required (R) or Optional (O):
  • sale
     (See description)
  • create_payment_token
     (See description)
  • sale,create_payment_token
     (See description)
  • update_payment_token
     (See description)
Data Type & Length:
 Alpha String (2)
e_commerce_indicator
Commerce indicator for the transaction type.
Value:
install
.
This field is required only for installment payments on Cybersource Latin American Processing.
Used By & Required (R) or Optional (O):
authorization
 (See description)
Data Type & Length:
 String (20)
echeck_account_number
Account number.
This value can be entered by your customer during the checkout process, or you can include this field in your request to
Secure Acceptance
. See Configuring ACH Information Fields.
Used By & Required (R) or Optional (O):
  • sale
     (R)
  • create_payment_token
     (R)
  • sale,create_payment_token
     (R)
  • update_payment_token
     (O)
Data Type & Length:
 Numeric Non-negative integer (8 to 17)
echeck_account_type
Account type. Possible values:
  • C
    : Checking
  • S
    : Savings (USD only)
  • X
    : Corporate checking (USD only)
  • G
    : General Ledger
This value can be entered by your customer during the checkout process, or you can include this field in your request to
Secure Acceptance
. See Configuring ACH Information Fields.
Used By & Required (R) or Optional (O):
  • sale
     (R)
  • create_payment_token
     (R)
  • sale,create_payment_token
     (R)
  • update_payment_token
     (O)
Data Type & Length:
 Enumerated String (1)
echeck_check_number
Check number.
If your payment processor is
TeleCheck
, you should include this field.
This value can be entered by your customer during the checkout process, or you can include this field in your request to
Secure Acceptance
. See Configuring ACH Information Fields.
Used By & Required (R) or Optional (O):
  • sale
     (See description)
  • create_payment_token
     (See description)
  • sale,create_payment_token
     (See description)
  • update_payment_token
     (See description)
Data Type & Length:
 Numeric Integer (8)
echeck_effective_date
Effective date for the transaction. This date must be within 45 days of the current date.
Format: MMDDyyyy
Used By & Required (R) or Optional (O):
  • sale
     (O)
  • sale,create_payment_token
     (O)
Data Type & Length:
 Date (b) String (8)
echeck_routing_number
Bank routing number.
If the currency being used is
CAD
, the maximum length of the routing number is 8 digits.
If the currency being used is
USD
, the maximum length of the routing number is 9 digits.
This value can be entered by your customer during the checkout process, or you can include this field in your request to
Secure Acceptance
. See Configuring ACH Information Fields.
Used By & Required (R) or Optional (O):
  • sale
     (R)
  • create_payment_token
     (R)
  • sale,create_payment_token
     (R)
  • update_payment_token
     (O)
Data Type & Length:
 Numeric Non-negative integer (See description)
echeck_sec_code
Authorization method used for the transaction. See SEC Codes.
Bank of America ACH
 possible values:
  • CCD
  • PPD
  • TEL
  • WEB
Chase Paymentech Solutions
 in Canada, use
WEB
 for all ACH transactions.
Chase Paymentech Solutions
 in the U.S. possible values:
  • CCD
  • PPD
  • TEL
  • WEB
TeleCheck
 possible values:
  • PPD
  • TEL
  • WEB
Wells Fargo ACH
 possible values:
  • CCD
  • PPD
  • TEL
  • WEB
Used By & Required (R) or Optional (O):
  • sale
     (O)
  • create_payment_token
     (O)
  • sale,create_payment_token
     (O)
  • update_payment_token
     (O)
Data Type & Length:
 Enumerated String (3)
health_care_#_amount
Amount of the healthcare payment. # can range from
0
 to
4
. Send this field with a corresponding
health_care_#_amount_type
 field.
Used By & Required (R) or Optional (O):
authorization
 (O)
Data Type & Length:
 String (13)
health_care_#_amount_type
Type of healthcare payment. # can range from
0
 to
4
. Mastercard possible values:
  • eligible-total
    : total amount of healthcare.
  • prescription
Visa possible values:
  • clinic
  • dental
  • healthcare
    : total amount of healthcare.
  • healthcare-transit
  • prescription
  • vision
Send this field with a corresponding
health_care_#_amount
 field.
Used By & Required (R) or Optional (O):
authorization
 (O)
Data Type & Length:
 String (35)
ignore_avs
Ignore the results of AVS verification. Possible values:
  • true
  • false
To prevent data tampering, sign this field.
Used By & Required (R) or Optional (O):
 Optional
Data Type & Length:
 Enumerated String (5)
ignore_cvn
Ignore the results of CVN verification. Possible values:
  • true
  • false
To prevent data tampering, sign this field.
Used By & Required (R) or Optional (O):
 Optional
Data Type & Length:
 Enumerated String (5)
industry_datatype
Indicates whether the transaction includes industry data. For certain industries, you must set this field to an industry data value to be sent to the processor. When this field is not set to an industry value or is not included in the request, industry data does not go to the processor. Possible values:
  • healthcare_medical
  • healthcare_transit
Used By & Required (R) or Optional (O):
authorization
 (O)
Data Type & Length:
 String (20)
installment_amount
Amount for the current installment payment.
This field is required only for installment payments on Cybersource Latin American Processing or
Visa Platform Connect
.
Used By & Required (R) or Optional (O):
authorization
 (See description)
Data Type & Length:
 Amount (12)
installment_frequency
Frequency of the installment payments. Possible values:
  • B
    : Biweekly
  • M
    : Monthly
  • W
    : Weekly
This field is supported only on
Visa Platform Connect
.
Used By & Required (R) or Optional (O):
authorization
 (See description)
Data Type & Length:
 AlphaNumeric (2)
installment_plan_type
Flag that indicates the type of funding for the installment plan associated with the payment. Possible values:
  • 1
    : Merchant-funded installment plan
  • 2
    : Issuer-funded installment plan
If you do not include this field in the request, the value in your account is used. To change this value, contact customer support.
Visa Platform Connect
:
 American Express-defined code that indicates the type of installment plan for this transaction. Contact American Express for:
  • Information about the types of installment plans that American Express provides.
  • Values for this field.
Used By & Required (R) or Optional (O):
authorization
 (See description)
Data Type & Length:
  • Cybersource Latin American Processing: String (1)
  • Visa Platform Connect
    : String (2)
installment_sequence
Installment number when making payments in installments. Used along with
installment_total_count
 to keep track of which payment is being processed. For example, the second of five payments would be passed as
installment_sequence
 = 2 and
installment_total_count
 = 5.
This field is required only for installment payments on
Visa Platform Connect
.
Used By & Required (R) or Optional (O):
authorization
 (See description)
Data Type & Length:
 Integer (2)
installment_total_amount
Total amount of the loan that is being paid in installments.
This field is required only for installment payments on Cybersource Latin American Processing and
Visa Platform Connect
.
Used By & Required (R) or Optional (O):
authorization
 (See description)
Data Type & Length:
 Amount (12)
installment_total_count
Total number of installment payments as part of an authorization. Possible values:
1
 to
99
.
This field is required only for installment payments on Cybersource Latin American Processing and
Visa Platform Connect
.
Used By & Required (R) or Optional (O):
authorization
 (See description)
Data Type & Length:
 Numeric String (2)
issuer_additional_data
Data defined by the issuer. See the “Discretionary Data” section in
Credit Card Services Optional Features Supplement
.
Used By & Required (R) or Optional (O):
authorization
 (O)
Data Type & Length:
 Alphanumeric String (256)
item_#_code
Type of product. # can range from
0
 to
199
.
Used By & Required (R) or Optional (O):
 Optional. If you include this field, you must also include the
line_item_count
 field.
Data Type & Length:
 AlphaNumericPunctuation String (255)
item_#_name
Name of the item. # can range from
0
 to
199
.
This field is required when the
item_#_code
 value is not default nor related to shipping or handling.
Used By & Required (R) or Optional (O):
 See description. If you include this field, you must also include the
line_item_count
 field.
Data Type & Length:
 AlphaNumericPunctuation String (255)
item_#_passenger_email
Passenger's email address.
Used By & Required (R) or Optional (O):
 Optional
Data Type & Length:
 String (255)
item_#_passenger_forename
Passenger's first name.
Used By & Required (R) or Optional (O):
 Optional
Data Type & Length:
 String (60)
item_#_passenger_id
ID of the passenger to whom the ticket was issued. For example, you can use this field for the frequent flyer number.
Used By & Required (R) or Optional (O):
 Optional
Data Type & Length:
 String (32)
item_#_passenger_phone
Passenger's phone number. If the order is from outside the U.S., include the country code.
Used By & Required (R) or Optional (O):
 Optional
Data Type & Length:
 String (15)
item_#_passenger_status
Your company's passenger classification, such as with a frequent flyer number. In this case, you might use values such as standard, gold, or platinum.
Used By & Required (R) or Optional (O):
 Optional
Data Type & Length:
 String (32)
item_#_passenger_surname
Passenger's last name.
Used By & Required (R) or Optional (O):
 Optional
Data Type & Length:
 String (60)
item_#_passenger_type
Passenger classification associated with the price of the ticket. Possible values:
  • ADT
    : Adult
  • CNN
    : Child
  • INF
    : Infant
  • YTH
    : Youth
  • STU
    : Student
  • SCR
    : Senior Citizen
  • MIL
    : Military
Used By & Required (R) or Optional (O):
 Optional
Data Type & Length:
 String (32)
item_#_quantity
Quantity of line items. The default value is
1
.
Required field when one of these product codes is used:
  • adult_content
  • coupon
  • electronic_good
  • electronic_software
  • gift_certificate
  • service
  • subscription
# can range from
1
 to
199
.
This field is required when the
item_#_code
 value is not default nor related to shipping or handling.
Used By & Required (R) or Optional (O):
 See description. If you include this field, you must also include the
line_item_count
 field.
Data Type & Length:
 Numeric String (10)
item_#_sku
Identification code for the product.
Required field when one of these product codes is used:
  • adult_content
  • coupon
  • electronic_good
  • electronic_software
  • gift_certificate
  • service
  • subscription
# can range from
0
 to
199
.
Used By & Required (R) or Optional (O):
 See description. If you include this field, you must also include the
line_item_count
 field.
Data Type & Length:
 AlphaNumericPunctuation String (255)
item_#_tax_amount
Tax amount to apply to the line item. # can range from
0
 to
199
. This value cannot be negative. The tax amount and the offer amount must be in the same currency.
Used By & Required (R) or Optional (O):
 Optional. If you include this field, you must also include the
line_item_count
 field.
Data Type & Length:
 Amount String (15)
item_#_unit_price
Price of the line item. # can range from
0
 to
199
. This value cannot be negative.
You must include either this field or the amount field in the request.
Used By & Required (R) or Optional (O):
 See description. If you include this field, you must also include the
line_item_count
 field.
Data Type & Length:
 Amount String (15)
journey_leg#_dest
Airport code for the destination leg of the trip, designated by the pound (#) symbol in the field name. A maximum of 30 legs can be included in the request. This code is usually three digits long, for example: SFO = San Francisco. Do not use the colon (:) or the hyphen (-). For a complete list of airport codes, see IATA's City Code Directory.
In your request, send either the
complete_route
 field or the individual legs (
journey_leg#_orig
 and
journey_leg#_dest
). If you send all the fields, the complete route takes precedence over the individual legs.
Used By & Required (R) or Optional (O):
 Optional
Data Type & Length:
 Alpha String (3)
journey_leg#_orig
Airport code for the origin leg of the trip, designated by the pound (#) symbol in the field name. A maximum of 30 legs can be included in the request. This code is usually three digits long, for example: SFO = San Francisco. Do not use the colon (:) or the hyphen (-). For a complete list of airport codes, see IATA's City Code Directory.
In your request, send either the
complete_route
 field or the individual legs (
journey_leg#_orig
 and
journey_leg#_dest
). If you send all the fields, the complete route takes precedence over the individual legs.
Used By & Required (R) or Optional (O):
 Optional
Data Type & Length:
 Alpha String (3)
journey_type
Type of travel, such as one way or round trip.
Used By & Required (R) or Optional (O):
 Optional
Data Type & Length:
 AlphaNumericPunctuation String (32)
jpo_installments
Total number of Japanese installment payments. Possible values:
  • 2
  • 3
  • 5
  • 6
  • 10
  • 12
  • 15
  • 18
  • 20
  • 24
Used By & Required (R) or Optional (O):
 Required when the
jpo_payment_method
 value is
4
 and the currency type is
JPY
.
Data Type & Length:
 Numeric String (2)
jpo_payment_method
Japanese payment method. Possible values:
  • 1
    : Single payment
  • 2
    : Bonus payment
  • 4
    : Installment payment
  • 5
    : Revolving repayment
Required when the currency type is
JPY
.
Data Type & Length:
 Numeric String (1)
line_item_count
Total number of line items. Maximum number is 200.
Used By & Required (R) or Optional (O):
 Required when you include any item fields in the request.
Data Type & Length:
 Numeric String (2)
locale
Indicates the language to use for customer-facing content. Possible value:
en-us
. See Activating a Profile.
To prevent data tampering, sign this field.
Used By & Required (R) or Optional (O):
 Required by the
Secure Acceptance
 application.
Data Type & Length:
 Locale String (5)
merchant_defined_data#
Optional fields that you can use to store information (see Configuring Customer Notifications). # can range from
1
 to
100
.
Merchant-defined data fields
1
 to
4
 are associated with the payment token and are used for subsequent token-based transactions. Merchant-defined data fields
5
 to
100
 are passed through to
Decision Manager
 as part of the initial payment request and are not associated with the payment token.
Merchant-defined data fields are not intended to and MUST NOT be used to capture personally identifying information. Accordingly, merchants are prohibited from capturing, obtaining, and/or transmitting any personally identifying information in or via the merchant-defined data fields and any
Secure Acceptance
 field that is not specifically designed to capture personally identifying information. Personally identifying information includes, but is not limited to, card number, bank account number, social security number, driver's license number, state-issued identification number, passport number, card verification numbers (CVV, CVC2, CVV2, CID, CVN). If it is discovered that a merchant is capturing and/or transmitting personally identifying information via the merchant-defined data fields, whether or not intentionally, the merchant's account WILL immediately be suspended, which will result in a rejection of any and all transaction requests submitted by the merchant after the point of suspension.
Used By & Required (R) or Optional (O):
 Optional
Data Type & Length:
 AlphaNumericPunctuation String (100)
merchant_descriptor
Your business name. This name appears on the cardholder’s statement. When you include more than one consecutive space, extra spaces are removed.
This value must consist of English characters.
Used By & Required (R) or Optional (O):
authorization
 (O)
Data Type & Length:
 String (23)
merchant_descriptor_alternate
Alternate contact information for your business, such as an email address or URL. This value might appear on the cardholder’s statement. When you do not include this value in your request, the merchant URL in your account is sent.
This value must consist of English characters.
Used By & Required (R) or Optional (O):
authorization
 (O)
Data Type & Length:
 String (13)
merchant_descriptor_city
City for your business location. This value might appear on the cardholder’s statement. When you do not include this value in your request, the merchant city in your account is sent.
This value must consist of English characters.
Used By & Required (R) or Optional (O):
authorization
 (O)
Data Type & Length:
 String (13)
merchant_descriptor_contact
Telephone number for your business. This value might appear on the cardholder’s statement. When you include more than one consecutive space, extra spaces are removed. When you do not include this value in your request, the merchant phone number in your account is sent.
This value must consist of English characters.
Used By & Required (R) or Optional (O):
authorization
 (O)
Data Type & Length:
 String (14)
merchant_descriptor_country
Country code for your business location. Use the standard ISO Standard Country Codes. This value might appear on the cardholder’s statement. When you do not include this value in your request, the merchant country in your account is sent.
This value must consist of English characters.
Used By & Required (R) or Optional (O):
authorization
 (O)
Data Type & Length:
 String (2)
merchant_descriptor_postal_code
Postal code for your business location. This value might appear on the cardholder’s statement. If your business is domiciled in the U.S., you can use a 5-digit or 9-digit postal code. A 9-digit postal code must follow this format: [5 digits][dash][4 digits]. Example: 12345-6789. If your business is domiciled in Canada, you can use a 6-digit or 9-digit postal code. A 6-digit postal code must follow this format: [alpha][numeric][alpha][space][numeric][alpha][numeric]. Example: A1B 2C3. When you do not include this value in your request, the merchant postal code in your account is sent.
This value must consist of English characters.
Mastercard requires a postal code for any country that uses postal codes. You can provide the postal code in your account or you can include this field in your request.
Used By & Required (R) or Optional (O):
authorization
 (O)
Data Type & Length:
 String (14)
merchant_descriptor_state
State code or region code for your business location. This value might appear on the cardholder’s statement. For the U.S. and Canada, use the standard state, province, and territory codes. When you do not include this value in your request, the merchant state in your account is sent.
This value must consist of English characters.
Used By & Required (R) or Optional (O):
authorization
 (O)
Data Type & Length:
 String (3)
merchant_descriptor_street
Street address for your business location. This value might appear on the cardholder’s statement. When you do not include this value in your request, the merchant street in your account is sent.
This value must consist of English characters.
Used By & Required (R) or Optional (O):
authorization
 (O)
Data Type & Length:
 String (60)
merchant_secure_data1, merchant_secure_data2, merchant_secure_data3
Optional fields that you can use to store information. The data is encrypted before it is stored in the payment repository.
Used By & Required (R) or Optional (O):
 Optional
Data Type & Length:
 AlphaNumericPunctuation String (100)
merchant_secure_data4
Optional field that you can use to store information. The data is encrypted before it is stored in the payment repository.
Used By & Required (R) or Optional (O):
 Optional
Data Type & Length:
 AlphaNumericPunctuation String (2000)
override_backoffice_post_url
Overrides the backoffice post URL profile setting with your URL. URL must be HTTPS and support TLS 1.2 or later.
Used By & Required (R) or Optional (O):
 Optional
Data Type & Length:
 URL String (255)
override_custom_cancel_page
Overrides the custom cancel page profile setting with your URL. URL must be HTTPS and support TLS 1.2 or later.
Used By & Required (R) or Optional (O):
 Optional
Data Type & Length:
 URL String (255)
override_custom_receipt_page
Overrides the custom receipt profile setting with your URL. URL must be HTTPS and support TLS 1.2 or later.
To prevent data tampering, sign this field.
Used By & Required (R) or Optional (O):
 Optional
Data Type & Length:
 URL String (255)
override_customer_utc_offset
Overrides the transaction date and time with the number of minutes the customer is ahead of or behind UTC. Use this field to override the local browser time detected by
Secure Acceptance
. This time determines the date on receipt pages and emails. For example, if the customer is 2 hours ahead, the value is
120
; if 2 hours behind, then
-120
; if UTC, the value is
0
.
Used By & Required (R) or Optional (O):
 Optional
Data Type & Length:
 Integer (5)
override_paypal_order_setup
Overrides the PayPal order setup profile setting. Possible values:
  • include_authorization
    : The PayPal order is created and authorized.
  • exclude_authorization
    : The PayPal order is created but not authorized.
Used By & Required (R) or Optional (O):
 Optional See Enabling PayPal Express Checkout.
Data Type & Length:
 String (21)
payer_authentication_acquirer_country
Send this to tell issuers that the acquirer's country differs from the merchant country, and the acquirer is in the European Economic Area (EEA) and UK and Gibraltar.
Used By & Required (R) or Optional (O):
 Optional
Data Type & Length:
 String (2)
payer_authentication_acs_window_size
Sets the challenge window size that displays to the cardholder. The Access Control Server (ACS) replies with content that is formatted appropriately for this window size. The sizes are width x height in pixels.
Secure Acceptance
 calculates this value based on the size of the window in which
Secure Acceptance
 is displayed, but you can override it. Possible values:
  • 01
    : 250 x 400
  • 02
    : 390 x 400
  • 03
    : 500 x 600
  • 04
    : 600 x 400
  • 05
    : Full page
Used By & Required (R) or Optional (O):
 Optional
Data Type & Length:
 Integer (2)
payer_authentication_challenge_code
Possible values:
  • 01
    : No preference
  • 02
    : No challenge request
  • 03
    : Challenge requested (3-D Secure requestor preference)
  • 04
    : Challenge requested (mandate)
  • 05
    : No challenge requested (transactional risk analysis is already performed)
  • 06
    : No challenge requested (data share only)
  • 07
    : No challenge requested (strong consumer authentication is already performed)
  • 08
    : No challenge requested (use whitelist exemption if no challenge required)
  • 09
    : Challenge requested (whitelist prompt requested if challenge required)
This field will default to
01
 on merchant configuration and can be overridden by the merchant. EMV 3-D Secure 2.1.0 supports values
01
-
04
. Version 2.2.0 supports values
01
-
09
.
Used By & Required (R) or Optional (O):
 Optional
Data Type & Length:
 Integer (2)
payer_authentication_customer_annual_transaction_count
Number of transactions (successful and abandoned) for this cardholder account within the past year.
Used By & Required (R) or Optional (O):
 Optional
Data Type & Length:
 Integer (3)
payer_authentication_customer_daily_transaction_count
Number of transaction (successful or abandoned) for this cardholder account within the past 24 hours.
Used By & Required (R) or Optional (O):
 Optional
Data Type & Length:
 Integer (3)
payer_authentication_indicator
Indicates the type of authentication request.
Secure Acceptance
 automatically populates this field, but you can override it. Possible values:
  • 01
    : Payment transaction
  • 02
    : Recurring transaction
  • 03
    : Installment transaction
  • 04
    : Add card
  • 05
    : Maintain card
  • 06
    : Cardholder verification as part of EMV token identity and verification (ID&V)
Used By & Required (R) or Optional (O):
 Optional
Data Type & Length:
 Integer (2)
payer_authentication_marketing_source
Indicates origin of the marketing offer.
Used By & Required (R) or Optional (O):
 Optional
Data Type & Length:
 String (40)
payer_authentication_merchant_fraud_rate
Calculated by merchants according to Payment Service Directive 2 (PSD2) and Regulatory Technical Standards (RTS). European Economic Area (EEA) and UK and Gibraltar card fraud divided by all EEA and UK and Gibraltar card volumes. Possible values:
  • 1
    : Represents fraud rate ≤1
  • 2
    : Represents fraud rate >1 and ≤6
  • 3
    : Represents fraud rate >6 and ≤13
  • 4
    : Represents fraud rate >13 and ≤25
  • 5
    : Represents fraud rate >25
Used By & Required (R) or Optional (O):
 Optional
Data Type & Length:
 Integer (2)
payer_authentication_merchant_name
Your company's name as you want it to appear to the customer in the issuing bank's authentication form. This value overrides the value specified by your merchant bank.
Used By & Required (R) or Optional (O):
 Optional
Data Type & Length:
 String (25)
payer_authentication_merchant_score
Risk score provided by merchants. Used for Cartes Bancaires transactions.
Used By & Required (R) or Optional (O):
 Optional
Data Type & Length:
 String (20)
payer_authentication_message_category
Identifies the category of the message for a specific use case 3-D Secure Server. Possible values:
  • 01
    : PA (payment authentication).
  • 02
    : NPA (non-payment authentication).
  • 03-71
    : Reserved for EMVCo future use (values invalid until defined by EMVCo).
  • 80-99
    : Reserved for directory server use.
Used By & Required (R) or Optional (O):
 Optional
Data Type & Length:
 String (2)
payer_authentication_mobile_phone
Cardholder's mobile phone number.
Required for Visa Secure transactions in Brazil. Do not use this request field for any other types of transactions.
Used By & Required (R) or Optional (O):
 Optional
Data Type & Length:
 Integer (25)
payer_authentication_new_customer
Indicates whether the customer is a new or existing customer with the merchant. Possible values:
  • true
  • false
Used By & Required (R) or Optional (O):
 Optional
Data Type & Length:
 String (5)
payer_authentication_pre_order
Indicates whether cardholder is placing an order with a future availability or release date. Possible values:
  • 01
    : Merchandise available
  • 02
    : Future availability
Used By & Required (R) or Optional (O):
 Optional
Data Type & Length:
 Integer (2)
payer_authentication_pre_order_date
Expected date that a pre-ordered purchase will be available.
Format: yyyyMMDD
Used By & Required (R) or Optional (O):
 Optional
Data Type & Length:
 Integer (8)
payer_authentication_prior_authentication_data
Data that the ACS can use to verify the authentication process.
Used By & Required (R) or Optional (O):
 Optional
Data Type & Length:
 String (2048)
payer_authentication_prior_authentication_method
Method that the cardholder used previously to authenticate to the 3-D Secure requester. Possible values:
  • 01
    : Frictionless authentication through the ACS
  • 02
    : Cardholder challenge through the ACS
  • 03
    : AVS verified
  • 04
    : Other issuer methods
  • 05-79
    : Reserved for EMVCo future use (values invalid until defined by EMVCo)
  • 80-99
    : Reserved for directory server use
Used By & Required (R) or Optional (O):
 Optional
Data Type & Length:
 Integer (2)
payer_authentication_prior_authentication_reference_id
This field contains the ACS transaction ID for an authenticated transaction. For example, the first recurring transaction that was authenticated with the cardholder.
Used By & Required (R) or Optional (O):
 Optional
Data Type & Length:
 String (36)
payer_authentication_prior_authentication_time
Date and time in UTC of the previous cardholder authentication.
Format: yyyyMMDDhhmm
Used By & Required (R) or Optional (O):
 Optional
Data Type & Length:
 Integer (12)
payer_authentication_product_code
Specifies the product code, which designates the type of transaction. Possible values:
  • AIR
    : Airline purchase
    Required for American Express SafeKey (U.S.).
  • ACC
    : Accommodation Rental
  • ACF
    : Account funding
  • CHA
    : Check acceptance
  • DIG
    : Digital Goods
  • DSP
    : Cash Dispensing
  • GAS
    : Fuel
  • GEN
    : General Retail
  • LUX
    : Luxury Retail
  • PAL
    : Prepaid activation and load
  • PHY
    : Goods or services purchase
  • QCT
    : Quasi-cash transaction
  • REN
    : Car Rental
  • RES
    : Restaurant
  • SVC
    : Services
  • TBD
    : Other
  • TRA
    : Travel
Required for Visa Secure transactions in Brazil. Do not use this request field for any other types of transactions.
Used By & Required (R) or Optional (O):
 Optional
Data Type & Length:
 String (3)
payer_authentication_recurring_end_date
The date after which no further recurring authorizations should be performed. Format: yyyyMMDD.
This field is required for recurring transactions. If
recurring_frequency
 and
recurring_number_of_installments
 are included in the request,
Secure Acceptance
 will automatically populate this field. Specify a value to override this logic.
Used By & Required (R) or Optional (O):
 Optional
Data Type & Length:
 Integer (8)
payer_authentication_recurring_frequency
Integer value indicating the minimum number of days between recurring authorizations. A frequency of monthly is indicated by the value 28. Multiple of 28 days will be used to indicate months.
Example:
 6 months= 168.
This field is required for recurring transactions. If
recurring_frequency
 is included in the request,
Secure Acceptance
 will automatically populate this field. Specify a value to override this logic.
Used By & Required (R) or Optional (O):
 Optional
Data Type & Length:
 Integer (3)
payer_authentication_reorder
Indicates whether the cardholder is reordering previously purchased merchandise. Possible values:
  • 01
    : First time ordered
  • 02
    : Reordered
Used By & Required (R) or Optional (O):
 Optional
Data Type & Length:
 Integer (2)
payer_authentication_secure_corporate_payment
Indicates that dedicated payment processes and procedures were used. Potential secure corporate payment exemption applies. Possible values:
  • 0
  • 1
Used By & Required (R) or Optional (O):
 Optional
Data Type & Length:
 String (1)
payer_authentication_ship_to_address_first_used
Date on which this shipping address was first used. Possible values:
  • -1
    : Guest account
  • 0
    : First used during this transaction
If neither value applies, enter the date in yyyyMMDD format.
Used By & Required (R) or Optional (O):
 Optional
Data Type & Length:
 Integer (8)
payer_authentication_transaction_mode
Transaction mode identifier. Identifies the channel from which the transaction originates. Possible values:
  • M
    : MOTO (Mail Order Telephone Order)
  • R
    : Retail
  • S
    : E-commerce
  • P
    : Mobile Device
  • T
    : Tablet
Used By & Required (R) or Optional (O):
Payer Authentication
 (R)
Data Type & Length:
 String (1)
payer_authentication_whitelisted
Enables the communication of trusted beneficiary and whitelist status among the ACS, the directory server, and the 3-D Secure requester. Possible values:
  • true
    : 3-D Secure requester is whitelisted by cardholder
  • false
    : 3-D Secure requester is not whitelisted by cardholder
Used By & Required (R) or Optional (O):
 Optional
Data Type & Length:
 String (5)
payment_method
Method of payment. Possible values:
  • card
  • echeck
  • paypal
  • visacheckout
Used By & Required (R) or Optional (O):
Optional
.
Data Type & Length:
 Enumerated String (30)
payment_token
Identifier for the payment details. The payment token retrieves the card data, billing information, and shipping information from the payment repository. When this field is included in the request, the card data and billing and shipping information are optional.
You must be using Token Management Services. Populate this field with the customer token.
This field is required for token-based transactions.
Used By & Required (R) or Optional (O):
  • authorization
     or
    sale
     (R)
  • authorization,update_payment_token
     (R)
  • sale,update_payment_token
     (R)
  • update_payment_token
     (R)
Data Type & Length:
 Numeric String (32)
payment_token_comments
Optional comments you can add for the customer token.
Used By & Required (R) or Optional (O):
 Optional
Data Type & Length:
 AlphaNumericPunctuation String (255)
payment_token_title
Name or title for the customer token.
Used By & Required (R) or Optional (O):
 Optional
Data Type & Length:
 AlphaNumericPunctuation String (60)
profile_id
Identifies the profile to use with each transaction.
Used By & Required (R) or Optional (O):
 Assigned by the
Secure Acceptance
 application.
Data Type & Length:
 ASCIIAlphaNumericPunctuation String (36)
promotion_code
Promotion code for a transaction.
Used By & Required (R) or Optional (O):
 Optional
Data Type & Length:
 String (100)
recipient_account_id
Identifier for the recipient's account. Use the first six digits and last four digits of the recipient's account number.
Used By & Required (R) or Optional (O):
authorization
 (R for recipient transactions, otherwise not used)
Data Type & Length:
 Numeric String (10)
recipient_date_of_birth
Recipient's date of birth. Format: yyyyMMDD.
Used By & Required (R) or Optional (O):
authorization
 (R for recipient transactions, otherwise not used)
Data Type & Length:
 Date (b) String (8)
recipient_postal_code
Partial postal code for the recipient's address.
For example, if the postal code is NN5 7SG, the value for this field should be the first part of the postal code: NN5.
Used By & Required (R) or Optional (O):
authorization
 (R for recipient transactions, otherwise not used)
Data Type & Length:
 Alphanumeric String (6)
recipient_surname
Recipient's last name.
Used By & Required (R) or Optional (O):
authorization
 (R for recipient transactions, otherwise not used)
Data Type & Length:
 Alpha String (6)
recurring_amount
Payment amount for each installment or recurring subscription payment.
Used By & Required (R) or Optional (O):
  • create_payment_token
     (R)
  • authorization,create_payment_token
     (R)
  • sale,create_payment_token
     (R)
  • update_payment_token
     (O)
Data Type & Length:
 Amount String (15)
recurring_automatic_renew
Indicates whether to automatically renew the payment schedule for an installment subscription. Possible values:
  • true
     (default): Automatically renew.
  • false
    : Do not automatically renew.
Used By & Required (R) or Optional (O):
  • create_payment_token
     (O)
  • authorization,create_payment_token
     (O)
  • sale,create_payment_token
     (O)
  • update_payment_token
     (O)
Data Type & Length:
 Enumerated String (5)
recurring_frequency
Frequency of payments for an installment or recurring subscription. Possible values:
  • weekly
    : Every 7 days.
  • bi-weekly
    : Every 2 weeks.
  • quad-weekly
    : Every 4 weeks.
  • monthly
  • semi-monthly
    : Twice every month (1st and 15th).
  • quarterly
  • semi-annually
    : Twice every year.
  • annually
Used By & Required (R) or Optional (O):
  • create_payment_token
     (R)
  • authorization,create_payment_token
     (R)
  • sale,create_payment_token
     (R)
  • update_payment_token
     (O)
Data Type & Length:
 Enumerated String (20)
recurring_number_of_installments
Total number of payments set up for an installment subscription. Maximum values:
  • 261
    : Weekly
  • 130
    : Bi-weekly
  • 65
    : Quad-weekly
  • 60
    : Monthly
  • 120
    : Semi-monthly
  • 20
    : Quarterly
  • 10
    : Semi-annually
  • 5
    : Annually
Used By & Required (R) or Optional (O):
  • create_payment_token
     (R)
  • authorization,create_payment_token
     (R)
  • sale,create_payment_token
     (R)
  • update_payment_token
     (O)
Data Type & Length:
 Numeric String (3)
recurring_start_date
First payment date for an installment or recurring subscription payment. Date must use the format yyyyMMDD. If a date in the past is supplied, the start date defaults to the day after the date was entered.
Used By & Required (R) or Optional (O):
  • create_payment_token
     (O)
  • authorization,create_payment_token
     (O)
  • sale,create_payment_token
     (O)
  • update_payment_token
     (O)
Data Type & Length:
 Date (b) String (8)
reference_number
Unique merchant-generated order reference or tracking number for each transaction.
To prevent data tampering, sign this field.
Used By & Required (R) or Optional (O):
 Required by the
Secure Acceptance
 application.
Data Type & Length:
Asia, Middle East, and Africa Gateway: String (40); All other processors:
String (50)
returns_accepted
Indicates whether product returns are accepted. This field can contain one of these values:
  • true
  • false
Used By & Required (R) or Optional (O):
 Optional
Data Type & Length:
 Enumerated String (5)
sales_organization_id
Company ID assigned to an independent sales organization. Obtain this value from Mastercard.
Visa Platform Connect
:
 The value for this field corresponds to this data in the TC 33 capture file:
  • Record: CP01 TCR6
  • Position: 106-116
  • Field: Mastercard Independent Sales Organization ID
Used By & Required (R) or Optional (O):
authorization
 (Required for Mastercard aggregator transactions on
Visa Platform Connect
)
Data Type & Length:
 Nonnegative integer (11)
ship_to_address_city
City of shipping address.
This value can be entered by your customer during the checkout process, or you can include this field in your request to
Secure Acceptance
.
Used By & Required (R) or Optional (O):
 Optional
Data Type & Length:
 AlphaNumericPunctuation String (50)
ship_to_address_country
Country code for the shipping address. Use the two-character ISO country codes.
This value can be entered by your customer during the checkout process, or you can include this field in your request to
Secure Acceptance
.
Used By & Required (R) or Optional (O):
 Optional
Data Type & Length:
 Alpha String (2)
ship_to_address_line1
First line of shipping address.
This value can be entered by your customer during the checkout process, or you can include this field in your request to
Secure Acceptance
.
Used By & Required (R) or Optional (O):
 Optional
Data Type & Length:
 AlphaNumericPunctuation String (60)
ship_to_address_line2
Second line of shipping address.
This value can be entered by your customer during the checkout process, or you can include this field in your request to
Secure Acceptance
.
Used By & Required (R) or Optional (O):
 Optional
Data Type & Length:
 AlphaNumericPunctuation String (60)
ship_to_address_postal_code
Postal code for the shipping address.
This field is required if
bill_to_address_country
 is U.S. or Canada.
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. For the rest of the world countries, the maximum length is 10.
This value can be entered by your customer during the checkout process, or you can include this field in your request to
Secure Acceptance
.
Used By & Required (R) or Optional (O):
 Optional
Data Type & Length:
 AlphaNumericPunctuation
ship_to_address_state
State or province of shipping address. For the U.S. and Canada, use the standard state, province, and territory codes.
This field is required if shipping address is U.S. or Canada.
This value can be entered by your customer during the checkout process, or you can include this field in your request to
Secure Acceptance
.
Used By & Required (R) or Optional (O):
 Optional
Data Type & Length:
 AlphaNumericPunctuation String (2)
ship_to_company_name
Name of the company receiving the product.
This value can be entered by your customer during the checkout process, or you can include this field in your request to
Secure Acceptance
.
Used By & Required (R) or Optional (O):
 Optional
Data Type & Length:
 AlphaNumericPunctuation String (40)
ship_to_forename
First name of the person receiving the product.
This value can be entered by your customer during the checkout process, or you can include this field in your request to
Secure Acceptance
.
Used By & Required (R) or Optional (O):
 Optional
Data Type & Length:
 AlphaNumericPunctuation String (60)
ship_to_phone
Phone number of the shipping address.
This value can be entered by your customer during the checkout process, or you can include this field in your request to
Secure Acceptance
.
Used By & Required (R) or Optional (O):
 Optional
Data Type & Length:
 Phone String (6 to 15)
ship_to_surname
Last name of the person receiving the product.
This can be entered by your customer during the checkout process, or you can include this in your request to
Secure Acceptance
.
Used By & Required (R) or Optional (O):
 Optional
Data Type & Length:
 AlphaNumericPunctuation String (60)
ship_to_type
Shipping destination.
Example:
 Commercial, residential, store
Used By & Required (R) or Optional (O):
 Optional
Data Type & Length:
 String (25)
shipping_method
Shipping method for the product. Possible values:
  • sameday
    : Courier or same-day service
  • oneday
    : Next day or overnight service
  • twoday
    : Two-day service
  • threeday
    : Three-day service
  • lowcost
    : Lowest-cost service
  • pickup
    : Store pickup
  • other
    : Other shipping method
  • none
    : No shipping method
Used By & Required (R) or Optional (O):
 Optional
Data Type & Length:
 Enumerated String (10)
signature
Merchant-generated Base64 signature. This is generated using the signing method for the
access_key
 field supplied.
Used By & Required (R) or Optional (O):
 Required by the
Secure Acceptance
 application.
Data Type & Length:
 AlphaNumericPunctuation
signed_date_time
Date and time that the signature was generated. Must be in UTC Date & Time format. This field is used to check for duplicate transaction attempts.
Format: yyyy-MM-DDThh:mm:ssZ.
Example:
 2020-08-11T22:47:57Z equals August 11, 2020, at 22:47:57 (10:47:57 p.m.). The T separates the date and the time. The Z indicates UTC.
Your system time must be accurate to avoid payment processing errors related to the
signed_date_time
 field.
To prevent data tampering, sign this field.
Used By & Required (R) or Optional (O):
 Required by the
Secure Acceptance
 application.
Data Type & Length:
 ISO 8601 Date String (20)
signed_field_names
A comma-separated list of request fields that are signed. This field is used to generate a signature that is used to verify the content of the transaction to protect it from tampering.
All request fields should be signed to prevent data tampering, with the exception of the
card_number
,
card_cvn
, and
signature
 fields.
Used By & Required (R) or Optional (O):
 Required by the
Secure Acceptance
 application.
Data Type & Length:
 AlphaNumericPunctuation Variable
skip_auto_auth
Indicates whether to skip or perform the preauthorization check when creating this token. Possible values:
  • true
     (skip the preauthorization check)
  • false
     (perform the preauthorization check)
Used By & Required (R) or Optional (O):
 Optional
Data Type & Length:
 Enumerated String (5)
skip_decision_manager
Indicates whether to skip
Decision Manager
. This field can contain one of these values:
  • true
    :
    Decision Manager
     is not enabled for this transaction, and the device fingerprint ID will not be displayed.
  • false
Used By & Required (R) or Optional (O):
 Optional
Data Type & Length:
 Enumerated String (5)
submerchant_city
Sub-merchant's city.
FDC Compass:
 This value must consist of uppercase characters.
Used By & Required (R) or Optional (O):
authorization
  • American Express Direct: R for all aggregator transactions.
  • Visa Platform Connect
    : not used.
  • FDC Compass: R for all aggregator transactions.
  • FDC Nashville Global: R for all aggregator transactions.
Data Type & Length:
  • American Express Direct: String (15)
  • FDC Compass: String (21)
  • FDC Nashville Global: String (11)
submerchant_country
Sub-merchant's country. Use the two-character ISO country code.
FDC Compass:
 This value must consist of uppercase characters.
Used By & Required (R) or Optional (O):
authorization
  • American Express Direct: R for all aggregator transactions.
  • Visa Platform Connect
    : not used.
  • FDC Compass: O for all aggregator transactions.
  • FDC Nashville Global: R for all aggregator transactions.
Data Type & Length:
 String (3)
submerchant_email
Sub-merchant's email address.
Visa Platform Connect
:
 With American Express, the value for this field corresponds to this data in the TC 33 capture file:
  • Record: CP01 TCRB
  • Position: 25-64
  • Field: American Express Seller E-mail Address
Used By & Required (R) or Optional (O):
authorization
  • American Express Direct: R for all aggregator transactions.
  • Visa Platform Connect
    : O for all aggregator transactions with American Express; otherwise, not used.
  • FDC Compass: O for all aggregator transactions.
  • FDC Nashville Global: R for all aggregator transactions.
Data Type & Length:
  • American Express Direct: String (40)
  • Visa Platform Connect
    : String (40)
  • FDC Compass: String (40)
  • FDC Nashville Global: String (19)
submerchant_id
The ID you assigned to your sub-merchant.
FDC Compass:
 This value must consist of uppercase characters.
Visa Platform Connect
:
 With American Express, the value for this field corresponds to this data in the TC 33 capture file:
  • Record: CP01 TCRB
  • Position: 65-84
  • Field: American Express Seller ID
With Mastercard, the value for this field corresponds to this data in the TC 33 capture file:
  • Record: CP01 TCR6
  • Position: 117-131
  • Field: Sub-Merchant ID
Used By & Required (R) or Optional (O):
authorization
  • American Express Direct: R for all aggregator transactions.
  • Visa Platform Connect
    :
    • O for all American Express aggregator transactions.
    • R for all Mastercard aggregator authorizations.
    • Otherwise, not used.
  • FDC Compass: R for all aggregator transactions.
  • FDC Nashville Global: R for all aggregator transactions.
Data Type & Length:
  • American Express Direct: String (20)
  • Visa Platform Connect
     with American Express: String (20)
  • Visa Platform Connect
     with Mastercard: String (15)
  • FDC Compass: String (20) FDC
  • Nashville Global: String (14)
submerchant_name
Sub-merchant's business name.
FDC Compass:
 This value must consist of uppercase characters.
Used By & Required (R) or Optional (O):
authorization
  • American Express Direct: R for all aggregator transactions.
  • Visa Platform Connect
    : not used.
  • FDC Compass: R for all aggregator transactions.
  • FDC Nashville Global: R for all aggregator transactions.
Data Type & Length:
  • American Express Direct: String (37)
  • FDC Compass with American Express: String (19)
  • FDC Compass with Mastercard: String (37)
  • FDC Nashville Global: String (12)
submerchant_phone
Sub-merchant's telephone number.
Visa Platform Connect
:
 With American Express, the value for this field corresponds to this data in the TC 33 capture file:
  • Record: CP01 TCRB
  • Position: 5-24
  • Field: American Express Seller Telephone Number
FDC Compass:
 This value must consist of uppercase characters. Use one of these recommended formats: NNN-NNN-NNNN NNN-AAAAAAA
Used By & Required (R) or Optional (O):
authorization
  • American Express Direct: R for all aggregator transactions.
  • Visa Platform Connect
    : O for all aggregator transactions with American Express; otherwise, not used.
  • FDC Compass: R for all aggregator transactions.
  • FDC Nashville Global: R for all aggregator transactions.
Data Type & Length:
  • American Express Direct: String (20)
  • Visa Platform Connect
    : String (20)
  • FDC Compass: String (13)
  • FDC Nashville Global: String (10)
submerchant_postal_code
Partial postal code for the sub-merchant's address.
FDC Compass:
 This value must consist of uppercase characters.
Used By & Required (R) or Optional (O):
authorization
  • American Express Direct: R for all aggregator transactions.
  • Visa Platform Connect
    : not used.
  • FDC Compass: O for all aggregator transactions.
  • FDC Nashville Global: R for all aggregator transactions.
Data Type & Length:
  • American Express Direct: String (9)
  • FDC Compass: String (15)
  • FDC Nashville Global: String (9)
submerchant_state
Sub-merchant's state or province. For the U.S. and Canada, use the standard state, province, and territory codes.
FDC Compass:
 This value must consist of uppercase characters.
Used By & Required (R) or Optional (O):
authorization
  • American Express Direct: R for all aggregator transactions.
  • Visa Platform Connect
    : not used.
  • FDC Compass: O for all aggregator transactions.
  • FDC Nashville Global: R for all aggregator transactions.
Data Type & Length:
 String (2)
submerchant_street
First line of the sub-merchant's street address.
FDC Compass:
 This value must consist of uppercase characters.
Used By & Required (R) or Optional (O):
authorization
  • American Express Direct: R for all aggregator transactions.
  • Visa Platform Connect
    : not used.
  • FDC Compass: O for all aggregator transactions.
  • FDC Nashville Global: R for all aggregator transactions.
Data Type & Length:
  • American Express Direct: String (30)
  • FDC Compass: String (38)
  • FDC Nashville Global: String (25)
tax_amount
Total tax amount to apply to the order. This value cannot be negative.
To prevent data tampering, sign this field.
Used By & Required (R) or Optional (O):
 Optional
Data Type & Length:
 Amount String (15)
transaction_agreement_id
A unique ID generated by the merchant for recurring and unscheduled card-on-file transactions. It is shared in subsequent transactions.
The merchant generates an agreement ID for each card holder or payment agreement. This field can contain Arabic characters. This value is forwarded to the Saudi Arabian payment processor.
Used By & Required (R) or Optional (O):
 Required when
transaction_reason
 is provided by Saudi merchants.
Data Type & Length:
 String (140)
transaction_reason
Reason for the transaction. Set this field to one of these values when you create a payment token. Possible values:
  • setup_recurring
    : Set to this value when you plan to use the
    payment_token
     field for a fixed amount on a fixed schedule.
  • setup_standing_order
    : Set to this value when you plan to use the
    payment_token
     field for a variable amount on a fixed schedule.
  • setup_installments
    : Set to this value when you plan to use the
    payment_token
     field for a regular payment with a specified recurring number of installments.
  • setup_unscheduled_payments
    : Set to this value when you plan to use the
    payment_token
     field for unscheduled payments (merchant or customer initiated).
Used By & Required (R) or Optional (O):
  • create_payment_token
     (O)
  • authorization,create_payment_token
     (O)
  • sale
    ,
    create_payment_token
     (O)
  • Required when you plan to use a payment token or establish a new agreement for scheduled or unscheduled payments using credentials-on-file in Saudi Arabia on the Saudi Payments Gateway.
Data Type & Length:
 Enumerated String (26)
transaction_type
The type of transaction. Possible values:
  • authorization
  • authorization,create_payment_token
  • authorization,update_payment_token
  • sale
  • sale,create_payment_token
  • sale,update_payment_token
  • create_payment_token
  • update_payment_token
Only authorization and sale are supported for
Visa Click to Pay
 transactions.
To prevent data tampering, sign this field.
Used By & Required (R) or Optional (O):
 Required by the
Secure Acceptance
 application.
Data Type & Length:
 Enumerated String (60)
transaction_uuid
Unique merchant-generated identifier. Include with the
access_key
 field for each transaction. This identifier must be unique for each transaction. This field is used to check for duplicate transaction attempts.
To prevent data tampering, sign this field.
Used By & Required (R) or Optional (O):
 Required by the
Secure Acceptance
 application.
Data Type & Length:
 ASCIIAlphaNumericPunctuation String (50)