openapi: 3.2.0 info: version: 1.7.57 title: Shift4 Payment Cards API contact: url: https://www.shift4.com/contact-us/ servers: - url: https://api.shift4test.com/api/rest/v1 description: Host Direct Test URL - url: https://api.shift4api.net/api/rest/v1 description: Host Direct Production URL tags: - name: Cards paths: /cards/verify: servers: - url: https://api.shift4test.com/api/rest/v1 description: Host Direct Test URL - url: https://api.shift4api.net/api/rest/v1 description: Host Direct Production URL - url: https://192.168.1.10:277/api/rest/v1 description: Locally Installed UTG URL - url: https://192.168.1.20:8085/api/rest/v1 post: tags: - Cards summary: Verify Card with Processor operationId: cardsverify security: - AccessToken: [] description: '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. ' parameters: - $ref: '#/components/parameters/InterfaceVersion' - $ref: '#/components/parameters/InterfaceName' - $ref: '#/components/parameters/CompanyName' - $ref: '#/components/parameters/AccessToken' requestBody: required: true content: application/json: schema: oneOf: - $ref: '#/components/schemas/cards_verify_comengdevice' - $ref: '#/components/schemas/cards_verify_comengcloud' - $ref: '#/components/schemas/cards_verify_utgdevice' - $ref: '#/components/schemas/cards_verify_token_gtv' - $ref: '#/components/schemas/cards_verify_token_legacy' - $ref: '#/components/schemas/cards_verify_p2pe_idtech' - $ref: '#/components/schemas/cards_verify_p2pe_tdesdukpt_emv' - $ref: '#/components/schemas/cards_verify_p2pe_tdesdukpt_msr' - $ref: '#/components/schemas/cards_verify_p2pe_onguardsde_emv' - $ref: '#/components/schemas/cards_verify_p2pe_onguardsde_msr' - $ref: '#/components/schemas/cards_verify_unencryptedcard' responses: '200': description: Request was processed content: application/json: schema: properties: result: type: array items: type: object properties: dateTime: $ref: '#/components/schemas/DateTime' customer: $ref: '#/components/schemas/Customer' card: type: object properties: expirationDate: $ref: '#/components/schemas/CardExpirationDateResponse' number: $ref: '#/components/schemas/CardMaskedNumber' type: $ref: '#/components/schemas/CardTypeResp' securityCode: $ref: '#/components/schemas/CardSecurityCode' token: $ref: '#/components/schemas/CardTokenResponse' device: $ref: '#/components/schemas/DeviceOnlyTIDResponse' merchant: $ref: '#/components/schemas/MerchantResponse' transaction: type: object properties: authorizationCode: $ref: '#/components/schemas/TransactionAuthorizationCode' responseCode: $ref: '#/components/schemas/TransactionResponseCodeCardsVerify' avs: $ref: '#/components/schemas/AVS' cardOnFile: $ref: '#/components/schemas/CardOnFile' server: $ref: '#/components/schemas/Server' accountNameInquiry: $ref: '#/components/schemas/AccountNameInquiryResponse' '400': $ref: '#/components/responses/ErrorResponse' '504': $ref: '#/components/responses/TimeoutResponse' /cards/identify: servers: - url: https://api.shift4test.com/api/rest/v1 description: Host Direct Test URL - url: https://api.shift4api.net/api/rest/v1 description: Host Direct Production URL - url: https://192.168.1.10:277/api/rest/v1 description: Locally Installed UTG URL - url: https://192.168.1.20:8085/api/rest/v1 post: tags: - Cards summary: Identify Card Type operationId: cardsidentify security: - AccessToken: [] description: "This function is used to request and return the card type.\n\n**Integration Methods:**\n- Host Direct\n- Locally Installed UTG\n\nSee 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.\n\nSee the [JSON Body Schemas](/guides/quickstart#json-body-schemas) for more details on the various JSON body formats. \n" parameters: - $ref: '#/components/parameters/InterfaceVersion' - $ref: '#/components/parameters/InterfaceName' - $ref: '#/components/parameters/CompanyName' - $ref: '#/components/parameters/AccessToken' requestBody: required: true content: application/json: schema: oneOf: - $ref: '#/components/schemas/cards_identify_utgdevice' - $ref: '#/components/schemas/cards_identify_token_gtv' - $ref: '#/components/schemas/cards_identify_token_legacy' - $ref: '#/components/schemas/cards_identify_p2pe_idtech' - $ref: '#/components/schemas/cards_identify_p2pe_tdesdukpt_emv' - $ref: '#/components/schemas/cards_identify_p2pe_tdesdukpt_msr' - $ref: '#/components/schemas/cards_identify_p2pe_onguardsde_emv' - $ref: '#/components/schemas/cards_identify_p2pe_onguardsde_msr' - $ref: '#/components/schemas/cards_identify_unencryptedcard' responses: '200': description: Request was processed content: application/json: schema: properties: result: type: array items: type: object properties: dateTime: $ref: '#/components/schemas/DateTime' card: $ref: '#/components/schemas/CardResponseIdentify' device: $ref: '#/components/schemas/DeviceOnlyTIDResponse' merchant: $ref: '#/components/schemas/MerchantResponse' server: $ref: '#/components/schemas/Server' '400': $ref: '#/components/responses/ErrorResponse' '504': $ref: '#/components/responses/TimeoutResponse' components: schemas: P2PEType0102IDTECH: type: object required: - data - format properties: data: $ref: '#/components/schemas/P2PEData' format: $ref: '#/components/schemas/P2PEFormatIDTech' cards_verify_p2pe_idtech: type: object title: P2PE - ID TECH - EMV/MSR/Manual required: - dateTime - p2pe properties: dateTime: $ref: '#/components/schemas/DateTime' p2pe: $ref: '#/components/schemas/P2PEType0102IDTECH' transaction: type: object properties: cardOnFile: $ref: '#/components/schemas/CardOnFile' purchaseCard: type: object properties: customerReference: $ref: '#/components/schemas/PurchaseCardCustomerReference' customer: $ref: '#/components/schemas/Customer' currencyCode: $ref: '#/components/schemas/CurrencyCode' apiOptions: $ref: '#/components/schemas/ApiOptions' example: dateTime: '2021-04-15T09:18:23.283-07:00' p2pe: data: 027101801F2D1E00939B%*432100******1119^VS/DUAL TRACK^2212******?*;432100******1119=2212******?*CECE3FCE7781142BEC8D0E267AE89F5D3C7E235BF1A70E637951E8D93003E5A2586C336CA4A3B31F6639B04005BB12A716D8BC4D3AB125C27AB11A9DDC02816569D42A20B036EE5E2C71CB70565FB43B000000000000000000000000000000000000000000000000000000000000000000000000000000003434345434363138343962994950010038200415953903 format: '01' CustomerPostalCode: type: string minLength: 1 maxLength: 9 example: '65144' description: '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** ' AVSPostalCodeVerified: type: string minLength: 1 maxLength: 1 example: Y enum: - Y - N description: 'Identifies whether the ZIP/postal code was verified (‘Y’) or not (‘N’) in an AVS check with a processor. ' DeviceCapability: type: object writeOnly: true description: '**Conditional: Required when using a non-UTG-controlled device.** ' properties: contactlessEMV: $ref: '#/components/schemas/DeviceCapabilityContactlessEMV' contactlessMSR: $ref: '#/components/schemas/DeviceCapabilityContactlessMSR' EMV: $ref: '#/components/schemas/DeviceCapabilityEMV' manualEntry: $ref: '#/components/schemas/DeviceCapabilityManualEntry' magstripe: $ref: '#/components/schemas/DeviceCapabilityMagstripe' PIN: $ref: '#/components/schemas/DeviceCapabilityPIN' quickChip: $ref: '#/components/schemas/DeviceCapabilityQuickChip' signature: $ref: '#/components/schemas/DeviceCapabilitySignature' cards_verify_comengdevice: type: object title: Commerce Engine For On Premise required: - dateTime properties: dateTime: $ref: '#/components/schemas/DateTime' device: type: object properties: terminalId: $ref: '#/components/schemas/DeviceTerminalId' transaction: type: object properties: cardOnFile: $ref: '#/components/schemas/CardOnFile' purchaseCard: type: object properties: customerReference: $ref: '#/components/schemas/PurchaseCardCustomerReference' customer: $ref: '#/components/schemas/Customer' currencyCode: $ref: '#/components/schemas/CurrencyCode' apiOptions: $ref: '#/components/schemas/ApiOptions' ui: type: object properties: language: $ref: '#/components/schemas/UILanguageRequest' mode: $ref: '#/components/schemas/UIMode' suppressFinalResult: $ref: '#/components/schemas/UISuppressFinalResult' example: dateTime: '2025-11-06T09:18:23.283-07:00' CardBin: type: string readOnly: true maxLength: 8 example: '541333' description: 'The first 6 or 8 digits of the card. ' P2PEType03OnguardSDEMSR: type: object description: 'See [P2PE Format 03 Ingenico On-Guard SDE](/guides/core-concepts/p2pe-format#ingenico-on-guard-sde---format-03) for more information. ' required: - data - format properties: data: $ref: '#/components/schemas/P2PEDataOnguardSDEMSR' format: $ref: '#/components/schemas/P2PEFormatOnguardSDE' UISuppressFinalResult: type: boolean example: 'true' description: 'When `true`, the terminal suppresses the final transaction result screen. ' CardOnFile: type: object description: '**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. ' properties: type: $ref: '#/components/schemas/CardOnFileType' recurringExpiry: $ref: '#/components/schemas/CardOnFileRecurringExpiry' recurringFrequency: $ref: '#/components/schemas/CardOnFileRecurringFrequency' transactionId: $ref: '#/components/schemas/CardOnFileTransactionId' transactionLinkId: $ref: '#/components/schemas/CardOnFileTransactionLinkId' DevicePromptStreetNumber: type: string minLength: 1 maxLength: 1 enum: - Y - N example: Y description: '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 address. N | Do not force the PIN pad to prompt the consumer for the street number of their billing address. **Note: Use only when you want to override MCE (Manual Card Entry) settings in UTG.** ' Error: type: object properties: code: $ref: '#/components/schemas/ErrorCode' severity: $ref: '#/components/schemas/ErrorSeverity' shortText: $ref: '#/components/schemas/ErrorShortText' longText: $ref: '#/components/schemas/ErrorLongText' primaryCode: $ref: '#/components/schemas/ErrorPrimaryCode' secondaryCode: $ref: '#/components/schemas/ErrorSecondaryCode' CustomerAddressLine1: type: string maxLength: 30 example: 65 Easy St description: 'Cardholder’s street address exactly as it appears on their billing statement. This field is used in AVS. ' cards_verify_token_legacy: title: Legacy TrueToken type: object required: - dateTime - card properties: dateTime: $ref: '#/components/schemas/DateTime' card: type: object required: - token properties: token: $ref: '#/components/schemas/CardTokenRequiredLegacy' expirationDate: $ref: '#/components/schemas/CardExpirationDate' securityCode: $ref: '#/components/schemas/CardSecurityCode' transaction: type: object properties: cardOnFile: $ref: '#/components/schemas/CardOnFile' purchaseCard: type: object properties: customerReference: $ref: '#/components/schemas/PurchaseCardCustomerReference' customer: $ref: '#/components/schemas/Customer' currencyCode: $ref: '#/components/schemas/CurrencyCode' apiOptions: $ref: '#/components/schemas/ApiOptions' example: dateTime: '2021-04-15T09:18:23.283-07:00' card: token: value: 11191pn83hbkkety serialNumber: '123456' expirationDate: 1225 MerchantName: type: string maxLength: 22 example: Merchant XYZ description: 'The merchant’s business name as configured with Shift4. ' CardTokenSerialNumber: description: '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 specify the serial number for the account where the card token is stored. ' type: string maxLength: 10 example: '266' CustomerLastName: type: string maxLength: 30 example: Smith description: '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. ' cards_identify_p2pe_onguardsde_msr: title: P2PE - On-Guard SDE - MSR/Manual type: object allOf: - type: object required: - dateTime - card - device - p2pe properties: dateTime: $ref: '#/components/schemas/DateTime' card: type: object required: - entryMode properties: entryMode: $ref: '#/components/schemas/CardEntryMode' device: type: object required: - manufacturer - model - serialNumber - capability properties: manufacturer: $ref: '#/components/schemas/DeviceManufacturer' model: $ref: '#/components/schemas/DeviceModel' serialNumber: $ref: '#/components/schemas/DeviceSerialNumber' capability: $ref: '#/components/schemas/DeviceCapability' p2pe: $ref: '#/components/schemas/P2PEType03OnguardSDEMSR' example: dateTime: 2023-124-13T09:18:23.283-07:00 card: entryMode: '2' device: manufacturer: Ingenico model: Axium DX8000 serialNumber: 20ACCD801843 capability: contactlessEMV: Y contactlessMSR: N EMV: Y manualEntry: Y magstripe: Y PIN: Y quickChip: Y signature: Y p2pe: data: FFFF495A0000000200000005:4:0128:F48C880DE0DAF549E642C5CC25E65ADF9947E7EB0636DB80C4A490B4C0930AEF64B7201505343CED533A2AE9AFABFE6453875F705519A8109362197CA3BD8DA0FE90DB3F954B9CDA0DB58BDA3330862ADD28CB31EFDA7C641575E33D395D8BFF72EBF0B1FF9630DB0EAB080FE8C9B2FAC28127CDC48CA9F7D532D5BDE4CCE270 format: '03' ErrorSeverity: type: string enum: - Info - Error - Alert readOnly: true example: Info description: '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 | ' P2PEType05TDESDUKPTMSR: type: object description: 'See [P2PE Format 05 TDES DUKPT](/guides/core-concepts/p2pe-format#tdes-dukpt---format-05) for more information. ' required: - data - format - ksn properties: data: $ref: '#/components/schemas/P2PEData' format: $ref: '#/components/schemas/P2PEFormatType05' ksn: $ref: '#/components/schemas/P2PEKSN' CustomerMiddleName: type: string maxLength: 30 example: Andrew description: 'Specifies a consumer’s middle name. ' DeviceCapabilityManualEntry: type: string enum: - Y - N example: Y description: '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 all transactions on the device, then the value ''N'' should be sent. ' ApiOptions: type: array items: type: string example: - RETURNEXPDATE - ALLOWPARTIALAUTH writeOnly: true description: 'API Options modify the request being made. See the [API Options](/guides/appendices/api-options.md) section for more information. ' P2PEDataOnguardSDEEMV: type: string maxLength: 2048 example: FFFF495A0000000200000002:E:0032:E0AB94F7704E77AB37F81A7E236A1ABC1465C6DFCE43A506240D6E7D6DDA7EA9 description: "EMV TLV Data for tags 5A and 57 encrypted with AES 256 DUKPT. Contains the following information, separated by colons:\n \nValue | Description\n----------------|------------\nksn | The key serial number (24 byte hex)\ntrack indicator | `E` indicating EMV TLV Data\nlength | The length of the encrypted data\nencrypted data | Encrypted TLV containing tags 57 and 5A\n\nExample: `FFFF495A0000000200000002:E:0032:E0AB94F7704E77AB37F81A7E236A1ABC1465C6DFCE43A506240D6E7D6DDA7EA9`\n" Server: type: object readOnly: true properties: name: $ref: '#/components/schemas/ServerName' PurchaseCardCustomerReference: type: string maxLength: 25 example: D019D09309F2 description: '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. ' DeviceCapabilityPIN: type: string enum: - Y - N example: Y description: '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 currently disabled for all transactions on the device, then the value ''N'' should be sent. ' CardSecurityCodeIndicator: type: string minLength: 1 maxLength: 1 writeOnly: true example: '1' enum: - '0' - '1' - '2' - '9' description: '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. ' CardSecurityCode: type: object description: '**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.** ' required: - indicator - value properties: indicator: $ref: '#/components/schemas/CardSecurityCodeIndicator' result: $ref: '#/components/schemas/CardSecurityCodeResult' valid: $ref: '#/components/schemas/CardSecurityCodeValid' value: $ref: '#/components/schemas/CardSecurityCodeValue' MerchantMID: type: number maxLength: 10 example: 15877 description: 'The merchant ID associated with the merchant account. ' CustomerEmailAddress: type: string maxLength: 80 example: john.smith@email.com description: 'Customer email address. ' LighthouseResponse: type: object readOnly: true properties: data: $ref: '#/components/schemas/LighthouseDataResponse' ServerName: type: string maxLength: 50 example: TM01CE description: 'The name of the server that processed the request. ' cards_verify_unencryptedcard: type: object title: Card Number Unencrypted required: - dateTime - card properties: dateTime: $ref: '#/components/schemas/DateTime' card: type: object required: - number - expirationDate properties: number: $ref: '#/components/schemas/CardNumber' expirationDate: $ref: '#/components/schemas/CardExpirationDate' securityCode: type: object properties: indicator: $ref: '#/components/schemas/CardSecurityCodeIndicator' value: $ref: '#/components/schemas/CardSecurityCodeValue' transaction: type: object properties: cardOnFile: $ref: '#/components/schemas/CardOnFile' purchaseCard: type: object properties: customerReference: $ref: '#/components/schemas/PurchaseCardCustomerReference' customer: $ref: '#/components/schemas/Customer' currencyCode: $ref: '#/components/schemas/CurrencyCode' apiOptions: $ref: '#/components/schemas/ApiOptions' example: dateTime: '2021-04-15T09:18:23.283-07:00' card: number: '4321000000001119' expirationDate: 1230 securityCode: indicator: '1' value: '333' customer: addressLine1: 65 Easy St firstName: John lastName: Smith postalCode: '65144' cards_verify_utgdevice: type: object title: UTG Controlled Device required: - dateTime - device properties: dateTime: $ref: '#/components/schemas/DateTime' device: type: object required: - terminalId properties: terminalId: $ref: '#/components/schemas/DeviceTerminalId' promptPostalCode: $ref: '#/components/schemas/DevicePromptPostalCode' promptCardSecurityCode: $ref: '#/components/schemas/DevicePromptCardSecurityCode' promptStreetNumber: $ref: '#/components/schemas/DevicePromptStreetNumber' transaction: type: object properties: cardOnFile: $ref: '#/components/schemas/CardOnFile' purchaseCard: type: object properties: customerReference: $ref: '#/components/schemas/PurchaseCardCustomerReference' customer: $ref: '#/components/schemas/Customer' currencyCode: $ref: '#/components/schemas/CurrencyCode' apiOptions: $ref: '#/components/schemas/ApiOptions' example: dateTime: '2021-04-15T09:18:23.283-07:00' device: terminalId: '1742' cards_identify_utgdevice: type: object title: UTG Controlled Device allOf: - type: object required: - dateTime - device properties: dateTime: $ref: '#/components/schemas/DateTime' device: type: object required: - terminalId properties: terminalId: $ref: '#/components/schemas/DeviceTerminalId' promptPostalCode: $ref: '#/components/schemas/DevicePromptPostalCode' promptCardSecurityCode: $ref: '#/components/schemas/DevicePromptCardSecurityCode' promptStreetNumber: $ref: '#/components/schemas/DevicePromptStreetNumber' example: dateTime: '2021-04-15T09:18:23.283-07:00' device: terminalId: '1742' CardTypeResp: type: string enum: - AX - AP - BC - CI - DB - GC - JC - MC - NS - PL - SC - VS - WP - YC example: VS description: "An abbreviation used to specify the type of card that was used when processing a transaction.\n\nValue| Description\n-----|------------\nAX | American Express\nAP | Alipay\nBC | Backed Card \nCI | Citgo \nDB | Debit card\nGC | Gift Card\nJC | JCB\nMC | Mastercard\nNS | Discover/JCB/Novus\nPL | Private Label\nSC | Sears Canada\nVS | Visa\nWP | WeChat Pay\nYC | IT’S YOUR CARD\n" CustomerFirstName: type: string maxLength: 30 example: John description: '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. ' TransactionResponseCodeCardsVerify: type: string minLength: 1 maxLength: 1 readOnly: true example: A enum: - A - D - e - f description: "Code indicating the Shift4 host response. \n\nValue | Description | Details\n-------|------------------------------------------------------------------|--------\nA | Approved | The card was successfully verified.\nD | Declined | The card failed verification.\ne | [Error](/guides/appendices/error-codes) | There is an error condition.\nf | [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.**\n" DateTime: type: string format: ISO 8601 example: '2024-05-21T09:18:23.283-07:00' description: '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 ' ErrorLongText: type: string maxLength: 255 readOnly: true example: Card type not recognized description: 'Extended error message that is returned if an error condition exists. ' cards_verify_p2pe_tdesdukpt_msr: type: object title: P2PE - TDES DUKPT - MSR/Manual required: - dateTime - card - device - p2pe properties: dateTime: $ref: '#/components/schemas/DateTime' card: type: object required: - entryMode properties: entryMode: $ref: '#/components/schemas/CardEntryMode' device: type: object required: - manufacturer - model - serialNumber - capability properties: manufacturer: $ref: '#/components/schemas/DeviceManufacturer' model: $ref: '#/components/schemas/DeviceModel' serialNumber: $ref: '#/components/schemas/DeviceSerialNumber' capability: $ref: '#/components/schemas/DeviceCapability' p2pe: $ref: '#/components/schemas/P2PEType05TDESDUKPTMSR' transaction: type: object properties: cardOnFile: $ref: '#/components/schemas/CardOnFile' purchaseCard: type: object properties: customerReference: $ref: '#/components/schemas/PurchaseCardCustomerReference' customer: $ref: '#/components/schemas/Customer' currencyCode: $ref: '#/components/schemas/CurrencyCode' apiOptions: $ref: '#/components/schemas/ApiOptions' example: dateTime: '2021-04-15T09:18:23.283-07:00' card: entryMode: '2' device: manufacturer: PAX model: A930 serialNumber: '1170301234' capability: contactlessEMV: N contactlessMSR: Y EMV: Y magstripe: Y manualEntry: Y quickChip: Y p2pe: data: 44188C9A20DD2092254F7FEB0AABD531D86EA10DA37E5540C25B53658BA4FBB903828F835A7287481F6FB5C17A879ECC9768D4C12F99532A format: '05' ksn: FFFF49517300010000C9 DevicePromptCardSecurityCode: type: string minLength: 1 maxLength: 1 enum: - Y - N example: Y description: '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 to prompt the consumer for a CSC. **Note: Use only when you want to override MCE (Manual Card Entry) settings in UTG.** ' DeviceCapabilityMagstripe: type: string enum: - Y - N example: Y description: '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 transactions on the device, then the value ''N'' should be sent. ' P2PEType05TDESDUKPTEMV: type: object description: 'See [P2PE Format 05 TDES DUKPT](/guides/core-concepts/p2pe-format#tdes-dukpt---format-05) for more information. ' required: - format - ksn properties: format: $ref: '#/components/schemas/P2PEFormatType05' ksn: $ref: '#/components/schemas/P2PEKSN' DeviceCapabilityEMV: type: string enum: - Y - N example: Y description: '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 transactions on the device, then the value ''N'' should be sent. ' EMVTlvDataOnguardSDE: type: string writeOnly: true example: 4F07A0000000041010500A4D6173746572436172645F201A546573742F4361726420303920202020202020202020202020205F24032512315F25031511015F2D02656E5F3401018407A0000000041010950508200000009B02C8009F02060000000004449F03060000000000009F34031E03009F3704C5BF918D9F390105 description: '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: type: string minLength: 1 maxLength: 1 enum: - '1' - '2' - C - E - M - Q - R example: M description: "**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 Transaction Gateway® (UTG®)-controlled PIN pad, this field should be left blank or not sent in a request; the UTG will capture the card entry mode and return it in the response. When P2PE data is being sent from a non-UTG controlled device, this field is not needed**\n\nThe method used to capture a payment card in an authorization/sale request. \n\nValue|Description\n-----|-----------\n1 | Track 1 Only or Dual Track (Track 1 & 2)\n2 | Track 2 Only\nC | EMV Contactless via card or mobile wallet\nE | EMV Chip\nM | Manual Entry\nQ | QR Code\nR | Contactless MSD\n" CardSecurityCodeResult: type: string minLength: 1 maxLength: 1 readOnly: true example: M enum: - M - N - P - S - U - Y - '1' - '2' - '3' description: '**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. ' DevicePromptPostalCode: type: string minLength: 1 maxLength: 1 enum: - Y - N example: Y description: '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 the PIN pad to prompt the consumer for a ZIP/Postal Code. **Note: Use only when you want to override MCE (Manual Card Entry) settings in UTG.** ' ErrorCode: type: integer maxLength: 5 readOnly: true example: 64100 description: '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.** ' ErrorSecondaryCode: type: integer maxLength: 4 readOnly: true example: 0 description: 'This code supplements the code specified in the `error.primaryCode` field to provide additional information about the error that occurred. ' cards_identify_token_legacy: title: Legacy TrueToken type: object allOf: - type: object required: - dateTime - card properties: dateTime: $ref: '#/components/schemas/DateTime' card: type: object required: - token properties: token: $ref: '#/components/schemas/CardTokenRequiredLegacy' expirationDate: $ref: '#/components/schemas/CardExpirationDate' securityCode: $ref: '#/components/schemas/CardSecurityCode' example: dateTime: '2021-04-15T09:18:23.283-07:00' card: token: value: 11191pn83hbkkety serialNumber: '123456' expirationDate: 1225 cards_identify_p2pe_idtech: type: object title: P2PE - ID TECH - EMV/MSR/Manual required: - dateTime - p2pe properties: dateTime: $ref: '#/components/schemas/DateTime' p2pe: $ref: '#/components/schemas/P2PEType0102IDTECH' example: dateTime: '2021-04-15T09:18:23.283-07:00' p2pe: data: 027101801F2D1E00939B%*432100******1119^VS/DUAL TRACK^2212******?*;432100******1119=2212******?*CECE3FCE7781142BEC8D0E267AE89F5D3C7E235BF1A70E637951E8D93003E5A2586C336CA4A3B31F6639B04005BB12A716D8BC4D3AB125C27AB11A9DDC02816569D42A20B036EE5E2C71CB70565FB43B000000000000000000000000000000000000000000000000000000000000000000000000000000003434345434363138343962994950010038200415953903 format: '01' CardSecurityCodeValue: type: string maxLength: 4 writeOnly: true example: '333' description: '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. ' CardOnFileRecurringFrequency: type: string example: '15' minLength: 1 maxLength: 4 description: '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.** ' cards_verify_p2pe_onguardsde_msr: type: object title: P2PE - On-Guard SDE - MSR/Manual required: - dateTime - card - device - p2pe properties: dateTime: $ref: '#/components/schemas/DateTime' card: type: object required: - entryMode properties: entryMode: $ref: '#/components/schemas/CardEntryMode' device: type: object required: - manufacturer - model - serialNumber - capability properties: manufacturer: $ref: '#/components/schemas/DeviceManufacturer' model: $ref: '#/components/schemas/DeviceModel' serialNumber: $ref: '#/components/schemas/DeviceSerialNumber' capability: $ref: '#/components/schemas/DeviceCapability' p2pe: $ref: '#/components/schemas/P2PEType03OnguardSDEMSR' transaction: type: object properties: cardOnFile: $ref: '#/components/schemas/CardOnFile' purchaseCard: type: object properties: customerReference: $ref: '#/components/schemas/PurchaseCardCustomerReference' customer: $ref: '#/components/schemas/Customer' currencyCode: $ref: '#/components/schemas/CurrencyCode' apiOptions: $ref: '#/components/schemas/ApiOptions' example: dateTime: '2023-12-13T09:18:23.283-07:00' card: entryMode: '2' device: manufacturer: Ingenico model: Axium DX8000 serialNumber: 20ACCD801843 capability: contactlessEMV: Y contactlessMSR: N EMV: Y manualEntry: Y magstripe: Y PIN: Y quickChip: Y signature: Y p2pe: data: FFFF495A0000000200000005:4:0128:F48C880DE0DAF549E642C5CC25E65ADF9947E7EB0636DB80C4A490B4C0930AEF64B7201505343CED533A2AE9AFABFE6453875F705519A8109362197CA3BD8DA0FE90DB3F954B9CDA0DB58BDA3330862ADD28CB31EFDA7C641575E33D395D8BFF72EBF0B1FF9630DB0EAB080FE8C9B2FAC28127CDC48CA9F7D532D5BDE4CCE270 format: '03' cards_verify_comengcloud: type: object title: Commerce Engine For Cloud required: - dateTime - device properties: dateTime: $ref: '#/components/schemas/DateTime' device: type: object required: - cloud - manufacturer - serialNumber properties: cloud: $ref: '#/components/schemas/DeviceCloud' manufacturer: $ref: '#/components/schemas/DeviceManufacturer' serialNumber: $ref: '#/components/schemas/DeviceSerialNumber' transaction: type: object properties: cardOnFile: $ref: '#/components/schemas/CardOnFile' purchaseCard: type: object properties: customerReference: $ref: '#/components/schemas/PurchaseCardCustomerReference' customer: $ref: '#/components/schemas/Customer' currencyCode: $ref: '#/components/schemas/CurrencyCode' apiOptions: $ref: '#/components/schemas/ApiOptions' ui: type: object properties: language: $ref: '#/components/schemas/UILanguageRequest' mode: $ref: '#/components/schemas/UIMode' suppressFinalResult: $ref: '#/components/schemas/UISuppressFinalResult' example: dateTime: '2025-11-06T09:18:23.283-07:00' device: cloud: true manufacturer: PAX serialNumber: '1170301234' TransactionAuthorizationCode: type: string maxLength: 6 example: '198399' description: '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. ' AVSStreetVerified: type: string minLength: 1 maxLength: 1 example: Y enum: - Y - N description: 'Identifies whether the street number was verified (‘Y’) or not (‘N’) in an AVS check with a processor. ' cards_identify_token_gtv: title: GTV Token type: object allOf: - type: object required: - dateTime - card properties: dateTime: $ref: '#/components/schemas/DateTime' card: type: object required: - token properties: token: $ref: '#/components/schemas/CardTokenRequired' expirationDate: $ref: '#/components/schemas/CardExpirationDate' securityCode: $ref: '#/components/schemas/CardSecurityCode' example: dateTime: '2021-04-15T09:18:23.283-07:00' card: token: value: '8048471746471119' expirationDate: 1225 P2PEFormatType05: type: string minLength: 2 maxLength: 2 enum: - '05' example: '05' description: '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) ' CardOnFileTransactionLinkId: type: string maxLength: 22 example: Z871868461726461879548 description: 'A unique identifier assigned to each transaction to link related events throughout the transaction lifecycle. 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 Global Token Vault token. If using Global Token Vault tokens then this field is not required** ' DeviceTerminalIdRequired: type: string maxLength: 32 example: '1742' description: '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: type: string enum: - light - dark example: dark description: 'Set the UI to light mode by sending `light` or dark mode by sending `dark` ' cards_identify_p2pe_onguardsde_emv: title: P2PE - On-Guard SDE - EMV type: object allOf: - type: object required: - dateTime - card - device - emv - p2pe properties: dateTime: $ref: '#/components/schemas/DateTime' card: type: object required: - entryMode properties: entryMode: $ref: '#/components/schemas/CardEntryMode' device: type: object required: - manufacturer - model - serialNumber - capability properties: manufacturer: $ref: '#/components/schemas/DeviceManufacturer' model: $ref: '#/components/schemas/DeviceModel' serialNumber: $ref: '#/components/schemas/DeviceSerialNumber' capability: $ref: '#/components/schemas/DeviceCapability' p2pe: $ref: '#/components/schemas/P2PEType03OnguardSDEEMV' emv: type: object required: - tlvData properties: tlvData: $ref: '#/components/schemas/EMVTlvDataOnguardSDE' example: dateTime: '2023-12-13T09:18:23.283-07:00' card: entryMode: E device: manufacturer: Ingenico model: Axium DX8000 serialNumber: 20ACCD801843 capability: contactlessEMV: Y contactlessMSR: N EMV: Y manualEntry: Y magstripe: Y PIN: Y quickChip: Y signature: Y emv: tlvData: 9F40056000F0A0019F02060000000111009F03060000000000009F26088D24914341485DE14F07A00000000310109F0607A000000003101082021C009F360202929F34035E03009F2701809F3901059F3303E0F8C89F1A0208409F350122950580800080005F2A0208409A032107229B0268009F21031016209C01009F3704D2EAB1B55F2D02656E5F3401018407A00000000310109F100706010A03A0A0009F0D05B0508088009F0E0500000000009F0F05B0508098009F0702FF009F080200969F0902008C5F280208409F4104000000085F24032212319F1E083131373031373332 p2pe: data: FFFF495A0000000200000002:E:0032:E0AB94F7704E77AB37F81A7E236A1ABC1465C6DFCE43A506240D6E7D6DDA7EA9 format: '03' MerchantResponse: type: object properties: mid: $ref: '#/components/schemas/MerchantMID' name: $ref: '#/components/schemas/MerchantName' P2PEType03OnguardSDEEMV: type: object description: 'See [P2PE Format 03 Ingenico On-Guard SDE](/guides/core-concepts/p2pe-format#ingenico-on-guard-sde---format-03) for more information. ' required: - data - format properties: data: $ref: '#/components/schemas/P2PEDataOnguardSDEEMV' format: $ref: '#/components/schemas/P2PEFormatOnguardSDE' AVSValid: type: string minLength: 1 maxLength: 1 example: Y enum: - Y - N description: 'Simplified AVS result based on the merchant’s list of accepted responses as configured with Shift4: (‘Y’) if accepted or (‘N’) if not accepted. ' AVSResult: type: string minLength: 1 maxLength: 1 example: X enum: - A - E - G - N - R - S - U - W - X - Y - Z - '1' - '2' - '3' - '4' - '5' - '6' - '7' - '8' description: '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 ' CardTokenRequired: type: object required: - value properties: value: $ref: '#/components/schemas/CardTokenValue' DeviceSerialNumber: type: string maxLength: 64 example: '1170301234' description: 'Specifies the serial number of the device. ' cards_identify_p2pe_tdesdukpt_msr: title: P2PE - TDES DUKPT - MSR/Manual type: object allOf: - type: object required: - dateTime - card - device - p2pe properties: dateTime: $ref: '#/components/schemas/DateTime' card: type: object required: - entryMode properties: entryMode: $ref: '#/components/schemas/CardEntryMode' device: type: object required: - manufacturer - model - serialNumber - capability properties: manufacturer: $ref: '#/components/schemas/DeviceManufacturer' model: $ref: '#/components/schemas/DeviceModel' serialNumber: $ref: '#/components/schemas/DeviceSerialNumber' capability: $ref: '#/components/schemas/DeviceCapability' p2pe: $ref: '#/components/schemas/P2PEType05TDESDUKPTMSR' example: dateTime: '2021-04-15T09:18:23.283-07:00' card: entryMode: '2' device: manufacturer: PAX model: A930 serialNumber: '1170301234' capability: contactlessEMV: N contactlessMSR: Y EMV: Y magstripe: Y manualEntry: Y quickChip: Y p2pe: data: 44188C9A20DD2092254F7FEB0AABD531D86EA10DA37E5540C25B53658BA4FBB903828F835A7287481F6FB5C17A879ECC9768D4C12F99532A format: '05' ksn: FFFF49517300010000C9 ErrorPrimaryCode: type: integer maxLength: 4 readOnly: true example: 9842 description: 'Code indicating the type of error that occurred. Refer to the [Error Codes](/guides/appendices/error-codes) section of this document for more details. ' ANIResponseCode: type: string enum: - E - A - B - C - D - F - G - H - I - J - N - U example: E description: "Account Name Inquiry Response Code. Returned if the `USEANI` API Option and customer name information is sent in the request.\n\n| ANI Response Code | Description |\n| ----------------- | ---------------------------------------------------------------------- |\n| E | Full name: match |\n| A | First name: partial match, Last name: match |\n| B | First name: no match, Last name: match |\n| C | First name: match, Last name: partial match |\n| D | First name: match, Last name: no match |\n| F | First name: partial match, Last name: partial match |\n| G | First name: no match, Last name: partial match |\n| H | First name: partial match, Last name: no match |\n| I | Last name: match |\n| J | Last name: partial match |\n| N | First name: no match, Last name: no match
or
Last name: no match |\n| U | Name match not performed | \n" CardExpirationDate: type: integer minLength: 3 maxLength: 4 format: MMYY example: 1230 description: '**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. ' P2PEFormatIDTech: type: string minLength: 2 maxLength: 2 enum: - '01' - '02' example: '01' description: '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) ' DeviceModel: type: string maxLength: 50 example: A800 description: '**Conditional: Required when using a non-UTG-controlled device.** Specifies the model of the device. ' DeviceCapabilityQuickChip: type: string enum: - Y - N example: Y description: '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 all transactions on the device, then the value ''N'' should be sent. ' AVS: type: object readOnly: true properties: postalCodeVerified: $ref: '#/components/schemas/AVSPostalCodeVerified' result: $ref: '#/components/schemas/AVSResult' streetVerified: $ref: '#/components/schemas/AVSStreetVerified' valid: $ref: '#/components/schemas/AVSValid' CardTokenRequiredLegacy: type: object required: - value properties: value: $ref: '#/components/schemas/CardTokenValue' serialNumber: $ref: '#/components/schemas/CardTokenSerialNumber' AccountNameInquiryResponse: type: object properties: aniResponseCode: $ref: '#/components/schemas/ANIResponseCode' CardDebitCapable: type: string enum: - Y - N example: Y description: 'In BIN management, specifies whether a card can be processed as debit (‘Y’) or not (‘N’). ' CardLevelResultIdentify: type: string example: 1P description: 'In BIN management, specifies the detailed card type. For a complete list of potential values, see the [Card Level Results]/guides/appendices/card-level-results) section in this document''s appendix. ' Customer: type: object properties: addressLine1: $ref: '#/components/schemas/CustomerAddressLine1' firstName: $ref: '#/components/schemas/CustomerFirstName' middleName: $ref: '#/components/schemas/CustomerMiddleName' lastName: $ref: '#/components/schemas/CustomerLastName' postalCode: $ref: '#/components/schemas/CustomerPostalCode' emailAddress: $ref: '#/components/schemas/CustomerEmailAddress' ipAddress: $ref: '#/components/schemas/CustomerIpAddress' DeviceCapabilitySignature: type: string enum: - Y - N example: Y description: '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 for all transactions on the device, then the value ''N'' should be sent. ' CardOnFileRecurringExpiry: type: string example: '20250401' minLength: 8 maxLength: 8 description: '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.** ' DeviceOnlyTIDResponse: type: object properties: terminalId: $ref: '#/components/schemas/DeviceTerminalIdRequired' P2PEKSN: type: string maxLength: 20 example: 6299495001100E200041 description: 'The key serial number which was used to encrypt the P2PE data. ' cards_identify_p2pe_tdesdukpt_emv: title: P2PE - TDES DUKPT - EMV type: object required: - dateTime - card - device - emv - p2pe properties: dateTime: $ref: '#/components/schemas/DateTime' card: type: object required: - entryMode properties: entryMode: $ref: '#/components/schemas/CardEntryMode' device: type: object required: - manufacturer - model - serialNumber - capability properties: manufacturer: $ref: '#/components/schemas/DeviceManufacturer' model: $ref: '#/components/schemas/DeviceModel' serialNumber: $ref: '#/components/schemas/DeviceSerialNumber' capability: $ref: '#/components/schemas/DeviceCapability' emv: type: object required: - tlvData properties: tlvData: $ref: '#/components/schemas/EMVTlvData' p2pe: $ref: '#/components/schemas/P2PEType05TDESDUKPTEMV' example: dateTime: '2021-04-15T09:18:23.283-07:00' card: entryMode: E device: manufacturer: PAX model: A930 serialNumber: '1170301234' capability: contactlessEMV: N contactlessMSR: Y EMV: Y magstripe: Y manualEntry: Y quickChip: Y emv: tlvData: 4F07A0000000041010500A4D61737465724361726457203CCEB572BE7DD0A38E62E6BD70E3DAACE9B46BD3BF65E188E7D8D68D2178DE1A5A10B1794BAC083B08F0A1444F189A5493255F201A546573742F4361726420303920202020202020202020202020205F24032512315F25031511015F2D02656E5F3401018407A0000000041010950508200000009B02C8009F02060000000004449F03060000000000009F34031E03009F3704C5BF918D9F390105 p2pe: format: '05' ksn: 6299495001100E200041 cards_verify_p2pe_tdesdukpt_emv: type: object title: P2PE - TDES DUKPT - EMV required: - dateTime - card - device - emv - p2pe properties: dateTime: $ref: '#/components/schemas/DateTime' card: type: object required: - entryMode properties: entryMode: $ref: '#/components/schemas/CardEntryMode' device: type: object required: - manufacturer - model - serialNumber - capability properties: manufacturer: $ref: '#/components/schemas/DeviceManufacturer' model: $ref: '#/components/schemas/DeviceModel' serialNumber: $ref: '#/components/schemas/DeviceSerialNumber' capability: $ref: '#/components/schemas/DeviceCapability' emv: type: object required: - tlvData properties: tlvData: $ref: '#/components/schemas/EMVTlvData' p2pe: $ref: '#/components/schemas/P2PEType05TDESDUKPTEMV' transaction: type: object properties: cardOnFile: $ref: '#/components/schemas/CardOnFile' purchaseCard: type: object properties: customerReference: $ref: '#/components/schemas/PurchaseCardCustomerReference' customer: $ref: '#/components/schemas/Customer' currencyCode: $ref: '#/components/schemas/CurrencyCode' apiOptions: $ref: '#/components/schemas/ApiOptions' example: dateTime: '2021-04-15T09:18:23.283-07:00' card: entryMode: E device: manufacturer: PAX model: A930 serialNumber: '1170301234' capability: contactlessEMV: N contactlessMSR: Y EMV: Y magstripe: Y manualEntry: Y quickChip: Y emv: tlvData: 4F07A0000000041010500A4D61737465724361726457203CCEB572BE7DD0A38E62E6BD70E3DAACE9B46BD3BF65E188E7D8D68D2178DE1A5A10B1794BAC083B08F0A1444F189A5493255F201A546573742F4361726420303920202020202020202020202020205F24032512315F25031511015F2D02656E5F3401018407A0000000041010950508200000009B02C8009F02060000000004449F03060000000000009F34031E03009F3704C5BF918D9F390105 p2pe: format: '05' ksn: 6299495001100E200041 DeviceManufacturer: type: string enum: - Ingenico - Innowi - PAX - Verifone - Castles - Miura example: PAX description: 'Specifies the company which manufactured the device. ' CardNumber: type: string maxLength: 32 example: '4321000000001119' description: 'The payment card number entered in an initial authorization/sale request. This field will always be masked when returned in a response. ' CardTokenResponse: type: object properties: value: $ref: '#/components/schemas/CardTokenValue' CardExpirationDateResponse: type: integer minLength: 3 maxLength: 4 format: MMYY example: 1230 description: "**Conditional: Requires API Option \"RETURNEXPDATE\".**\n\nCard expiration date in MMYY format. This value will only be populated if \"RETURNEXPDATE\" is included in the `apiOptions` array. \n" P2PEFormatOnguardSDE: type: string minLength: 2 maxLength: 2 enum: - '03' example: '03' description: 'Classifies the type of payment device being used for P2PE. Value|Description -----|----------- 03 | Ingenico Onguard SDE Format ' CustomerIpAddress: type: string maxLength: 20 example: 63.57.84.101 description: 'Public source IP Address where the request originates, not the IP Address of the web server. ' DeviceCapabilityContactlessMSR: type: string enum: - Y - N example: Y description: '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 disabled for all transactions on the device, then the value ''N'' should be sent. ' CardResponseIdentify: type: object properties: bin: $ref: '#/components/schemas/CardBin' dccCapable: $ref: '#/components/schemas/CardDccCapable' debitCapable: $ref: '#/components/schemas/CardDebitCapable' levelResult: $ref: '#/components/schemas/CardLevelResultIdentify' type: $ref: '#/components/schemas/CardTypeResp' P2PEData: type: string maxLength: 2048 example: 027101801F2D1E00939B%*432100******1119^VS/DUAL TRACK^2212******?*;432100******1119=2212******?*CECE3FCE7781142BEC8D0E267AE89F5D3C7E235BF1A70E637951E8D93003E5A2586C336CA4A3B31F6639B04005BB12A716D8BC4D3AB125C27AB11A9DDC02816569D42A20B036EE5E2C71CB70565FB43B000000000000000000000000000000000000000000000000000000000000000000000000000000003434345434363138343962994950010038200415953903 description: 'The full output of a P2PE keypad/magnetic swipe reader (MSR). ' cards_verify_token_gtv: title: GTV Token type: object required: - dateTime - card properties: dateTime: $ref: '#/components/schemas/DateTime' card: type: object required: - token properties: token: $ref: '#/components/schemas/CardTokenRequired' expirationDate: $ref: '#/components/schemas/CardExpirationDate' securityCode: $ref: '#/components/schemas/CardSecurityCode' transaction: type: object properties: cardOnFile: $ref: '#/components/schemas/CardOnFile' purchaseCard: type: object properties: customerReference: $ref: '#/components/schemas/PurchaseCardCustomerReference' customer: $ref: '#/components/schemas/Customer' currencyCode: $ref: '#/components/schemas/CurrencyCode' apiOptions: $ref: '#/components/schemas/ApiOptions' example: dateTime: '2021-04-15T09:18:23.283-07:00' card: token: value: '8048471746471119' expirationDate: 1225 P2PEDataOnguardSDEMSR: type: string maxLength: 2048 example: FFFF495A0000000200000005:4:0128:F48C880DE0DAF549E642C5CC25E65ADF9947E7EB0636DB80C4A490B4C0930AEF64B7201505343CED533A2AE9AFABFE6453875F705519A8109362197CA3BD8DA0FE90DB3F954B9CDA0DB58BDA3330862ADD28CB31EFDA7C641575E33D395D8BFF72EBF0B1FF9630DB0EAB080FE8C9B2FAC28127CDC48CA9F7D532D5BDE4CCE270 description: "Track information encrypted with AES 256 DUKPT. Contains the following information, separated by colons:\n \n|Value | Description\n|----------------|------------\n|ksn | The key serial number (24 byte hex)\n|track indicator | `1` = track 1 only
`2` = track 2 only
`3` = manual entry
`4` = dual track
\n|length | The length of the encrypted data\n|encrypted data | Encrypted track/manual entry data\n\nDual Track Example: `FFFF495A0000000200000005:4:0128:F48C880DE0DAF549E642C5CC25E65ADF9947E7EB0636DB80C4A490B4C0930AEF64B7201505343CED533A2AE9AFABFE6453875F705519A8109362197CA3BD8DA0FE90DB3F954B9CDA0DB58BDA3330862ADD28CB31EFDA7C641575E33D395D8BFF72EBF0B1FF9630DB0EAB080FE8C9B2FAC28127CDC48CA9F7D532D5BDE4CCE270`\n\nManual entry Example: `FFFF495A0000000200000006:3:0032:E394820DB97AF927B9B5E05F356750BBF5DFCCB3BC18B87E8FC3C9BC596229E7`\n" UILanguageRequest: type: string example: en description: '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. ' cards_verify_p2pe_onguardsde_emv: type: object title: P2PE - On-Guard SDE - EMV required: - dateTime - card - device - emv - p2pe properties: dateTime: $ref: '#/components/schemas/DateTime' card: type: object required: - entryMode properties: entryMode: $ref: '#/components/schemas/CardEntryMode' device: type: object required: - manufacturer - model - serialNumber - capability properties: manufacturer: $ref: '#/components/schemas/DeviceManufacturer' model: $ref: '#/components/schemas/DeviceModel' serialNumber: $ref: '#/components/schemas/DeviceSerialNumber' capability: $ref: '#/components/schemas/DeviceCapability' p2pe: $ref: '#/components/schemas/P2PEType03OnguardSDEEMV' emv: type: object required: - tlvData properties: tlvData: $ref: '#/components/schemas/EMVTlvDataOnguardSDE' transaction: type: object properties: cardOnFile: $ref: '#/components/schemas/CardOnFile' purchaseCard: type: object properties: customerReference: $ref: '#/components/schemas/PurchaseCardCustomerReference' customer: $ref: '#/components/schemas/Customer' currencyCode: $ref: '#/components/schemas/CurrencyCode' apiOptions: $ref: '#/components/schemas/ApiOptions' example: dateTime: 2023-124-13T09:18:23.283-07:00 card: entryMode: E device: manufacturer: Ingenico model: Axium DX8000 serialNumber: 20ACCD801843 capability: contactlessEMV: Y contactlessMSR: N EMV: Y manualEntry: Y magstripe: Y PIN: Y quickChip: Y signature: Y emv: tlvData: 9F40056000F0A0019F02060000000111009F03060000000000009F26088D24914341485DE14F07A00000000310109F0607A000000003101082021C009F360202929F34035E03009F2701809F3901059F3303E0F8C89F1A0208409F350122950580800080005F2A0208409A032107229B0268009F21031016209C01009F3704D2EAB1B55F2D02656E5F3401018407A00000000310109F100706010A03A0A0009F0D05B0508088009F0E0500000000009F0F05B0508098009F0702FF009F080200969F0902008C5F280208409F4104000000085F24032212319F1E083131373031373332 p2pe: data: FFFF495A0000000200000002:E:0032:E0AB94F7704E77AB37F81A7E236A1ABC1465C6DFCE43A506240D6E7D6DDA7EA9 format: '03' cards_identify_unencryptedcard: type: object title: Card Number Unencrypted allOf: - type: object required: - dateTime - card properties: dateTime: $ref: '#/components/schemas/DateTime' card: type: object required: - number - expirationDate - entryMode properties: number: $ref: '#/components/schemas/CardNumber' expirationDate: $ref: '#/components/schemas/CardExpirationDate' entryMode: type: string minLength: 1 maxLength: 1 enum: - M example: M description: "**Conditional: The Card Entry Mode should be sent in an initial request; in subsequent requests, it should be left blank or not sent.**\n\nThe method used to capture a payment card in an authorization/sale request. \n\nValue|Description\n-----|-----------\nM | Manual Entry\n" securityCode: type: object properties: indicator: $ref: '#/components/schemas/CardSecurityCodeIndicator' value: $ref: '#/components/schemas/CardSecurityCodeValue' example: dateTime: '2021-04-15T09:18:23.283-07:00' card: number: '4321000000001119' expirationDate: 1230 securityCode: indicator: '1' value: '333' DeviceTerminalId: type: string maxLength: 32 example: '1742' description: 'To prompt a specific UTG-controlled PIN pad in a request, the API Terminal ID configured in UTG TuneUp must be specified in this field. ' CardOnFileType: type: string enum: - S01 - S02 - U01 - U02 - U03 - U04 - U05 - U06 - U07 - U08 - U09 example: S01 description: '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. ' CardOnFileTransactionId: type: string maxLength: 15 example: Z62537846172646 description: '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** ' CardMaskedNumber: type: string maxLength: 32 example: XXXXXXXXXXXX1119 description: 'The card number field will always be masked when returned in a response. ' ErrorShortText: type: string maxLength: 16 readOnly: true example: NOT IN CARDRANGE description: 'Abbreviated error message that is always returned if an error condition exists ' LighthouseDataResponse: type: string example: eyJwYXltZW50SWQiOiI4NWM0MWNhNy01NzVjLTQzNGUtODIyZi0xYzZlOTE0ZDAzODYiLCJyZW1haW5pbmdBbW91bnQiOjB9 description: 'Base64 encoded JSON formatted data that will be returned from Lighthouse to be passed back to SkyTab. This data will contain variable information. ' CardDccCapable: type: string enum: - Y - N example: Y description: 'In BIN management, specifies whether or not the card is dynamic currency conversion (DCC) capable. ' CardTokenValue: description: '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. ' type: string maxLength: 16 example: '8048471746471119' DeviceCapabilityContactlessEMV: type: string enum: - Y - N example: Y description: '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 for all transactions on the device, then the value ''N'' should be sent. ' EMVTlvData: type: string writeOnly: true example: 4F07A0000000041010500A4D61737465724361726457203CCEB572BE7DD0A38E62E6BD70E3DAACE9B46BD3BF65E188E7D8D68D2178DE1A5A10B1794BAC083B08F0A1444F189A5493255F201A546573742F4361726420303920202020202020202020202020205F24032512315F25031511015F2D02656E5F3401018407A0000000041010950508200000009B02C8009F02060000000004449F03060000000000009F34031E03009F3704C5BF918D9F390105 description: '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 ' DeviceCloud: type: boolean example: true description: '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 request to the payment device at the merchant location. ' CurrencyCode: type: string format: ISO 4217 3 Character Alphabetic Code example: USD description: '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.** ' CardSecurityCodeValid: type: string minLength: 1 maxLength: 1 readOnly: true example: Y description: '**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. ' parameters: AccessToken: required: true name: AccessToken in: header schema: type: string format: uuid maxLength: 52 example: EA79FB05-3AA7-4500-AF9A-73F986FF2C1D description: '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`. ' CompanyName: required: true name: CompanyName in: header schema: type: string maxLength: 26 example: PAWS description: '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: $ % : ^ - ~ ` < > , ? “ ” ‘ ’ { } [ ] \ + = ' InterfaceName: required: true name: InterfaceName in: header schema: type: string maxLength: 25 example: ForwardPOS description: '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: $ % : ^ - ~ ` < > , ? “ ” ‘ ’ { } [ ] \ + = ' InterfaceVersion: required: true name: InterfaceVersion in: header schema: type: string maxLength: 11 example: '2.1' description: 'Refers to the version of the program or application that is sending requests to Shift4. The following special characters are not allowed: $ % : ^ - ~ < > , ? “ ” ‘ ’ { } [ ] \ + = ' responses: TimeoutResponse: description: Timeout content: application/json: schema: properties: result: type: array items: type: object properties: error: $ref: '#/components/schemas/Error' lighthouse: type: object properties: data: $ref: '#/components/schemas/LighthouseDataResponse' server: $ref: '#/components/schemas/Server' example: result: - error: primaryCode: 9951 secondaryCode: 0 shortText: RESPONSE TIMEOUT longText: Timeout waiting for response across the internet lighthouse: data: eyJwYXltZW50SWQiOiI4NWM0MWNhNy01NzVjLTQzNGUtODIyZi0xYzZlOTE0ZDAzODYiLCJyZW1haW5pbmdBbW91bnQiOjB9 server: name: U2API01CE ErrorResponse: description: Error content: application/json: schema: properties: result: type: array items: type: object properties: error: $ref: '#/components/schemas/Error' lighthouse: $ref: '#/components/schemas/LighthouseResponse' server: $ref: '#/components/schemas/Server' example: result: - error: primaryCode: 9842 secondaryCode: 0 shortText: NOT IN CARDRANGE longText: Card type not recognized lighthouse: data: eyJwYXltZW50SWQiOiI4NWM0MWNhNy01NzVjLTQzNGUtODIyZi0xYzZlOTE0ZDAzODYiLCJyZW1haW5pbmdBbW91bnQiOjB9 server: name: U2API01CE securitySchemes: AccessToken: type: apiKey name: AccessToken in: header description: "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. \n\nExample:\n ```\n AccessToken: EA79FB05-3AA7-4500-AF9A-73F986FF2C1D\n ```\n" HMAC-SHA256: type: http scheme: hmac-sha256 description: "Authentication using HMAC-256 signatures as the authorization scheme.\n\nSent in the `Authorization` header in the following format:\n\n`Authorization`: **HMAC-SHA256** `Credential`={value}&`Signature`={value}\n\n| Argument | Description |\n|---------------|--------------------------------------------------|\n| HMAC-SHA256 | Authorization scheme. |\n| Credential | The ID of the key used to compute the signature. |\n| Signature | base64 encoded HMACSHA256 value. |\n\nExample: \n ```\n Authorization: HMAC-SHA256 Credential=AESKEY1&Signature=8SFtIc6zQlswxAZqDKXL+BpRmlDvIWyjOwU8wdl0zK4=\n ```\n"