# Verify Card with Processor

This function is used to request card validation by going online to verify the card information with the processor. If Address Verification System (AVS) and/or Card Security Code (CSC) data are sent in the request, that information will also be validated.
To process an Account Name Inquiry request the `USEANI` API Option and `customer.lastName` must be sent in the request. `customer.firstName` and `customer.middleName` are optional. Account Name Inquiry requests are currently limited to Visa cards.
**Integration Methods:**
- Host Direct
- Commerce Engine For On Premise
- Commerce Engine For Cloud
- Locally Installed UTG

See the [Integration Methods](/guides/quickstart#integration-methods) and [URLs Section](/guides/quickstart#urls) sections of the Development Quick Start guide for details regarding each processing option.
See the [JSON Body Schemas](/guides/quickstart#json-body-schemas) for more details on the various JSON body formats.

Endpoint: POST /cards/verify
Version: 1.7.67
Security: AccessToken

## Header parameters:

  - `InterfaceVersion` (string, required)
    Refers to the version of the program or application that is sending requests to Shift4. The following special characters are not allowed&colon;  $ % &colon; ^ - ~ < > , ? “ ” ‘ ’ { } [ ] \ + =

  - `InterfaceName` (string, required)
    Refers to the name of the program or application that is sending requests to Shift4. This should be the name of the program that you purchased or created. The following special characters are not allowed&colon;  $ % &colon; ^ - ~ ` < > , ? “ ” ‘ ’ { } [ ] \ + =

  - `CompanyName` (string, required)
    Refers to the vendor or partner that designed and certified the interface. The information you use in this field should match what Shift4 has on file or what was agreed upon in your Integration Plan. The following special characters are not allowed&colon;  $ % &colon; ^ - ~ ` < > , ? “ ” ‘ ’ { } [ ] \ + =

  - `AccessToken` (string, required)
    A security credential used to authenticate API requests and all [i4Go®](https://s4-myportal.s3.amazonaws.com/downloads/documentation/i4go/i4go%20technical%20reference%20guide.pdf) authorizeClient/preauthorizeClient requests. An Access Token is the alias for the merchant account and interface being used. The Access Token is required in all requests except an [Access Token Exchange](/apis/payments-platform-rest/openapi/credentials/accesstokenexchange) request, which generates an Access Token using an `authToken` and `clientGuid`.

## Request fields (application/json):

  - `dateTime` (string, required)
    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 example, a request processed at a merchant in the Pacific time zone at 9:18am on April 15th 2021 would be sent as 2021-04-15T09:18:23.283-07:00
Send `dateTime` as the merchant's local date and time, including milliseconds and an explicit numeric timezone offset. Never use the `Z` timezone designator. When the merchant's local UTC offset is zero, send `+00:00`. For other offsets, send the merchant's actual local offset for that date, including daylight-saving time where applicable.
- Use: `2026-10-26T09:18:23.283+00:00`
- Do not use: `2026-10-26T09:18:23.283Z`
    Example: 2024-05-21T09:18:23.283-07:00

  - `device` (object)

  - `device.terminalId` (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.
    Example: 1742

  - `transaction` (object)

  - `transaction.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 [Card On File Transactions](/guides/advanced-concepts/card-on-file-transactions) section for more information.

  - `transaction.cardOnFile.type` (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 card data to store on file.
| Value | Initiator | Recurring | 3D Secure | Description |
|  --- | --- | --- | --- | --- |
| S01 | Cardholder | No | Yes | Used when the initial transaction/card verification request is not for a recurring payment. |
| S02 | Cardholder | Yes | Yes | Used when the initial transaction/card verification request is for a recurring payment. Requires sending `cardOnFile.recurringFrequency` and `cardOnFile.recurringExpiry` |

Below is a table showing the valid values for uses cases where you already have a card on file and are using that existing card to process a transaction.
| Value | Initiator | Recurring | 3D Secure | Description |
|  --- | --- | --- | --- | --- |
| U01 | Cardholder | No | Yes | Unscheduled transaction using the card on file initiated by the cardholder |
| U02 | Merchant | No | No | Unscheduled transaction using the card on file initiated by the merchant |
| U03 | Merchant | Yes | No | Merchant initiated recurring payment using the card on file |
| U04 | Merchant | No | No | Identifies a transaction as a Reauthorization COF transaction. |
| U05 | Merchant | No | No | Identifies a transaction as a Resubmission COF transaction. Only certain merchant categories are able to send a resubmission, and it can only be done if the original authorization attempt was declined due to insufficient funds. |
| U06 | Merchant | No | No | Identifies a transaction as an Estimated Authorization COF transaction. |
| U07 | Merchant | No | No | Identifies a transaction as a Delayed Charges COF transaction. For example, a hotel might charge a customer for room damages after the guest has already checked out. |
| U08 | Merchant | No | No | Identifies a transaction as an Incremental COF transaction. For example, a hotel which authorized a customer’s card for one night at check-in might increase the authorization amount to cover two nights when the customer decides to extend their stay. Shift4 automatically detects this scenario and sends the appropriate value to the processor. |
| U09 | Merchant | No | No | Identifies a transaction as a No Show COF transaction. For example, a hotel might charge a customer who does not show up for a booked stay. |

See the [Card On File Transactions](/guides/advanced-concepts/card-on-file-transactions) section for additional details.
    Enum: "S01", "S02", "U01", "U02", "U03", "U04", "U05", "U06", "U07", "U08", "U09"

  - `transaction.cardOnFile.recurringExpiry` (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 field is required if it's the first recurring transaction (`cardOnFile.type = S02`). This field is not needed if the transaction is not recurring or if the transaction is a subsequent recurring transaction.**
    Example: 20250401

  - `transaction.cardOnFile.recurringFrequency` (string)
    Indicates the minimum number of days between authorizations.
**Conditional: 'This field is required if it's the first recurring transaction (`cardOnFile.type = S02`). This field is not needed if the transaction is not recurring or if the transaction is a subsequent recurring transaction.**
    Example: 15

  - `transaction.cardOnFile.transactionId` (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 on a card for the first time, they will receive a transactionId back in the response.  A month later, when the merchant wants to perform an additional Sale with the card on file, they would send a Sale request including the transactionId they received from the first sale.
**Conditional: Must be sent in subsequent COF requests if you are not processing with a Global Token Vault token. If using Global Token Vault tokens then this field is not required**
    Example: Z62537846172646

  - `transaction.cardOnFile.transactionLinkId` (string)
    A unique identifier assigned to each transaction to link related events throughout the transaction lifecycle, or to track the relationship between separate economically linked transactions. This field is supported for Mastercard brand only.
For example, if a merchant runs a Sale on a card for the first time, they will receive a transactionLinkId back in the response. A month later, when the merchant wants to perform an additional Sale with the card on file, they would send a Sale request including the transactionLinkId they received from the first sale.
**Conditional: Must be sent in subsequent COF requests if you are not processing with a Shift4 Token. If you are processing using a Shift4 Token, this field is not required.**
    Example: Z871868461726461879548

  - `transaction.purchaseCard` (object)

  - `transaction.purchaseCard.customerReference` (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 would use this field to collect the consumer’s purchase order or employee identification number. In lodging transactions, this may be unique transaction details, such as a reservation code or third-party booking source.  This field is part of Level 2 card data.
    Example: D019D09309F2

  - `customer` (object)

  - `customer.addressLine1` (string)
    Cardholder’s street address exactly as it appears on their billing statement. This field is used in AVS.
    Example: 65 Easy St

  - `customer.firstName` (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 response, unless the API Option [USECARDNAME](/guides/appendices/api-options#usecardname) is included in the request and a Commerce Engine or UTG-controlled PIN pad is in use. If the interface does not send the `customer` object, the consumer's name will be returned in the `customer` object if the name is present in the card's EMV or track data.
    Example: John

  - `customer.middleName` (string)
    Specifies a consumer’s middle name.
    Example: Andrew

  - `customer.lastName` (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 response, unless the API Option [USECARDNAME](/guides/appendices/api-options#usecardname) is included in the request and a Commerce Engine or UTG-controlled PIN pad is in use. If the interface does not send the `customer` object, the consumer's name will be returned in the `customer` object if the name is present in the card's EMV or track data.
    Example: Smith

  - `customer.postalCode` (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 alphanumeric characters (a-z, A-Z, 0-9). Special characters including - are not allowed. If you are sending in zip+4 you must not include the dash so 89134-1234 would be sent as 891341234**
    Example: 65144

  - `customer.emailAddress` (string)
    Customer email address.
    Example: john.smith@email.com

  - `customer.ipAddress` (string)
    Public source IP Address where the request originates, not the IP Address of the web server.
    Example: 63.57.84.101

  - `currencyCode` (string)
    Transaction currency code. See the [Currency Codes](/guides/appendices/currency-codes) section for details.
**Note: This is currently supported when processing for a merchant outside of the US and Canada. If processing for a US or Canadian merchant then this field will be ignored and the transaction will process in the merchant's configured currency.**
    Example: USD

  - `apiOptions` (array)
    API Options modify the request being made. See the [API Options](/guides/appendices/api-options) section for more information.
    Example: ["RETURNEXPDATE","ALLOWPARTIALAUTH"]

  - `ui` (object)

  - `ui.language` (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 configured default language for the duration of the session. Value persists across transactions until a new value is passed. Send default to reset the device back to its default language.
    Example: en

  - `ui.mode` (string)
    Set the UI to light mode by sending `light` or dark mode by sending `dark`
    Enum: "light", "dark"

  - `ui.suppressFinalResult` (boolean)
    When `true`, the terminal suppresses the final transaction result screen.
    Example: true

  - `dateTime` (string, required)
    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 example, a request processed at a merchant in the Pacific time zone at 9:18am on April 15th 2021 would be sent as 2021-04-15T09:18:23.283-07:00
    Example: 2024-05-21T09:18:23.283-07:00

  - `card` (object, required)

  - `card.token` (object, required)

  - `card.token.value` (string, required)
    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 to store this card token for future use. The latest card token received should be used in any subsequent request that references the same card data.
    Example: 8048471746471119

  - `card.expirationDate` (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 expiration date in MMYY format. This value should only be populated in the initial sale/authorization request.
    Example: 1230

  - `card.securityCode` (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 initial card on file request but is not required for subsequent merchant initiated  charges.**

  - `card.securityCode.indicator` (string, required)
    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 on card, or card did not have a CSC. |
    Enum: "0", "1", "2", "9"

  - `card.securityCode.value` (string, required)
    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 stored by the interface. When sending `card.securityCode.value`, `card.securityCode.indicator` must also be sent.
    Example: 333

  - `p2pe` (object, required)

  - `p2pe.data` (string, required)
    The full output of a P2PE keypad/magnetic swipe reader (MSR).
    Example: 027101801F2D1E00939B%*432100******1119^VS/DUAL TRACK^2212******?*;432100******1119=2212******?*CECE3FCE7781142BEC8D0E267AE89F5D3C7E235BF1A70E637951E8D93003E5A2586C336CA4A3B31F6639B04005BB12A716D8BC4D3…

  - `p2pe.format` (string, required)
    Classifies the type of payment device being used for P2PE.
| Value | Description |
|  --- | --- |
| 01 | IDTech Enhanced Encryption format (Keyboard Mode) |
| 02 | IDTech Enhanced Encryption format (USB HID Mode) |
    Enum: "01", "02"

  - `emv` (object, required)

  - `emv.tlvData` (string, required)
    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 entire TLV string encrypted and the encrypted data will be in a TLV format using the same tag. For example, tag 5A would look like the following:
- Encrypted: 5A103737DA95D8062F647A0FF747CC496570
- Decrypted: 5A084761739001010010
    Example: 4F07A0000000041010500A4D61737465724361726457203CCEB572BE7DD0A38E62E6BD70E3DAACE9B46BD3BF65E188E7D8D68D2178DE1A5A10B1794BAC083B08F0A1444F189A5493255F201A546573742F43617264203039202020202020202020202020…

  - `p2pe` (object, required)
    See [P2PE Format 05 TDES DUKPT](/guides/core-concepts/p2pe-format#tdes-dukpt---format-05) for more information.

  - `p2pe.format` (string, required)
    Classifies the type of payment device being used for P2PE.
| Value | Description |
|  --- | --- |
| 05 | [Shift4 TDES DUKPT format](/guides/core-concepts/p2pe-format#tdes-dukpt---format-05) |
    Enum: "05"

  - `p2pe.ksn` (string, required)
    The key serial number which was used to encrypt the P2PE data.
    Example: 6299495001100E200041

  - `p2pe` (object, required)
    See [P2PE Format 03 Ingenico On-Guard SDE](/guides/core-concepts/p2pe-format#ingenico-on-guard-sde---format-03) for more information.

  - `p2pe.data` (string, required)
    EMV TLV Data for tags 5A and 57 encrypted with AES 256 DUKPT. Contains the following information, separated by colons:
| Value | Description |
|  --- | --- |
| ksn | The key serial number (24 byte hex) |
| track indicator | `E` indicating EMV TLV Data |
| length | The length of the encrypted data |
| encrypted data | Encrypted TLV containing tags 57 and 5A |

Example: `FFFF495A0000000200000002:E:0032:E0AB94F7704E77AB37F81A7E236A1ABC1465C6DFCE43A506240D6E7D6DDA7EA9`
    Example: FFFF495A0000000200000002:E:0032:E0AB94F7704E77AB37F81A7E236A1ABC1465C6DFCE43A506240D6E7D6DDA7EA9

  - `p2pe.format` (string, required)
    Classifies the type of payment device being used for P2PE.
| Value | Description |
|  --- | --- |
| 03 | Ingenico Onguard SDE Format |
    Enum: "03"

  - `threeDSecure` (object, required)

  - `threeDSecure.cryptogram` (string, required)
    Ecommerce Cryptogram information
    Example: AAAAAAAA/COBt84dnIEcwAA3gAAGhgEDoLABAAhAgAABAAAALnNCLw==

  - `threeDSecure.ecommIndicator` (string, required)
    E-commerce Indicator as provided by the application generating the cryptogram.
| Value | Description |
|  --- | --- |
| 5 | Secure electronic commerce transaction |
| 6 | Authentication attempted, non-authenticated security transaction |
| 7 | Non-authenticated Security Transaction |
    Enum: "5", "6", "7"

  - `threeDSecure.securityLevelIndicator` (string, required)
    This field contains the electronic commerce indicators representing the security level and cardholder authentication associated with the transaction. This field must be present in all Auth Request messages for electronic commerce transactions.
First 2 positions:
| Value | Description |
|  --- | --- |
| 21 | Channel encryption; cardholder certificate not used (preferred value for Mastercard SecureCode, Identity Check, and all eCommerce) |
| 22 | Masterpass-generated transaction |
| 24 | Digital Secure Remote Payment (DSRP) with UCAF Data |
| 91 | No security protocol; cardholder certificate not used |

Third position:
| Value | Description |
|  --- | --- |
| 0 | UCAF Data collection is not supported by the merchant; or the merchant supports SecureCode or Identity Check but has chosen not to undertake it on this transaction; or authentication failed and merchant desires to proceed with the transaction. |
| 1 | UCAF data collection is supported by the merchant and UCAF data must be present and contain an attempt AAV |
| 2 | UCAF data collection is supported by the merchant and UCAF data must be present and contain a fully authenticated AAV |
| 3 | UCAF data collection is supported by the merchant and UCAF (Mastercard assigned Static Accountholder Authentication Value) data must be present. Note that the UCAF Data is required for Static AAV transactions. This value identifies participation in one of the following programs: Maestro Recurring Payments Program, Mastercard Utility Payment Program, Maestro Static AAV for Masterpass |
| 4 | Merchant has chosen to share authentication data within authorization; UCAF data collection not supported |
    Example: 241

  - `threeDSecure.programProtocol` (string, required)
    Indicates the 3D Secure protocol version.
**Required when processing for merchants in the United States. For merchants outside of the United States use the `threeDSecure.version` field instead.**
| Value | Description |
|  --- | --- |
| 1 | EMV 3-D Secure Version 2.1 |
| 2 | EMV 3-D Secure Version 2.2 |
| 3 | EMV 3-D Secure Version 2.3 |
| 4 | EMV 3-D Secure Version 2.4 |
| 5 | EMV 3-D Secure Version 2.5 |
| 6 | EMV 3-D Secure Version 2.6 |
| 7 | EMV 3-D Secure Version 2.7 |
| 8 | EMV 3-D Secure Version 2.8 |
| 9 | EMV 3-D Secure Version 2.9 |
    Enum: "1", "2", "3", "4", "5", "6", "7", "8", "9"

  - `threeDSecure.version` (string, required)
    Indicates the 3D Secure protocol version.
**Required when processing for merchants outside of the United States. For merchants in the United States use the `threeDSecure.programProtocol` field instead.**
    Enum: "2.0", "2.1.0", "2.2.0"

  - `threeDSecure.directoryServerTranId` (string, required)
    The Directory Server Transaction ID is generated by the EMV 3DS Mastercard Directory Server during the authentication transaction and passed back to the merchant with the authentication results. This field allows the merchant to pass the Directory Server Transaction ID during authorization in order to link authentication and authorization data for Mastercard Identity Check.
    Example: 07e54000-2721-4df9-aa51-04fa0e079aa8

  - `threeDSecure.authenticationSource` (string, required)
    Authentication Source for the cryptogram value.
| Value | Description |
|  --- | --- |
| 2 | ACS |
    Enum: "2"

  - `threeDSecure.cavvResult` (string)
    This is a response field that contains 3–D Secure Electronic Commerce Transaction Response Code that contains the Visa Cardholder Authentication Verification Value (CAVV) or the American Express Verification Value (AEVV) results code.
| Value | Description |
|  --- | --- |
| Blank | CAVV not present or CAVV not verified, issuer has not selected CAVV verification option |
| 0 | CAVV could not be verified or CAVV data was not provided when expected |
| 1 | CAVV failed verification-cardholder authentication |
| 2 | CAVV passed verification-cardholder authentication |
| 3 | CAVV passed verification-attempted authentication. A 3-D Secure Authentication Results Code value of 07 from the Issuer Attempts Server indicates that authentication was attempted. Issuer attempts CAVV key was used to generate the CAVV. |
| 4 | CAVV failed verification-attempted authentication. A 3-D Secure Authentication Results Code value of 07 from the Issuer Attempts Server indicates authentication was attempted. Issuer attempts CAVV key was used to generate the CAVV. |
| 5 | Reserved for future use |
| 6 | Reserved for future use |
| 7 | CAVV failed verification-attempted authentication. A 3-D Secure Authentication Results Code value of 07 from Visa Attempts Service indicates that an authentication attempt was performed. Visa attempts CAVV key was used to generate the CAVV. Note that Results Code value of 7 is also valid for American Express SafeKey responses, including those for non-U.S. cards. |
| 8 | CAVV passed verification-attempted authentication. A 3-D Secure Authentication Results Code value of 07 from Visa Attempts Service indicates that an authentication attempt was performed. Visa attempts CAVV key was used to generate the CAVV. Note that Results Code value of 8 is also valid for American Express SafeKey responses, including those for non-U.S. cards. |
| 9 | CAVV failed verification-attempted authentication. A 3-D Secure Authentication Results Code value of 08 from Visa Attempts Service indicates that an authentication attempt was performed when the Issuer ACS was not available. Visa attempts CAVV key was used to generate the CAVV. Note that Results Code value of 9 is also for American Express SafeKey responses, including those for non-U.S. cards. |
| A | CAVV passed verification-attempted authentication. A 3-D Secure Authentication Results Code value of 08 from Visa Attempts Service indicates that an authentication attempt was performed when the Issuer ACS was not available. Visa attempts CAVV key was used to generate the CAVV. Note that Results Code value of A is also for American Express SafeKey responses, including those for non-U.S. cards. |
| B | CAVV passed verification-attempted authentication, no liability shift. Only Visa generates this code; issuers do not. |
| C | CAVV was not verified-attempted authentication (for Visa use only). If 3-D Secure Authentication Results Code value is 07 in the CAVV and the issuer did not return a CAVV results code in the authorization response, or CAVV results code = 0 in the response message and the CAVV encryption keys do not exist in V.I.P., V.I.P. sets the value to C in CAVV results code. |
| D | CAVV was not verified-cardholder authentication (for Visa use only). If 3-D Secure Authentication Results Code value is 00 in the CAVV and the issuer did not return a CAVV results code in the authorization response, or CAVV results code = 0 in the response message and the CAVV encryption keys do not exist in V.I.P., V.I.P. sets the value to D in CAVV results code. |
| U | CAVV Unchecked [AX] |
    Example: 2

  - `threeDSecure.authenticationValue` (string)
    Used only if both CAVV/UCAF and TAVV present in the transactions token contains the Visa token authentication verification value (TAVV) to support 3-D Secure (3DS) validation for token-based card-on-file, e-commerce, and application-based e-commerce transactions. Visa will allow two separate cryptograms in the authorization; one for token validation (TAVV) and one for cardholder authentication (Cardholder Authentication Verification Value).
    Example: <Cavv>Y2FyZGluYWxjb21tZXJjZWF1dGg=</Cavv>

  - `threeDSecure.tavvResult` (string)
    TAVVResult (Visa token authentication verification value).
| Value | Description |
|  --- | --- |
| 1 | TAVV cryptogram failed validation |
| 2 | TAVV cryptogram passed validation |
    Example: 2

  - `threeDSecure.walletID` (string)
    Provides information about transactions initiated through the Masterpass Online platform or through the Mastercard Digital Enablement Service (MDES) and identifies the Wallet Provider.
| Value | Description |
|  --- | --- |
| 103 | Apple Pay |
| 216 | Google Pay |
| 217 | Samsung Pay |
| 327 | Merchant tokenization program |
    Example: 103

  - `cardBrandToken` (object, required)

  - `cardBrandToken.requestorId` (string, required)
    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 token vault.
For Apple Pay requests, this is mapped from the `token.paymentData.data.deviceManufacturerIdentifier` field
    Example: 12345678901

## Response 200 fields (application/json):

  - `result` (array)

  - `result.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 example, a request processed at a merchant in the Pacific time zone at 9:18am on April 15th 2021 would be sent as 2021-04-15T09:18:23.283-07:00
    Example: 2024-05-21T09:18:23.283-07:00

  - `result.customer` (object)

  - `result.customer.addressLine1` (string)
    Cardholder’s street address exactly as it appears on their billing statement. This field is used in AVS.
    Example: 65 Easy St

  - `result.customer.firstName` (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 response, unless the API Option [USECARDNAME](/guides/appendices/api-options#usecardname) is included in the request and a Commerce Engine or UTG-controlled PIN pad is in use. If the interface does not send the `customer` object, the consumer's name will be returned in the `customer` object if the name is present in the card's EMV or track data.
    Example: John

  - `result.customer.middleName` (string)
    Specifies a consumer’s middle name.
    Example: Andrew

  - `result.customer.lastName` (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 response, unless the API Option [USECARDNAME](/guides/appendices/api-options#usecardname) is included in the request and a Commerce Engine or UTG-controlled PIN pad is in use. If the interface does not send the `customer` object, the consumer's name will be returned in the `customer` object if the name is present in the card's EMV or track data.
    Example: Smith

  - `result.customer.postalCode` (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 alphanumeric characters (a-z, A-Z, 0-9). Special characters including - are not allowed. If you are sending in zip+4 you must not include the dash so 89134-1234 would be sent as 891341234**
    Example: 65144

  - `result.customer.emailAddress` (string)
    Customer email address.
    Example: john.smith@email.com

  - `result.customer.ipAddress` (string)
    Public source IP Address where the request originates, not the IP Address of the web server.
    Example: 63.57.84.101

  - `result.card` (object)

  - `result.card.expirationDate` (integer)
    **Conditional: Requires API Option "RETURNEXPDATE".**
Card expiration date in MMYY format. This value will only be populated if "RETURNEXPDATE" is included in the `apiOptions` array.
    Example: 1230

  - `result.card.number` (string)
    The card number field will always be masked when returned in a response.
    Example: XXXXXXXXXXXX1119

  - `result.card.type` (string)
    An abbreviation used to specify the type of card that was used when processing a transaction.
| Value | Description |
|  --- | --- |
| AX | American Express |
| AP | Alipay |
| BC | Backed Card |
| CI | Citgo |
| DB | Debit card |
| GC | Gift Card |
| JC | JCB |
| MC | Mastercard |
| NS | Discover/JCB/Novus |
| PL | Private Label |
| SC | Sears Canada |
| VS | Visa |
| WP | WeChat Pay |
| YC | IT’S YOUR CARD |
    Enum: "AX", "AP", "BC", "CI", "DB", "GC", "JC", "MC", "NS", "PL", "SC", "VS", "WP", "YC"

  - `result.card.securityCode` (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 initial card on file request but is not required for subsequent merchant initiated  charges.**

  - `result.card.securityCode.result` (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 Shift4 to determine the value sent in the `card.securityCode.valid` field (based on the merchant’s list of accepted verification results as configured with Shift4).
| Value | Description |
|  --- | --- |
| M | CSC matched. |
| N | CSC did not match. |
| P | CSC not processed. |
| S | CSC should have been present. |
| U | Issuer unable to process. |
| Y | CVC1 incorrect. |
| 1 | CSC Unavailable - processor / card type does not support this parameter. |
| 2 | An unrecognised result code was returned by the processor. |
| 3 | No result code was returned by the processor. |
    Enum: "M", "N", "P", "S", "U", "Y", "1", "2", "3"

  - `result.card.securityCode.valid` (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 the `card.securityCode.result` field and the merchant’s accepted verification results as configured with Shift4. The value returned will be ‘Y’ if CSC verification passed or ‘N’ if CSC verification did not pass.
    Example: Y

  - `result.card.token` (object)

  - `result.card.token.value` (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 to store this card token for future use. The latest card token received should be used in any subsequent request that references the same card data.
    Example: 8048471746471119

  - `result.device` (object)

  - `result.device.terminalId` (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.
    Example: 1742

  - `result.merchant` (object)

  - `result.merchant.mid` (number)
    The merchant ID associated with the merchant account.
    Example: 15877

  - `result.merchant.name` (string)
    The merchant’s business name as configured with Shift4.
    Example: Merchant XYZ

  - `result.transaction` (object)

  - `result.transaction.authorizationCode` (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 a referral response, it is also specified in [Manual Sale](/apis/payments-platform-rest/openapi/transactions/manualsale) requests.
    Example: 198399

  - `result.transaction.responseCode` (string)
    Code indicating the Shift4 host response.
| Value | Description | Details |
|  --- | --- | --- |
| A | Approved | The card was successfully verified. |
| D | Declined | The card failed verification. |
| e | [Error](/guides/appendices/error-codes) | There is an error condition. |
| f | [AVS or CSC failure](/guides/response-handling/understanding-avs-and-csc-verification) | An AVS or CSC failure has occurred (credit card only). **Note: This value will only be returned if the [POSHANDLEAVSFAIL Api Option](/guides/appendices/api-options#poshandleavsfail) was sent in the request.** |
    Enum: "A", "D", "e", "f"

  - `result.transaction.avs` (object)

  - `result.transaction.avs.postalCodeVerified` (string)
    Identifies whether the ZIP/postal code was verified (‘Y’) or not (‘N’) in an AVS check with a processor.
    Enum: "Y", "N"

  - `result.transaction.avs.result` (string)
    Identifies the response code returned from an Address Verification System (AVS) check with a processor.
| Value | Description |
|  --- | --- |
| A | 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 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 | Street address did not match, but ZIP/postal code matched. |
| X | Street address and 9-digit ZIP/postal code matched. |
| Y | Street address and 5-digit ZIP code matched. |
| Z | Only the ZIP/postal code matched. |
| 1 | Cardholder name and ZIP match |
| 2 | Cardholder name, address, and ZIP match |
| 3 | Cardholder name, address match |
| 4 | Cardholder name matches |
| 5 | Cardholder name incorrect, ZIP matches |
| 6 | Cardholder name incorrect; address and ZIP match |
| 7 | Cardholder name incorrect; address matches |
| 8 | Cardholder name, address, and ZIP do not match |
    Enum: "A", "E", "G", "N", "R", "S", "U", "W", "X", "Y", "Z", "1", "2", "3", "4", "5", "6", "7", "8"

  - `result.transaction.avs.streetVerified` (string)
    Identifies whether the street number was verified (‘Y’) or not (‘N’) in an AVS check with a processor.
    Enum: "Y", "N"

  - `result.transaction.avs.valid` (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.
    Enum: "Y", "N"

  - `result.transaction.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 [Card On File Transactions](/guides/advanced-concepts/card-on-file-transactions) section for more information.

  - `result.transaction.cardOnFile.type` (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 card data to store on file.
| Value | Initiator | Recurring | 3D Secure | Description |
|  --- | --- | --- | --- | --- |
| S01 | Cardholder | No | Yes | Used when the initial transaction/card verification request is not for a recurring payment. |
| S02 | Cardholder | Yes | Yes | Used when the initial transaction/card verification request is for a recurring payment. Requires sending `cardOnFile.recurringFrequency` and `cardOnFile.recurringExpiry` |

Below is a table showing the valid values for uses cases where you already have a card on file and are using that existing card to process a transaction.
| Value | Initiator | Recurring | 3D Secure | Description |
|  --- | --- | --- | --- | --- |
| U01 | Cardholder | No | Yes | Unscheduled transaction using the card on file initiated by the cardholder |
| U02 | Merchant | No | No | Unscheduled transaction using the card on file initiated by the merchant |
| U03 | Merchant | Yes | No | Merchant initiated recurring payment using the card on file |
| U04 | Merchant | No | No | Identifies a transaction as a Reauthorization COF transaction. |
| U05 | Merchant | No | No | Identifies a transaction as a Resubmission COF transaction. Only certain merchant categories are able to send a resubmission, and it can only be done if the original authorization attempt was declined due to insufficient funds. |
| U06 | Merchant | No | No | Identifies a transaction as an Estimated Authorization COF transaction. |
| U07 | Merchant | No | No | Identifies a transaction as a Delayed Charges COF transaction. For example, a hotel might charge a customer for room damages after the guest has already checked out. |
| U08 | Merchant | No | No | Identifies a transaction as an Incremental COF transaction. For example, a hotel which authorized a customer’s card for one night at check-in might increase the authorization amount to cover two nights when the customer decides to extend their stay. Shift4 automatically detects this scenario and sends the appropriate value to the processor. |
| U09 | Merchant | No | No | Identifies a transaction as a No Show COF transaction. For example, a hotel might charge a customer who does not show up for a booked stay. |

See the [Card On File Transactions](/guides/advanced-concepts/card-on-file-transactions) section for additional details.
    Enum: "S01", "S02", "U01", "U02", "U03", "U04", "U05", "U06", "U07", "U08", "U09"

  - `result.transaction.cardOnFile.recurringExpiry` (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 field is required if it's the first recurring transaction (`cardOnFile.type = S02`). This field is not needed if the transaction is not recurring or if the transaction is a subsequent recurring transaction.**
    Example: 20250401

  - `result.transaction.cardOnFile.recurringFrequency` (string)
    Indicates the minimum number of days between authorizations.
**Conditional: 'This field is required if it's the first recurring transaction (`cardOnFile.type = S02`). This field is not needed if the transaction is not recurring or if the transaction is a subsequent recurring transaction.**
    Example: 15

  - `result.transaction.cardOnFile.transactionId` (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 on a card for the first time, they will receive a transactionId back in the response.  A month later, when the merchant wants to perform an additional Sale with the card on file, they would send a Sale request including the transactionId they received from the first sale.
**Conditional: Must be sent in subsequent COF requests if you are not processing with a Global Token Vault token. If using Global Token Vault tokens then this field is not required**
    Example: Z62537846172646

  - `result.transaction.cardOnFile.transactionLinkId` (string)
    A unique identifier assigned to each transaction to link related events throughout the transaction lifecycle, or to track the relationship between separate economically linked transactions. This field is supported for Mastercard brand only.
For example, if a merchant runs a Sale on a card for the first time, they will receive a transactionLinkId back in the response. A month later, when the merchant wants to perform an additional Sale with the card on file, they would send a Sale request including the transactionLinkId they received from the first sale.
**Conditional: Must be sent in subsequent COF requests if you are not processing with a Shift4 Token. If you are processing using a Shift4 Token, this field is not required.**
    Example: Z871868461726461879548

  - `result.server` (object)

  - `result.server.name` (string)
    The name of the server that processed the request.
    Example: TM01CE

  - `result.accountNameInquiry` (object)

  - `result.accountNameInquiry.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 |
|  --- | --- |
| E | Full name: match |
| A | First name: partial match, Last name: match |
| B | First name: no match, Last name: match |
| C | First name: match, Last name: partial match |
| D | First name: match, Last name: no match |
| F | First name: partial match, Last name: partial match |
| G | First name: no match, Last name: partial match |
| H | First name: partial match, Last name: no match |
| I | Last name: match |
| J | Last name: partial match |
| N | First name: no match, Last name: no matchorLast name: no match |
| U | Name match not performed |
    Enum: "E", "A", "B", "C", "D", "F", "G", "H", "I", "J", "N", "U"

## Response 400 fields (application/json):

  - `result` (array)

  - `result.error` (object)

  - `result.error.code` (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: This is currently only supported for European merchant processing.**
    Example: 64100

  - `result.error.severity` (string)
    Severity level of the error.
| Severity | Description |
|  --- | --- |
| Info | Action not required - Data input/formatting is incorrect |
| Error | Action may be required - Communication, timeout or network issue |
| Alert | Action required - System issue |
    Enum: "Info", "Error", "Alert"

  - `result.error.shortText` (string)
    Abbreviated error message that is always returned if an error condition exists
    Example: NOT IN CARDRANGE

  - `result.error.longText` (string)
    Extended error message that is returned if an error condition exists.
    Example: Card type not recognized

  - `result.error.primaryCode` (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.
    Example: 9842

  - `result.error.secondaryCode` (integer)
    This code supplements the code specified in the `error.primaryCode` field to provide additional information about the error that occurred.
    Example: 0

  - `result.lighthouse` (object)

  - `result.lighthouse.data` (string)
    Base64 encoded JSON formatted data that will be returned from Lighthouse to be passed back to SkyTab. This data will contain variable information.
    Example: eyJwYXltZW50SWQiOiI4NWM0MWNhNy01NzVjLTQzNGUtODIyZi0xYzZlOTE0ZDAzODYiLCJyZW1haW5pbmdBbW91bnQiOjB9

  - `result.server` (object)

  - `result.server.name` (string)
    The name of the server that processed the request.
    Example: TM01CE

## Response 504 fields (application/json):

  - `result` (array)

  - `result.error` (object)

  - `result.error.code` (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: This is currently only supported for European merchant processing.**
    Example: 64100

  - `result.error.severity` (string)
    Severity level of the error.
| Severity | Description |
|  --- | --- |
| Info | Action not required - Data input/formatting is incorrect |
| Error | Action may be required - Communication, timeout or network issue |
| Alert | Action required - System issue |
    Enum: "Info", "Error", "Alert"

  - `result.error.shortText` (string)
    Abbreviated error message that is always returned if an error condition exists
    Example: NOT IN CARDRANGE

  - `result.error.longText` (string)
    Extended error message that is returned if an error condition exists.
    Example: Card type not recognized

  - `result.error.primaryCode` (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.
    Example: 9842

  - `result.error.secondaryCode` (integer)
    This code supplements the code specified in the `error.primaryCode` field to provide additional information about the error that occurred.
    Example: 0

  - `result.lighthouse` (object)

  - `result.lighthouse.data` (string)
    Base64 encoded JSON formatted data that will be returned from Lighthouse to be passed back to SkyTab. This data will contain variable information.
    Example: eyJwYXltZW50SWQiOiI4NWM0MWNhNy01NzVjLTQzNGUtODIyZi0xYzZlOTE0ZDAzODYiLCJyZW1haW5pbmdBbW91bnQiOjB9

  - `result.server` (object)

  - `result.server.name` (string)
    The name of the server that processed the request.
    Example: TM01CE