shift4 payments integration · 2019-02-19 · written license agreement from shift4 payments. all...

Join us for treats Thursday, Month Day, at 3:00 p.m. in the kitchen.

Reference Guide

Copyright © 2018 Shift4 Payments, LLC. All rights reserved.

Shift4® Payments Integration

Reference Guide

© 2018 Shift4 Payments, LLC. All rights reserved. Version 2.27 External Use NDA of 81

Copyright Notice

Shift4 Payments 1491 Center Crossing Road Las Vegas, NV 89144 702.597.2480

www.shift4.com [email protected]

Document Title: Shift4 Payments Integration: Reference Guide

Publication Date: June 15, 2018

Copyright © 2018 Shift4 Payments, LLC. All rights reserved worldwide.

*Universal Transaction Gateway® (UTG®), DOLLARS ON THE NET®, 4Go®, i4Go®, and 4Word® are covered by one or more of the following U.S.Pat. Nos.: 7770789; 7841523; 7891563; 8328095; 8688589; 8690056; 9082120; 9256874; 9495680.

All trademarks, service marks, product names, and logos are the property of their respective owners. Shift4 Payments may have patents, patent applications, trademarks, copyrights, or other intellectual property rights covering subject matter in this document. The furnishing of this document does not give any license to these patents, trademarks, copyrights, or other intellectual property except as expressly provided in any written license agreement from Shift4 Payments. All graphics are property of Shift4 Payments.

No part of this publication may be reproduced, stored in a retrieval system, or transmitted in any form or by any means without prior written permission of Shift4 Payments. The contents of this publication are the property of Shift4 Payments. Shift4 Payments reserves the right to revise this document and to periodically make changes to the content thereof without any obligation or notification to any organization of such revisions or changes unless required to do so by prior written agreement.

Notice of Confidentiality

By using this document, the recipient is hereby informed that this document may contain information that is proprietary to and/or a trade secret of Shift4 Payments. It carries the Shift4 Payments classification “External Use NDA.” As such it may be used by anyone with the stipulation that it is provided for the sole purpose of specifying instructions for the Shift4 Payments products contemplated herein. The recipient agrees to maintain this information in confidence, not reproduce or otherwise disclose this information, and only use this document for none other than its intended purpose.

Notice to Governmental End Users

If any Shift4 Payments product is acquired under the terms of a Department of Defense contract: use, duplication, or disclosure by the US Government is subject to restrictions as set forth in subparagraph (c)(1)(ii) of 252.227.7013. Civilian agency contract: use, reproduction, or disclosure is subject to 52.227-19 (a) through (d) and restrictions set forth in the accompanying end user agreement. Unpublished rights reserved under the copyright laws of the United States.

Reference Guide


Shift4 Payments Integration: Reference Guide The Shift4 Payments Integration: Reference Guide is a resource to support your integration with Shift4 Payments. This document provides detailed information about the following subjects:

• Shift4 Payments’ field descriptions• Shift4 Payments’ function request codes (FRCs)• API Options• Test card numbers and test server logic• Tables for your reference, including common error codes, approval identifiers, and more

For a step-by-step walkthrough of writing a integration to Shift4 Payments’ DOLLARS ON THE NET®, please refer to the Shift4 Payments Integration: API Integration Guide available in MyPortal API Corner.

You should also refer to the complete functions guides in MyPortal API Corner to ensure that you apply the correct format to all Shift4 Payments API messages.

As always, if you have any questions or need assistance, you can email your assigned Shift4 Payments API Analyst at [email protected].

Tip: A list of initializations and acronyms that are commonly used within this document and throughout the payments industry can be found in Appendix A – Initializations and Acronyms.

mailto:[email protected]

Reference Guide


Field Descriptions For your reference, this section provides informative descriptions about every field in Shift4 Payments’ DOLLARS ON THE NET API.

A

AccessToken

A security credential used to authenticate API requests and all i4Go® authorizeClient/preauthorizeClient requests. An Access Token is the alias for the merchant account and interface version being used. The Access Token is required in all requests except a Token Exchange request (FRC CE), which generates an Access Token using an AuthToken and ClientGUID. (Max 51 bytes; data block 094.)

APIFormat

Identifies which API format will be used. Always ‘0’ unless another value is specified by Shift4 Payments. This field is included in every request. (1 byte; Transaction Header data block.)

APIOptions

Specifies the API Option(s) used to modify a request being made. Refer to the API Options section of this document for more information. (Max 255 bytes; data block 023.)

APISignature

Always set to ‘$’ unless another value is specified by Shift4 Payments. This field is included in every request. (1 byte; Transaction Header data block.)

ArrivalDate

Arrival date of a guest’s hotel stay in MMDDYY format. For hotel transactions that are a straight sale (such as advanced deposit, no-show charge, and late charges), the arrival date needs to be one day before the sale date. (6 bytes; data block 003.)

Authorization

The authorization code provided by the consumer’s issuing bank. It is provided in a response if an online authorization or sale request is approved. Following a referral response, it is also specified in Offline Auth (FRC 05) and Sale with Offline Sale (FRC 06) requests. (6 bytes; data block 001.)

AuthSource

In a response, a code returned by the processor to indicate which host issued the response. (1 byte; data block 016.)

AuthToken

A unique encrypted identifier that refers to a specific merchant account. It is required when making a Token Exchange request (FRC CE). For detailed information about the AuthToken, please see the Understanding the Access Token Process section of the Shift4 Payments Integration: API Integration Guide available in MyPortal API Corner. (51 bytes; data block 095.)

Reference Guide


AutoAdditionalCharges

The codes used to provide a reason for additional charges in an auto rental sale. Up to six codes can be specified to indicate different types of charges. (6 bytes; data block 004.)

Code Description

0 N/A

1 Fuel

2 Mileage

3 Late Return

4 One-Way Fee

5 Parking or Moving Violation

AutoEstimatedDays

Estimated contract length of car rental. (2 bytes; data block 014.)

AVSResult

Identifies the response code returned from an Address Verification System (AVS) check with a processor. (1 byte; data block 001.)

Primary AVS Responses

The table below contains the most common AVS response codes:

Code Street Address Match

ZIP/Postal Code Match

Description

A Yes No Street address matched, but ZIP/postal code did not match.

E Error (AVS data is invalid or not allowed).

G Card issuer does not participate in AVS.

N No No No street address and no ZIP/postal code match.

R Card issuer system is unavailable.

S AVS service not supported.

U Street address information unavailable.

W No Yes Street address did not match, but ZIP/postal code matched.

X Yes Yes Street address and 9-digit ZIP/postal code matched.

Y Yes Yes Street address and 5-digit ZIP code matched.

Z Yes Only the ZIP/postal code matched.

Reference Guide


Secondary AVS Responses

The table below contains response codes that are only seen from specific card types and processors.

Code Street Address Match

ZIP/Postal Code Match

Name Match

Description

B Yes No Returned only on Visa cards issued outside the United States. Street address matched, but the ZIP/postal code did not match.

C No No Returned only on Visa cards issued outside the United States. Street address and ZIP/postal code did not match.

D Yes Yes Returned only on Visa cards issued outside the United States. Street address and ZIP/postal code matched.

F Yes No Returned only for American Express. Card member's name did not match, but ZIP/postal code matched.

H Yes Yes No Returned only for American Express. Card member's name did not match, but street address and ZIP/postal code matched.

I No Returned only on Visa cards issued outside the United States. Street address did not match.

J Yes Yes Yes Returned only for American Express. Card member's name, street address, and ZIP/postal code matched.

K No No Yes Returned only for American Express. Card member's name matched, but street address and ZIP/postal code did not match.

L No Yes Yes Returned only for American Express. Card member's name and ZIP/postal code matched, but street address did not match.

M Yes Yes Returned only on Visa cards issued outside the United States. Street address and ZIP/postal code matched.

AVSStreetVerified

Identifies whether the street number was verified (‘Y’) or not (‘N’) in an AVS check with a processor. (1 byte; data block 001.)

AVSZipVerified

Identifies whether the ZIP/postal code was verified (‘Y’) or not (‘N’) in an AVS check with a processor. (1 byte; data block 001.)

Reference Guide


B

Balance

Returns the balance on a prepaid payment card (e.g., Visa Prepaid Debit Card, American Express Gift Card, or MasterCard Prepaid Credit Card). (14 bytes; data block 075.)

BalanceReturnIndicator

Indicates if the balance for a prepaid payment card is being returned in the Balance field (‘Y’) or not (‘N’). (1 byte; data block 075.)

Birthdate

In a Check Approval request (FRC 1F), specifies the customer’s date of birth in MMDDYY format. (6 bytes; data block 011.)

BusinessDayEndingTime

The time the merchant’s business day ends as configured with Shift4 Payments. (6 bytes; data block 012.)

C

CardAbbreviations

A list of abbreviations for the card types that a merchant is configured to accept. The response is returned in alphabetical order. If more than 10 card types are accepted, additional values will be dropped in the response. (20 bytes; data block 012.)

Abbreviation Card Type

AX American Express

CK Check

DB Debit

DC Diners Club

GC Gift Card

JC Japan Credit Bureau (JCB)

MC Mastercard

NS Discover/JCB/Novus (previously Diners Club/Carte Blanche)

PL Private Label

SC Sears Canada

VS Visa

YC IT’S YOUR CARD®

CardEntryMode

The method used to capture a payment card in an authorization/sale request. The CardEntryMode should be sent in an initial request and left blank in subsequent requests. When using a Universal Transaction Gateway® (UTG®)-controlled PIN pad, this field is left blank in a request; the UTG will capture the card entry mode and return it in the response. (1 byte; data block 001.)

Reference Guide


CardEntryMode Requests

The table below contains the values that can be submitted in requests:

Value Description

M Manual Entry

1 Track 1 Only or Dual Track (Track 1 & 2)

2 Track 2 Only

Blank Not Specified

CardEntryMode Responses

The table below contains the values that may be returned in a response:

Value Description

M Manual Entry

1 Track 1 Only or Dual Track (Track 1 & 2)

2 Track 2 Only

E EMV Chip Was Detected and Successfully Captured

R RFID Transaction Was Sent Using Tap-and-Pay Functionality

CardLevelResults

Classifies the type of card used in an authorization/sale request. This field is returned in a response if the data is provided by the processor. See Appendix B – Detailed Card Types for a complete list of values. (2 bytes; data block 074.)

CardNumber

The payment card number entered in an initial authorization/sale request. This field is not specified when using True P2PE® (point-to-point encryption) or a UTG-controlled PIN pad. This field will always be masked when returned in a response. (Max 32 bytes; Transaction Header data block.)

WARNING! Sending both the payment card number and a TrueToken® in a request will result in an error.

Reference Guide


CardPresent

Indicates whether a card was present (‘Y’) or not (‘N’) at the time a transaction took place. This should be set appropriately in the initial authorization/sale request and left blank in subsequent requests. (1 byte; data block 001.)

CardType

An abbreviation used to specify the type of card used when processing a transaction. When using a UTG-controlled device, this field is left blank in a request and returned in the response. (2 bytes; data block 001.)

CardType Requests

The table below contains the values that can be submitted in requests:

Value Card Type

CC Credit Card

DB Debit Card

HF Flex/HSA/FSA Card

GC Gift Card

YC IT’S YOUR CARD

CardType Responses

The table below contains the values that may be returned in a response:

Value Card Type

AX American Express

JC JCB

MC Mastercard

NS Discover/JCB/Novus

PL Private Label

VS Visa

SC Sears Canada

DB Debit

GC Gift Card

YC IT’S YOUR CARD

CashBack

Specifies the cashback amount in a transaction. When using a UTG-controlled PIN pad with the ALLOWCASHBACK API Option, this field will return the cashback amount requested by the consumer. The interface can also send the desired cashback amount in a request by adding it to the PrimaryAmount and including it in the CashBack amount field. This will bypass prompting the consumer for a cashback amount. For example, a purchase of $100 with a $20 cashback would be “120.00” in the PrimaryAmount field and “20.00” in the Cashback field. (14 bytes; data block 056.)

Reference Guide


CheckAmount

Full dollar amount of a check. (14 bytes; data block 011.)

CheckingAccountNumber

The appropriate account number for a check. (Max 24 bytes; data block 011.)

CheckType

Identifies the type of check being processed. (1 byte; data block 011.)

Value Description

0 Personal

1 Company

2 Payroll

Clerk

Number used to identify the point-of-sale (POS) or property management system (PMS) clerk or user. This field is required to be dynamic for all interfaces except e-commerce because the end user is not a clerk. (5 bytes; data block 001.)

ClientGUID

The Client GUID is a unique identifier that is used to track the software version of an interface across all of the merchant accounts that use it. When a new interface version is certified or recertified, you will receive a new Client GUID, which must be hard coded into the application and must not be a configurable field. The Client GUID is required when making a Token Exchange request (FRC CE). For detailed information about the Client GUID, please see the Understanding the Access Token Process section of the Shift4 Payments Integration: API Integration Guide available in MyPortal API Corner. (Max 51 bytes; data block 095.)

Requirement: The Client GUID supplied by your API Analyst must be hard coded into your application because it will permanently identify that version of your interface across all merchant accounts.

ContentType

Used by HTTP interfaces to specify the return message format. Send “XML” to receive XML data. Send “TEXT” to receive key-value pairs.

CustomerName

Specifies a consumer’s name. When a transaction is manually entered, this field is sent in the initial sale/authorization request for AVS validation. If the interface sends a consumer’s name in the CustomerName field, the value specified by the interface will be returned in the response unless the API Option USECARDNAME is included in the request and a UTG-controlled PIN pad is in use. If left blank, the consumer’s name will be returned in the CustomerName field if it’s present in the card’s track data. (35 bytes; data block 002.)

Reference Guide


CustomerReceiptText

