# 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 API Option and must be sent in the request. and are optional. Account Name Inquiry requests are currently limited to Visa cards. - Host Direct - Locally Installed UTG See the Integration Methods and URLs Section sections of the Development Quick Start guide for details regarding each processing option. See the JSON Body Schemas for more details on the various JSON body formats. Endpoint: POST /cards/verify Version: 1.7.43 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: $ % : ^ - ~ , ? “ ” ‘ ’ { } [ ] \ + = Example: "2.1" - `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: $ % : ^ - ~ ` , ? “ ” ‘ ’ { } [ ] \ + = Example: "ForwardPOS" - `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: $ % : ^ - ~ ` , ? “ ” ‘ ’ { } [ ] \ + = Example: "PAWS" - `AccessToken` (string, required) A security credential used to authenticate API requests and all i4Go® authorizeClient/preauthorizeClient requests. An Access Token is the alias for the merchant account and interface being used. The Access Token is required in all requests except an Access Token Exchange request, which generates an Access Token using an and . Example: "EA79FB05-3AA7-4500-AF9A-73F986FF2C1D" ## 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 - `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. - `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 object, the consumer's name will be returned in the object if the name is present in the card's EMV or track data. - `result.customer.middleName` (string) Specifies a consumer’s middle name. - `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 object, the consumer's name will be returned in the object if the name is present in the card's EMV or track data. - `result.customer.postalCode` (string) Cardholder’s ZIP/postal code from their billing statement. This field is used in AVS. Do not include special characters. - `result.customer.emailAddress` (string) Customer email address. - `result.customer.ipAddress` (string) Public source IP Address where the request originates, not the IP Address of the web server. - `result.card` (object) - `result.card.expirationDate` (integer) Card expiration date in MMYY format. This value will only be populated if "RETURNEXPDATE" is included in the array. - `result.card.number` (string) The card number field will always be masked when returned in a response. - `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) - `result.card.securityCode.result` (string) The result of a CSC check. This field will be used by Shift4 to determine the value sent in the 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) A simplified CSC check result based on the value in the 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. - `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. - `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. - `result.merchant` (object) - `result.merchant.mid` (number) The merchant ID associated with the merchant account. - `result.merchant.name` (string) The merchant’s business name as configured with Shift4. - `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. - `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). 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) 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 and | 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. - `result.transaction.cardOnFile.recurringFrequency` (string) Indicates the minimum number of days between authorizations. - `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. - `result.server` (object) - `result.server.name` (string) The name of the server that processed the request. - `result.accountNameInquiry` (object) - `result.accountNameInquiry.aniResponseCode` (string) Account Name Inquiry Response Code. Returned if the 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) Example: [{"error":{"primaryCode":9842,"secondaryCode":0,"shortText":"NOT IN CARDRANGE","longText":"Card type not recognized"},"lighthouse":{"data":"eyJwYXltZW50SWQiOiI4NWM0MWNhNy01NzVjLTQzNGUtODIyZi0xYzZlOTE0ZDAzODYiLCJyZW1haW5pbmdBbW91bnQiOjB9"},"server":{"name":"U2API01CE"}}] - `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. - `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 - `result.error.longText` (string) Extended error message that is returned if an error condition exists. - `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. - `result.error.secondaryCode` (integer) This code supplements the code specified in the field to provide additional information about the error that occurred. - `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. - `result.server` (object) - `result.server.name` (string) The name of the server that processed the request. ## 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. - `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 - `result.error.longText` (string) Extended error message that is returned if an error condition exists. - `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. - `result.error.secondaryCode` (integer) This code supplements the code specified in the field to provide additional information about the error that occurred. - `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. - `result.server` (object) - `result.server.name` (string) The name of the server that processed the request.