On This Page

Checkout
 API Fields

Data Type Definitions

Unless otherwise noted, all fields are order and case sensitive. It is recommended that you not include URL-encoded characters in any request field prior to generating a signature.
Data Type Definitions
Data Type
Permitted Characters and Formats
Alpha
Any letter from any language
AlphaNumeric
Alpha with any numeric character in any script
AlphaNumericPunctuation
Alphanumeric including ! "#$%&'()*+,-./:;=?@^_~
Amount
012x456789 // Replace X with 3 including a decimal point (.)
ASCIIAlphaNumericPunctuation
Any ASCII alphanumeric character including !&'()+,-./:@
Date (a)
MM-yyyy
Date (b)
yyyyMMDD
Date (c)
yyyy-MM-DD hh:mm z
yyyy-MM-DD hh:mm a z
yyyy-MM-DD hh:mma z
Email
Valid email address.
Enumerated String
Comma-separated alphanumeric string
IP
Valid IP address
ISO 8601 Date
yyyy-MM-DDThh:mm:ssZ
Locale
[a-z] including a hyphen (-)
Numeric
012x456789 // Replace X with 3
Phone
( ),+-.*#xX12x456789 // Replace X with 30
URL
Valid URL (http or https)

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.
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)
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 (60)
auth_type
Authorization type. Possible values:
  • AUTOCAPTURE
    : Automatic capture.
  • STANDARDCAPTURE
    : Standard capture.
  • verbal
    : Forced capture.
Used By & Required (R) or Optional (O):
  • authorization
     (See description)
  • capture
     (Required for a verbal authorization; otherwise, not used.)
Data Type & Length:
 String (11)
bill_to_address_city
City in the billing address.
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.
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.
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:
 String (60)
bill_to_address_line2
Second line of the billing address.
Used By & Required (R) or Optional (O):
 Optional
Data Type & Length:
 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.
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.
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.
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.
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.
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.
Barclays
 recommends that you include the country code if the order is from outside the U.S.
This field is optional for card payments.
Used By & Required (R) or Optional (O):
 See description.
Data Type & Length:
 Phone String (6 to 15)
bill_to_surname
Customer last name. This name must be the same as the name on the card.
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)
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)
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)
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)
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
Barclays
-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)
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)
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)
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 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_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)
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
  • 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_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_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
  • paypal
Used By & Required (R) or Optional (O):
Required by the
Secure Acceptance
 application
.
Data Type & Length:
 Enumerated String (30)
payment_token
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)
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:
 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)
ship_to_address_city
City of shipping address.
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.
Used By & Required (R) or Optional (O):
 Optional
Data Type & Length:
 Alpha String (2)
ship_to_address_line1
First line of shipping address.
Used By & Required (R) or Optional (O):
 Optional
Data Type & Length:
 AlphaNumericPunctuation String (60)
ship_to_address_line2
Second line of shipping address.
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.
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.
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.
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.
Used By & Required (R) or Optional (O):
 Optional
Data Type & Length:
 AlphaNumericPunctuation String (60)
ship_to_phone
Phone number of the shipping address.
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.
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 . This field can contain one of these values:
  • true
    : 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)
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_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
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)
unsigned_field_names
A comma-separated list of request fields that are not signed.
Used By & Required (R) or Optional (O):
 Required by the
Secure Acceptance
 application.
Data Type & Length:
 AlphaNumericPunctuation Variable

Response Fields

Response fields are sent using these notification methods:
Notification methods are enabled on the Notifications and Customer Response pages of your
Secure Acceptance
 profile.
To ensure the integrity of the response fields, a signature is included in the response. This signature is generated using the same
secret_key
 value that was used to generate the request signature.
To verify that the response fields have not been tampered with, create a signature using the fields listed in the
signed_field_names
 response field. This signature must be the same value that is included in the signature response field. Refer to the receipt page that is included in the sample scripts. See Scripting Language Samples.
Because response fields and reason codes can be added at any time, proceed as follows:
  • Parse the response data according to the names of the fields instead of their order in the response. For more information on parsing response fields, see the documentation for your scripting language.
  • The signature that you generate must be the same value that is included in the signature response field.
  • Your error handler should use the
    decision
     field to determine the transaction result if it receives a reason code that it does not recognize.
