Shift4 Tokens API
The Tokens API from Shift4 — 5 operation(s) for tokens.
Shift4 Tokens API is one of 21 APIs that Shift4 publishes on the APIs.io network, described by a machine-readable OpenAPI specification.
Tagged areas include Tokens. The published artifact set on APIs.io includes an OpenAPI specification, API documentation, and an API reference.
This API exposes 5 operations across 5 paths, and defines 108 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.
5 operations
5 paths
108 schemas
1 GET4 POST
Metadata
The identity and technical contract details declared by the specification.
Authentication & Security 2
Shift4 Tokens 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 5
Across 5 paths, the API surfaces 5 operations — 1 GET, 4 POST. Each is listed below with its method, path, parameters, and response codes.
Tokens 5
POST
/tokens/add
TokenStore Add
POST
/tokens/duplicate
TokenStore Duplicate
POST
/tokens/delete
TokenStore Delete
GET
/tokens/universaltoken
Universal Token
POST
/tokens/4words
Get Four Words
Schemas 108
The contract defines 108 schemas that model the data the API accepts and returns. The most detailed are DeviceCapability (8 properties), Customer (7 properties), tokens_add_p2pe_tdesdukpt_emv (6 properties), tokens_add_p2pe_onguardsde_emv (6 properties). Each schema is shown below with its type and property counts.
P2PEType0102IDTECH
object
2 properties
2 required
tokens_add_p2pe_idtech
object
4 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…
DeviceCapability
object
Conditional: Required when using a non-UTG-controlled device.
8 properties
CardResponseFourWords
object
3 properties
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.
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…
ACHAccountHolderName
string
ACH account holder's name
Error
object
6 properties
CustomerAddressLine1
string
Cardholder’s street address exactly as it appears on their billing statement. This field is used in AVS.
TokenTypeACH
string
Specifies the type of token. Value = ACH
MerchantName
string
The merchant’s business name as configured with Shift4.
EMVEmptyCandidateList
string
When EMV is attempted but fallback occurs due to an empty candidate list, this field should be sent as 'Y' and emv.fallback should also be sent as 'Y'. If this…
EMVOnguardSDE
object
Conditional: Required when processing an EMV transaction without using a UTG.
2 properties
1 required
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…
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.
tokens_add_comengcloud
object
5 properties
2 required
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.
CardToken
object
Conditional: Send this object when using a card on file.
1 property
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
tokens_add_p2pe_tdesdukpt_msr
object
5 properties
3 required
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…
MerchantMID
number
The merchant ID associated with the merchant account.
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…
CustomerEmailAddress
string
Customer email address.
P2PEType07AESMCE
object
3 properties
3 required
LighthouseResponse
object
1 property
ServerName
string
The name of the server that processed the request.
CardFourWords
string
Four words that reference cardholder data (CHD). The four words can be entered into Shift4’ 4Word® web app separated by spaces to temporarily reveal CHD. In ad…
CardTypeResp
string
An abbreviation used to specify the type of card that was used when processing a transaction. Value| Description -----|------------ AX | American Express AP |…
tokens_add_p2pe_tdesdukpt_emv
object
6 properties
4 required
tokens_add_p2pe_onguardsde_msr
object
5 properties
3 required
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…
CardMaskedNumberGC
string
The card number field will always be masked when returned in a response.
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…
tokens_add_unencryptedcard
object
4 properties
2 required
ErrorLongText
string
Extended error message that is returned if an error condition exists.
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
TokenValueACH
string
The token representing the customer's bank account credentials.
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…
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.
P2PEKIDAES
string
The key identifier for the key that was used to encrypt the P2PE data. Note: The encryption key will be exchanged manually per customer.
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…
P2PEFormatAES
string
Classifies the type of payment device being used for P2PE. Value|Description -----|----------- 07 | AES-128 or AES-256
DeviceCommerceEngineCloud
object
3 properties
3 required
TokenACH
object
2 properties
1 required
P2PEDataAESMCE
string
Manual card entry information encrypted with AES 128. The decrypted information must be in the following format: pan= |exp= |cvv= |Value | Description |-------…
tokens_add_utgdevice
object
4 properties
2 required
P2PEFormatType05
string
Classifies the type of payment device being used for P2PE. Value|Description -----|----------- 05 | [Shift4 TDES DUKPT format](/guides/core-concepts/p2pe-forma…
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
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
DeviceSerialNumber
string
Specifies the serial number of the device.
ACHAccountNumber
string
Bank Account Number. Do not include any dashes, spaces, or additional zeros.
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.
tokens_add_ach
object
2 properties
2 required
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.
EMV
object
Conditional: Required when processing an EMV transaction without using a UTG.
2 properties
1 required
tokens_add_p2pe_aes_mce
object
5 properties
3 required
tokens_add_response_card
object
1 property
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…
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…
DeviceOnlyTIDResponse
object
1 property
P2PEKSN
string
The key serial number which was used to encrypt the P2PE data.
tokens_add_response_ach
object
1 property
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
ACHAccountType
string
Bank account type Value | Description ------|--------------- PC | Personal Checking PS | Personal Savings CC | Corporate Checking CS | Corporate Savings
tokens_add_comengdevice
object
5 properties
1 required
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…
P2PEData
string
The full output of a P2PE keypad/magnetic swipe reader (MSR).
ACHAccountVerified
boolean
Send as true if the ACH account was verified through a 3rd party.
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…
UniversalToken
object
1 property
tokens_add_p2pe_onguardsde_emv
object
6 properties
4 required
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.
CardMaskedNumber
string
The card number field will always be masked when returned in a response.
CardEntryModeManual
string
The method used to capture a payment card. Value|Description -----|----------- M | Manual Entry
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.
UniversalTokenValue
string
An identifier for a card or payment account across all Shift4 merchants.
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…
ACHVerificationType
string
The type of verification used to validate the account. Value | Description ------|--------------- P | Prenotification M | Micro Deposits B | Bank Login
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…
ACHRoutingNumber
string
The routing number identifying the bank.
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 Cards 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
#Tokens
Where this information came from
This is an independent, third-party profile of Shift4 Tokens 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.