Skip to content
/
TokenStore Add

Shift4 Payment API (1.7.43)

Overview
URL

https://www.shift4.com/contact-us/

Languages
Servers
Host Direct Test URL

https://api.shift4test.com/api/rest/v1/

Host Direct Production URL

https://api.shift4api.net/api/rest/v1/

Credentials

Operations

Transactions

Operations

Tokens

Operations

TokenStore Add

Request

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 and URLs Section sections of the Development Quick Start guide for details regarding each processing option.

See the JSON Body Schemas for more details on the various JSON body formats.

Security
AccessToken
Headers
InterfaceVersionstring<= 11 charactersrequired

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

Example: 2.1
InterfaceNamestring<= 25 charactersrequired

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

Example: ForwardPOS
CompanyNamestring<= 26 charactersrequired

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

Example: PAWS
AccessTokenstring(uuid)<= 52 charactersrequired

A security credential used to authenticate API requests and all i4Go® authorizeClient/preauthorizeClient requests. An Access Token is the alias for the merchant account and interface being used. The Access Token is required in all requests except an Access Token Exchange request, which generates an Access Token using an authToken and clientGuid.

Example: EA79FB05-3AA7-4500-AF9A-73F986FF2C1D
Bodyapplication/jsonrequired
One of:
dateTimestring(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

Example: "2024-05-27T09:18:23.283-07:00"
apiOptionsArray of stringswrite-only

API Options modify the request being made. See the API Options section for more information.

customerobject
deviceobject
application/json
{
  "dateTime": "2024-05-27T09:18:23.283-07:00"
}

Responses

Request was processed

Bodyapplication/json
One of:
resultArray of objects
Example: [{"dateTime":"2021-04-15T09:18:23.283-07:00","card":{"entryMode":"2","number":"XXXXXXXXXXX2221","token":{"value":"8038471748812221"},"type":"AX"},"device":{"terminalId":"1742"},"merchant":{"mid":15877,"name":"Merchant XYZ"},"server":{"name":"U2API01CE"}}]
Response
application/json
{
  "result": [
    {
      "dateTime": "2021-04-15T09:18:23.283-07:00",
      "card": {
        "entryMode": "2",
        "number": "XXXXXXXXXXX2221",
        "token": { … },
        "type": "AX"
      },
      "device": {
        "terminalId": "1742"
      },
      "merchant": {
        "mid": 15877,
        "name": "Merchant XYZ"
      },
      "server": {
        "name": "U2API01CE"
      }
    }
  ]
}

TokenStore Duplicate

Request

This function requests that a new card token be generated using an existing card token. This request can be used to deposit a card token into a Global TokenStore or as a means to continue using a token that is about to expire. The card’s short-term data (if sent by the interface) will be stored until it is used or for the period configured in the merchant’s Lighthouse Transaction Manager account.

Note: This request only works for Legacy TrueToken style tokens. It will not work for Global Token Vault style tokens.

Integration Methods:

  • Host Direct
  • Locally Installed UTG

See the Integration Methods and URLs Section sections of the Development Quick Start guide for details regarding each processing option.

Security
AccessToken
Headers
InterfaceVersionstring<= 11 charactersrequired

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

Example: 2.1
InterfaceNamestring<= 25 charactersrequired

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

Example: ForwardPOS
CompanyNamestring<= 26 charactersrequired

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

Example: PAWS
AccessTokenstring(uuid)<= 52 charactersrequired

A security credential used to authenticate API requests and all i4Go® authorizeClient/preauthorizeClient requests. An Access Token is the alias for the merchant account and interface being used. The Access Token is required in all requests except an Access Token Exchange request, which generates an Access Token using an authToken and clientGuid.

Example: EA79FB05-3AA7-4500-AF9A-73F986FF2C1D
Bodyapplication/jsonrequired
dateTimestring(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

cardobjectrequired
card.​tokenobjectrequired
card.​token.​valuestring<= 16 charactersrequired

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.

card.​token.​serialNumberstring<= 10 characters

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.

apiOptionsArray of stringswrite-only

API Options modify the request being made. See the API Options section for more information.

customerobject
deviceobject
application/json
{
  "dateTime": "2021-04-15T09:18:23.283-07:00",
  "card": {
    "token": {
      "serialNumber": "266",
      "value": "1119eqetd26hfne4"
    }
  }
}

Responses

Request was processed

Bodyapplication/json
resultArray of objects
Response
application/json
{
  "result": [
    {
      "dateTime": "2022-05-10T06:34:25.049-07:00",
      "card": {
        "expirationDate": 1230,
        "number": "XXXXXXXXXXXX1119",
        "type": "VS",
        "token": { … }
      },
      "merchant": {
        "mid": 15877,
        "name": "Merchant XYZ"
      },
      "server": {
        "name": "TM01CE"
      },
      "universalToken": {
        "value": "97032276-5944-00000001-16985FD179D"
      }
    }
  ]
}

TokenStore Delete

Request

This function requests that a token be deleted from the TrueToken vault. This process is irreversible. Once the token is deleted, there is no way to recover it.

Note: This request only works for Legacy TrueToken style tokens. It will not work for Global Token Vault style tokens.

Integration Methods:

  • Host Direct
  • Locally Installed UTG

See the Integration Methods and URLs Section sections of the Development Quick Start guide for details regarding each processing option.

Security
AccessToken
Headers
InterfaceVersionstring<= 11 charactersrequired

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

Example: 2.1
InterfaceNamestring<= 25 charactersrequired

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

Example: ForwardPOS
CompanyNamestring<= 26 charactersrequired

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

Example: PAWS
AccessTokenstring(uuid)<= 52 charactersrequired

A security credential used to authenticate API requests and all i4Go® authorizeClient/preauthorizeClient requests. An Access Token is the alias for the merchant account and interface being used. The Access Token is required in all requests except an Access Token Exchange request, which generates an Access Token using an authToken and clientGuid.

Example: EA79FB05-3AA7-4500-AF9A-73F986FF2C1D
Bodyapplication/jsonrequired
dateTimestring(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

cardobjectrequired
card.​tokenobjectrequired
card.​token.​valuestring<= 16 charactersrequired

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.

application/json
{
  "dateTime": "2021-04-15T09:18:23.283-07:00",
  "card": {
    "token": {
      "value": "1119eqetd26hfne4"
    }
  }
}

Responses

Request was processed

Bodyapplication/json
resultArray of objects
Response
application/json
{
  "result": [
    {
      "dateTime": "2022-05-10T06:34:25.049-07:00",
      "card": {
        "token": { … }
      },
      "merchant": {
        "mid": 15877,
        "name": "Merchant XYZ"
      },
      "server": {
        "name": "TM01CE"
      }
    }
  ]
}

Universal Token

Request

This function requests that the existing universal token for a card be returned.

Note: The GET request does not support a request body. Sending an empty request body may result in an error.

Integration Methods:

  • Host Direct
  • Locally Installed UTG
  • Commerce Engine For On Premise
  • Commerce Engine For Cloud

See the Integration Methods and URLs Section sections of the Development Quick Start guide for details regarding each processing option.

Security
AccessToken
Headers
InterfaceVersionstring<= 11 charactersrequired

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

Example: 2.1
InterfaceNamestring<= 25 charactersrequired

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

Example: ForwardPOS
CompanyNamestring<= 26 charactersrequired

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

Example: PAWS
AccessTokenstring(uuid)<= 52 charactersrequired

A security credential used to authenticate API requests and all i4Go® authorizeClient/preauthorizeClient requests. An Access Token is the alias for the merchant account and interface being used. The Access Token is required in all requests except an Access Token Exchange request, which generates an Access Token using an authToken and clientGuid.

Example: EA79FB05-3AA7-4500-AF9A-73F986FF2C1D
CardNumberstring<= 32 characters

The payment card number. This field will always be masked when returned in a response.

Example: 4321000000001119
P2PEDatastring<= 2048 characters

The full output of a P2PE keypad/magnetic swipe reader (MSR).

P2PEFormatstring= 2 characters

Classifies the type of payment device being used for P2PE.

ValueDescription
01IDTech Enhanced Encryption format, USB KB mode
02IDTech Enhanced Encryption format, USB HID mode
03Ingenico format
04VeriFone format
05Shift4 TDES DUKPT format
Enum"01""02""03""04""05"
Example: 01
P2PEKsnstring<= 20 characters

Conditional: Required when p2pe.format == "05"

The key serial number which was used to encrypt the P2PE data.

Example: 6299495001100E200041
SerialNumberstring<= 10 characters

In requests that require the use of a shared card token that is held by another merchant account, such as in TokenStore or TokenShare®, this field is used to specify the serial number for the account where the card token is stored.

Example: 266
Tokenstring<= 16 characters

This field is used to specify the token for the payment method.

Example: 8048471746471119
TrackDatastring<= 128 characters

Conditional: Send in the initial authorization/sale request when processing a swiped MSR transaction. This field is not specified when using True P2PE® (point-to-point encryption) or a UTG-controlled PIN pad.

Card swipe data exactly as read by an MSR.

Example: ;4321000000001119=2212201999999?
No request payload

Responses

Request was processed

Bodyapplication/json
resultArray of objects
Response
application/json
{
  "result": [
    {
      "dateTime": "2024-05-21T09:18:23.283-07:00",
      "merchant": {
        "mid": 15877,
        "name": "Merchant XYZ"
      },
      "server": {
        "name": "TM01CE"
      },
      "universalToken": {
        "value": "97032276-5944-00000001-16985FD179D"
      }
    }
  ]
}

Get Four Words

Request

This function is used to generate a unique combination of four words that can be used to reference cardholder data (CHD).

Note: This functionality is supported with Legacy TrueTokens only. It is not supported with GTV tokens.

Integration Methods:

  • Host Direct
  • Locally Installed UTG

See the Integration Methods and URLs Section sections of the Development Quick Start guide for details regarding each processing option.

Security
AccessToken
Headers
InterfaceVersionstring<= 11 charactersrequired

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

Example: 2.1
InterfaceNamestring<= 25 charactersrequired

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

Example: ForwardPOS
CompanyNamestring<= 26 charactersrequired

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

Example: PAWS
AccessTokenstring(uuid)<= 52 charactersrequired

A security credential used to authenticate API requests and all i4Go® authorizeClient/preauthorizeClient requests. An Access Token is the alias for the merchant account and interface being used. The Access Token is required in all requests except an Access Token Exchange request, which generates an Access Token using an authToken and clientGuid.

Example: EA79FB05-3AA7-4500-AF9A-73F986FF2C1D
Bodyapplication/jsonrequired
dateTimestring(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

cardobjectrequired
card.​tokenobjectrequired

Conditional: Send this object when using a card on file.

card.​token.​valuestring<= 16 characters

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.

application/json
{
  "dateTime": "2021-04-15T09:18:23.283-07:00",
  "card": {
    "token": {
      "value": "8048471746471119"
    }
  }
}

Responses

Request was processed

Bodyapplication/json
resultArray of objects
Response
application/json
{
  "result": [
    {
      "dateTime": "2024-05-21T09:18:23.283-07:00",
      "card": {
        "entryMode": "M",
        "fourWords": "cat blue washington enter",
        "number": "XXXXXXXXXXXX8774"
      },
      "merchant": {
        "mid": 15877,
        "name": "Merchant XYZ"
      },
      "server": {
        "name": "TM01CE"
      }
    }
  ]
}

Merchants

Operations

Gift Cards

Operations

Cards

Operations

Devices

Operations

Reports

Operations

Batches

Operations

QR Payments

Operations

Mode

Operations

Risk

Operations

PayPal

Operations

3D Secure

Operations

OCT

Operations

ACH

OperationsWebhooks

Updater

Operations

DCC

Operations

Rules

Operations