If configured, these response fields are sent back to your Merchant POST URL or email. See Merchant Notifications. Your error handler should use the
decision
 field to obtain the transaction result if it receives a reason code that it does not recognize.
auth_amount
Amount that was authorized.
Data Type & Length:
 String (15)
auth_avs_code
AVS result code. See AVS Codes.
Data Type & Length:
 String (1)
auth_avs_code_raw
AVS result code sent directly from the processor. Returned only if a value is returned by the processor.
Data Type & Length:
 String (10)
auth_cavv_result
Mapped response code for the Visa Secure and American Express SafeKey:
Data Type & Length:
 String (3)
auth_cavv_result_raw
Raw response code sent directly from the processor for Visa Secure and American Express SafeKey.
Data Type & Length:
 String (3)
auth_code
Authorization code. Returned only if a value is returned by the processor.
Data Type & Length:
 String (7)
auth_cv_result
CVN result code. See CVN Codes.
Data Type & Length:
 String (1)
auth_cv_result_raw
CVN result code sent directly from the processor. Returned only if a value is returned by the processor.
Data Type & Length:
 String (10)
auth_reconciliation_reference_number
Unique number that
Barclays
 generates to identify the transaction.
Data Type & Length:
 String (20)
auth_response
For most processors, this is the error message sent directly from the bank. Returned only if a value is returned by the processor.
Data Type & Length:
 String (10)
auth_time
Time of authorization in UTC.
Data Type & Length:
 String (20)
auth_trans_ref_no
Reference number that you use to reconcile your transaction reports with your processor reports.
Data Type & Length:
AlphaNumeric (60)
bill_trans_ref_no
Reference number that you use to reconcile your transaction reports with your processor reports.
Data Type & Length:
 AlphaNumeric (60)
card_type_name
Name of the card type.
For security reasons, this field is returned only in the merchant POST URL and email notifications (not in the receipt POST through the browser).
Data Type & Length:
 String (50)
decision
The result of your request. Possible values:
  • ACCEPT
  • DECLINE
  • REVIEW
  • ERROR
  • CANCEL
Data Type & Length:
 String (7)
invalid_fields
Indicates which request fields were invalid.
Data Type & Length:
 Variable
message
Response message from the payment gateway.
Data Type & Length:
 String (255)
payer_authentication_acs_transaction_id
Unique transaction identifier assigned by the ACS to identify a single transaction.
Data Type & Length:
 String (36)
payer_authentication_cavv
Cardholder authentication verification value (CAVV). Transaction identifier generated by the issuing bank. This field is used by the payer authentication validation service.
Data Type & Length:
 String (50)
payer_authentication_challenge_type
The type of 3-D Secure transaction flow that occurred. Possible values:
  • CH
    : Challenge
  • FR
    : Frictionless
  • FD
    : Frictionless with delegation (challenge not generated by the issuer but by the scheme on behalf of the issuer).
Used for Cartes Bancaires transactions.
Data Type & Length:
 String (2)
payer_authentication_eci
Electronic commerce indicator (ECI). This field is used by payer authentication validation and enrollment services. Possible values for Visa, American Express,
China UnionPay
 and JCB:
  • 05
    : Successful authentication.
  • 06
    : Authentication attempted.
  • 07
    : Failed authentication.
Possible values for Mastercard:
  • 00
    : Failed authentication.
  • 01
    : Authentication attempted.
  • 02
    : Successful authentication.
Data Type & Length:
 String (15)
payer_authentication_enroll_e_commerce_indicator
Commerce indicator for cards not enrolled. Possible values:
  • internet
    : Card not enrolled or card type not supported by Payer Authentication. No liability shift.
  • js_attempted
    : JCB card not enrolled, but attempt to authenticate is recorded. Liability shift.
  • js_failure
    : J/Secure directory service is not available. No liability shift.
  • spa
    : Mastercard card not enrolled in the Identity Check program. No liability shift.
  • up3ds
    : China UnionPay card authentication verified successfully.
  • up3ds_attempted
    : China UnionPay card not enrolled, but the attempt to authenticate is recorded.
  • up3ds_failure:
     China UnionPay card authentication unavailable.
  • vbv_attempted
    : Visa card not enrolled, but attempt to authenticate is recorded. Liability shift.
