# TokenStore 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.

Endpoint: POST /tokens/add
Version: 1.7.67
Security: AccessToken

## Header parameters:

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

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

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

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

## Request fields (application/json):

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

  - `customer` (object)

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

  - `customer.firstName` (string)
    Specifies a consumer’s first name. This field is used in AVS. If the interface sends this field, the value specified by the interface will be returned in the response, unless the API Option [USECARDNAME](/guides/appendices/api-options#usecardname) is included in the request and a Commerce Engine or UTG-controlled PIN pad is in use. If the interface does not send the `customer` object, the consumer's name will be returned in the `customer` object if the name is present in the card's EMV or track data.
    Example: John

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

  - `customer.lastName` (string)
    Specifies a consumer’s last name. This field is used in AVS. If the interface sends this field, the value specified by the interface will be returned in the response, unless the API Option [USECARDNAME](/guides/appendices/api-options#usecardname) is included in the request and a Commerce Engine or UTG-controlled PIN pad is in use. If the interface does not send the `customer` object, the consumer's name will be returned in the `customer` object if the name is present in the card's EMV or track data.
    Example: Smith

  - `customer.postalCode` (string)
    Cardholder’s ZIP/postal code from their billing statement. This field is used in AVS. Do not include special characters.
**Note: This field only allows alphanumeric characters (a-z, A-Z, 0-9). Special characters including - are not allowed. If you are sending in zip+4 you must not include the dash so 89134-1234 would be sent as 891341234**
    Example: 65144

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

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

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

  - `device` (object)

  - `device.terminalId` (string)
    To prompt a specific UTG-controlled PIN pad in a request, the API Terminal ID configured in UTG TuneUp must be specified in this field.
    Example: 1742

  - `ui` (object)

  - `ui.language` (string)
    ISO 639-1 2-letter language code specifying the UI display language for the transaction (e.g. "en", "fr", "de"). When provided, overrides the device's configured default language for the duration of the session. Value persists across transactions until a new value is passed. Send default to reset the device back to its default language.
    Example: en

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

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

  - `dateTime` (string, required)
    The date and time in ISO 8601 format including the timezone offset (yyyy-mm-ddThh:mm:ss.nnn+hh:mm).
Must be sent as the local date/time of the merchant. For example, a request processed at a merchant in the Pacific time zone at 9:18am on April 15th 2021 would be sent as 2021-04-15T09:18:23.283-07:00
    Example: 2024-05-21T09:18:23.283-07:00

  - `p2pe` (object, required)

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

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

  - `emv` (object, required)
    **Conditional: Required when processing an EMV transaction without using a UTG.**

  - `emv.emptyCandidateList` (string)
    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.
    Enum: "Y", "N"

  - `emv.tlvData` (string, required)
    This field will contain all EMV tags in standard TLV format including the P2PE encrypted tags (5A and 57).  The P2PE encrypted tags (5A and 57) will have the entire TLV string encrypted and the encrypted data will be in a TLV format using the same tag. For example, tag 5A would look like the following:
- Encrypted: 5A103737DA95D8062F647A0FF747CC496570
- Decrypted: 5A084761739001010010
    Example: 4F07A0000000041010500A4D61737465724361726457203CCEB572BE7DD0A38E62E6BD70E3DAACE9B46BD3BF65E188E7D8D68D2178DE1A5A10B1794BAC083B08F0A1444F189A5493255F201A546573742F43617264203039202020202020202020202020…

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

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

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

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

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

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

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

  - `card` (object, required)

  - `card.entryMode` (string, required)
    The method used to capture a payment card.
| Value | Description |
|  --- | --- |
| M | Manual Entry |
    Enum: "M"

  - `ach` (object, required)

  - `ach.accountNumber` (string, required)
    Bank Account Number. Do not include any dashes, spaces, or additional zeros.
    Example: 1234567890

  - `ach.routingNumber` (string, required)
    The routing number identifying the bank.
    Example: 121000248

  - `ach.accountType` (string, required)
    Bank account type
| Value | Description |
|  --- | --- |
| PC | Personal Checking |
| PS | Personal Savings |
| CC | Corporate Checking |
| CS | Corporate Savings |
    Example: PC

  - `ach.accountHolderName` (string, required)
    ACH account holder's name
    Example: John Smith

  - `ach.accountVerified` (boolean, required)
    Send as `true` if the ACH account was verified through a 3rd party.
    Example: true

  - `ach.verificationType` (string, required)
    The type of verification used to validate the account.
| Value | Description |
|  --- | --- |
| P | Prenotification |
| M | Micro Deposits |
| B | Bank Login |
    Enum: "P", "M", "B"

## Response 200 fields (application/json):

  - `result` (array)

  - `result.dateTime` (string)
    The date and time in ISO 8601 format including the timezone offset (yyyy-mm-ddThh:mm:ss.nnn+hh:mm).
Must be sent as the local date/time of the merchant. For example, a request processed at a merchant in the Pacific time zone at 9:18am on April 15th 2021 would be sent as 2021-04-15T09:18:23.283-07:00
    Example: 2024-05-21T09:18:23.283-07:00

  - `result.card` (object)

  - `result.card.entryMode` (string)
    **Conditional: The Card Entry Mode should be sent in an initial request; in subsequent requests, it should be left blank or not sent. When using a Universal 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 |
    Enum: "1", "2", "C", "E", "M", "Q", "R"

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

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

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

  - `result.card.token` (object)

  - `result.card.token.value` (string)
    This field is used to specify a card token. Whenever CHD is sent in a request, a card token will be returned in this field. Your interface should be designed to store this card token for future use. The latest card token received should be used in any subsequent request that references the same card data.
    Example: 8048471746471119

  - `result.customer` (object)

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

  - `result.customer.firstName` (string)
    Specifies a consumer’s first name. This field is used in AVS. If the interface sends this field, the value specified by the interface will be returned in the response, unless the API Option [USECARDNAME](/guides/appendices/api-options#usecardname) is included in the request and a Commerce Engine or UTG-controlled PIN pad is in use. If the interface does not send the `customer` object, the consumer's name will be returned in the `customer` object if the name is present in the card's EMV or track data.
    Example: John

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

  - `result.customer.lastName` (string)
    Specifies a consumer’s last name. This field is used in AVS. If the interface sends this field, the value specified by the interface will be returned in the response, unless the API Option [USECARDNAME](/guides/appendices/api-options#usecardname) is included in the request and a Commerce Engine or UTG-controlled PIN pad is in use. If the interface does not send the `customer` object, the consumer's name will be returned in the `customer` object if the name is present in the card's EMV or track data.
    Example: Smith

  - `result.customer.postalCode` (string)
    Cardholder’s ZIP/postal code from their billing statement. This field is used in AVS. Do not include special characters.
**Note: This field only allows alphanumeric characters (a-z, A-Z, 0-9). Special characters including - are not allowed. If you are sending in zip+4 you must not include the dash so 89134-1234 would be sent as 891341234**
    Example: 65144

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

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

  - `result.device` (object)

  - `result.device.terminalId` (string)
    To prompt a specific UTG-controlled PIN pad in a request, the API Terminal ID configured in UTG TuneUp must be specified in this field.
    Example: 1742

  - `result.merchant` (object)

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

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

  - `result.server` (object)

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

  - `result.universalToken` (object)

  - `result.universalToken.value` (string)
    An identifier for a card or payment account across all Shift4 merchants.
    Example: 97032276-5944-00000001-16985FD179D

## Response 400 fields (application/json):

  - `result` (array)

  - `result.error` (object)

  - `result.error.code` (integer)
    Code indicating the type of error that occurred. Refer to the [Error Codes](/guides/appendices/error-codes) section of this document for more details.
**Note: This is currently only supported for European merchant processing.**
    Example: 64100

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

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

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

  - `result.error.primaryCode` (integer)
    Code indicating the type of error that occurred. Refer to the [Error Codes](/guides/appendices/error-codes) section of this document for more details.
    Example: 9842

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

  - `result.lighthouse` (object)

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

  - `result.server` (object)

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

## Response 504 fields (application/json):

  - `result` (array)

  - `result.error` (object)

  - `result.error.code` (integer)
    Code indicating the type of error that occurred. Refer to the [Error Codes](/guides/appendices/error-codes) section of this document for more details.
**Note: This is currently only supported for European merchant processing.**
    Example: 64100

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

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

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

  - `result.error.primaryCode` (integer)
    Code indicating the type of error that occurred. Refer to the [Error Codes](/guides/appendices/error-codes) section of this document for more details.
    Example: 9842

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

  - `result.lighthouse` (object)

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

  - `result.server` (object)

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