Shift4 3D Secure API
The 3D Secure API from Shift4 — 2 operation(s) for 3d secure.
Shift4 3D Secure API is one of 21 APIs that Shift4 publishes on the APIs.io network, described by a machine-readable OpenAPI specification.
Tagged areas include 3D Secure. 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 142 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
142 schemas
2 POST
Metadata
The identity and technical contract details declared by the specification.
Authentication & Security 2
Shift4 3D Secure 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.
3D Secure 2
POST
/3dsecure/standalone
3D Secure Standalone
POST
/3dsecure/completion
3D Secure Completion
Schemas 142
The contract defines 142 schemas that model the data the API accepts and returns. The most detailed are CardResponse (10 properties), 3dsecure_standalone_cardnumber (10 properties), 3dsecure_standalone_token_gtv (10 properties), Amount (8 properties). Each schema is shown below with its type and property counts.
AVSPostalCodeVerified
string
Identifies whether the ZIP/postal code was verified (‘Y’) or not (‘N’) in an AVS check with a processor.
ShippingCityThreeDSecure
string
Shipping address - City Recommended for increasing the possibility of frictionless flow
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…
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
ShippingRegionThreeDSecure
string
Shipping address - A level 2 country subdivision code according to ISO-3166-2. Recommended for increasing the possibility of frictionless flow
RedirectURL3DSResponse
string
URL to redirect the browser to the 3D Secure transaction response indicates a Device Fingerprint or 3D Secure challenge is required.
Error
object
6 properties
RiskAssessmentRequest
string
The risk assessment value received in the [Risk Assessment](/apis/payments-platform-rest/openapi/risk/riskassess) response. Conditional: must be sent if [Risk…
CardLevelResult
string
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 [Card Lev…
CustomerAddressLine1
string
Cardholder’s street address exactly as it appears on their billing statement. This field is used in AVS.
MerchantName
string
The merchant’s business name as configured with Shift4.
ThreeDSecureBrowserColorDepth
string
Value representing the bit depth of the colour palette for displaying images, in bits per pixel. Accepted values are: Value| Description -----|------------ 1 |…
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…
TransactionS4RiskIdRequest
string
Unique transaction identification number generated by Shift4 to identify a specific risk transaction and a field that can be searched in LTM. Conditional: must…
TransactionVendorReference
string
Optional field for information that can be searched in the merchant portal.
ErrorSeverity
string
Severity level of the error. | Severity | Description | | -------- | ---------------------------------------------------------------- | | Info | Action not req…
HostResponseReasonCode
string
Returns a response code from the host. Value |Category|Description ------|--------|----------- 04 | 1 | Pick Up Card 07 | 1 | Pick Up Card, Special Condition 1…
TransactionResponseCode3DSStandalone
string
Code indicating the Shift4 host response. Value | Description | Details -------|---------------|-------- A | Approved | The 3D Secure process was approved. D |…
AmountSurcharge
number
Conditional: Send in the request if a surcharge was applied to the transaction. In a sale or authorization transaction, the surcharge field specifies a fee amo…
AmountTotal
number
The amount being charged for a particular transaction. If other amount fields are sent, they must be included in the total amount. Amount cannot be zero.
Receipt
object
3 properties
HostResponseReasonDescription3DSecure
string
Returns a description from the host.
ThreeDSecureReqChallengeInd
string
Indicates whether a challenge is requested for this transaction. For example: For payment authentication, a merchant may have concerns about the transaction, a…
ShippingCountryThreeDSecure
string
Shipping address - 2 character ISO Country Code. Recommended for increasing the possibility of frictionless flow
ThreeDSecureHeaderContent
string
Exact content of the HTTP user-agent header.
ThreeDSecureCryptogram
string
Ecommerce Cryptogram information
ApiOptions
array
API Options modify the request being made. See the [API Options](/guides/appendices/api-options.md) section for more information.
CustomerRegion
string
A level 2 country subdivision code according to ISO-3166-2.
AmountCheckTotal
number
Optional field specifying the total amount of the entire bill/invoice that this transaction is part of. It can be larger than amount.total in scenarios where t…
TransactionSaleFlag
string
Specifies a transaction is a sale (‘S’) or credit (‘C’). In an [Invoice Information](/apis/payments-platform-rest/openapi/transactions/getinvoice) request, an…
CustomerAddressLine2
string
Customer address line 2.
Server
object
1 property
CustomerCity
string
Customer address city.
HostResponseReasonDescription
string
Returns a description from the host.
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…
MerchantMID
number
The merchant ID associated with the merchant account.
CustomerEmailAddress
string
Customer email address.
ThreeDSecureEcommIndicator
string
E-commerce Indicator as provided by the application generating the cryptogram. Value| Description -----|------------ 5 | Secure electronic commerce transaction…
HostResponseReattemptPermission
string
Returns one of the following values: Value |Description ----------------------------------------|----------- Reattempt not permitted | Returned when the reason…
ThreeDSecureCardholderInfo
string
Provides additional information to the customer in particular cases when 3D secure Authentication failed.
CardBrandTokenAssuranceLevel
string
This is a response field defined by the token service provider. This Visa, Discover, or Mastercard value indicates the assigned confidence level of the token-t…
ServerName
string
The name of the server that processed the request.
CustomerPostalCodeThreeDSecure
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…
CardTypeResp
string
An abbreviation used to specify the type of card that was used when processing a transaction. Value| Description -----|------------ AX | American Express AP |…
CardBrandTokenPANLast4
string
This is a response field that contains 4 characters that represent the last 4 digits of the actual cardholder PAN.
ReceiptArray
array
Array of receipt key/value pairs that should be printed on the receipt.
ThreeDSecureChannel
string
Indicates the type of channel interface being used to initiate the transaction. Value| Description -----|------------ 01 | App-based (APP) 02 | Browser (BRW) 0…
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…
CustomerCityThreeDSecure
string
Customer address city. Recommended for increasing the possibility of frictionless flow
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…
TransactionInvoice
string
10-digit invoice number assigned by the interface to identify a transaction. An invoice number serves as a unique key that identifies a transaction within a ba…
CardBrandTokenAcctRangeStatus
string
This is a response field contains a one-character value that indicates the Visa regulatory status of the actual card number for which the token represents. Val…
ErrorLongText
string
Extended error message that is returned if an error condition exists.
ThreeDSecureBrowser
object
8 properties
8 required
BalanceAmount
number
The balance remaining on the card. Depending on which processor is being used, the balance may be returned for a gift card, debit card, EBT card, or other stor…
CardBrandToken
object
4 properties
1 required
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…
3dsecure_standalone_cardnumber
object
10 properties
8 required
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…
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…
ThreeDSecureBrowserLanguage
string
Value representing the browser language as defined in IETF BCP47.
CardResponse
object
10 properties
CustomerShipping3DSecure
object
Conditional: must be sent if threeDSecure.addressMatch is 'false'
6 properties
CustomerRegionThreeDSecure
string
A level 2 country subdivision code according to ISO-3166-2. Recommended for increasing the possibility of frictionless flow
AmountTotalOnly
object
Object containing information regarding the amount being requested. The total field within the object is required and specifies the amount being requested. Not…
1 property
1 required
ThreeDSecureTrxId
string
The assigned 3D Secure transaction ID
ErrorSecondaryCode
integer
This code supplements the code specified in the error.primaryCode field to provide additional information about the error that occurred.
AmountTax
number
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 amou…
ThreeDSecureBrowserJavascriptEnabled
boolean
Indicates whether the cardholder's browser has the ability to execute Javascript. Value | Description ------|------------ true | Cardholder's browser does have…
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…
CustomerCountry
string
2 character ISO Country Code. See the [ISO](https://www.iso.org/obp/ui/search/code/) website for details.
CompletionURL3DSRequest
string
Contains the merchant URL to which the browser should be redirected after the challenge session.
IIASAmountsArray
array
Conditional: Send in the request if processing for a health care merchant. For Vision related charges you must send only iiasAmounts.type = 4V and the correspo…
CustomerAddressLine1ThreeDSecure
string
Cardholder’s street address exactly as it appears on their billing statement. This field is used in AVS. Recommended for increasing the possibility of friction…
CustomerCountryThreeDSecure
string
2 character ISO Country Code. See the [ISO](https://www.iso.org/obp/ui/search/code/) website for details. Recommended for increasing the possibility of frictio…
ThreeDSecureChallengeWindowSize
string
Dimensions of the challenge window that will be displayed to the cardholder. The issuer replies with content that is formatted to appropriately render in this…
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.
TransactionResponseCode3DSFingerprint
string
Response code indicating that the 3D Secure transaction requires device fingerprinting. Value |Description -------|----------- H | Device fingerprinting requir…
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…
TransactionRetrievalReference
string
Reference retrieval number assigned by the authorizing agency. This value is printed on some receipts.
ThreeDSecureAddressMatch
boolean
Indicates whether the Cardholder Shipping Address and Cardholder Billing Address are identical. Value | Description ------|------------ true | Shipping Address…
IIASType
string
This code classifies eligible healthcare expenses. Value|Description -----|----------- 4O | Cash Disbursement (Discover Only) – Amount of Cash Back Being Reque…
CustomerPhoneCountry
string
Country calling code of the phone number. Required when sending customer.phoneNumber.
MerchantResponse
object
2 properties
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.
ThreeDSecureProgramProtocol
string
Indicates the 3D Secure protocol version. Required when processing for merchants in the United States. For merchants outside of the United States use the three…
AVSResult
string
Identifies the response code returned from an Address Verification System (AVS) check with a processor. Value|Description -----|----------- A | Street address…
CardResponse3DSChallenge
object
6 properties
AmountCashback
number
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 amou…
CardBrandTokenRequestorID
string
This field uniquely identifies the pairing of token requestor with the token domain. It is assigned by the token service provider and is unique within the toke…
CardTokenRequired
object
1 property
1 required
ShippingAddressLine2
string
Shipping street address - Line 2
CardDebitType
string
Specifies the type of debit card that was used when processing a transaction. Only returned if card.type = DB
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.
AmountTip
number
Conditional: Send in the request if a tip is included. The tip amount of the transaction.
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…
AVS
object
4 properties
TransactionNotes
string
A free-form notes field that supports the use of HTML tags. This can be used for reference in [Lighthouse Transaction Manager](https://ltm.shift4test.com/) and…
3dsecure_standalone_token_gtv
object
10 properties
8 required
ThreeDSecureBrowserJavaEnabled
boolean
Indicates whether the cardholder's browser has the ability to execute Java. Value | Description ------|------------ true | Cardholder's browser does have the a…
CardPresent
string
Conditional: Send in the initial authorization/sale request Indicates whether a card was present (‘Y’) or not (‘N’) at the time a transaction took place. This…
HostResponseReasonCode3DSecure
string
Returns a response code from the host. | Value | Description | | ----- | ----------------------------------------------------------------------------------- |…
CardBalance
object
1 property
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…
ShippingPostalCodeThreeDSecure
string
Shipping address - Postal Code Recommended for increasing the possibility of frictionless flow
CardSecurityCodeResponse
object
Conditional: Returned if card.securityCode was sent in the request.
2 properties
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
ThreeDSecureSecurityLevelIndicator
string
This field contains the electronic commerce indicators representing the security level and cardholder authentication associated with the transaction. This fiel…
IIASAmount
number
The subtotal for this type of healthcare expenses.
ThreeDSecureBrowserScreenWidth
integer
Total height of the Cardholder's screen in pixels.
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…
CustomerIpAddress
string
Public source IP Address where the request originates, not the IP Address of the web server.
CustomerPhoneNumber
string
Customer phone number
TransactionResponseCode3DSChallenge
string
Response code indicating that the 3D Secure transaction requires a challenge. Value |Description -------|----------- G | 3D Secure challenge required. Issuer c…
RiskTranIdRequest
string
The risk tranId value received in the [Risk Assessment](/apis/payments-platform-rest/openapi/risk/riskassess) response. Conditional: must be sent if [Risk Asse…
ShippingAddressLine1ThreeDSecure
string
Shipping street address - Line 1 Recommended for increasing the possibility of frictionless flow
ThreeDSecureBrowserScreenHeight
integer
Total height of the Cardholder's screen in pixels.
UniversalToken
object
1 property
CardMaskedNumber
string
The card number field will always be masked when returned in a response.
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…
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…
HostResponse
object
Returns the response code detailing why the transaction was declined. Notes: - For Visa, the response codes are categorized, detailing how declined transaction…
3 properties
ErrorShortText
string
Abbreviated error message that is always returned if an error condition exists
ThreeDSecureBrowserTZ
integer
Time difference between UTC time and the Cardholder browser local time, in minutes.
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.
ThreeDSecureDirectoryServerTranId
string
The Directory Server Transaction ID is generated by the EMV 3DS Mastercard Directory Server during the authentication transaction and passed back to the mercha…
ThreeDSecureBrowserAcceptHeader
string
Exact content of the HTTP accept headers.
TransactionAuthSource
string
In a response, a code returned by the processor to indicate which host issued the response. Value | Description -------|---------------------------- E | Engine…
IIASAmounts
object
2 properties
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…
Amount
object
Object containing information regarding the amount being requested. The total field within the object is required and specifies the amount being requested. All…
8 properties
2 required
AmountTaxIndicator
string
Value|Description -----|----------- Y | Tax is included N | Tax is not included
ThreeDSecureTransType
string
Identifies the type of transaction being authenticated. The values are derived from ISO 8583. Value| Description -----|------------ 01 | Goods / Service purcha…
ThreeDSecureInitiateStandalone
string
Indicates whether to initiate the 3D Secure authentication process Value| Description -----|------------ 01 | Force 3D Secure authentication 03 | Initiate 3D S…
RiskTransactionRequest
object
Conditional: must be sent if [Risk Assessment](/apis/payments-platform-rest/openapi/risk/riskassess) was completed prior to processing the transaction.
2 properties
ThreeDSecureCompInd
string
Indicates whether or not the device fingerprint was completed successfully. Value| Description -----|------------ Y | Yes N | No U | Unknown
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 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
Shift4 Payment Links API
#3D Secure
Where this information came from
This is an independent, third-party profile of Shift4 3D Secure 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.