Data Type & Length:
 String (255)
payer_authentication_pares_status
Raw result of the authentication check. Possible values:
  • A
    : Proof of authentication attempt was generated.
  • N
    : Customer failed or cancelled authentication. Transaction denied.
  • U
    : Authentication not completed regardless of the reason.
  • Y
    : Customer was successfully authenticated.
Data Type & Length:
 String (255)
payer_authentication_pares_status_reason
Provides additional information about the PARes status value.
Data Type & Length:
 Integer (2)
payer_authentication_proof_xml
XML element containing proof of enrollment verification.
For cards not issued in the U.S. or Canada, your bank can require this data as proof of enrollment verification for any payer authentication transaction that you re-submit because of a chargeback.
For cards issued in the U.S. or Canada, Visa can require this data for specific merchant category codes.
This field is HTML encoded.
This field is not returned for 3-D Secure 2.0 transactions.
Data Type & Length:
 String (1024)
payer_authentication_reason_code
Numeric value corresponding to the result of the payer authentication request. See Reason Codes.
Data Type & Length:
 String (5)
payer_authentication_specification_version
This field contains the 3-D Secure version that was used to process the transaction. For example, 1.0.2 or 2.0.0.
Data Type & Length:
 String (20)
payer_authentication_transaction_id
Payer authentication transaction identifier used by
Secure Acceptance
 to link the enrollment check and validate authentication messages.
Data Type & Length:
 String (20)
payer_authentication_type
Indicates the type of authentication that is used to challenge the cardholder. Possible values:
  • 01
    : Static
  • 02
    : Dynamic
  • 03
    : OOB (Out of Band)
Data Type & Length:
 Integer (2)
payer_authentication_uad
Mastercard Identity Check UCAF authentication data. Returned only for Mastercard Identity Check transactions.
Data Type & Length:
 String (32)
payer_authentication_uci
Mastercard Identity Check UCAF collection indicator. This field indicates whether authentication data is collected at your website. Possible values:
  • 0
    : Authentication data was not collected and customer authentication not completed.
  • 1
    : Authentication data was not collected because customer authentication not completed.
  • 2
    : Authentication data was collected. Customer completed authentication.
Data Type & Length:
 String (1)
payer_authentication_validate_e_commerce_indicator
Indicator that distinguishes Internet transactions from other types. The authentication failed if this field is not returned.
The value of this field is passed automatically to the authorization service if you request the services together. Possible values:
  • aesk
    : American Express SafeKey authentication verified successfully.
  • aesk_attempted
    : Card not enrolled in American Express SafeKey, but the attempt to authenticate was recorded.
  • internet
    : Authentication was not verified successfully.
  • js
    : J/Secure authentication verified successfully.
  • js_attempted
    : JCB card not enrolled in J/Secure, but the attempt to authenticate was recorded.
  • spa
    : Mastercard Identity Check authentication verified successfully.
  • spa_failure
    : Mastercard Identity Check failed authentication.
  • vbv
    : Visa Secure authentication verified successfully.
  • vbv_attempted
    : Card not enrolled in Visa Secure, but the attempt to authenticate was recorded.
  • vbv_failure
    : Visa Secure authentication unavailable.
Data Type & Length:
 String (255)
payer_authentication_validate_result
Raw authentication data that comes from the card-issuing bank that indicates whether authentication was successful and whether liability shift occurred. Possible values:
  • -1
    : Invalid PARes.
  • 0
    : Successful validation.
  • 1
    : Cardholder is not participating, but the attempt to authenticate was recorded.
  • 6
    : Issuer unable to perform authentication.
  • 9
    : Cardholder did not complete authentication.
Data Type & Length:
 String (255)