When the API Option ENHANCEDRECEIPTS is included in a transaction request that requires a receipt (e.g., sale, authorization, decline, referral, error, refund, or void), this field returns the text that is required to be printed on a consumer’s receipt. For detailed receipt printing guidelines, please see the Receipt Printing Requirements section of the Shift4 Payments Integration: API Integration Guide available in MyPortal API Corner. (Max 4,096 bytes; data block 091.)

CustomerReference

A unique value used to identify the consumer or transaction. If a merchant has a significant amount of revenue from purchasing card customers, the interface would use this field to collect the consumer’s purchase order or employee identification number. (25 bytes; data block 008.)

CVV2Code

The 3- or 4-digit Card Security Code (CSC) found on a payment card. This value should only be sent in an initial sale/authorization request. It should not be stored by the interface. When sending the CVV2Code, the CVV2Indicator must also be sent. (4 bytes; data block 022.)

CVV2Indicator

In a manually entered transaction, indicates the presence of a CSC. (1 byte; data block 022.)

Value Description

0 CSC not provided by user.

1 CSC provided.

2 CSC illegible.

9 CSC not on card, or card did not have a CSC.

CVV2Prompt

When using a UTG-controlled PIN pad, this field is specified as ‘Y’ or ‘N’. ‘Y’ will force the PIN pad to prompt the consumer for a CSC. This field is specified as ‘N’ when other AVS/CVV fields are being requested, but this field is not. (1 byte; data block 112.)

CVV2Result

The result of a CSC check. This field will be used by Shift4 Payments to determine the value sent in the CVV2Valid field (based on the merchant’s list of accepted verification results as configured with Shift4 Payments). (1 byte; data block 022.)

Value Description

M CVV2 matched.

N CVV2 did not match.

P CVV2 not processed.

S CVV2 should have been present.

U Issuer unable to process.

Reference Guide


CVV2Valid

A simplified CSC check result based on the value in the CVV2Result field and the merchant’s accepted verification results as configured with Shift4 Payments. The value sent will be ‘Y’ if CSC verification passed or ‘N’ if CSC verification did not pass. (1 byte; data block 022.)

D

Date

The transaction date in MMDDYY format. Sending the Date field is required in every request and will be echoed back in the response. The value specified cannot be a future date. (6 bytes; data block 001.)

DBA

The merchant’s business name as configured with Shift4 Payments. (22 bytes; data block 012.)

DBAAddressLine1

First line in the merchant’s business address as configured with Shift4 Payments. (38 bytes; data block 012.)

DBAAddressLine2

Second line in the merchant’s business address as configured with Shift4 Payments. (38 bytes; data block 012.)

DBACity

City in the merchant’s business address as configured with Shift4 Payments. (13 bytes; data block 012.)

DBAPhone

The merchant’s business telephone number as configured with Shift4 Payments. (15 bytes; data block 012.)

DBAState

The state in the merchant’s business address as configured with Shift4 Payments. (3 bytes; data block 012.)

DBAZipCode

ZIP/postal code in the merchant’s business address as configured with Shift4 Payments. (9 bytes; data block 012.)

DepartureDate

The departure date of a guest’s hotel stay in MMDDYY format. For hotel transactions that are a straight sale (such as advanced deposit, no-show charges, and late charges), the departure date needs to be the day of the sale. (6 bytes; data block 003.)

DestinationZipCode

When items are shipped, the ZIP/postal code to which merchandise will be shipped; otherwise, the ZIP/postal code where the goods or services are rendered. (9 bytes; data block 008.)

Reference Guide


DeviceExtensions

In UTG4Cloud® interfaces, this value is received in the response to a request for device credentials; interfaces should be programmed to pass this field unaltered. “Device credentials” refers to the DeviceService, DeviceGuid, and DeviceExtensions fields, which identify the local UTG to DOLLARS ON THE NET in UTG4Cloud setups. (Max 1,024 bytes; data block 098.)

DeviceInputIndex

In an Input Prompt request (FRC DB), specifies a value to be collected from a consumer using a UTG-controlled PIN pad. (3 bytes; data block 113.)

The DeviceInputIndex values are described in the table below:

Value Description Return Format

001 CVV2 Numeric

002 Street Number Numeric

003 ZIP Code Numeric

004 Social Security Number (SSN) Numeric, no formatting

005 Last 4 of SSN Numeric

006 Date of Birth MM/DD/YYYY

007 Annual Income Numeric, no commas or decimals

008 Home Phone Number Numeric, no formatting

009 Business Phone Number Numeric, no formatting

010 Email Address (Requires Touchscreen) Alphanumeric

011 Driver’s ID (Requires Touchscreen) Alphanumeric

012 Tip Numeric

DeviceInputResponse

The variable text returned in the response to an Input Prompt request (FRC DB), which contains the consumer’s input. (Max 4,096 bytes; data block 113.)

DeviceGuid

In UTG4Cloud interfaces, this is a unique value that the UTG uses to find the device controlled by the local UTG. It is received in the response to a device credentials request; interfaces should be programmed to pass this field unaltered. “Device credentials” refers to the DeviceService, DeviceGuid, and DeviceExtensions fields, which identify the local UTG to DOLLARS ON THE NET in UTG4Cloud setups. (Max 200 bytes; data block 097.)

DeviceLanguage

Specifies the text language to be displayed on a UTG-controlled PIN pad: “eng” = English, “spa” = Spanish, and “fra” = French. (3 bytes; data block 116.)

Reference Guide


DeviceService

In UTG4Cloud interfaces, this is the name of the internal service the UTG uses to find the device controlled by the local UTG. It is received in the response to a device credentials request; interfaces should be programmed to pass this field unaltered. “Device credentials” refers to the DeviceService, DeviceGuid, and DeviceExtensions fields, which identify the local UTG to DOLLARS ON THE NET in UTG4Cloud setups. (10 bytes; data block 097.)

DriverName

In a sale/authorization request for an auto rental, the customer’s name exactly as it appears on their driver’s license. (35 bytes; data block 004.)

E

EnhancedDataID

Classification used to determine the context of the EnhancedDataValues field. (2 bytes; data block 068.)

Values are specified in the table below:

Value Description

DR Default response

PL Private label

OL Reserved for future use by Petroleum

GA Reserved for future use by General Customer Account

EnhancedDataValues

A series of pipe delimited key-value pairs specifying enhanced data values for private-label cards. (Max 1,024 bytes; data block 068.)

ErrorIndicator

An error flag returned in a response. If Shift4 Payments was unable to process a request, the value ‘Y’ is returned. The value ‘N’ indicates no error condition. This field is not populated in requests. (1 byte; Transaction Header data block.)

ExpirationDate

Card expiration date in MMYY format. This value should only be populated in the initial sale/authorization request when the card is manually entered. (4 bytes; data block 001.)

F

FormName

Specifies a 12-character, alphanumeric string containing the form name to display on a UTG-controlled PIN pad in a Process Forms request (FRC 86). The file extension should not be included in the request. (12 bytes; data block 100.)

Reference Guide


FormResponse

Returns a 5-character, alphanumeric string containing the ID of the button pressed by the consumer on a UTG-controlled PIN pad in a Process Forms response (FRC 86). This field is not specified in a request. (5 bytes; data block 100.)

FourWords

Four space-separated words that reference cardholder data (CHD). The four words can be entered into Shift4 Payments’ 4Word® web app to temporarily reveal CHD. In addition, the four words can be entered during an Online Entry or Offline Entry transaction in DOLLARS ON THE NET to securely charge the corresponding card number. (Max 28 bytes; data block 073.)

FunctionRequestCode

A 2-character alphanumeric code indicating what function is being requested. For example, “1B” indicates an Online Auth. Refer to the Function Request Codes section of this document for more detail about the available functions. (2 bytes; Transaction Header data block.)

G

GiftCardExtendedDataValues

A series of key-value pairs, pipe delimited, specifying values related to gift cards. (Max 1,024 bytes; data block 089)

H

HostResponse

The response text for a check approval. The value (e.g., Approved, App., Okay, Dec., Declined, Refused, etc.) varies depending on the merchant’s settings with Shift4 Payments and display preferences. (24 bytes; data block 011.)

HotelAdditionalCharges

Reason codes for additional charges in a lodging sale request at the time a consumer checks out. (6 bytes; data block 003.)

Code Description

0 N/A

2 Restaurant

3 Gift shop

4 Mini-bar

5 Telephone

6 Other

7 Laundry

HotelEstimatedDays

Used to communicate the estimated number of days of a guest’s stay. This value is included in authorization requests for a consumer’s hotel stay. (2 bytes; data block 013.)

Reference Guide


I

IDNumber

Identification number used to process a check transaction. Do not embed spaces or symbols. (24 bytes; data block 011.)

IDTypeCode

Code representing the type of identification used to process a check transaction. Refer to Appendix D – Required IDs for Check Verification for more details. (2 bytes; data block 011.)

IIASAmountN

The total amount of healthcare costs for an HSA/FSA transaction. N can be 1-4 and must correlate with the transaction classification indicated in the IIASTypeN field. (14 bytes; data block 070.)

IIASTypeN

This code classifies eligible healthcare expenses. N can be 1-4. IIASType1 is always 4S. Types 2-4 are subcategories and amounts 2-4 are correlated to the types. (2 bytes; data block 070.)

The following table provides detailed information about the eligible healthcare expenses and codes used in the IIASTypeN field:

Code Description

4S Healthcare (Visa/MC Only) – Qualified Medical Expenses or Over-the-Counter

4T Transit (Visa Only) – Transit Fare Media (e.g., Commuter and Parking Passes, Mass Transit Vouchers, and Tickets)

4O Cash Disbursement (Discover Only) – Amount of Cash Back Being Requested

4U RX (Visa/MC Only)

4V Vision (Visa Only)

4W Clinical (Visa Only)

4X Dental (Visa Only)

Invoice

10-digit invoice number assigned by the interface to identify a transaction. The combination of a card number and an invoice number creates a unique key that identifies a transaction within a batch in DOLLARS ON THE NET. Each invoice number must be unique per batch and for each transaction flow. (10 bytes; Transaction Header data block.)

IYCAvailableBalance

The adjusted balance of a gift card received in a response. The amount reflects the IYCBalance adjusted by pending credits or authorizations. (14 bytes; data block 025.)

IYCBalance

In a request, specifies the balance to load on the gift card. In a response, specifies the current balance remaining on the gift card (not adjusted for pending credits or authorizations). (14 bytes; data block 025.)

Reference Guide


Important: As the IYCBalance field is not adjusted for pending credits or authorizations, be sure to check the IYCAvailableBalance field to confirm the card’s adjusted balance.

IYCCardFormatted

Formatted IYC number with hyphens (e.g., “XXXX-XXXX-XXXX-XXXX”). (Max 24 bytes; data block 025.)

IYCCardType

Type of card to be processed by the IYC processor. Always ‘G’ unless a different value is specified by Shift4 Payments. (1 byte; data block 025.)

IYCDiscount

Discount percentage to be applied to a transaction. (5 bytes; data block 025.)

IYCExpiration

IYC expiration date in MMDDYY format. If an expiration date was set on the IYC card, this field is received in an IYC transaction response. (6 bytes; data block 025.)

IYCReasonText

In a Deactivate request (FRC 25), specifies the reason for deactivation. In an IYC redemption or inquiry response, specifies the reason for denial sent by the processor. This field will be echoed back in responses other than FRC 25, which may cause errors detecting deactivated cards and therefore should only be included in FRC 25 requests. (Max 32 bytes; data block 026.)

The default reason text in a request is as follows:

• Administrative Hold • Cancelled • Closed • ID Verification Requested • Lost or Stolen • Merchant Restriction on Card • Stolen • User Defined Reason Code

K

KeyValueN

In a Process Forms request (FRC 86), a 200-character, alphanumeric string containing a maximum of ten custom text fields to display on a UTG-controlled PIN pad for consumer input. N can be 1-10. (Max 200 bytes; data block 100.)

L

LateAdjustment

A dollar amount for late adjustment fees for an auto rental, including refueling charges, a surcharge, or charges for damage incurred during use. (14 bytes; data block 004.)

Reference Guide


LineItem

In a Display Line Item request (FRC 92), a single line item to be displayed on a UTG-controlled PIN pad. (30 bytes; data block 055.)

LineItemCount

In a Display Line Items request (FRC 95), specifies the number of line items being sent in the request. (2 bytes; data block 054.)

LineItemN

In a Display Line Items request (FRC 95), the line items to be displayed on a UTG-controlled PIN pad (N can be 1-10). (30 bytes for each LineItemN; data block 054.)

LongError

Extended error message that is returned if an error condition exists. (Max 255 bytes; data block 999.)

M

ManualCheckNumber

Check number as seen on the upper right corner of a consumer’s check. This field is specified if the check is manually keyed. (10 bytes; data block 011.)

MerchantReceiptText

When the API Option ENHANCEDRECEIPTS was included in a transaction request that requires a receipt (e.g., sale, authorization, decline, referral, error, refund, or void), this field returns the text that is required to be printed on the merchant’s receipt. For detailed receipt printing guidelines, please see the Receipt Printing Requirements section of the Shift4 Payments Integration: API Integration Guide available in MyPortal API Corner. (Max 4,096 bytes; data block 090.)

MerchantType

Classifies the merchant type for a merchant’s account with Shift4 Payments. (1 byte; data block 012.)

Value Description

R Retail

H Hotel

F Food & Beverage (F&B)

A Auto Rental

M Mail Order/Telephone Order (MO/TO) or E-Commerce

MetaTokenData

A 16-digit, numeric value used to track payment card usage across multiple revenue centers within an organization. This value is only sent in responses. (16 bytes; data block 086.)

Reference Guide


MetaTokenType

Requests the type of MetaToken™ to be returned. The two MetaToken types are “IL” and “F6”. For the last four digits of the MetaToken to be the last four digits of the payment card, send “IL” in the request. For the last six digits of the MetaToken to be the first six digits of the payment card, send “F6” in the request.

