--- title: "TokenStore Add" method: POST path: "/tokens/add" tags: ["Tokens"] --- # TokenStore Add `POST /tokens/add` This function requests that CHD be added to the Global Token Vault and that a card token be returned for future use. This function cannot be used for EMV processing. **Integration Methods:** - Host Direct - Locally Installed UTG - Commerce Engine For On Premise - Commerce Engine For Cloud 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. ## Headers - `InterfaceVersion` string, required - `InterfaceName` string, required - `CompanyName` string, required - `AccessToken` string, uuid, required ## Request body - union - TokensAddComengdevice - `apiOptions` string[] — API Options modify the request being made. See the [API Options](/guides/appendices/api-options.md) section for more information. - `customer` Customer - `addressLine1` string — Cardholder’s street address exactly as it appears on their billing statement. This field is used in AVS. - `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. - `middleName` string — Specifies a consumer’s middle name. - `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. - `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** - `emailAddress` string — Customer email address. - `ipAddress` string — Public source IP Address where the request originates, not the IP Address of the web server. - `dateTime` string, ISO 8601, 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 - `device` object - `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. - `ui` object - `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. - `mode` 'light' | 'dark' — Set the UI to light mode by sending `light` or dark mode by sending `dark` - `suppressFinalResult` boolean — When `true`, the terminal suppresses the final transaction result screen. - TokensAddComengcloud - `apiOptions` string[] — API Options modify the request being made. See the [API Options](/guides/appendices/api-options.md) section for more information. - `customer` Customer - `addressLine1` string — Cardholder’s street address exactly as it appears on their billing statement. This field is used in AVS. - `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. - `middleName` string — Specifies a consumer’s middle name. - `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. - `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** - `emailAddress` string — Customer email address. - `ipAddress` string — Public source IP Address where the request originates, not the IP Address of the web server. - `dateTime` string, ISO 8601, 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 - `device` DeviceCommerceEngineCloud, required - `cloud` boolean, required — 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. - `manufacturer` 'Ingenico' | 'Innowi' | 'PAX' | 'Verifone' | 'Castles' | 'Miura', required — Specifies the company which manufactured the device. - `serialNumber` string, required — Specifies the serial number of the device. - `ui` object - `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. - `mode` 'light' | 'dark' — Set the UI to light mode by sending `light` or dark mode by sending `dark` - `suppressFinalResult` boolean — When `true`, the terminal suppresses the final transaction result screen. - TokensAddUtgdevice - `apiOptions` string[] — API Options modify the request being made. See the [API Options](/guides/appendices/api-options.md) section for more information. - `customer` Customer - `addressLine1` string — Cardholder’s street address exactly as it appears on their billing statement. This field is used in AVS. - `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. - `middleName` string — Specifies a consumer’s middle name. - `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. - `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** - `emailAddress` string — Customer email address. - `ipAddress` string — Public source IP Address where the request originates, not the IP Address of the web server. - `dateTime` string, ISO 8601, 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 - `device` object, required - `terminalId` string, required — 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. - `promptPostalCode` 'Y' | 'N' — 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.** - `promptCardSecurityCode` 'Y' | 'N' — 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.** - `promptStreetNumber` 'Y' | 'N' — 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.** - TokensAddP2peIdtech - `dateTime` string, ISO 8601, 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 - `p2pe` P2PEType0102IDTECH, required - `data` string, required — The full output of a P2PE keypad/magnetic swipe reader (MSR). - `format` '01' | '02', 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) - `apiOptions` string[] — API Options modify the request being made. See the [API Options](/guides/appendices/api-options.md) section for more information. - `customer` Customer - `addressLine1` string — Cardholder’s street address exactly as it appears on their billing statement. This field is used in AVS. - `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. - `middleName` string — Specifies a consumer’s middle name. - `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. - `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** - `emailAddress` string — Customer email address. - `ipAddress` string — Public source IP Address where the request originates, not the IP Address of the web server. - TokensAddP2peTdesdukptEmv - `dateTime` string, ISO 8601, 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 - `device` object, required - `manufacturer` 'Ingenico' | 'Innowi' | 'PAX' | 'Verifone' | 'Castles' | 'Miura', required — Specifies the company which manufactured the device. - `model` string, required — **Conditional: Required when using a non-UTG-controlled device.** Specifies the model of the device. - `serialNumber` string, required — Specifies the serial number of the device. - `capability` DeviceCapability, required — **Conditional: Required when using a non-UTG-controlled device.** - `contactlessEMV` 'Y' | 'N' — 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. - `contactlessMSR` 'Y' | 'N' — 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. - `EMV` 'Y' | 'N' — 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. - `manualEntry` 'Y' | 'N' — 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. - `magstripe` 'Y' | 'N' — 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. - `PIN` 'Y' | 'N' — 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. - `quickChip` 'Y' | 'N' — 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. - `signature` 'Y' | 'N' — 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. - `emv` EMV, required — **Conditional: Required when processing an EMV transaction without using a UTG.** - `emptyCandidateList` 'Y' | 'N' — When EMV is attempted but fallback occurs due to an empty candidate list, this field should be sent as 'Y' and `emv.fallback` should also be sent as 'Y'. If this field is not sent, a value of 'N' is assumed. - `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 - `p2pe` P2PEType05TDESDUKPTEMV, required — See [P2PE Format 05 TDES DUKPT](/guides/core-concepts/p2pe-format#tdes-dukpt---format-05) for more information. - `format` '05', 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) - `ksn` string, required — The key serial number which was used to encrypt the P2PE data. - `apiOptions` string[] — API Options modify the request being made. See the [API Options](/guides/appendices/api-options.md) section for more information. - `customer` Customer - `addressLine1` string — Cardholder’s street address exactly as it appears on their billing statement. This field is used in AVS. - `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. - `middleName` string — Specifies a consumer’s middle name. - `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. - `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** - `emailAddress` string — Customer email address. - `ipAddress` string — Public source IP Address where the request originates, not the IP Address of the web server. - TokensAddP2peTdesdukptMsr - `dateTime` string, ISO 8601, 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 - `device` object, required - `manufacturer` 'Ingenico' | 'Innowi' | 'PAX' | 'Verifone' | 'Castles' | 'Miura', required — Specifies the company which manufactured the device. - `model` string, required — **Conditional: Required when using a non-UTG-controlled device.** Specifies the model of the device. - `serialNumber` string, required — Specifies the serial number of the device. - `capability` DeviceCapability, required — **Conditional: Required when using a non-UTG-controlled device.** - `contactlessEMV` 'Y' | 'N' — 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. - `contactlessMSR` 'Y' | 'N' — 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. - `EMV` 'Y' | 'N' — 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. - `manualEntry` 'Y' | 'N' — 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. - `magstripe` 'Y' | 'N' — 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. - `PIN` 'Y' | 'N' — 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. - `quickChip` 'Y' | 'N' — 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. - `signature` 'Y' | 'N' — 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. - `p2pe` P2PEType05TDESDUKPTMSR, required — See [P2PE Format 05 TDES DUKPT](/guides/core-concepts/p2pe-format#tdes-dukpt---format-05) for more information. - `data` string, required — The full output of a P2PE keypad/magnetic swipe reader (MSR). - `format` '05', 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) - `ksn` string, required — The key serial number which was used to encrypt the P2PE data. - `apiOptions` string[] — API Options modify the request being made. See the [API Options](/guides/appendices/api-options.md) section for more information. - `customer` Customer - `addressLine1` string — Cardholder’s street address exactly as it appears on their billing statement. This field is used in AVS. - `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. - `middleName` string — Specifies a consumer’s middle name. - `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. - `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** - `emailAddress` string — Customer email address. - `ipAddress` string — Public source IP Address where the request originates, not the IP Address of the web server. - TokensAddP2peOnguardsdeEmv - `dateTime` string, ISO 8601, 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 - `device` object, required - `manufacturer` 'Ingenico' | 'Innowi' | 'PAX' | 'Verifone' | 'Castles' | 'Miura', required — Specifies the company which manufactured the device. - `model` string, required — **Conditional: Required when using a non-UTG-controlled device.** Specifies the model of the device. - `serialNumber` string, required — Specifies the serial number of the device. - `capability` DeviceCapability, required — **Conditional: Required when using a non-UTG-controlled device.** - `contactlessEMV` 'Y' | 'N' — 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. - `contactlessMSR` 'Y' | 'N' — 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. - `EMV` 'Y' | 'N' — 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. - `manualEntry` 'Y' | 'N' — 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. - `magstripe` 'Y' | 'N' — 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. - `PIN` 'Y' | 'N' — 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. - `quickChip` 'Y' | 'N' — 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. - `signature` 'Y' | 'N' — 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. - `p2pe` P2PEType03OnguardSDEEMV, required — See [P2PE Format 03 Ingenico On-Guard SDE](/guides/core-concepts/p2pe-format#ingenico-on-guard-sde---format-03) for more information. - `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` - `format` '03', required — Classifies the type of payment device being used for P2PE. Value|Description -----|----------- 03 | Ingenico Onguard SDE Format - `emv` EMVOnguardSDE, required — **Conditional: Required when processing an EMV transaction without using a UTG.** - `emptyCandidateList` 'Y' | 'N' — When EMV is attempted but fallback occurs due to an empty candidate list, this field should be sent as 'Y' and `emv.fallback` should also be sent as 'Y'. If this field is not sent, a value of 'N' is assumed. - `tlvData` string, required — 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. - `apiOptions` string[] — API Options modify the request being made. See the [API Options](/guides/appendices/api-options.md) section for more information. - `customer` Customer - `addressLine1` string — Cardholder’s street address exactly as it appears on their billing statement. This field is used in AVS. - `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. - `middleName` string — Specifies a consumer’s middle name. - `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. - `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** - `emailAddress` string — Customer email address. - `ipAddress` string — Public source IP Address where the request originates, not the IP Address of the web server. - TokensAddP2peOnguardsdeMsr - `dateTime` string, ISO 8601, 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 - `device` object, required - `manufacturer` 'Ingenico' | 'Innowi' | 'PAX' | 'Verifone' | 'Castles' | 'Miura', required — Specifies the company which manufactured the device. - `model` string, required — **Conditional: Required when using a non-UTG-controlled device.** Specifies the model of the device. - `serialNumber` string, required — Specifies the serial number of the device. - `capability` DeviceCapability, required — **Conditional: Required when using a non-UTG-controlled device.** - `contactlessEMV` 'Y' | 'N' — 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. - `contactlessMSR` 'Y' | 'N' — 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. - `EMV` 'Y' | 'N' — 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. - `manualEntry` 'Y' | 'N' — 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. - `magstripe` 'Y' | 'N' — 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. - `PIN` 'Y' | 'N' — 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. - `quickChip` 'Y' | 'N' — 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. - `signature` 'Y' | 'N' — 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. - `p2pe` P2PEType03OnguardSDEMSR, required — See [P2PE Format 03 Ingenico On-Guard SDE](/guides/core-concepts/p2pe-format#ingenico-on-guard-sde---format-03) for more information. - `data` string, required — Track information encrypted with AES 256 DUKPT. Contains the following information, separated by colons: |Value | Description |----------------|------------ |ksn | The key serial number (24 byte hex) |track indicator | `1` = track 1 only
`2` = track 2 only
`3` = manual entry
`4` = dual track
|length | The length of the encrypted data |encrypted data | Encrypted track/manual entry data Dual Track Example: `FFFF495A0000000200000005:4:0128:F48C880DE0DAF549E642C5CC25E65ADF9947E7EB0636DB80C4A490B4C0930AEF64B7201505343CED533A2AE9AFABFE6453875F705519A8109362197CA3BD8DA0FE90DB3F954B9CDA0DB58BDA3330862ADD28CB31EFDA7C641575E33D395D8BFF72EBF0B1FF9630DB0EAB080FE8C9B2FAC28127CDC48CA9F7D532D5BDE4CCE270` Manual entry Example: `FFFF495A0000000200000006:3:0032:E394820DB97AF927B9B5E05F356750BBF5DFCCB3BC18B87E8FC3C9BC596229E7` - `format` '03', required — Classifies the type of payment device being used for P2PE. Value|Description -----|----------- 03 | Ingenico Onguard SDE Format - `apiOptions` string[] — API Options modify the request being made. See the [API Options](/guides/appendices/api-options.md) section for more information. - `customer` Customer - `addressLine1` string — Cardholder’s street address exactly as it appears on their billing statement. This field is used in AVS. - `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. - `middleName` string — Specifies a consumer’s middle name. - `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. - `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** - `emailAddress` string — Customer email address. - `ipAddress` string — Public source IP Address where the request originates, not the IP Address of the web server. - TokensAddP2peAesMce - `card` object, required - `entryMode` 'M', required — The method used to capture a payment card. Value|Description -----|----------- M | Manual Entry - `dateTime` string, ISO 8601, 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 - `p2pe` P2PEType07AESMCE, required - `data` string, required — Manual card entry information encrypted with AES 128. The decrypted information must be in the following format: `pan=|exp=|cvv=` |Value | Description |----------------|------------ |pan | Credit card number |exp | Expiration date in MMYY format |cvv | Card security code (optional) The unencrypted data must be padded with \x00 to be a muliple of 16 before encrypting. Example: `pan=4761730000000011|exp=1226\x00\x00\x00` - `format` '07', required — Classifies the type of payment device being used for P2PE. Value|Description -----|----------- 07 | AES-128 or AES-256 - `kid` string, required — The key identifier for the key that was used to encrypt the P2PE data. **Note: The encryption key will be exchanged manually per customer.** - `apiOptions` string[] — API Options modify the request being made. See the [API Options](/guides/appendices/api-options.md) section for more information. - `customer` Customer - `addressLine1` string — Cardholder’s street address exactly as it appears on their billing statement. This field is used in AVS. - `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. - `middleName` string — Specifies a consumer’s middle name. - `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. - `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** - `emailAddress` string — Customer email address. - `ipAddress` string — Public source IP Address where the request originates, not the IP Address of the web server. - TokensAddUnencryptedcard - `dateTime` string, ISO 8601, 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 - `card` object, required - `number` string, required — The payment card number entered in an initial authorization/sale request. This field will always be masked when returned in a response. - `expirationDate` integer, required — **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. - `securityCode` object - `indicator` '0' | '1' | '2' | '9' — 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. - `value` string — The three- or four-digit Card Security Code found on a payment card. This value should only be sent in an initial sale/authorization request. It should not be stored by the interface. When sending `card.securityCode.value`, `card.securityCode.indicator` must also be sent. - `apiOptions` string[] — API Options modify the request being made. See the [API Options](/guides/appendices/api-options.md) section for more information. - `customer` object - `addressLine1` string — Cardholder’s street address exactly as it appears on their billing statement. This field is used in AVS. - `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. - `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. - `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** - TokensAddAch - `dateTime` string, ISO 8601, 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 - `ach` object, required - `accountNumber` string, required — Bank Account Number. Do not include any dashes, spaces, or additional zeros. - `routingNumber` string, required — The routing number identifying the bank. - `accountType` string, required — Bank account type Value | Description ------|--------------- PC | Personal Checking PS | Personal Savings CC | Corporate Checking CS | Corporate Savings - `accountHolderName` string, required — ACH account holder's name - `accountVerified` boolean, required — Send as `true` if the ACH account was verified through a 3rd party. - `verificationType` 'P' | 'M' | 'B', required — The type of verification used to validate the account. Value | Description ------|--------------- P | Prenotification M | Micro Deposits B | Bank Login ## Response `200` Request was processed - union - TokensAddResponseCard - `result` object[] - `dateTime` string, ISO 8601 — 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 - `card` object - `entryMode` '1' | '2' | 'C' | 'E' | 'M' | 'Q' | 'R' — **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** The method used to capture a payment card in an authorization/sale request. Value|Description -----|----------- 1 | Track 1 Only or Dual Track (Track 1 & 2) 2 | Track 2 Only C | EMV Contactless via card or mobile wallet E | EMV Chip M | Manual Entry Q | QR Code R | Contactless MSD - `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. - `number` string — The card number field will always be masked when returned in a response. - `type` 'AX' | 'AP' | 'BC' | 'CI' | 'DB' | 'GC' | 'JC' | 'MC' | 'NS' | 'PL' | 'SC' | 'VS' | 'WP' | 'YC' — 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 - `token` CardTokenResponse - `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. - `customer` Customer - `addressLine1` string — Cardholder’s street address exactly as it appears on their billing statement. This field is used in AVS. - `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. - `middleName` string — Specifies a consumer’s middle name. - `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. - `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** - `emailAddress` string — Customer email address. - `ipAddress` string — Public source IP Address where the request originates, not the IP Address of the web server. - `device` DeviceOnlyTIDResponse - `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. - `merchant` MerchantResponse - `mid` number — The merchant ID associated with the merchant account. - `name` string — The merchant’s business name as configured with Shift4. - `server` Server - `name` string — The name of the server that processed the request. - `universalToken` UniversalToken - `value` string — An identifier for a card or payment account across all Shift4 merchants. - TokensAddResponseAch - `result` object[] - `dateTime` string, ISO 8601 — 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 - `merchant` MerchantResponse - `mid` number — The merchant ID associated with the merchant account. - `name` string — The merchant’s business name as configured with Shift4. - `token` TokenACH - `value` string, required — The token representing the customer's bank account credentials. - `type` 'ACH' — Specifies the type of token. Value = `ACH` - `server` Server - `name` string — The name of the server that processed the request. ## Other responses - `400` — Error - `504` — Timeout --- [API](https://skmtc.dev/shift4/apis/shift4-payment-api.md) · [All operations](https://skmtc.dev/shift4/apis/shift4-payment-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/shift4/shift4-payment-api/revisions/2f85c87cc9e5/schema)