payer_authentication_white_list_status
Enables the communication of trusted beneficiary and whitelist status among the ACS, the directory server, and the 3-D Secure requester. Possible Values:
  • Y
    : 3-D Secure requester is whitelisted by cardholder
  • N
    : 3-D Secure requester is not whitelisted by cardholder
Data Type & Length:
 String (1)
payer_authentication_white_list_status_source
This field is populated by the system setting whitelist status. Possible Values:
  • 01
    : 3-D Secure Server
  • 02
    : Directory server
  • 03
    : ACS
Data Type & Length:
 Integer (2)
payer_authentication_xid
Transaction identifier generated by payer authentication. Used to match an outgoing payer authentication request with an incoming payer authentication response.
Data Type & Length:
 String (28)
payment_account_reference
Reference number serves as a link to the cardholder account and to all transactions for that account. The same value is returned whether the account is represented by a PAN or a network token.
Data Type & Length:
 String (32)
payment_solution
Type of credential-on-file (COF) payment network token. Returned in authorizations that use a payment network token associated with a TMS token. Possible values:
  • 014
    : Mastercard
  • 015
    : Visa
  • 016
    : American Express
Data Type & Length:
 String (3)
payment_token
Identifier for the payment details. The payment token retrieves the card data, billing information, and shipping information from the payment repository.
This payment token supersedes the previous payment token and is returned if:
  • The merchant is configured for a 16-digit payment token that displays the last four digits of the primary account number (PAN) and passes Luhn mod-10 check. See Payment Tokens.
  • The customer has updated the card number on their payment token. This payment token supersedes the previous payment token and should be used for subsequent transactions.
You must be using Token Management Services.
Data Type & Length:
 String (32)
payment_token_instrument_identifier_id
Unique identifier for the
Token Management Service
 (
TMS
) instrument identifier token. You can use it to understand when the same PAN is being used in different tokens, without being exposed to the PAN.
Data Type & Length:
 String (32)
payment_token_instrument_identifier_new
Indicates whether the tokenized credential already exists as an Instrument Identifier or is a new credential. Possible values:
  • Y
  • N
Data Type & Length:
 String (1)
payment_token_instrument_identifier_status
Issuer's status for the card number. If you use Account Updater, the status can be updated to
closed
 if the PAN is not longer active. If you use network tokenization, the PAN might be
closed
 (e.g. lost card), but the network token might still be active. Possible values:
  • ACTIVE
  • CLOSED
    : The card account is closed.
Data Type & Length:
 String (6)
payment_token_latest_card_expiry_date
Card expiration date of the latest card issued to the cardholder.
Returned when Network Tokenization is enabled, and a
payment_token
 with an associated Network Token is used in a transaction. Network Tokens can continue to be used even if the original card has expired.
Format: MM-yyyy
Data Type & Length:
 Date (a) (7)
payment_token_latest_card_suffix
Last four digits of the latest card issued to the cardholder.
Returned when Network Tokenization is enabled, and a
payment_token
 with an associated Network Token is used in a transaction. Network Tokens can continue to be used even if the original card number has changed due to a new card being issued. Use the last four digits in payment confirmation messages to cardholders, for example: "Thank you for your payment using your Visa card ending [payment_token_latest_card_suffix]".
Data Type & Length:
 String (4)
paypal_address_status
Status of the street address on file with PayPal. Possible values:
  • None
  • Confirmed
  • Unconfirmed
Data Type & Length:
 String (12)
paypal_authorization_correlation_id
PayPal identifier that is used to investigate any issues.
Data Type & Length:
 String (20)
paypal_authorization_transaction_id
Unique identifier for the transaction.
Data Type & Length:
 String (17)
paypal_customer_email
Email address of the customer as entered during checkout. PayPal uses this value to pre-fill the PayPal membership sign-up portion of the PayPal login page.
Data Type & Length:
 String (127)
paypal_do_capture_correlation_id
PayPal identifier that is used to investigate any issues.
Data Type & Length:
 String (20)
paypal_do_capture_transaction_id
Unique identifier for the transaction.
Data Type & Length:
 String (17)
paypal_ec_get_details_correlation_id
PayPal identifier that is used to investigate any issues.
Data Type & Length:
 String (20)