N

NoShowIndicator

Indicates whether a customer picked up a reserved rental car (‘Y’) or not (‘N’). (1 byte; data block 004.)

Notes

A free-form notes field that supports the use of HTML tags. Shift4 Payments strongly suggests including the transaction information in HTML format. This will be used for reference in DOLLARS ON THE NET and is not sent to the authorization host. (Max 4,096 bytes; data block 017.)

O

OverrideBusDate

Desired business date of a transaction in MMDDYY format. Include when overriding the existing business date of a transaction. The overriding date may be earlier or later than the existing date. (6 bytes; data block 031.)

P

P2PEBlock

The full output of a P2PE keypad/magnetic swipe reader (MSR). (2,048 bytes; data block 076.)

P2PEBlockLength

The length of the P2PEBlock being sent by a P2PE keypad/MSR. This field is only sent in TCP/IP interfaces. (4 bytes; data block 076.)

Reference Guide


P2PEDeviceType

Classifies the type of payment device being used for P2PE. (2 bytes; data block 076.)

Two examples of track data output from the same card are below:

When the P2PEDeviceType is specified as “01” in a request, the masked track data output from the terminal consists of ASCII characters:

028301801F331E00139B%*432100******1119^VS/SHIFT4 TEST CARD^1612******?*;432100******1119=1612******?*C0D70C303BF7DFAB26DFEB59B33A407163D236798BE68580A7355B43D4F5F21DC40C46C366290C116F1C34601C5BB56C1D13EE0A7FDCF1C1FD6D1D53796647C131F1F2CBD3752720B7E22AC92BB1D17168AE7D081AFC204A47D8277280C6A7AFC433D7A8EA0CA1D202ACD0AC9354F424DA0ACD9B50EAF605873994F7A7A724224B7DF49F00BC68C662994950010000000C4F5E9203

When the P2PEDeviceType is specified as “02” in a request, the masked track data output from the terminal is a hexadecimal string representation of ASCII characters:

029800801D3300000189252A3534333230302A2A2A2A2A2A333333325E4D432F534849465434205445535420434152445E2A2A2A2A2A2A2A2A2A2A3F2AB2818A2789D83EE9481BFA5CDCA19CBEB30F53F2F286CEC554413F52E369ECBBE4547354BED4438884DEC31060F223FA935AA4302184F2C3823628E128376CA272EDE9AF39C237E73DEF3FB8459A6E911228B9266299490032001FE00169BBEB03

Requirement: The P2PEDeviceType field will be returned with the P2PE block in the response if an On-Demand Card Read request (FRC DA) is sent using a UTG-controlled PIN pad. “03” specifies an Ingenico RBA PIN pad and “04” specifies a Verifone MX PIN pad. If you plan to store the P2PE block for future use, you will need to store the correlated P2PEDeviceType parameter as well. This P2PEDeviceType must be specified when using the P2PE block in future API requests that refer to the same data.

PhotoData

The base64-encoded data sent when a signature is captured as a Portable Network Graphics (PNG) file. (Max 4,194,304 bytes; data block 088.)

PhotoType

When sending a signature as a PNG file, this value must be ‘P’. (1 byte; data block 088.)

PinBlock

Encrypted PIN data received from a POS-controlled PIN pad (not controlled by the UTG). (16 bytes; data block 005.)

PinPadBlockFormat

Identifies the format of the PinBlock field for a POS-controlled PIN pad (not controlled by the UTG). Always “71” unless a different value is specified by Shift4 Payments. (2 bytes; data block 005.)

Reference Guide


PinPadKey

Key serial number (KSN) received from a POS-controlled PIN pad (not controlled by the UTG). The PINPadKey field is a hexadecimal field that should be padded with leading ‘F’s. (20 bytes; data block 005.)

PinPadType

Identifies the PIN pad type for a POS-controlled PIN pad (not controlled by the UTG). Set to “03” unless a different value is specified by Shift4 Payments. (2 bytes; data block 005.)

PostalCodePrompt

When using a UTG-controlled PIN pad, this field is specified as ‘Y’ to force a PIN pad to prompt the consumer for a ZIP/postal code. This field is specified as ‘N’ when other AVS/CVV fields are being requested, but this field is not. (1 byte: data block 112.)

PreauthorizedAmount

In an Online Auth response (FRC 1B), indicates the total transaction amount currently authorized. This field is not specified in a request. (14 bytes; data block 016.)

PreauthorizedTolerance

In an Online Auth response (FRC 1B), this field indicates the maximum amount that can be incrementally authorized (when allowed) based on the merchant’s acceptable tolerance level as configured with Shift4 Payments. A merchant’s tolerance level is the allowable authorization level above the primary and secondary amounts at which a merchant may process a payment without requesting additional approval from the processor. This field is not specified in a request. (14 bytes; data block 016.)

PrimaryAmount

The amount being charged for a particular transaction. (14 bytes; data block 001.)

PrimaryChargeType

Guest’s transaction type at a hotel. (1 byte; data block 003.)

Value Description

1 Lodging

2 Restaurant

3 Gift Shop

PrimaryErrorCode

Code indicating the type of error that occurred. This is a response-only field. Refer to the Shift4 Payments Common Error Codes section of this document for more details. (6 bytes; Transaction Header data block.)

ProductDescriptorN

A text description of the items purchased or services sold. This can be a generic text description of what the merchant sells (such as “Groceries”) or specific transaction data (such as the name of the item sold). At least one product descriptor field is required in a sale/authorization request. N can be 1-4. (Max 40 bytes; data block 009.)

Reference Guide


PromptConfirmQuestion

In a Prompt Confirmation request (FRC 82), this field displays an inquiry prompting a consumer’s confirmation. (64 bytes; data block 087.)

PromptConfirmResult

In the response to a Prompt Confirmation request (FRC 82), this field specifies whether the consumer has opted to confirm (‘Y’) or deny (‘N’) the requested value. (1 byte; data block 087.)

PromptConfirmValue

In a Prompt Confirmation request (FRC 82), this field displays an email address, legal text, or other text for a consumer’s confirmation. (Max 4,096 bytes; data block 087.)

R

RawMagneticData

Data from the front of a check containing the routing number, checking account number, and check number as read by a Magnetic Ink Character Recognition (MICR) reader. (80 bytes; data block 011.)

ReaderIndicator

Identifies how the checking account and transit routing number were obtained. (The transit routing number is also known as the ABA number.) ‘0’ if it was manually obtained; ‘1’ if it was read through a check reader. (1 byte; data block 011.)

ReceiptText

The raw text message to print on the receipt if not using the API Option ENHANCEDRECEIPTS. (Max 4,000 bytes; data block 033.)

ReceiptTextColumns

Indicates the column width per line for a printed receipt. This allows the receipt text to wrap to fit the printed receipt. The receipt lines are separated by a CR/LF pair (ASCII 13, 10). To meet the needs of standard receipt formatting, Shift4 Payments has set the maximum number of characters to “048”. (3 bytes; data block 033.)

RentalAgreement

Contract number for an auto rental agreement. (9 bytes; data block 004.)

RentalCity

City where rental car was picked up. (18 bytes; data block 004.)

RentalDate

Date when rental car was picked up in MMDDYY format. (6 bytes; data block 004.)

RentalState

State where rental car was picked up in U.S. postal abbreviation format. (2 bytes; data block 004.)

Reference Guide


RentalTime

Time when rental car was picked up in HHMMSS format. (6 bytes; data block 004.).

Note: Time must be formatted in military format (e.g., 4:14:49 p.m. would be formatted “161449”) for the local time zone where the merchant makes the sale.

RentalZipCode

ZIP/postal code where rental car was picked up. (9 bytes; data block 004.)

ReportCardType

Used to request a Totals Report (FRC 5F) for a specific card type. To return the totals for all card types, fill this field with spaces (TCP/IP) or send a blank value (HTTP). (2 bytes; data block 032.)

ReportClerk

The clerk ID number used when submitting a Totals Report request (FRC 5F), if applicable. If no Clerk ID has been defined, this field should be filled with zeroes (TCP/IP) or left blank (HTTP). (5 bytes; data block 032.)

ReportEndDate

The end date for a Totals Report request (FRC 5F) in MMDDYY format. (6 bytes; data block 032.)

ReportEndTime

The end time for a Totals Report request (FRC 5F) in HHMMSS format. (6 bytes; data block 032.)


ReportStartDate

The start date for a Totals Report request (FRC 5F) in MMDDYY format. (6 bytes; data block 032.)

ReportStartTime

The start time for a Totals Report request (FRC 5F) in HHMMSS format. (6 bytes; data block 032.)


ReportTerminalID

The API Terminal ID used when requesting a Totals Report (FRC 5F) for a specific terminal. If not requesting a Totals Report for a specific terminal, this field should be filled in with zeroes (TCP/IP) or left blank (HTTP). (Max 32 bytes; data block 032.)

RequestorReference

A unique, alphanumeric value that must be sent in every request. This value must be different from the invoice number and new for each request, including subsequent requests. Shift4 Payments will return the corresponding value in the correlated response, which should be used by your interface to match up requests with responses. This value will also facilitate troubleshooting in production, as it is recorded in the UTG trace files. However, it will not be recorded in DOLLARS ON THE NET. (12 bytes; Transaction Header data block.)

Reference Guide


Response

Code indicating the Shift4 Payments host response. (1 byte; data block 001.)

Code Description

A The transaction is approved.

C

The transaction is approved without requiring additional authorization because it is less than or equal to a ceiling amount. (The ceiling amount is the original authorization amount multiplied by the tolerance per the merchant’s settings with Shift4 Payments.)

D The transaction is declined.

R The transaction requires a voice referral.

f An AVS or CVV2 failure has occurred (credit card only).

e There is an error condition.

[Blank] The approval status is unknown.

RetrievalReference

Reference retrieval number assigned by the authorizing agency. This value is printed on some receipts. (12 bytes; data block 016.)

ReturnCity

City where rental car was returned. (18 bytes; data block 004.)

ReturnDate

Date when rental car was returned in MMDDYY format. (6 bytes; data block 004.)

ReturnState

State where rental car was returned in U.S. postal abbreviation format. (2 bytes; data block 004.)

ReturnTime

Time when rental car was returned in HHMMSS format. (6 bytes; data block 004.)


ReturnZipCode

ZIP/postal code where rental car was returned. (9 bytes; data block 004.)

Revision

Shift4 Payments software revision number. (8 bytes; data block 012.)

Reference Guide


S

SaleFlag

Specifies a transaction is a sale (‘S’) or credit (‘C’). (1 byte; data block 001.)

SecondaryAmount

Additional charge added to the PrimaryAmount. Typically used for food and beverage tip. (14 bytes; data block 001.)

SecondaryErrorCode

This code supplements the code specified in the PrimaryErrorCode field to provide additional information about the error that occurred, if applicable. This is a response-only field. Refer to the Shift4 Payments Common Error Codes section of this document for more details. (3 bytes; Transaction Header data block.)

SerialNumber

The merchant’s serial number (i.e., account number) with Shift4 Payments. When utilizing TokenStore®, this value is used in the TokenSerialNumber field to identify a serial number where a TrueToken is stored. (10 bytes; data block 012.)

ShortError

Abbreviated error message that is always returned if an error condition exists (for example, “TRAN TIMEOUT”). See the Shift4 Payments Common Error Codes section of this document for more details. (16 bytes; data block 999.)

SignatureBlock

In a request, the raw signature data from the signature capture device. In a response, the data is formatted in Shift4 Payments 8-byte format. If the RETURNSIGNATURE API Option is included in a payment request, this field will be returned. (Max 16,384 bytes; data block 006.)

SignatureBlockNumber

Identifies the block number of the SignatureBlock field. Always ‘1’ unless a different value is specified by Shift4 Payments. If the RETURNSIGNATURE API Option is included in a payment request, this field will be returned. (1 byte; data block 006.)

Reference Guide


SignatureDeviceType

Identifies the format of the SignatureBlock field in a request. In a response, the value is always “04” because Shift4 Payments converts all signature data into the Shift4 Payments 8-byte format. If the RETURNSIGNATURE API Option is included in a payment request, this field will be returned. (2 bytes; data block 006.)

Value Device Type

01 Checkmate 2020

02 NCR

03 IVI ENTouch 1000

04 Shift4 Payments Format, Mobinetix, @POS, or Symbol Tech Palm Device

05 Scribex/Topaz SIG Format

SignatureSuppressed

Indicates whether a transaction would have required a signature (‘Y’) or not (‘N’). Returned only when the NOSIGNATURE API Option is sent in a request using a UTG-controlled PIN pad. (1 byte; data block 111.)

SignatureTotalBlocks

Identifies the total number of signature blocks. Always ‘1’ unless a different value is specified by Shift4 Payments. If the RETURNSIGNATURE API Option was included in a payment request, this field will be returned. (1 byte; data block 006.)

SpecialCode

The SpecialCode field is used to provide additional detail for lodging transactions. If a lodging charge does not match one of the listed descriptions, the default value of ‘1’ should be sent in the request. When a value of ‘4’ is sent, the HotelAdditionalCharges field needs to be sent as well. (1 byte; data block 003.)

Code Description

1 No Special Code

2 Assured Reservation/No Show

3 Advance Deposit

4 Delayed Charge

5 Express Check-Out Service

6 Assured Reservation/Normal

Reference Guide


SpinAbb

Specifies the card type for Bank Identification Number (BIN) management. (2 bytes; data block 064.)

Value Description

AX American Express

GC Gift Card

JC JCB

MC Mastercard

NS Discover/JCB/Novus

PL Private Label

VS Visa

SC Sears Canada

YC IT’S YOUR CARD

SpinIsDCC

In BIN management, specifies whether or not the card is dynamic currency conversion (DCC) capable. (1 byte; data block 064.)

