Shift4 Cards API
The Cards API from Shift4 — 2 operation(s) for cards.
Shift4 Cards API is one of 21 APIs that Shift4 publishes on the APIs.io network, described by a machine-readable OpenAPI specification.
Tagged areas include Cards. The published artifact set on APIs.io includes an OpenAPI specification, API documentation, and an API reference.
This API exposes 2 operations across 2 paths, and defines 118 schemas. It is described by OpenAPI 3.2.0, at version 1.7.57.
Requests are made against 2 base URLs: https://api.shift4test.com/api/rest/v1, https://api.shift4api.net/api/rest/v1.
2 operations
2 paths
118 schemas
2 POST
Metadata
The identity and technical contract details declared by the specification.
Authentication & Security 2
Shift4 Cards API declares
2 security schemes
for authenticating requests.
An API key is passed in the header as AccessToken (AccessToken).
It uses HTTP hmac-sha256 authentication (HMAC-SHA256).
AccessToken— A security credential used to authenticate API requests and all [i4Go®](https://s4-myportal.s3.amazonaws.com/downloads/documentation/i4go/i4go%20technical%20re…HMAC-SHA256— Authentication using HMAC-256 signatures as the authorization scheme. Sent in the Authorization header in the following format: Authorization: HMAC-SHA256 Cred…
Paths & Operations 2
Across 2 paths, the API surfaces 2 operations — 2 POST. Each is listed below with its method, path, parameters, and response codes.
Cards 2
POST
/cards/verify
Verify Card with Processor
POST
/cards/identify
Identify Card Type
Schemas 118
The contract defines 118 schemas that model the data the API accepts and returns. The most detailed are cards_verify_p2pe_onguardsde_emv (9 properties), cards_verify_p2pe_tdesdukpt_emv (9 properties), DeviceCapability (8 properties), cards_verify_p2pe_tdesdukpt_msr (8 properties). Each schema is shown below with its type and property counts.
P2PEType0102IDTECH
object
2 properties
2 required
cards_verify_p2pe_idtech
object
6 properties
2 required
CustomerPostalCode
string
Cardholder’s ZIP/postal code from their billing statement. This field is used in AVS. Do not include special characters. Note: This field only allows alphanume…
AVSPostalCodeVerified
string
Identifies whether the ZIP/postal code was verified (‘Y’) or not (‘N’) in an AVS check with a processor.
DeviceCapability
object
Conditional: Required when using a non-UTG-controlled device.
8 properties
cards_verify_comengdevice
object
7 properties
1 required
CardBin
string
The first 6 or 8 digits of the card.
P2PEType03OnguardSDEMSR
object
See [P2PE Format 03 Ingenico On-Guard SDE](/guides/core-concepts/p2pe-formatingenico-on-guard-sde---format-03) for more information.
2 properties
2 required
UISuppressFinalResult
boolean
When true, the terminal suppresses the final transaction result screen.
CardOnFile
object
Conditional: Send this object when the transaction being performed is using a card on file or when the request will result in storing a card on file. See the […
5 properties
DevicePromptStreetNumber
string
When using a UTG-controlled PIN pad: Value|Description -----|----------- Y | Force the PIN pad to prompt the consumer for the street number of their billing ad…
Error
object
6 properties
CustomerAddressLine1
string
Cardholder’s street address exactly as it appears on their billing statement. This field is used in AVS.
cards_verify_token_legacy
object
6 properties
2 required
MerchantName
string
The merchant’s business name as configured with Shift4.
CardTokenSerialNumber
string
In requests that require the use of a shared card token that is held by another merchant account, such as in a TokenStore or TokenShare®, this field is used to…
CustomerLastName
string
Specifies a consumer’s last name. This field is used in AVS. If the interface sends this field, the value specified by the interface will be returned in the re…
cards_identify_p2pe_onguardsde_msr
object
ErrorSeverity
string
Severity level of the error. | Severity | Description | | -------- | ---------------------------------------------------------------- | | Info | Action not req…
P2PEType05TDESDUKPTMSR
object
See [P2PE Format 05 TDES DUKPT](/guides/core-concepts/p2pe-formattdes-dukpt---format-05) for more information.
3 properties
3 required
CustomerMiddleName
string
Specifies a consumer’s middle name.
DeviceCapabilityManualEntry
string
Specifies whether or not the device supports manual entry. If this input method can be supported by the device, but the input method is currently disabled for…
ApiOptions
array
API Options modify the request being made. See the [API Options](/guides/appendices/api-options.md) section for more information.
P2PEDataOnguardSDEEMV
string
EMV TLV Data for tags 5A and 57 encrypted with AES 256 DUKPT. Contains the following information, separated by colons: Value | Description ----------------|---…
Server
object
1 property
PurchaseCardCustomerReference
string
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 wo…
DeviceCapabilityPIN
string
Specifies whether or not the device supports PIN entry (for debit or EMV). If this input method can be supported by the device, but the input method is current…
CardSecurityCodeIndicator
string
This field indicates the presence of a CSC. Value|Description -----|----------- 0 | CSC not provided by user. 1 | CSC provided. 2 | CSC illegible. 9 | CSC not…
CardSecurityCode
object
Conditional: Send only when card data is manually entered. This object should not be specified when using an encrypted device. This object should be sent for i…
4 properties
2 required
MerchantMID
number
The merchant ID associated with the merchant account.
CustomerEmailAddress
string
Customer email address.
LighthouseResponse
object
1 property
ServerName
string
The name of the server that processed the request.
cards_verify_unencryptedcard
object
6 properties
2 required
cards_verify_utgdevice
object
6 properties
2 required
cards_identify_utgdevice
object
CardTypeResp
string
An abbreviation used to specify the type of card that was used when processing a transaction. Value| Description -----|------------ AX | American Express AP |…
CustomerFirstName
string
Specifies a consumer’s first name. This field is used in AVS. If the interface sends this field, the value specified by the interface will be returned in the r…
TransactionResponseCodeCardsVerify
string
Code indicating the Shift4 host response. Value | Description | Details -------|------------------------------------------------------------------|-------- A |…
DateTime
string
The date and time in ISO 8601 format including the timezone offset (yyyy-mm-ddThh:mm:ss.nnn+hh:mm). Must be sent as the local date/time of the merchant. For ex…
ErrorLongText
string
Extended error message that is returned if an error condition exists.
cards_verify_p2pe_tdesdukpt_msr
object
8 properties
4 required
DevicePromptCardSecurityCode
string
When using a UTG-controlled PIN pad: Value|Description -----|----------- Y | Force the PIN pad to prompt the consumer for a CSC. N | Do not force the PIN pad t…
DeviceCapabilityMagstripe
string
Specifies whether or not the device supports magstripe. If this input method can be supported by the device, but the input method is currently disabled for all…
P2PEType05TDESDUKPTEMV
object
See [P2PE Format 05 TDES DUKPT](/guides/core-concepts/p2pe-formattdes-dukpt---format-05) for more information.
2 properties
2 required
DeviceCapabilityEMV
string
Specifies whether or not the device supports EMV. If this input method can be supported by the device, but the input method is currently disabled for all trans…
EMVTlvDataOnguardSDE
string
This field will contain all EMV tags in standard TLV format except tags 5A and 57, which will be sent encrypted in the p2pe.data field.
CardEntryMode
string
Conditional: The Card Entry Mode should be sent in an initial request; in subsequent requests, it should be left blank or not sent. When using a Universal Tran…
CardSecurityCodeResult
string
Conditional: Returned if card.securityCode.indicator and card.securityCode.value are sent in the request. The result of a CSC check. This field will be used by…
DevicePromptPostalCode
string
When using a UTG-controlled PIN pad: Value|Description -----|----------- Y | Force the PIN pad to prompt the consumer for a ZIP/Postal Code. N | Do not force t…
ErrorCode
integer
Code indicating the type of error that occurred. Refer to the [Error Codes](/guides/appendices/error-codes) section of this document for more details. Note: Th…
ErrorSecondaryCode
integer
This code supplements the code specified in the error.primaryCode field to provide additional information about the error that occurred.
cards_identify_token_legacy
object
cards_identify_p2pe_idtech
object
2 properties
2 required
CardSecurityCodeValue
string
The three- or four-digit Card Security Code found on a payment card. This value should only be sent in an initial sale/authorization request. It should not be…
CardOnFileRecurringFrequency
string
Indicates the minimum number of days between authorizations. Conditional: 'This field is required if it's the first recurring transaction (cardOnFile.type = S0…
cards_verify_p2pe_onguardsde_msr
object
8 properties
4 required
cards_verify_comengcloud
object
7 properties
2 required
TransactionAuthorizationCode
string
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…
AVSStreetVerified
string
Identifies whether the street number was verified (‘Y’) or not (‘N’) in an AVS check with a processor.
cards_identify_token_gtv
object
P2PEFormatType05
string
Classifies the type of payment device being used for P2PE. Value|Description -----|----------- 05 | [Shift4 TDES DUKPT format](/guides/core-concepts/p2pe-forma…
CardOnFileTransactionLinkId
string
A unique identifier assigned to each transaction to link related events throughout the transaction lifecycle. This field is supported for Mastercard brand only…
DeviceTerminalIdRequired
string
To prompt a specific UTG-controlled PIN pad in a request, the API Terminal ID configured in UTG TuneUp must be specified in this field.
UIMode
string
Set the UI to light mode by sending light or dark mode by sending dark
cards_identify_p2pe_onguardsde_emv
object
MerchantResponse
object
2 properties
P2PEType03OnguardSDEEMV
object
See [P2PE Format 03 Ingenico On-Guard SDE](/guides/core-concepts/p2pe-formatingenico-on-guard-sde---format-03) for more information.
2 properties
2 required
AVSValid
string
Simplified AVS result based on the merchant’s list of accepted responses as configured with Shift4: (‘Y’) if accepted or (‘N’) if not accepted.
AVSResult
string
Identifies the response code returned from an Address Verification System (AVS) check with a processor. Value|Description -----|----------- A | Street address…
CardTokenRequired
object
1 property
1 required
DeviceSerialNumber
string
Specifies the serial number of the device.
cards_identify_p2pe_tdesdukpt_msr
object
ErrorPrimaryCode
integer
Code indicating the type of error that occurred. Refer to the [Error Codes](/guides/appendices/error-codes) section of this document for more details.
ANIResponseCode
string
Account Name Inquiry Response Code. Returned if the USEANI API Option and customer name information is sent in the request. | ANI Response Code | Description |…
CardExpirationDate
integer
Conditional: Send only when card data is manually entered or when using a token. This field should not be specified when using an encrypted device. Card expira…
P2PEFormatIDTech
string
Classifies the type of payment device being used for P2PE. Value|Description -----|----------- 01 | IDTech Enhanced Encryption format (Keyboard Mode) 02 | IDTe…
DeviceModel
string
Conditional: Required when using a non-UTG-controlled device. Specifies the model of the device.
DeviceCapabilityQuickChip
string
Specifies whether or not the device supports quick chip. If this input method can be supported by the device, but the input method is currently disabled for al…
AVS
object
4 properties
CardTokenRequiredLegacy
object
2 properties
1 required
AccountNameInquiryResponse
object
1 property
CardDebitCapable
string
In BIN management, specifies whether a card can be processed as debit (‘Y’) or not (‘N’).
CardLevelResultIdentify
string
In BIN management, specifies the detailed card type. For a complete list of potential values, see the [Card Level Results]/guides/appendices/card-level-results…
Customer
object
7 properties
DeviceCapabilitySignature
string
Specifies whether or not the device supports signature capture. If this input method can be supported by the device, but the input method is currently disabled…
CardOnFileRecurringExpiry
string
Date after which no further authorizations shall be performed. This field is limited to 8 characters, and the accepted format is YYYYMMDD. Conditional: This fi…
DeviceOnlyTIDResponse
object
1 property
P2PEKSN
string
The key serial number which was used to encrypt the P2PE data.
cards_identify_p2pe_tdesdukpt_emv
object
5 properties
5 required
cards_verify_p2pe_tdesdukpt_emv
object
9 properties
5 required
DeviceManufacturer
string
Specifies the company which manufactured the device.
CardNumber
string
The payment card number entered in an initial authorization/sale request. This field will always be masked when returned in a response.
CardTokenResponse
object
1 property
CardExpirationDateResponse
integer
Conditional: Requires API Option "RETURNEXPDATE". Card expiration date in MMYY format. This value will only be populated if "RETURNEXPDATE" is included in the…
P2PEFormatOnguardSDE
string
Classifies the type of payment device being used for P2PE. Value|Description -----|----------- 03 | Ingenico Onguard SDE Format
CustomerIpAddress
string
Public source IP Address where the request originates, not the IP Address of the web server.
DeviceCapabilityContactlessMSR
string
Specifies whether or not the device supports contactless magstripe. If this input method can be supported by the device, but the input method is currently disa…
CardResponseIdentify
object
5 properties
P2PEData
string
The full output of a P2PE keypad/magnetic swipe reader (MSR).
cards_verify_token_gtv
object
6 properties
2 required
P2PEDataOnguardSDEMSR
string
Track information encrypted with AES 256 DUKPT. Contains the following information, separated by colons: |Value | Description |----------------|------------ |k…
UILanguageRequest
string
ISO 639-1 2-letter language code specifying the UI display language for the transaction (e.g. "en", "fr", "de"). When provided, overrides the device's configur…
cards_verify_p2pe_onguardsde_emv
object
9 properties
5 required
cards_identify_unencryptedcard
object
DeviceTerminalId
string
To prompt a specific UTG-controlled PIN pad in a request, the API Terminal ID configured in UTG TuneUp must be specified in this field.
CardOnFileType
string
This field specifies the type of the card-on-file transaction. Below is a table showing the valid values for use cases where the cardholder is entering their c…
CardOnFileTransactionId
string
This field is returned in the initial COF response, and ties subsequent COF transactions to the original authorization. For example, if a merchant runs a Sale…
CardMaskedNumber
string
The card number field will always be masked when returned in a response.
ErrorShortText
string
Abbreviated error message that is always returned if an error condition exists
LighthouseDataResponse
string
Base64 encoded JSON formatted data that will be returned from Lighthouse to be passed back to SkyTab. This data will contain variable information.
CardDccCapable
string
In BIN management, specifies whether or not the card is dynamic currency conversion (DCC) capable.
CardTokenValue
string
This field is used to specify a card token. Whenever CHD is sent in a request, a card token will be returned in this field. Your interface should be designed t…
DeviceCapabilityContactlessEMV
string
Specifies whether or not the device supports contactless EMV. If this input method can be supported by the device, but the input method is currently disabled f…
EMVTlvData
string
This field will contain all EMV tags in standard TLV format including the P2PE encrypted tags (5A and 57). The P2PE encrypted tags (5A and 57) will have the en…
DeviceCloud
boolean
Indicates the transaction will be processed via the Commerce Engine solution for cloud based POS/PMS systems. Value must be sent as true in order to route the…
CurrencyCode
string
Transaction currency code. See the [Currency Codes](/guides/appendices/currency-codes) section for details. Note: This is currently supported when processing f…
CardSecurityCodeValid
string
Conditional: Returned if card.securityCode.indicator and card.securityCode.value are sent in the request. A simplified CSC check result based on the value in t…
Specification
The full machine-readable OpenAPI contract behind this narrative.
Source
More from Shift4 12
Other APIs Shift4 publishes across the network.
Shift4 3D Secure API
Shift4 ACH API
Shift4 Batches API
Shift4 Checkout Sessions API
Shift4 Credentials API
Shift4 DCC API
Shift4 Devices API
Shift4 Gift Cards API
Shift4 Merchants API
Shift4 Mode API
Shift4 OCT API
Shift4 Payment Links API
#Cards
Where this information came from
This is an independent, third-party profile of Shift4 Cards API, published by API Evangelist. We do not operate, host, resell, or support these APIs, and we are not affiliated with or endorsed by the company unless stated above. Everything here is built from publicly available information — the company's own site, developer portal, documentation, public repositories, and the specifications it publishes for public use. Nothing is obtained by breaching a system, defeating an access control, or using credentials.
The Kin Score and Agent Readiness rating are independently calculated assessments of a company's public API artifacts, scored against a published rubric. They are not certifications, endorsements, security assessments, or audits.
Corrections, re-scores, and removal are free — no partnership or purchase required, and you do not need to justify the request. A removed company is recorded as unrated, never scored zero for having asked. Acknowledgement within one business day; removal within two.
info@apievangelist.com
·
Read the full data-sourcing policy →
On a security or compliance team? Put security in the subject line and
you will get a person, not a form — we will tell you exactly which public URLs this profile was built from.