paypal_ec_get_details_request_id
Value of the request ID returned from a PayPal get details service request.
Data Type & Length:
 String (26)
paypal_ec_get_details_transaction_id
Unique identifier for the transaction.
Data Type & Length:
 String (17)
paypal_ec_order_setup_correlation_id
PayPal identifier that is used to investigate any issues.
Data Type & Length:
 String (20)
paypal_ec_order_setup_transaction_id
Unique identifier for the transaction.
Data Type & Length:
 String (17)
paypal_ec_set_request_id
Value of the request ID returned from a PayPal set service request.
Data Type & Length:
 String (26)
paypal_fee_amount
PayPal fee charged for the transaction. This value does not exceed the equivalent of 10,000 USD in any currency and does not include a currency symbol. The decimal separator is a period (.), and the optional thousands separator is a comma (,).
Data Type & Length:
 String (9)
paypal_order_request_id
Value of the request ID returned from a PayPal order setup service request.
Data Type & Length:
 String (26)
paypal_payer_id
Customer's PayPal account identification number.
Alphanumeric
Data Type & Length:
 String (13)
paypal_payer_status
Customer's status. Possible values:
  • verified
  • unverified
Data Type & Length:
 String (10)
paypal_pending_reason
Indicates the reason that payment is pending. Possible values:
  • address
    : Your customer did not include a confirmed shipping address, and your Payment Receiving preferences are set to manually accept or deny such payments. To change your preferences, go to the Preferences section of your PayPal profile.
  • authorization
    : The payment has been authorized but not settled. Capture the authorized amount.
  • electronic check
    : Payment was made by an echeck that has not yet cleared.
  • intl
    : You have a non-U.S. account and do not have a withdrawal mechanism. You must manually accept or deny this payment in your PayPal Account Overview.
  • multi-currency
    : You do not have a balance in the currency sent, and your Payment Receiving preferences are not set to automatically convert and accept this payment. You must manually accept or deny this payment in your PayPal Account Overview.
  • none
    : No pending reason.
  • order
    : The payment is part of an order that has been authorized but not settled.
  • paymentreview
    : The payment is being reviewed by PayPal for possible fraud.
  • unilateral
    : The payment was made to an email address that is not registered or confirmed.
  • verify
    : Your account is not yet verified. You must verify your account before you can accept this payment.
Data Type & Length:
 String (14)
paypal_pending_status
Status of the transaction. Possible values:
  • Canceled-Reversal
    : PayPal canceled the reversal, which happens when you win a dispute, and the funds for the reversal are returned to you.
  • Completed
    : PayPal completed the payment and added the funds to your account.
  • Denied
    : You denied a payment, which happens only if the payment was pending for the reason indicated in the
    reason_code
     field.
  • Expired
    : The authorization expired.
  • Failed
    : The payment failed. This event can happen only when the payment is made from your customer's bank account.
  • In-Progress
    : The transaction is not complete yet.
  • None
    : No status.
  • Partially-Refunded
    : The payment was partially refunded.
  • Pending
    : The payment is pending for the reason indicated in the
    paypal_pending_reason
     field.
  • Processed
    : PayPal accepted the payment.
  • ReasonCode
  • Refunded
    : You refunded the payment.
Data Type & Length:
 String (20)
paypal_pending_status
Continued status of the transaction. Possible values:
  • Reversed
    : PayPal reversed the payment for the reason specified in the
    reason_code
     field. The funds were transferred from your account to the customer's account.
  • Voided
    : The authorization was voided.
Data Type & Length:
 String (20)
paypal_protection_eligibility
Seller protection in force for the transaction. Possible values:
  • Eligible
    : You are protected by the PayPal Seller Protection Policy for unauthorized payment and item not received.
  • PartiallyEligible
    : You are protected by the PayPal Seller Protection Policy for item not received.
  • Ineligible
    : You are not protected under the PayPal Seller Protection Policy.
Data Type & Length:
 String (17)