SpinIsDebit

In BIN management, specifies whether a card can be processed as debit (‘Y’) or not (‘N’). (1 byte; data block 064.)

SpinPrefix

In BIN management, specifies the first 10 digits of the card. (10 bytes; data block 064.)

SpinResult

In BIN management, specifies the detailed card type. For a complete list of potential values, see Appendix B – Detailed Card Types in this document. (2 bytes; data block 064.)

StreetAddress

Consumer’s street address exactly as it appears on their billing statement. This field is used for AVS verification. (30 bytes; data block 002.)

StreetNumberPrompt

When using a UTG-controlled PIN pad, this field is specified as ‘Y’ or ‘N’. ‘Y’ will force the PIN pad to prompt the consumer for the street number in their billing address. This field is specified as ‘N’ when other AVS/CVV fields are being requested, but this field is not. (1 byte; data block 112.)

Reference Guide


Surcharge

In a sale or authorization transaction, the Surcharge field specifies a fee amount that a consumer is charged in addition to the PrimaryAmount. Using the Surcharge field is required by the processors to identify any fee amount being charged when a consumer pays for a transaction with a credit or debit card. (14 bytes; data block 056.)

T

TaxAmount

The amount of sales tax charged for a transaction. The tax amount is used by businesses to track tax expenses for accounting purposes. Identifying the tax amount also helps consumers understand the total amount that they were billed. Your interface must be able to send an amount of ‘0’ as well as other, variable amounts. (14 bytes; data block 008.)

Note: The TAXEXEMPT API Option can be used if the transaction is tax exempt.

TaxIndicator

Indicates whether tax was applied or not. If the TaxAmount is greater than ‘0’ and has been applied, the indicator should be set to ‘Y’. If the transaction is tax exempt, not taxed, or TaxAmount is ‘0’, the indicator should be set to ‘N’. (1 byte; data block 008.)

Note: The TAXEXEMPT API Option can be used if the transaction is tax exempt.

TermsAndConditionsResult

Returns the result of the Terms and Conditions screen on the PIN pad (based on the consumer’s input). ‘A’ indicates the consumer has accepted the terms and conditions and ‘D’ indicates the consumer has declined accepting the terms and conditions. (1 byte; data block 108.)

TermsAndConditions

Contains the Terms and Conditions text for the UTG-controlled PIN pad to display to a consumer. (Max 4,096 bytes; data block 108.)

TerminalID

To prompt a specific UTG-controlled PIN pad in a request, the API Terminal ID configured in UTG TuneUp must be specified in the TerminalID field. (Max 32 bytes; data block 018.)

Time

The time of a transaction in HHMMSS format. In a request, the Time field is required, indicates the time of the request, and will be echoed back in the response. (6 bytes; data block 001.)


TokenSerialNumber

In requests that require the use of a shared TrueToken that is held by another merchant account, such as in TokenStore or TokenShare®, the TokenSerialNumber field is used to specify the serial number for the account where the TrueToken is stored. (10 bytes; data block 039.)

TrackInformation

Card swipe data exactly as read by an MSR. (Max 128 bytes; data block 001.)

Reference Guide


TranID

A 10-digit ID that Shift4 Payments assigns to every transaction. This field is specified in a Void request (FRC 08) to void an incremental authorization. (10 bytes; Transaction Header data block.)

TransitRoutingNumber

The ABA number located in the lower left corner on the front of the check. (10 bytes; data block 011.)

TrueToken

A TrueToken is a unique, 16-character value created by DOLLARS ON THE NET to reference CHD. This value is used in the UniqueID field in place of actual CHD, providing the merchant advanced security and improved PCI compliance.

U

UniqueID

This field is used to specify a TrueToken. Whenever CHD is sent in a request, a TrueToken will be returned in the corresponding response’s UniqueID field. Your interface should be designed to store this TrueToken for future use. The latest TrueToken received should be used in any subsequent request that references the same card data. (16 bytes; data block 039.)

V

ValidAVS

A simplified AVS result based on the merchant’s list of accepted responses as configured with Shift4 Payments: (‘Y’) if accepted or (‘N’) if not accepted. (1 byte; data block 001.)

ValidIDTypes

Codes that define the identification required for the proper verification of a check. Up to 100 codes may be returned in a response. Refer to Appendix D – Required IDs for Check Verification for more information. (Max 100 bytes; data block 010.)

Reference Guide


Vendor

This field identifies who wrote the interface the merchant is using, which software application is being used, and the version number. It is specified in every API call. (Max 64 bytes; data block 000.)

The configuration of this field should follow the guidelines below:

1. The following components make up the Vendor field, separated by colons:

CompanyName (max 26 characters):InterfaceName (max 25 characters):Version (max 11 characters)

Where:

CompanyName refers to the vendor or partner that designed and certified the interface, and the information you use in the Vendor field should match what we have on file or what was agreed upon in your Integration Plan.

InterfaceName is the name of the program or application that is sending requests to Shift4 Payments. This should be the name of the program that you purchased or created, not the UTG or protocol (HTTP, TCP/IP).

Version refers to the version of the program or application that is sending requests to Shift4 Payments.

In practice, it should look something like this:

PAWS:POS:2.1

(In this example, the vendor’s company name is PAWS, the interface name is POS, and the version number is 2.1.)

or

HotelsToGo:HotelManager:13579

(In this example, the vendor’s company name is Hotels to Go, the interface name is Hotel Manager, and the version number is 13579.)

2. Pay attention to the characters that are and aren’t allowed. These special characters are allowed in the Vendor field:

_ | @ # & * ; ( ) . /

The following special characters are not allowed:

: $ % ^ - ~ ` < > , ? “ ” ‘ ’ { } [ ] \ + =

3. Like the Client GUID, this information should be hard-coded into your application. In the Shift4 Payments Integration: API Integration Guide available in MyPortal API Corner, we outline the importance of the Client GUID, which is permanently tied to your software version. The Vendor field is similar. The company name, interface name, and version noted in this field should be identical for all merchants using the same software and version number. It should be hard-coded into your application by version, and should not change unless a new Shift4 Payments certification is obtained for a new version number.

Reference Guide


Verbose

In an HTTPS POST API request, this parameter must be specified as “YES” to cause all applicable data to be returned in the response.

VoiceMerchantAccount

The merchant’s account number as configured with Shift4 Payments. This field is returned in response to a Get Voice Center Information request (FRC 22) because the clerk is required to provide it when attempting to obtain a voice authorization code. This information must be displayed to the clerk. (Max 20 bytes; data block 015.)

VoicePhoneNumber

The phone number a clerk must call to obtain a voice authorization code. This field is returned in response to Get Voice Center Information request (FRC 22). This information must be displayed to the clerk. (20 bytes; data block 015.)

Z

ZipCode

Customer’s ZIP/postal code from their billing statement. Used for AVS verification. Do not include special characters. (9 bytes; data block 002.)

Deprecated Fields The fields in this section have been deprecated for use in new certifications but are included for reference.

A – M

APIPassword

This field is deprecated and has been replaced by the AccessToken field. This unique password was previously required in all transaction requests. During the certification process, it was assigned by Shift4 Payments’ API Support team. After an interface had been certified and moved to production, a different API password was assigned by Shift4 Payments’ Customer Support team; therefore, this field was required to be configurable. (32 bytes; data block 019.)

APISerialNumber

This field is deprecated and has been replaced by the AccessToken field. This unique serial number was previously required in all transaction requests. During the certification process, it was assigned by Shift4 Payments’ API Support team. After an interface had been certified and moved to production, a different API serial number was assigned by Shift4 Payments’ Customer Support team; therefore, this field was required to be configurable. (10 bytes; data block 019.)

EMVOfflineDecision

This field is deprecated. It was used to indicate whether offline approval was obtained for a transaction and why. (1 byte; data block 072.)

EMVOnlineDecision

This field is deprecated. It was used to indicate whether online approval was obtained for a transaction and why. (1 byte; data block 072.)

Reference Guide


EMVRequireSignature

This field is deprecated. It was used to indicate whether the customer’s signature was required (‘Y’) or not (‘N’) on an EMV receipt. (1 byte; data block 072.)

MerchantID

This field is deprecated and has been replaced by the Access Token. This 10-digit ID was previously assigned by Shift4 Payments to identify the merchant. In TCP/IP interfaces, this field should be filled with zeros. (10 bytes; Transaction Header data block.)

N – Z

ResponseCode

This field is deprecated and has been replaced by the Response field. It was the field in which the response code was returned. (1 byte; data block 001.)

VerifyID

This field is deprecated. If supported by the POS/PMS, VerifyID was returned with an approval in an Auth or Sale transaction, prompting the clerk to verify a consumer’s identification. If the consumer ID did not match, a Void was sent. If Verify ID was not supported by the POS/PMS, an error was returned by the UTG. (1 byte; data block 085.)

Reference Guide


Function Request Codes Below is a list of Shift4 Payments FRCs:

Transaction Functions FRC Name Description

1B Online Auth

This function is used to request processor approval for an authorization only. If the invoice number already exists, the amount requested will be compared to the approved amount on file, and Shift4 Payments will request approval for the additional amount only. If approved, the authorization will remain in DOLLARS ON THE NET until it’s converted to a sale.

1D Online Sale

This function is used to request processor approval for an authorization and a sale. If the invoice number already exists, the amount requested will be compared to the approved amount on file, and Shift4 Payments will request approval for the additional amount only. If approved, a new sale transaction will be displayed in DOLLARS ON THE NET and ready to be batched.

05 Offline Auth This function is used to request authorization in an offline scenario, which means that Shift4 Payments will not seek processor approval. An authorization code should be included in this request.

06 Offline Sale

This function is used to request authorization and a sale in an offline scenario, which means that Shift4 Payments will not seek processor approval. An authorization code should be included in this request if the amount being submitted in the request is greater than the authorization amount currently on file.

08 Void This function is used to request that an existing invoice be cancelled.

Non-Transaction Functions FRC Name Description

07 Get Invoice Information

This function is used to request the status (e.g., approved, declined, error, referral, etc.) for a specific invoice; it is primarily used after a timeout or error has occurred. Voided or batched and settled invoices will return an “Invoice Not Found” error. For more information, see the Timeouts and Communication Failures section of the Shift4 Payments Integration: API Integration Guide available in MyPortal API Corner.

0B Get DBA Information This function is used to request Doing Business As (DBA) information for a specific merchant ID.

20 Signature Upload This function is used to upload the captured signature to an existing invoice in DOLLARS ON THE NET.

Reference Guide


FRC Name Description

22 Get Voice Center Information

This function is used to request the voice center phone number and merchant account number that should be displayed to the clerk so they can obtain a voice authorization code for a transaction. (The merchant must provide this information to Shift4 Payments.) The function should be sent after receiving a Referral response to an Online Auth (FRC 1B) or Online Sale (FRC 1D) request.

23 Identify Card Type This function is used to request and return the card type.

2F Verify Card This function is used to request card validation; it also validates Address Verification (AVS) and Card Security Code (CSC) data (if sent in the request) without consuming short-term data.

47 Request Signature This function is used to request a prompt for signature on a UTG-controlled PIN pad and returns the signature.

64 Get Four Words from TrueToken

This function is used to generate a unique combination of four words that can be used to reference CHD.

CA Status Request This function is used to verify data center connectivity and thread count.

F1 Print Receipt This function is used to request that a receipt be printed using a device’s built-in printer. The receipt may include a scannable bar code.

F2 Get Device Info

This function is used to request information regarding the status of a specific device. Depending on the type of device in use, this request may return a variety of device information in the response, including the types of encryption keys injected on the device and more.

Consumer-Prompt Functions FRC Name Description

82 Prompt Confirmation This function is used to display text for a consumer’s confirmation on a UTG-controlled PIN pad.

86 Process Forms This function is used to display a custom form and text for a consumer’s input on a UTG-controlled PIN pad.

CF Terms and Conditions This function is used to display terms and conditions for a consumer to accept or decline on a UTG-controlled PIN pad.

DA On-Demand Card Read

This function is used to prompt a P2PE-enabled UTG-controlled PIN pad to request a pass-through card swipe, causing the output of the swipe to be returned directly to the interface without any action or validation by Shift4 Payments or the processor.

Reference Guide



DB Input Prompt

This function is used to prompt a UTG-controlled PIN pad to collect a specified value from a consumer. The interface will specify the value based on the DeviceInputIndex field. (For a complete list of DeviceInputIndex values, see the Sending the Input Prompt Function section of the Shift4 Payments Integration: API Integration Guide available in MyPortal API Corner.) Each request will collect one specified value; when multiple values need to be collected, separate requests must be sent.

Check Functions FRC Name Description

17 Get Valid Check IDs

This function is used to request that an identification (ID) type be returned in a response. The value returned will indicate the type of ID that may be used to verify a consumer paying with a check. For information about the values returned, please see Appendix D – Required IDs for Check Verification in this document.

1F Check Approval Request

This function is used to request an online check approval.

Report Functions FRC Name Description

5F Totals Report This function is used to request a simple URL-encoded totals report for automated analysis. It does not supersede the standard auditing and reporting tools that are included with Shift4 Payments’ products.

Enhanced Itemization Functions FRC Name Description

92 Display Line Item This function is used to display a line item on a UTG-controlled PIN pad. In additional FRC 92 requests, if the API Option APPENDLINEITEM is sent, the UTG will append a line item to the existing line item(s) displayed.

94 Clear Line Items This function is used to clear the line items displayed on a UTG-controlled PIN pad.

95 Display Line Items This function is used to display up to 10 line items on a UTG-controlled PIN pad. In additional FRC 95 requests, if the API Option APPENDLINEITEM is sent, the UTG will append a line item to the existing line item(s) displayed.

96 Swipe Ahead This function is used to request a card swipe, insert, or tap (if applicable) on a UTG-controlled PIN pad before an Online Auth (FRC 1B) or Online Sale (FRC 1D) request is sent.

Reference Guide



97 PIN Pad Reset

This function is used to reset a UTG-controlled PIN pad to idle. When there is pending consumer input (e.g., waiting for the consumer to confirm the amount, swipe their card, select credit or debit, etc.), sending FRC 97 will cancel the request.

Gift Card Functions FRC Name Description

24 Activate/Reload This function requests that a new gift card be activated for use, that a new gift card be loaded with funds, or that an active gift card be loaded with additional funds.

25 Deactivate

This function requests that an active gift card be deactivated so that it can’t be used to process transactions. The API Option GCCASHOUT must be sent in the request to return any remaining funds to the consumer. If GCCASHOUT is not sent, a balance will remain on the gift card (if doing so is supported by the processor).

26 Reactivate

This function requests that a previously deactivated gift card be reactivated. If there was a balance remaining on the gift card at the time of deactivation, the balance will again become available for use. Funds cannot be added to a gift card during a Reactivate request.

61 Inquiry This function requests that a gift card’s balance, masked card number, expiration date, and discount percentage be returned. Merchants may be required to pay a fee for an inquiry request depending on their processor agreement.

TokenStore Functions FRC Name Description

E0 TokenStore Add

This function requests that CHD be added to a local or Global TokenStore and that a TrueToken be returned for use in a subsequent transaction. The card’s short-term data will not be consumed during the tokenization process when using this function. This function cannot be used for EMV processing.

E2 TokenStore Duplicate

This function requests that a new TrueToken be generated using an existing TrueToken. This request can be used to deposit a TrueToken into a Global TokenStore or as a means to continue using a token that is about to expire. The card’s short-term data (if sent by the interface) will be stored until it is used or for the period configured in the merchant’s DOLLARS ON THE NET account.

Reference Guide


Blocked Card Functions FRC Name Description

D7 Block Card This function requests that a card be placed on a list that prevents it from being used across an account.

D8 Unblock Card This function requests that a card be unblocked,, allowing it to be used across an account again.

D9 Card Block Status This function requests that the status of a card (“Blocked” or “Unblocked”) be returned.

MetaToken Functions FRC Name Description

CD Get MetaToken This function requests that a 16-digit MetaToken be returned for tracking card usage across multiple revenue centers.

Token Exchange Functions FRC Name Description

CE Token Exchange This function is used to request exchanging a Client GUID and Auth Token for an Access Token.

Citcon Functions FRC Name Description

6C Get QR Code This function returns a link to a QR Code image or a string that can be converted to a QR code image.

6D Get QR Pay Status This function requests a QR Pay transaction status.

Reference Guide


Deprecated Function Request Codes The following Shift4 Payments FRCs have been deprecated:


91 Display Clear This function is deprecated and has been replaced by FRC 94. It was used to request to clear a line item or a list of line items from a PIN pad display.

93 Poll Swipe Data This function is deprecated and should no longer be used by a point of sale (POS) or property management system (PMS). It was used to poll the PIN pad device for the card-swipe data.

Reference Guide


API Options API Options are sent to pass values that modify the request being made. API Options will be sent using the APIOptions field/API Options data block.

Requirement: When sending multiple options in a request, API Options must be separated by a comma.

Transaction Auth Request Options API Option Description

ALLDATA

This option is used to return all available fields in a response. ALLDATA is required to be sent in every request. Interfaces must be designed to ignore any fields in a response that are not applicable to a given request. Using ALLDATA enables support of Shift4 Payments’ TrueTokenization® technology, which facilitates payment security, as well as for IYC information to be returned in response to a sale/authorization request. As enhancements are made to Shift4 Payments’ products and offerings, new fields may be returned in a response and interfaces must be able to handle these responses accordingly.

ALLOWPARTIALAUTH

This option is used to enable the processor to issue a partial approval (if they support it). When ALLOWPARTIALAUTH is included in a request, the interface must interrogate the amount returned in the PrimaryAmount field in the response and compare it to the amount requested to determine if a transaction is partially approved because the approved amount may be less than the requested amount.

RETURNEXPDATE* This option is used to return a card’s expiration date unmasked.

TAXEXEMPT This option indicates that a transaction is tax exempt. TAXEXEMPT should only be used when a transaction is explicitly tax exempt.

USECARDNAME When using a UTG-controlled PIN pad, this option is used to overwrite the value in the CustomerName field with the information from the track data.

*The expiration date returned should only be used to determine the life of a TrueToken. It should never be used to evaluate whether or not a transaction should be approved.

Reference Guide


Sales Transaction Options API Option Description

INVMUSTEXIST This option returns an error if the invoice specified in an Online Sale (FRC 1D) does not already exist.

EBT Auth Request Options API Option Description

EBTCASH This option is used to indicate the transaction is an EBT cash benefit.

EBTFOOD This option is used to indicate the transaction is an EBT food stamps benefit.

EBTWITHDRAW This option is used to indicate the transaction is an EBT cash withdrawal.

Get DBA Options API Option Description

FULLDBANAME This option is used to return the merchant’s full DBA Name in the Notes field on DBA requests.

RETURNCURRENCYCODE This option is used to return the merchant’s configured currency code in the CurrencyCode field.

Gift Card Options API Option Description

GCCASHOUT

This option is used to clear any remaining balance from a gift card and return it to the consumer as cash. The card’s balance must be recorded before using the GCCASHOUT API Option. GCCASHOUT can be used with a Deactivate request (FRC 25) or an Online Sale request (FRC 1D).

IYCRECHARGE

This option is used to add the amount sent in the IYCBalance field to a gift card’s existing balance in an Activate/Reload request (FRC 24). For example, a card has a balance of $25 and an FRC 24 request is sent with an IYCBalance of $50 and the API Option IYCRECHARGE. The result will be the card having a balance of $75. If the IYCRECHARGE API Option is left out of the request, the card will be left with an incorrect balance of $50.

Reference Guide


API Option Description

IYCACTIVEONLY

This option is used to limit the processing capability to active cards when using Activate/Reload (FRC 24) and Deactivate (FRC 25) requests. This API Option is required in flows with active IYC cards to prevent unexpected results.

IYCDEACTIVEONLY

This option is used to limit the processing capability to inactive cards when using Activate/Reload (FRC 24) and Deactivate (FRC 25) requests. This API Option is required in flows with inactive IYC cards to prevent unexpected results.

Line Item Options API Option Description

APPENDLINEITEM

When using a UTG-controlled PIN pad, this option is used to append a line item to the existing line item(s) displayed on the screen. This API Option works with both Display Line Item (FRC 92) and Display Line Items (FRC 95) requests.

MetaToken Options API Option Description

RETURNMETATOKEN This option is used to return a MetaToken in a response (if enabled).

UTG-Controlled PIN Pad Options API Option Description

ALLOWCASHBACK This option is used to allow the interface to process cash back requests from a consumer.

BYPASSAMOUNTOK

This option is used to bypass the Amount OK screen and go straight to the insert/swipe screen. If Tip is enabled on the device, it will cause the UTG to prompt for Tip prior to going to the insert/swipe screen.†

BYPASSSIGCAP This option is used to suppress requesting an electronic signature from a consumer for a given transaction. Instead, a signature line will be included in the receipt text (if applicable).

BYPASSUTG This option is used to bypass the PIN pad (even if a TerminalID is included in a request).

BYPASSTIP This option is used to prevent the PIN pad from prompting for tip for the current transaction (if Tip is enabled for the PIN pad device in UTG TuneUp).

Reference Guide



DISABLEEMV This option is used to process a transaction using a specialized payment card via an alternate merchant ID (MID).

DISABLEMCE

This option is used to override the UTG TuneUp setting allowing manual card entry (MCE). The UTG will display a Please Swipe/Insert (or Tap, if applicable) form with the Manual Entry button disabled or hidden.

DISABLECONTACTLESS This option is used to disable the PIN pad’s contactless functionality for the current transaction.

DISCARDTRACKINFO This option is used to make a swiped card appear manually entered by discarding the swipe data other than the card number and expiration date.

LANECLOSED

This option is used with a PIN Pad Reset (FRC 97) request to put a terminal into a Lane Closed state. The Lane Closed screen will be displayed on the device instead of the standard idle screens. A second FRC 97 request without the LANECLOSED API Option will cancel the display of the lane closed screen.

NOSIGNATURE

This option is used to suppress requesting a signature from a consumer for a given transaction. Additionally, sending this option will ensure that a signature line will not be included in the receipt text (if applicable).

PLCCSIGNATURE

This option is used with a Request Signature (FRC 47) request. If PLCCSIGNATURE is included, the screen on the PIN pad will display “I have received and agree with the Terms and Conditions” instead of “Please sign and tap ok with pen”.

PRINTTIPLINE This option is used to include a tip line in the receipt text.

RETURNSIGNATURE This option is used to return the signature captured on a PIN pad to the interface. The returned signature can then be used by the interface to display to the clerk or print on a receipt.

USEMCE

This option is used to bypass the Please Swipe Card screen and display the Enter Card Number screen instead. This allows the interface to force MCE (even if it is disabled by default in UTG TuneUp).

†The Amount OK screen can be bypassed for all transactions on Ingenico PIN pad devices by selecting the “Bypass Amount OK” setting in UTG TuneUp.

WARNING! Using the NOSIGNATURE API Option to skip collecting signatures on low-dollar-amount transactions can increase the merchant’s chargeback risk.

Reference Guide


Receipt Text Options API Option Description

ENHANCEDRECEIPTS

This option is used to return two receipt text blocks: one for the merchant copy receipt and one for the customer copy receipt. This API Option must be sent with every FRC 1B, 1D, 05, 06, 07, and 08 request.

TokenStore Options API Option Description

TOKENAUTH

This option is used to trigger the system to perform a $0 or $1 authorization to validate the card. If the card is valid, the card number will be stored and a TrueToken will be returned. All other responses will return error 9858. This API Option will be ignored if the CVV2 information or track data is included in the request because CVV2 and track data cannot be stored after authorization and would be consumed by the TOKENAUTH API Option.

Totals Report Option API Option Description

NONPROBLEMSONLY This option is used to return only non-problem transactions in the response to a Totals Report request (FRC 5F).

Citcon Option API Option Description

QRLINK This option only applies to the GetQRCode (FRC 6C) function. If included, the response will return a link to a QR code image or a string that can be converted to a QR code image.

Reference Guide


Deprecated API Options The following Shift4 Payments API Options have been deprecated:


ALLOWVERIFYID This function is deprecated and should no longer be used by a POS/PMS. This option was used to enable the processor to issue an approval and request cardholder ID verification.

Reference Guide


Shift4 Payments Test Card Numbers The test card numbers listed in the tables below are the only acceptable numbers that may be used in the Shift4 Payments test environment. The use of any card number that is not listed in this section will result in an error.

Acceptable Test Card Numbers The following table contains acceptable test card numbers:

Card Type Card Number Expiration Date

VS – Visa 4321000000001119 Any Future Date



MC – Mastercard 5432000000003332 Any Future Date




AX – American Express 373400000002221 Any Future Date



JC – JCB 3337000000005551 Any Future Date

JC – JCB 3112030205926211 Any Future Date

VS – FSA Visa Debit, PIN Capable 4843609999999981 Any Future Date

VS – FSA Visa Debit, No PIN 4960049898989899 Any Future Date

MC – FSA Mastercard Debit, PIN Capable 5329809999999995 Any Future Date

MC – FSA Mastercard Debit, No PIN 5543249898989898 Any Future Date

VS – Interac Visa 4506364400038106 Any Future Date

NS – Novus/Discover 30103869233631 Any Future Date



NS – Discover 3059910000007215 Any Future Date






Reference Guide












NS – Diners Club International 36998900076186 Any Future Date



NS – Discover - JCB Test Card 3528000000123429 Any Future Date

NS – Discover - China Union Pay Test Card 6221261111112650 Any Future Date

NS – Discover - China Union Pay Test Card 6282000123842342 Any Future Date

Acceptable Private-Label Test Card Numbers The following table contains acceptable private-label test card numbers:


PL – Private Label 980000159 Any Future Date











Reference Guide






Private-Label Promotional Code Test Values

The following table contains a list of acceptable private-label promotional code test values:

Promo Type 01 Promo Type 02 Promo Type 03

F1: 000000 F1: 000002 F1: 000000

F2: 000010 F2: 000025 F2: 000000

F3: 12 MONTHS F3: 9 MONTHS F3: 6 MONTHS

F4: NO INTEREST F4: BILLED INTEREST F4: EQUAL PAYMENT

Reference Guide


Acceptable Test Card Trigger Numbers The following table contains acceptable test card trigger numbers; however, it is preferable to use the dollar amount trigger values for most testing. Refer to the Shift4 Payments Test Server Logic section of this document for dollar amount values.

Card Type Card Number Description

VS – Visa 4417010617574247 Used to trigger a demo host error.

MC – Mastercard 5301933782570466 Used to trigger a demo host error.

VS – Visa 4184324142934805 Used to trigger a timeout response.

VS – Visa 4184026860115661 Used to trigger a timeout response.

MC – Mastercard 5410648714659090 Used to trigger a timeout response.

MC – Mastercard 5410191817369234 Used to trigger a timeout response.

VS – Visa 4024007135532710 Used to trigger an invalid card response when sending a Verify Card request (FRC 2F).

MC – Mastercard 5135299256640694 Used to trigger an invalid card response when sending a Verify Card request (FRC 2F).

NS – Novus/Discover 30249963622904 Used to trigger an invalid card response when sending a Verify Card request (FRC 2F).

AX – American Express 371449635398431 Used to trigger an invalid card response when sending a Verify Card request (FRC 2F).

JC – JCB 3088518677707770 Used to trigger an invalid card response when sending a Verify Card request (FRC 2F).

NS – Novus/Discover 6011186767363105 Used to trigger an invalid card response when sending a Verify Card request (FRC 2F).

VS – Visa 4321000000001118 This card number will fail the Luhn mod 10 check.

Reference Guide


Shift4 Payments Test Server Logic Shift4 Payments’ test server simulates connectivity to a credit card processing network and provides processor-like responses to credit card transactions. The test host can be triggered for specific responses, allowing you to properly code for errors, declines, referrals, and other failures.

Desired Response Trigger(s)

Response=A (Authorized)

PrimaryAmount ≤ $500 or PrimaryAmount and Secondary Amount ≤ $500 or SecondaryAmount ≤ $500

Response=R (Referral)

$500 < PrimaryAmount ≤ $1000 or $500 < PrimaryAmount and Secondary Amount ≤ $1000 or $500 < SecondaryAmount ≤ $1000

Response=D (Declined)

$1,000 < PrimaryAmount < $10,000 or $1,000 < PrimaryAmount and Secondary Amount or $1,000 < SecondaryAmount

Demo Host Error $10,000 <= PrimaryAmount < $1,000,000

Application Timeout Response=‘A’ PrimaryAmount=111.XX, where XX is the number of seconds that the transaction response will be delayed.

Application Timeout Response=‘e’ PrimaryAmount=$112.XX, where XX is the number of seconds that the transaction response will be delayed.

Application Timeout Response=‘R’ PrimaryAmount=$511.XX, where XX is the number of seconds that the transaction response will be delayed.

Application Timeout Response=‘D’ PrimaryAmount=$1,111.XX, where XX is the number of seconds that the transaction response will be delayed.

Reference Guide



AVSResult

For each value in the AVSResult field, include the corresponding 2-digit trigger sequence in either the StreetAddress or ZipCode field.

AVSResult Trigger Sequence A 65 E 69 N 78 R 82 S 83 U 85 X 88 Y 89 Z 90

If more than one trigger sequence is present, values are read from left to right with the values in the StreetAddress field taking precedence over the values in the ZipCode field. For example, if StreetAddress=6545 Elm and ZipCode=49081, the AVSResult would return ‘A’ because ‘65’ occurred before ‘90’.

CardLevelResults returned in the CardLevelResult field:

CardLevelResult Card Type 2V VS 2C MC 1A AX 1B NS

PrimaryAmount=$6.66

CVV2Result=M (Match) CVV2Code=333 or 3333

CVV2Result=N (No match) CVV2Code=444 or 4444

CVV2Result=P (Not processed) CVV2Code=555 or 5555

CVV2Result=S (Should have been present) CVV2Code=666 or 6666

CVV2Result=U (Issuer unavailable to process) CVV2Code=777 or 7777

Approval is returned with a random partial auth amount

$219.00=Partial Auth

ResponseCode=A (Authorized) with a balance of $43.44 (pre-paid Visa/Mastercard/AMEX card)

PrimaryAmount=$6.66

ResponseCode=R (Referral) with a balance of $83.44 (pre-paid Visa/Mastercard/AMEX card)

PrimaryAmount=$516.66

ResponseCode=D (Decline) with a balance of $133.44 (pre-paid Visa/Mastercard/AMEX card)

PrimaryAmount=$1116.66

1-Pass Validation

PrimaryAmount ≤ $100 and send appropriate AVS/CVV2 triggers (see above) or PrimaryAmount and Secondary Amount ≤ $100 and send appropriate AVS/CVV2 triggers (see above)

Reference Guide



2-Pass Validation

PrimaryAmount > $100 and send appropriate AVS/CVV2 triggers (see above) or PrimaryAmount and Secondary Amount > $100 and send appropriate AVS/CVV2 triggers (see above)

Partial Authorization

Trigger by sending a PrimaryAmount and SecondaryAmount value that totals $219 in the initial Authorization (FRC 1B) or Sale (FRC 1D), or by increasing the amount by $219 on Incremental Authorizations (FRC 1B) or Settlements (FRC 1D).

Note: Triggers for existing invoices may be honored by using the trigger value and the current authorization on file.

Reference Guide


Shift4 Payments Common Error Codes Shift4 Payments has created error codes to identify error conditions as they occur when processing a transaction. An error condition is any condition where a card was not successfully processed with an approval, referral, or decline response. When appropriate, the interface notifies the user when an error occurs by displaying an error code, a short error message, and a long error message.

AVS and CVV failures are not considered error codes; instead, they are considered non-authorized responses from the issuer.

During testing, please contact your assigned API Analyst for assistance if you encounter a critical error or if any error persists after you attempt a solution described below.

Prim

ary

Erro

r Co

de

Seco

ndar

y Er

ror C

ode

Short Error Message

Long Error Message Cause Solution

1001 0 <Processing Service> UNAVAILABLE

No connection to processor

Connection to processor not available.

2011 0 <Varies, depending on failure>

Communication failure to processor

Communication failure with processor.

4003 0 <Text varies> Timeout waiting for response

No response from remote system.

Check network connectivity.

9012 0 Com Timeout Timeout waiting for response from modem

Modem/serial error. Send a Get Invoice Information request (FRC 07). Log the transaction if error is still received.

9018 0 Com Enq Timeout Timeout waiting for ENQ Modem/serial error. Send a Get Invoice Information request (FRC 07). Log the transaction if error is still received.

9020 0 Com Ack Nak Timeout

Timeout waiting for ACK or NAK


9023 0 Comm Char Timeout Timeout waiting for a character


9033 0 TRAN TIMEOUT Shift4 Client Socket Timeout

Connection problem between vendor software and the UTG.

Check network connectivity between the POS application and the UTG.

Reference Guide


Prim

ary

Erro

r Co

de

Seco

ndar

y Er

ror C

ode

Short Error Message


9034 0 INVALID API Sig Invalid API Signature. Expecting $

APISignature field does not contain ‘$’.

Confirm software is sending ‘$’ in the APISignature field.

9035 0 INVALID API Fmt Invalid API Format APIFormat field does not contain ‘0’.

Confirm software is sending ‘0’ in the APIFormat field.

9036 0 APIInvData Invalid data in API request

Transaction request contains invalid data.

Correct data.

9037 0 APIInvFunction Invalid API Function request

An invalid FRC was sent.

Confirm software is sending correct FRC for transaction request.

9070 0 BASEKEY FAILURE The P2PE key injected in the device is not valid.

Contact the device manufacturer/supplier to have the correct key injected.

9076 0 INCORRECT FORMAT Original encryption format not supported

Device is set for original encryption mode.

Must use Enhanced Encryption Format with AES.

9076 1 INCORRECT FORMAT TDES not supported Device is set up for Triple DES.

Must use Enhanced Encryption Format with AES.

9076 2 INCORRECT FORMAT The encrypted block is corrupted or in an unknown format

Unable to decrypt data.

9076 3 DECRYPTION FAILED The encrypted block is corrupt

Unable to decrypt data.

9076 6 NOT P2PE DATA The P2PE device returned unencrypted Card Brand data. Call Shift4 Support immediately.

9083 1 PLEASE RETRY Problem processing terms and conditions request DEFAULT

91XX‡ 0 <Response varies, depending upon error>

Host Error Processor host error. Contact Shift4 Payments.

9179 0 USEMCE ERROR Can’t specify track information when using USEMCE

POS Vendor sent track information along with the USEMCE option.

Reference Guide


Prim

ary

Erro

r Co

de

Seco

ndar

y Er

ror C

ode

Short Error Message


9179 1 USEMCE ERROR Can’t specify card information when using USEMCE

POS Vendor sent card information along with the USEMCE option.

9179 2 USEMCE ERROR Can’t specify UniqueID when using USEMCE

POS Vendor sent a UniqueID along with the USEMCE option.

9180 0 PAN MISMATCH Personal Account Number mismatch between tags 57 and 5A

The cardholder’s card has a different card number in the track 2 equivalent data (tag 57) and the Application PAN (tag 5A) on the Chip. Request a different form of payment.

9270 0 NoMSRdata No MSR data Wait for customer to swipe their card.

9271 0 NoCouponData No Coupon Data

9401‡ 0 DB NO RETURN Credit (Returns) cannot be processed for Debit cards

Some processors do not support debit refunds.

Contact Shift4 Payments.

9402 0 NEED TRACK2 Debit transactions require a track2 swipe.

Debit transactions require Track 2 data. EBT transactions require Track 2 data or must be manually keyed.

9402 0 TRACK 1 N/A EBT/Food transactions require a track2 swipe or manual keyed

Debit transactions require Track 2 data. EBT transactions require Track 2 data or must be manually keyed.

9402 1 NOT A DEBIT CARD Debit transaction cannot be processed with this card

Debit not allowed for the account.

Request a different form of payment.

9501 1 TX FAIL TO DEVICE Failed to send packet to device

There are communication problems between the UTG/UTG Stub and the PIN pad.

Check the connection to the PIN pad.

Reference Guide


Prim

ary

Erro

r Co

de

Seco

ndar

y Er

ror C

ode

Short Error Message


9501 1 TX PINPAD ERR TX PINPAD ERROR There are communication problems between the UTG/UTG Stub and the external device.


9501 2 RX PINPAD ERR RX PINPAD ERROR There are communication problems between the UTG/UTG Stub and the PIN pad.


9501 3 INVALID INPUT INVALID INPUT FROM CUSTOMER

Customer pressed an unrecognized button on the PIN pad.

Retry transaction.

9501 3 NO INPUT FROM CUST

NO INPUT FROM CUSTOMER

The transaction failed due to no input from the consumer in the specified time.

Retry transaction.

9501 3 No DUKPT Key Device not seeded The PIN pad was not injected correctly.

Contact your MSP to inject the PIN pad.

9501 3 TO MANY PIN TRANS One Million Trans Proc Retry transactions.

9501 3 TRAN Cancelled No pin entered Transaction cancelled by customer.

9501 5 FORM MISSING The form necessary to process this request is missing on the device.

The PIN pad does not have the correct forms loaded for the request.

Update the forms package loaded on the PIN pad.

9501 20 UNABLE TO READ CARD

UNABLE TO READ CARD DATA

Card reader is bad or dirty.

Retry transaction. Clean or replace card reader if problem persists.

9503 0 NO DATA You must send receipt data in the request

9503 1 PAPER JAM Printer has a paper jam

9503 2 PAPER OUT Printer is out of paper

9503 3 PRINTER ERROR Printer has returned a printer error

9503 4 PRINTER ERROR Printer has returned a request error (Continue or Finish message received without a Start)

9503 5 NO PRINTER Printer has returned a no printer found error

Reference Guide


Prim

ary

Erro

r Co

de

Seco

ndar

y Er

ror C

ode

Short Error Message


9551 2 CANCELLED Transaction cancelled by user

The transaction was cancelled by the user.

9551 2 NO PIN NO PIN was entered by cardholder

Customer did not enter PIN.

Retry transaction and have customer enter PIN.

9551 3 NO SIGNATURE CANCELLED Transaction cancelled by customer.

9551 4 NO SIGNATURE SIGNATURE NOT CAPTURED

Transaction still approved. Signature not captured electronically.

Obtain a hard copy of the consumer’s signature (i.e., on paper).

9551 5 BAD SIGIMAGE Signature image too large

The image is too large. Send smaller image.

9551 6 BAD SIGIMAGE Signature not captured The image file could not be converted to signature coordinates.

9551 7 BAD SIGIMAGE No image data Photo block was sent with empty PhotoData field.

9553 0 BAD IMAGE No photo data Photo block was sent with empty PhotoData field.

9553 1 BAD IMAGE Photo type not supported

A format other than PNG was specified.

Use a supported image format.

9553 2 BAD IMAGE Maximum size exceeded The image is too large. Send a smaller image.

9553 3 BAD IMAGE Missing photo data block

Required data block missing.

9553 4 INVALID BLOCK Function does not support photo

PhotoData field not supported with this function.

9601 1 NO PIN No PIN entered by customer

Customer did not enter PIN.

Retry transaction and have customer enter PIN.

9774 0 UnsupportedFRC Unsupported Function Code & FRC No.

This device does not support this FRC.

9774 4 NO SUPPORT Device does not support receipt printing

Reference Guide


Prim

ary

Erro

r Co

de

Seco

ndar

y Er

ror C

ode

Short Error Message


9774 5 NO SUPPORT Device does not support Get Device Info

9774 6 PRINTER ERROR Printer has returned an unrecognized response

9775 0 NO SUPPORT Function not supported in offline mode DEFAULT

A request was attempted when the UTG was offline that could not be processed.

9803‡ 0 INVALID CK Checks CK for Merchant ID not found

Check verification not configured for merchant.

Call Shift4 Payments regarding check support.

9803‡ 0 INVALID DCC Dynamic Currency Conversion for Merchant Id not found

DCC not configured for merchant.

Call Shift4 Payments regarding DCC support.

9803‡ 0 INVALID MID Invalid Shift4 merchant ID or card type not configured for merchant

The MID is not recognized by Shift4 Payments.

Confirm POS software is sending correct Shift4 Payments MID and check the UTG configurations. Contact Shift4 Payments.

9803‡ 0 INVALID MID Merchant ID is zero POS software is sending ‘0’ as MID. Invalid merchant ID.


9804 0 INVALID MID No merchants after <Merchant number>

No more DBA records.

9805 0 INVALID MID No merchants before <Merchant number>

No more prior DBA records.

9811 0 BAD TRAN Invalid Transaction ID -or- Bad Transaction Id <Transaction ID number>

Transaction ID not found in database.

9815 0 NO INV Invoice not found Invoice number not found in database.

9819 0 NO CARD INFO ENGINE01CE

Reference Guide


Prim

ary

Erro

r Co

de

Seco

ndar

y Er

ror C

ode

Short Error Message


9820 0 LUHN FAIL Card doesn’t pass Luhn check

Account number did not pass Luhn mod 10 check. Card is possibly invalid.

9822 0‡ INVALID CK Checks CK for merchant not found



9822 0 INVALID CK Checks not configured for merchant



9822 0 INVALID DCC Dynamic Currency Conversion for Merchant Id not found

DCC not configured for merchant.

Call Shift4 Payments regarding DCC support.

9824 0 INVALID INVOICE Invoice is invalid – not numeric

Invoice number contains non-numeric data.

Correct data and retry transaction.

9825 0 UNKNOWN REQUEST -or- UNRECOGNIZED

Unknown function request “XX.” -or- Unrecognized function request

An invalid FRC was sent.

Confirm software is sending correct FRC for transaction requested.

9830 0 NOT ENABLED Blocked cards are not enabled for serial X (X will be the serial number sent in the request.

9830 1 DENY(constraint ID) DENY(constraint ID) Transaction is denied due to triggering the Transaction Constraint defined in DOLLARS ON THE NET as a constraint ID.

9836 0 CARD < > SWIPE Card track swipe data does not match card number

Card number in track data does not match data in card number field.

9836 0 CARD MISMATCH Can’t Change Cards-Split tender is required

One card is being used for authorization and another for settlement on the same transaction.

9837 0 BAD EXPIRATION Invalid Exp Date Expiration date not valid.

Reference Guide


Prim

ary

Erro

r Co

de

Seco

ndar

y Er

ror C

ode

Short Error Message


9837 0 EXPIRED CARD This card has expired Card has expired. Request a different form of payment.

9838 0 AMT EXCEEDED Amount Exceeded $99,999.99

Amount exceeded $99,999.99. Cannot process transactions greater than $99,999.99.

9840‡ 0 OVERFLOW UTG must enable large API requests

Call Shift4 Payments to enable.

9841 0 CURRENCY ERR Can’t change currency code on existing transactions.

Unable to change currency code.

Retry transaction without changing currency code on settle or reauthorize transaction in intended currency.

9842‡ 0 INVALID CARD Card is invalid–garbage found -or- CardSwipe is invalid–garbage found

Invalid card number. Card number data is non-numeric.


9842‡ 0 NOT IN CARDRANGE Card type not recognized

Card type not recognized for merchant. Or, card type does not start with the expected card range.

Use a different card for payment.

9842‡ 0 NOT IYC Card type is not It’s Your Card

Attempting a gift card transaction on a non-gift card account.


9843 1 NEED SWIPE PLEASE SWIPE CARD A card swipe is required to perform the transaction.

Retry the transaction with a card swipe.

9844‡ 0 I/O ERROR Record not posted Contact Shift4 Payments.

9845‡ 0 UNIQUE ID ERR Can’t specify card information when using unique identifier

The UniqueID is being supplied in card information.


9845‡ 1 UNIQUE ID ERR Can’t specify unique identifier when sending E0

Reference Guide


Prim

ary

Erro

r Co

de

Seco

ndar

y Er

ror C

ode

Short Error Message


9846‡ 0 BAD UNIQUE ID Unique Identifier not found for Merchant

Shift4 Payments has no record of the UniqueID being sent by the merchant. If utilizing TOKENSTORE, the UniqueID and its associated card data have been purged from the TOKENSTORE.

Contact Shift4 Payments. If utilizing TOKENSTORE and this problem occurs frequently, the Long Term Data Storage Duration timer can be adjusted in DOLLARS ON THE NET.

9846‡ 1 IMPOSSIBLE Received a unique identifier on a database without the column defined


9847 0 NOT ENABLED MetaToken is Disabled. No MetaToken generated

Feature not enabled by Shift4 Payments.

If the MetaToken feature is desired, contact Shift4 Payments.

9858 0 CARD FAILED The card number is not approved or failed CVV2/AVS

TokenStore Add request (FRC E0) was sent with the APIOption TOKENAUTH, but the $1 authorization failed.

The clerk must obtain a different form of payment to complete the transaction.

9861 0 ACCESS DENIED Global TOKENSTORE permission denied

Serial number is not on the Global TokenStore’s allowed list.

Verify that the correct serial number is specified in the TokenSerialNumber field. Remember: If trying to access your local TokenStore, the TokenSerialNumber is not required.

9861 1 NOT ALLOWED Cannot send unencrypted card data with P2PE

9861 7 NOT ALLOWED Cannot send unique id with Card Read request

9862

2 AccessToken AccessToken not found

Reference Guide


Prim

ary

Erro

r Co

de

Seco

ndar

y Er

ror C

ode

Short Error Message


9862 3 AuthToken AuthToken not valid Entered incorrectly into the application interface or it could be revoked.

9862 4 AuthToken AuthToken has already been used

A production Auth Token may only be used once.

9862 5 AuthToken Time expired for the AuthToken

The Auth Token was not used in the time allotted by the DOLLARS ON THE NET Account Administrator.

9862 8 AccessToken TokenValidation Value does not match

The value in the TokenValidation field does not match what is stored.

9863 0 VERIFY ID The processor returned approved with ID Verification

POS doesn’t support this functionality.

Request a different form of payment.

9864 0 INVALID TOKEN Token contains invalid characters

9864 1 INVALID INDEX DeviceInputIndex XXX is not a valid value.

The DeviceInputIndex field contains an unrecognized value.

Correct the value being requested in the DeviceInputIndex field.

9866 0 MULT TOKEN ERR Can’t specify track information when using MultiTokenStoreAdd Block

This can happen when the UTG cannot connect to the data center and the Access Token sent does not match what is stored in the UTG cache.

9866 1 MULT TOKEN ERR Can't specify card number when using MultiTokenStoreAdd Block

9866 2 MULT TOKEN ERR Can't specify unique identifier when using MultiTokenStoreAdd Block

Reference Guide


Prim

ary

Erro

r Co

de

Seco

ndar

y Er

ror C

ode

Short Error Message


9866 3 MULT TOKEN ERR Can't specify P2PEBlock when using MultiTokenStoreAdd Block

9876‡ 0 HOST ERR Generic test host error Host error generated on the test system. NOTE: Error only occurs on Shift4 Payments test host.


9902 0 TIMEOUT Timeout waiting for response from Secure NCIS <National Check Network>

Transaction timeout.

9910 0 Invalid XML Invalid XML Structure XML General.

9910 1 Invalid XML No Records XML General.

2 Invalid XML Missing Attributes XML General.

9910 3 Invalid XML Unexpected Attributes XML General.

9910 4 Invalid XML Invalid Card Length XML E0 specific (when using MultiTokenStoreAdd block).

9910 5 Invalid XML Invalid NonNumeric Card Number

XML E0 specific (when using MultiTokenStoreAdd block).

9910 6 Invalid XML Invalid Ref Length XML E0 specific (when using MultiTokenStoreAdd block).

9910 8 Invalid XML Duplicate Ref Found XML E0 specific (when using MultiTokenStoreAdd block).

9910 9 Invalid XML Invalid Exp Value XML E0 specific (when using MultiTokenStoreAdd block).

9910 10 Invalid XML Missing Nodes XML E0 specific (when using MultiTokenStoreAdd block).

Reference Guide


Prim

ary

Erro

r Co

de

Seco

ndar

y Er

ror C

ode

Short Error Message


9910 11 Invalid XML Unexpected Nodes XML E0 specific (when using MultiTokenStoreAdd block).

9910 12 Invalid XML Max Records Exceeded XML E0 specific (when using MultiTokenStoreAdd block).

9910 13 Invalid XML Invalid Street Length XML E0 specific (when using MultiTokenStoreAdd block).

9910 14 Invalid XML Invalid ZipCode XML E0 specific (when using MultiTokenStoreAdd block).

9910 99 Invalid XML Unknown Error XML General.

9951 0 RESPONSE TIMEOUT Timeout waiting for response across the internet

Transaction timeout at data center or processor.

9955 0 The PIN Pad for Terminal(1) is not ready to process transactions DEFAULT

9956 0 TID NO PINPAD Terminal <terminal number> is not configured for any PinPad

The terminal ID passed from the vendor interface is not configured for any PIN pad connected to the UTG.

Check your PIN pad configuration.

9957 0‡ EXCH KEYS NDC ONLY

NDCKeyChange not configured for NDC debit Mid

POS integration problem.


9957 0 NO CLIENT UTG client is not ready No connection to the Shift4 Payments data center.

Restart the UTG.

9957 0‡ NO HOST <Text regarding processor varies.> Not connected.

Processor not available.


9960 0 INTERNET FAILURE Transaction timeout with processor


Reference Guide


Prim

ary

Erro

r Co

de

Seco

ndar

y Er

ror C

ode

Short Error Message


9961 0 INTERNET FAILURE Transaction timeout <location>


9962 0 PIN timeout Timeout waiting for response

Timeout after PIN entry.

Send a Get Invoice Information request (FRC 07) to check invoice status.

9964 0 INTERNET FAILURE UTG Internet failure The UTG connection is unable to contact the Shift4 Payments data center.

Confirm Internet connectivity. Contact Shift4 Payments if problem persists.

9978 0 Engine timeout Pinpad Request

PIN pad Timeout Contact Shift4 Payments if problem persists.

9979‡ 0 BAD FUNC IMMEDIATE CREDIT supported only by It’s Your Card

Processor does not support Shift4 Payments’ IYC immediate credit capability.

Batch must be settled before refund can be credited. Contact Shift4 Payments.

9992 3 Invalid tm data Invalid numeric data for time field 811144 “81144” DEFAULT

9999 0‡ <Text varies> Unclassified error Error has not been classified as of yet.


9999 0 UnknownFRC Unknown Function Code & FRC No.

9999 000 NDC KEY EXCH FAILED

NDC Key request failed The key exchange failed. Retry transaction.

‡Critical errors require Shift4 Payments’ assistance. Contact the Shift4 Payments Customer Support team immediately at 702.597.2480, option 2. ‡S66 and S70 are from a Verifone SC 5000 PIN pad.

Reference Guide


Appendix A – Initializations and Acronyms Below is a list of initializations and acronyms that are commonly used within this document and throughout the payment industry.

Abbreviation Description

ABA American Bankers Association

API Application Programming Interface

AVS Address Verification System

BIN Bank Identification Number

CAD Canadian Dollar

CSC Card Security Code or CVV2

DBA Doing Business As

DCC Dynamic Currency Conversion

EMV Europay, Mastercard, and Visa (standard for chip and PIN technology)

FRC Function Request Code

GUID Globally Unique ID

IIAS Inventory Information Approval System (HSA/FSA)

IYC IT’S YOUR CARD

MCE Manual Card Entry

MICR Magnetic Ink Character Recognition

MID Merchant Identification Number (MerchantID)

MO/TO Mail Order/Telephone Order

PA-DSS Payment Application Data Security Standard

P2PE Point-to-Point Encryption

PAN Primary Account Number

SOS Secure Offline Stand-In®

USD U.S. Dollar

UTG Universal Transaction Gateway

Reference Guide


Appendix B – Detailed Card Types Below is a list of values specifying a detailed card type if returned by a processor.

Value Description

1A American Express

1B Discover

1C Mastercard (International Use)

1D Mastercard Credit

1E Mastercard Electronic

1F Mastercard Gold

1G Mastercard New World

1H Mastercard Standard

1I Mastercard Titanium

1J Mastercard Unembossed Credit

1K Mastercard/EuroCard and Diners Club

1L Platinum Mastercard

1M Visa Infinitel

1N Visa Signature

1P Visa Traditional

1R World Elite Mastercard

1S World Mastercard

2A Mastercard Credit BusinessCard Prepaid Outside U.S.

2B Mastercard Debit BusinessCard Prepaid Workplace Business-to-Business

2C Mastercard Debit Standard Prepaid – Payroll

2D Mastercard Debit Standard Prepaid – Gift

2E Mastercard Debit Standard Prepaid – General Spend

2F Mastercard Debit Standard Prepaid – Consumer Incentive

2G Mastercard Debit Standard Prepaid – Insurance

2H Mastercard Debit Standard Prepaid – Other

2I Mastercard Debit Standard Prepaid – Travel

2J Mastercard Debit Standard Prepaid – Teen

Reference Guide


Value Description

2K Mastercard Debit Standard Prepaid – Government

2L Mastercard Debit Standard Prepaid – Flex Benefit

2M Mastercard Debit Standard Prepaid – Employee Incentive

2N Mastercard Electronic BusinessCard Prepaid Outside U.S.

2P Mastercard Electronic Consumer Prepaid Outside U.S.

2R Mastercard Electronic Commercial Prepaid Outside U.S.

2S Mastercard Standard Prepaid Outside U.S.

2T Prepaid

2U Private Label Prepaid

2V Visa General Prepaid

2W Visa Prepaid Commercial

2X Visa Prepaid Gift

2Y Visa Prepaid Healthcare

2Z Visa Travel Money

3A Mastercard BusinessCard

3B Mastercard Electronic BusinessCard

3C Mastercard Executive BusinessCard

3D Mastercard Executive BusinessCard

3E Mastercard Purchasing Card

3F Mastercard World BusinessCard

3G Visa Business

3H Visa Business Check Card

3I Visa Commerce

3K Visa GSA Purchasing with Fleet

3L Visa Purchasing

3M Visa Purchasing with Fleet

3N Visa Signature Business

3P World Mastercard BusinessCard

3R American Express Purchasing

Reference Guide


Value Description

4A Mastercard Corporate

4B Mastercard Corporate Executive Card

4C Mastercard Electronic Commercial

4D Mastercard Executive Corporate Card

4E Mastercard World Corporate Card

4F Visa Corporate Card

4G Visa GSA Corporate T&E

4H World Mastercard Corporate Card

5A Visa Traditional Rewards

6A Debit Brokerage

6B Debit Business Card

6C Debit Gold Mastercard

6D Debit Mastercard

6E Debit Other

6F Debit Platinum Mastercard

6G Maestro Point-of-Sale Debit Program

6H Mastercard Debit

6I Mastercard Deferred Debit Business

6J Mastercard Deferred Debit Consumer

6K Mastercard Electronic Consumer Debit Outside U.S.

6L Mastercard Unembossed Debit Outside U.S.

6M Mastercard Unembossed Debit

6N World Mastercard Debit

7A Visa Check Card

7B Visa Flex/HSA/FSA Card

7C Mastercard Flex/HSA/FSA Card

8A U.K. Domestic Switch Brand

8B U.K. Domestic Solo Brand

8C Common Proprietary Swedish Credit Card

Reference Guide


Value Description

8D Common Proprietary Swedish Debit Card

8E Maestro

8F Mastercard Fleet Card

8G Private Label

8H Proprietary

8I Proprietary Credit Card (Sweden Domestic)

8J Proprietary Debit Card (Sweden Domestic)

8K Kelly Springfield Credit Card

8L Goodyear Credit Card

8M Goodyear Commercial Card

8N Wright Express Credit Card

9X Reserved/Interlink

Reference Guide


Appendix C – Track Information Format The table below defines the track information format of card information depending on how CHD is entered.

How was cardholder data entered?

Track Information Format Example

Track 1 Swipe

Track 1 Format:

• %B

• Payment card number

• ^

• Cardholder name

• ^

• Expiration date (YYMM)

• ?

Track 2 Swipe

Track 2 Format:

• ;


• =


• ?

Reference Guide




Tracks 1 and 2 Swipe

Track 1 Format:

• %B


• ^

• Cardholder name

• ^


• ?

-and-

Track 2 Format:

• ;


• =


• ?

P2PE Device Type 01 –

Track 1 Swipe

Track 1 Format:

• See example

P2PE Device Type 01 –

Track 2 Swipe

Track 2 Format:

• See example

Reference Guide




P2PE Device Type 01–

Track 1 and 2 Swipe

Track 1 Format:

• See example

-and-

Track 2 Format:

• See example

Reference Guide


Appendix D – Required IDs for Check Verification The table below provides a list of values identifying the ID type required for check verification.

Value Description Value Description Value Description

00 Check MICR No. 41 Nova Scotia DL 70 Puerto Rico DL

01 Northwest Territories DL

42 Georgia DL 71 Quebec DL

02-09 Unused 43 Idaho DL 72 South Carolina DL

10 Military ID (SSN #) 44 Hawaii DL 73 South Dakota DL

11 British Columbia DL 45 Illinois DL 74 Rhode Island DL

12 Saskatchewan DL 46 Indiana DL 75 North Carolina DL

13 New Brunswick DL 47 New Hampshire DL 76 Unused

14 Telephone Number 48 Unused 77 Mississippi DL

15-19 Unused 49 Iowa DL 78 Pennsylvania DL

20 Arizona DL 50 Choice Card 79 Maryland DL

21 Alberta DL 51 Ontario DL 80 Unused

22 Visa Card 52 Louisiana DL 81 Prince Edward Island DL

23 California DL 53 New Jersey DL 82 Virginia DL

24 Carte Blanche Card 54 Unused 83 Vermont DL

25 Alabama DL 55 Alaska DL 84-85 Unused

26 Colorado DL 56 Maine DL 86 Tennessee DL

27 Arkansas 57 Kansas DL 87 Massachusetts DL

28 Connecticut 58 Unused 88 Utah DL

29-30 Unused 59 Kentucky DL 89 Texas DL

31 Newfoundland 60 Ohio DL 90 Unused

32 Unused 61 Manitoba DL 91 Yukon Territories DL

33 Delaware DL 62 Mastercard 92 Washington State DL

34 Unused 63 Nebraska DL 93 Washington, DC DL

35 Florida DL 64 Minnesota DL 94 Wisconsin DL

36 North Dakota DL 65 Oklahoma DL 95 Discover Card

37 Unused 66 Missouri DL 96-97 Unused

38 Nevada DL 67 Oregon DL 98 West Virginia DL

39 New Mexico DL 68 Montana DL 99 Wyoming DL

40 Michigan DL 69 New York DL

Reference Guide


Change Log

10/16/15 Change Log API Reference Guide Page Change

7 Added CashBack field.

7 Added CurrencyCode field

10 ETX – The property value pair indicating the end of an HTTP transaction message.

10 Added FormName and FormResponse fields.

12 Added section for K and KeyValueX field

17 Added SignatureSupressed, STX, and Surcharge fields.

18 Updated TerminalID definition.

18 Added TrueToken definition.

18 Marked VerifyID field as deprecated

19 Updated UniqueID definition.

19 Added Verbose field.

46 Marked VerifyID API Option as deprecated.

47 Updated ALLDATA API Option definition.

47 Added USECARDNAME API Option definition

49 Added ALLOWCASHBACK API Option definition

49 Added BYPASSTIP API Option definition.

49 Updated NOSIGNATURE API Option definition

Reference Guide


11/05/15 Change Log API Reference Guide Page Change

Throughout doc replaced cardholder as consumer when referring to a merchant’s customer.

7 Fixed ContentType definition

9 Fixed FormResponse definition

10 Fixed KeyValueN definition

15 Fixed Requestor Reference definition

16 Fixed Response definition

18 Added definitions for TermsAndConditionsResult and TermsandConditions fields

22 Fixed FRC 2F definition

22 Fixed FRC86 definition

23 Marked FRC 22 Swipe Ahead as deprecated.

29 Updated Test Sever Logic for AVSResult.

37 Fixed description of error code 9775

Page Change

6 Updated CardPresent definition

7 Updated ContentType definition

7 Updated CustomerName definition

12 Updated KeyValueN definition

17 Updated Response definition

19 Added TermsAndConditions fields

23 Updated 2F definition

27 Added new Mastercard test number

30 Updated AVSResult test server logic

Reference Guide


1/18/15 Change Log API Reference Guide 3/22/15 Change Log Reference Guide

Page Change

6 Enhanced CardEntryMode definition

6 Enhanced CardPresent definition

9 Enhanced ErrorIndicator definition

9 Enhanced ExpirationDate definition

17 Enhanced TerminalID definition

47 Deprecated GCRETURN API Option

47 Enhanced ALLOWCASHBACK API Option definition

47 Added LANECLOSED API Option

48 Enhanced TOKENAUTH API Option definition

6/14/15 Change Log Reference Guide Page Change

Throughout document added field length to definitions

3 Moved APIPassword and APISerialNumber fields to the deprecated fields section

Modified Authorization field definition

5 Modified AVSResult field definition

11 Modified ClientGUID field definition

Modified CustomerName field definition

14 Added DeviceInputIndex field definition

16 Updated IYYAvailableBalance, IYCBalance, IYCCardFormatted, IYCCardType, IYCDiscount, IYCExpiration, and IYCReasonText field definitions.

17 Moved KeyValue field content to API Integration Guide

Modified MerchantReceiptText field definition

Reference Guide


Page Change

19 Modified P2PEDeviceType field definition

Added PostalCodePrompt field definition

21 Modified ReceiptText field definition

Modified ReceiptTextColumns field definition

22 Moved ResponseCode to deprecated fields section

23 Modified SerialNumber field definition

Modified SignatureBlock, SignatureBlockNumber, SignatureDeviceType, and SignatureTotalBlocks field definition

24 Added SignatureNumberPrompt field definition

25 Modified TerminalID field definition

Modified Time field definition

Modified TokenSerialNumber field definition

Moved VerifyID field to deprecated fields section

27 Created section for deprecated fields

28 Added BIN, GUID, MO/TO, PA-DSS, SOS to Initializations and Acronyms list

29 Updated FRC 23 definition

30 Updated FRC 82, 86,95, CF, DB definitions

Added FRC DB definition

31 Updated FRC CD, E0 definition

Created section for Deprecated Functions

Moved FRC CA data to API Integration Guide

33 Added Private Label Promotional Code Test Values

37 Fixed formatting of Error Codes table.

53 Enhanced ALLDATA API Option definition

64 Moved FRC 5F information to API Integration Guide

Reference Guide


5/10/17 Change Log Reference Guide Page Change

• Formatting o Updated headings and document organization. o Updated entire formatting of document to comply with the current Development

Documentation Standards. o Updated the formatting of all tables. o Verified all field lengths against the complete functions guides and included them in

the field descriptions. o Ensured the reference symbols were used correctly throughout the document.

• Mechanics o Moved FRC 5F from the Reference Guide to the API Integration Guide. o Added trademark to the first in-text use of IT’S YOUR CARD, MetaToken, Secure Offline

Stand-In, and UTG4Cloud. o Updated instances of MasterCard to Mastercard to match current Mastercard

branding. o Changed deprecated field descriptions, FRC descriptions, and API Option descriptions

from present tense to past tense

2 • Copyright page o Added new patents.

3 • Introduction to the Reference Guide o Drafted an introduction to the Shift4 Integration: Reference Guide. o Added a callout referring to Appendix A – Initializations and Acronyms as a reference

tool.

4-30 • Field Descriptions o Reviewed and updated field descriptions. o Added “postal” to ZIP code areas where appropriate. o Updated CardEntryMode field description and the correlated table to better specify

the requests and responses. o Added a Warning callout that sending a payment card number and a TrueToken in a

request will result in an error. o Added tables to the CardType field description. o Moved the IIAS Type table from the end of the document to underneath the IIASTypeN

field description for clarity. o Updated the P2PEDeviceType field description to incorporate behavior with FRC DA. o Added a note regarding P2PEDeviceTyoe with FRC DA. o Updated the ReceiptText field to 4,000 bytes instead of 4,096 bytes to match length in

testing. o Added SpinPrefix field description. o Added SpinIsDCC field description. o Updated the Vendor field to incorporate more guidance. o Placed Deprecated Fields as a subsection

31-36 • Function Request Codes

Reference Guide


Page Change

o Reviewed and updated FRC descriptions. o Updated the name of FRC 20 Send Signature Capture request to Signature Upload

request. o Updated FRC 97 to describe recent UTG update. o Placed Deprecated Function Request Codes as a subsection. o Updated Swipe Ahead, FRC DA, and FRC DB. o Added FRC F1 and FRC F2.

37-42 • API Options o Reviewed and updated API Option descriptions. o Placed Deprecated API Options as a subsection. o Added BYPASSAMOUNTOK. o Deleted Delete Invoice Options DELETESALE, FULLVOID, and ROLLBACKERR, since they

are no longer being introduced to new vendors. These fields have not yet been deprecated.

43-46 • Shift4 Test Card Numbers o Added and tested new test card numbers.

47-48 • Shift4 Test Server Logic o Minor updates to the test server logic for responses A, R, and D to match behavior in

testing. o Added desired responses for the CardLevelResults trigger based on SME input. o Updated the pre-paid response code triggers to clarify the responses are for prepaid

Visa, Mastercard, or AMEX cards based on SME input. o Deleted triggers that are not in used based on SME input.

49-66 • Shift4 Common Error Codes o Added communication error codes 9012, 9018, 9020, and 9023. o Added 9503 error codes with secondary error of 0, 1, 2, 3, 4, and 5 for FRC F1 errors. o Added 9774 error with secondary error code of 4 Device does not support receipt

printing. o Added 9774 error with secondary error code of 5 Device does not support Get Device

Info. o Added 9774 error with secondary error code of 6 printer error. o Updated the Solution for 9956 error with a secondary error code of 0 since the section

that the developer was being referred to does not exist anymore in the UTG Quick Installation Guide. Updated Solution to make it more general.

o Updated formatting within the table.

67 • Appendix A – Initializations and Acronyms o Moved the Initializations and Acronyms table to an appendix for ease of reference.

68-71 • Appendix B – Detailed Card Types o Moved the Detailed Card Types table to an appendix for ease of reference.

72 • Appendix C – Required IDs for Check Verification o Moved the Required IDs for Check Verification table to an appendix for ease of

reference.

Reference Guide


6/15/18 - Change Log Reference Guide Page Change

• Formatting o Replaced “Shift4 Corporation” references with “Shift4 Payments” throughout the

document. o Updated reference symbols throughout the document.

22 • RentalTime o Definition updated. o Note added for formatting time.

23 • ReportEndTime o Note added for formatting time.

24 • ReturnTime o Note added for formatting time.

27 • TaxAmount o Note added for formatting time

28 • TaxIndicator o New entry added o Note added for formatting time.

29 • Time o Note added for formatting time

29 • Vendor o Configuration guidelines added to Vendor definition

36 • CitCon o CitCon FRCs added.

37 • API Options o TaxExempt API Option added to Transaction Auth Request Options.

38 • Sales Transaction Options o INVMUSTEXIST API Option added.

40 • UTG Controlled PIN Pad Options o PLCCSIGNATURE API Option added.

42 • CitCon Options o QRLINK API Options added.

48-50 • Shift4 Test Server Logic o Trigger values added for:

1 Pass Verification 2 Pass Verification Demo Host Error FRC 07 Response = ‘e’ FRC 07 Response = ‘R’ FRC 07 Response = ‘D’ Settlements of Auth Capture Transactions

Reference Guide


Page Change

53-67 • Shift4 Common Error Codes o 9083 added o 9466 deleted o 9470 0 deleted o 9470 1 deleted o 9470 2 deleted o 9470 3 deleted o 9470 4 deleted o 9470 6 deleted o 9470 100 deleted o 9471 16 deleted o 9471 98 deleted o 9471 998 deleted o 9471 999 deleted o 9489 deleted o 9803 footnote added o 9819 added o 9833 deleted o 9839 deleted o 9840 footnote added o 9842 footnote added o 9844 footnote added o 9845 footnote added o 9846 footnote added o 9876 footnote added o 9898 deleted o 9955 added o 9957 footnote added o 9992 added o 9998 deleted

shift4 payments integration · 2019-02-19 · written license agreement from shift4 payments. all...

Documents