paypal_protection_eligibility_type
Seller protection in force for the transaction. Possible values:
  • Eligible
    : You are protected by the PayPal Seller Protection Policy for unauthorized payment and item not received.
  • ItemNotReceivedEligible
    : You are protected by the PayPal Seller Protection Policy for item not received.
  • UnauthorizedPaymentEligible
    : You are protected by the PayPal Seller Protection Policy for unauthorized payment.
  • Ineligible
    : You are not protected under the PayPal Seller Protection Policy.
To enable the
paypal_protection_eligibility_type
 field, contact customer support to have your account configured for this feature.
Data Type & Length:
 String (32)
paypal_request_id
Identifier for the request generated by the client.
Data Type & Length:
 String (26)
paypal_token
Timestamped PayPal token that identifies that PayPal Express Checkout is processing the transaction. Save this value to send in future request messages.
Data Type & Length:
 String (20)
paypal_transaction_type
Indicates the PayPal transaction type. Possible value:
expresscheckout
Data Type & Length:
 String (16)
reason_code
Numeric value corresponding to the result of the payment card transaction request. See Reason Codes.
Data Type & Length:
 String (5)
req_access_key
Authenticates the merchant with the application.
Data Type & Length:
 String (32)
req_amount
Total amount for the order. Must be greater than or equal to zero.
Data Type & Length:
 String (15)
req_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.
Data Type & Length:
 String (1)
req_auth_type
Authorization type. Possible values:
  • AUTOCAPTURE
    : Automatic capture.
  • STANDARDCAPTURE
    : Standard capture.
  • verbal
    : Forced capture.
Forced Capture
 Set this field to
verbal
 and include it in the authorization request to indicate that you are performing a forced capture; therefore, you receive the authorization code outside the transaction processing system.
Verbal Authorization
 Set this field to
verbal
 and include it in the capture request to indicate that the request is for a verbal authorization.
Data Type & Length:
String (11)
req_bill_to_address_city
City in the billing address.
Data Type & Length:
 String (50)
req_bill_to_address_country
ISO country code for the billing address.
Data Type & Length:
 String (2)
req_bill_to_address_line1
First line of the street address in the billing address.
Data Type & Length:
 String (60)
req_bill_to_address_line2
Second line of the street address in the billing address.
Data Type & Length:
 String (60)
req_bill_to_address_postal_code
Postal code for the billing address. This field is returned if
bill_to_address_country
 is U.S. or Canada.
Data Type & Length:
 String (10)
req_bill_to_address_state
The state or province for the bill-to address. For the United States and Canada, the two-character ISO state and province code is returned. See .
Data Type & Length:
 String (20)
req_bill_to_company_name
Name of the customer's company.
Data Type & Length:
 String (60)
req_bill_to_email
Customer email address.
Data Type & Length:
 String (255)
req_bill_to_forename
Customer first name.
Data Type & Length:
 String (60)
req_bill_to_phone
Customer phone number.
Data Type & Length:
 String (15)
req_bill_to_surname
Customer last name.
Data Type & Length:
 String (60)
req_card_expiry_date
Card expiration date.
Data Type & Length:
 String (7)
req_card_number
Card number.
Data Type & Length:
 String (20)
req_card_type
Type of card.
Data Type & Length:
 String (3)
req_company_tax_id
Company's tax identifier. The last four digits are not masked.
Data Type & Length:
 String (9)
req_complete_route
Concatenation of individual travel legs in the format: 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 field 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.
Data Type & Length:
 String (255)
req_currency
Currency used for the order. See ISO currency codes.
Data Type & Length:
 String (3)
req_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.
Data Type & Length:
 String (5)
req_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.
Data Type & Length:
 String (5)
req_customer_ip_address
Customer IP address reported by your web server using socket information.
req_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.
Data Type & Length:
 String (29)
req_device_fingerprint_id
Field that contains the session ID for the fingerprint. The
Data Type & Length:
 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 sessions IDs.
The session ID must be unique for each merchant ID. You can use any
Data Type & Length:
 String that you are already generating, such as an order number or web session ID.
Data Type & Length:
 String (88)
req_ignore_avs
Ignore the results of AVS verification. Possible values:
  • true
  • false
Data Type & Length:
 String (5)
req_ignore_cvn
Ignore the results of CVN verification. Possible values:
  • true
  • false
Data Type & Length:
 String (5)
req_item_#_code
Type of product. # can range from
0
 to
199
.
Data Type & Length:
 String (255)
req_item_#_description
Description of the item. # can range from
0
 to
199
.
Data Type & Length:
 String (255)
req_item_#_name
Name of the item. # can range from
0
 to
199
.
Data Type & Length:
 String (255)
req_item_#_passenger_email
Passenger's email address.
Data Type & Length:
 String (255)
req_item_#_passenger_forename
Passenger's first name.
Data Type & Length:
 String (60)
req_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.
Data Type & Length:
 String (32)
req_item_#_passenger_phone
Passenger's phone number. If the order is from outside the U.S., it is recommended that you include the country code.
Data Type & Length:
 String (15)
req_item_#_passenger_status
Your company's passenger classification, such as with a frequent flyer classification. In this case, you might use values such as standard, gold, or platinum.
Data Type & Length:
 String (32)
req_item_#_passenger_surname
Passenger's last name.
Data Type & Length:
 String (60)
req_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
Data Type & Length:
 String (32)
req_item_#_quantity
Quantity of line items. # can range from
0
 to
199
.
Data Type & Length:
 String (10)
req_item_#_sku
Identification code for the product. # can range from
0
 to
199
.
Data Type & Length:
 String (255)
req_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.
Data Type & Length:
 String (15)
req_item_#_unit_price
Price of the line item. # can range from
0
 to
199
. This value cannot be negative.
Data Type & Length:
 String (15)
req_journey_leg#_dest
Airport code for the origin of the leg of the trip, designated by the pound (#) symbol in the field name. For a complete list of airport codes, see IATA's City Code Directory.
Data Type & Length:
 String (3)
req_journey_leg#_orig
Airport code for the origin 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. For a complete list of airport codes, see IATA's City Code Directory.
Data Type & Length:
 String (3)
req_journey_type
Type of travel, such as one way or round trip.
Data Type & Length:
 String (32)
req_line_item_count
Total number of line items. Maximum amount is 200.
Data Type & Length:
 String (3)
req_locale
Indicates the language to use for customer content. See Activating a Profile.
Data Type & Length:
 String (5)
req_merchant_defined_data#
Optional fields that you can use to store information. # 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 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.
Data Type & Length:
 String (100)
req_merchant_descriptor
Your business name. This name appears on the cardholder’s statement.
Data Type & Length:
 String (23)
req_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.
Data Type & Length:
 String (13)
req_merchant_descriptor_city
City for your business location. This value might appear on the cardholder’s statement.
Data Type & Length:
 String (13)
req_merchant_descriptor_contact
Telephone number for your business. This value might appear on the cardholder’s statement.
Data Type & Length:
 String (14)
req_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.
Data Type & Length:
 String (2)
req_merchant_descriptor_postal_code
Postal code for your business location. This value might appear on the cardholder’s statement.
Data Type & Length:
 String (14)
req_merchant_descriptor_state
State code or region code for your business location. This value might appear on the cardholder’s statement.
Data Type & Length:
 String (3)
req_merchant_descriptor_street
Street address for your business location. This value might appear on the cardholder’s statement.
Data Type & Length:
 String (60)
req_merchant_secure_data1
Optional field that you can use to store information. The data is encrypted before it is stored in the payment repository.
Data Type & Length:
 String (100)
req_merchant_secure_data2
Optional field that you can use to store information. The data is encrypted before it is stored in the payment repository.
Data Type & Length:
 String (100)
req_merchant_secure_data3
Optional field that you can use to store information. The data is encrypted before it is stored in the payment repository.
Data Type & Length:
 String (100)
req_merchant_secure_data4
Optional field that you can use to store information. The data is encrypted before it is stored in the payment repository.
Data Type & Length:
 String (2000)
req_override_backoffice_post_url
Overrides the backoffice post URL profile setting with your own URL.
Data Type & Length:
 URL (255)
req_override_custom_cancel_page
Overrides the custom cancel page profile setting with your own URL.
Data Type & Length:
 URL (255)
req_override_custom_receipt_page
Overrides the custom receipt profile setting with your own URL.
Data Type & Length:
 URL (255)
req_payment_method
Method of payment. Possible values:
  • card
  • paypal
Data Type & Length:
 String (30)
req_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 currently using the Token Management Service.
Data Type & Length:
 String (32)
req_payment_token_comments
Optional comments about the customer token.
Data Type & Length:
 String (255)
req_payment_token_title
Name of the customer token.
Data Type & Length:
 String (60)
req_profile_id
Identifies the profile to use with each transaction.
Data Type & Length:
 String (36)
req_promotion_code
Promotion code included in the transaction.
Data Type & Length:
 String (100)
req_recipient_account_id
Identifier for the recipient's account. Use the first six digits and last four digits of the recipient's account number.
Data Type & Length:
 Numeric String (10)
req_recipient_date_of_birth
Recipient's date of birth.
Format: yyyyMMDD.
Data Type & Length:
 Date (b) String (8)
req_recipient_postal_code
Partial postal code for the recipient's address.
Data Type & Length:
Alphanumeric String (6)
req_recipient_surname
Recipient's last name.
Data Type & Length:
 Alpha String (6)
req_reference_number
Unique merchant-generated order reference or tracking number for each transaction.
Data Type & Length:
 String (50)
req_returns_accepted
Indicates whether product returns are accepted. Possible values:
  • true
  • false
Data Type & Length:
 String (5)
req_ship_to_address_city
City of shipping address.
Data Type & Length:
 String (50)
Visa Click to Pay
: String (100)
req_ship_to_address_country
The two-character ISO country code.
Data Type & Length:
 String (2)
req_ship_to_address_line1
First line of shipping address.
Data Type & Length:
 String (60)
Visa Click to Pay
: String (100)
req_ship_to_address_line2
Second line of shipping address.
Data Type & Length:
 String (60)
Visa Click to Pay
: String (100)
req_ship_to_address_postal_code
Postal code for the shipping address.
Data Type & Length:
 String (10)
Visa Click to Pay
: String (100)
req_ship_to_address_state
Data Type & Length:
 String (2)
req_ship_to_company_name
Name of the company receiving the product.
Data Type & Length:
 String (40)
req_ship_to_forename
First name of person receiving the product.
Data Type & Length:
 String (60)
Visa Click to Pay
: String (256)
req_ship_to_phone
Phone number for the shipping address.
Data Type & Length:
 String (15)
Visa Click to Pay
: String (30)
req_ship_to_surname
Last name of person receiving the product.
Data Type & Length:
 String (60)
Visa Click to Pay
: String (256)
req_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 pick-up
  • other
    : Other shipping method
  • none
    : No shipping method
Data Type & Length:
 String (10)
req_skip_decision_manager
Indicates whether to skip . Possible values:
  • true
  • false
Data Type & Length:
 String (5)
req_tax_amount
Total tax to apply to the product.
Data Type & Length:
 String (15)
req_transaction_type
The type of transaction requested.
Data Type & Length:
 String (60)
req_transaction_uuid
Unique merchant-generated identifier. Include with the
access_key
 field for each transaction.
Data Type & Length:
 String (50)
Visa Click to Pay
: String (100)
request_token
Request token data created for each response. This field is an encoded string that contains no confidential information.
Data Type & Length:
 String (256)
required_fields
Indicates which of the request fields were required but not provided.
Data Type & Length:
 Variable
service_fee_amount
The service fee amount for the order.
Data Type & Length:
 String (15)
signature
The Base64 signature returned by the server.
Data Type & Length:
 String (44)
signed_date_time
The date and time of when the signature was generated by the server. 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.
Data Type & Length:
 String (20)
signed_field_names
A comma-separated list of response data that was signed by the server. All fields within this list should be used to generate a signature that can then be compared to the response signature to verify the response.
Data Type:
 Variable
transaction_id
The transaction identifier returned from the payment gateway.
Data Type & Length:
 String (26)
utf8
Indicates whether the unicode characters are encoded. Possible value:
✓
Data Type & Length:
 String (3)
RELATED TO THIS PAGE