The integration of your interface with Shift4 can begin once a Client GUID (Globally Unique ID) and Auth Token are supplied by your API Analyst. If you have not yet received these items, please reach out to Shift4 to have them supplied for your integration.
This quickstart will follow in order and inline through the documentation for the following most used commands:
- Exchanging your GUID and Auth Token for an Access Token (Required)
- Authorizing a payment
- Capturing a payment
- Making a sale/purchase in one call
- Refunding a payment
- Retrieving invoice information
- Voiding a payment
Please note that if you are tokenzing your credit card information outside of Shift4, authorizing and capturing a payment is not available unless you store the tokenized value from Shift4 from an authorized payment request and use this token in the subsequent capture request.
Setting up a UTG locally is only required when an integrator is dealing with physical card transactions and needs a payment device to read the card. If you are an e-commerce integrator only (card not present transactions), this step can be skipped.
Commerce Engine is our next-generation payment platform for card present transactions. See the Commerce Engine section of the documentation for more details.
If you get any certificate type errors when attempting to establish a connection to our gateway, you'll need to install this server certificate issued by GeoTrust manually on your server. The ZIP file contains a single .p7b file that includes the entire certificate chain.
Our test scripts are provided to our integration partners directly from your API Analyst that is geared toward your integration in particular. If you have not yet received it, please ask your API Analyst for a copy.
To accommodate diverse operational requirements and infrastructure, choose to route API requests using one or more of the following integration methods:
Host Direct: This option allows direct connection to our hosted service, ensuring access and utilization of our API through the internet without the need for local deployment. This environment is ideal for scenarios when a payment device is not required.
Locally Installed UTG: Utilize our Universal Transaction Gateway (UTG) installed directly at the merchant site. This setup is primarily used for card-present payment processing, employing a UTG-controlled payment device to handle transactions securely and efficiently on premises. For more information, please refer to the UTG-Controlled Devices section.
Commerce Engine For On-Premise: A next-generation payment platform designed for card-present transactions. Commerce Engine runs directly on the payment device, allowing initiation of payment requests through the local network. This solution is tailored for POS/PMS vendors who install their software solutions on hardware operating at the merchant’s location. For more information, please refer to the Commerce Engine For On-Premise Deployments section.
Commerce Engine For Cloud: Specifically crafted for processing card-present transactions in cloud-based POS/PMS setups, this option suits vendors that deploy their solutions in the cloud rather than at the merchant’s physical location. For more information, please refer to the Commerce Engine for Cloud-Based Deployments section.
Each option is designed to meet various technological and business needs, ensuring that integrators can choose the most suitable solution for their specific operational needs.
Furthermore, it is possible to leverage a hybrid approach by combining these options. For instance, initial transaction requests (e.g., authorization, sale, refund, etc.) requiring payment entry on a device can utilize the Commerce Engine For Cloud or Commerce Engine For On-Premise option, while all subsequent transactions (e.g., incremental authorizations, captures, voids, etc.) can utilize the Host Direct option. This flexibility facilitates a tailored implementation that optimizes transaction processing efficiency to meet precise business requirements.
Below are the URLs to utilize based on your chosen processing option:
- Host Direct:
- Test: https://api.shift4test.com/api/rest/v1
- Production: https://api.shift4api.net/api/rest/v1
- Locally Installed UTG: https://[UTG_LISTENING_IP_ADDRESS]:[UTG_PORT]/api/rest/v1
- For example, if the IP address of the UTG you are connecting to is 192.168.1.10, and the REST port of UTG API interface is 277, then the URL would be: https://192.168.1.10:277/api/rest/v1
- Commerce Engine For On Premise: https://[COMMERCE_ENGINE_LISTENING_IP_ADDRESS]:[COMMERCE_ENGINE_PORT]/api/rest/v1
- For example, if the IP address of the Commerce Engine you are connecting to is 192.168.1.20, and the port of the REST interface is 8085, then the URL would be: https://192.168.1.20:8085/api/rest/v1
- Commerce Engine For Cloud:
- Test: https://api.shift4test.com/api/rest/v1
- Production: https://api.shift4api.net/api/rest/v1
- Utilize the Commerce Engine For Cloud request body format.
Note: If you have an existing integration, you may be using an older URL for test/production. While those URLs will continue to work, we suggest migrating to the new URLs listed above.
Your interface will need to retrieve an Access Token via an Access Token Exchange for each merchant account. This process requires a Client GUID (globally unique ID), which will be provided by Shift4, and an Auth Token, which will be provided by the merchant's Lighthouse Transaction Manager Account Administrator. After performing an Access Token Exchange, the Access Token should be stored securely and will be used to identify your interface and the merchant account in all subsequent API requests. This gives merchants more control over who is able to make API requests on their behalf.
Shift4 authenticates your interface to the Shift4 API via an Access Token, which is obtained by supplying your Client GUID and Auth Token in an Access Token Exchange POST.
Your Client GUID is permanent for that interface and will be the same for testing and production. Therefore, it must be hard coded into your application to identify the interface across all merchant accounts and must not be a configurable field. The Client GUID serves as a digital thumbprint that uniquely identifies your interface to Shift4.
An Auth Token gives your application permission to make API requests on behalf of a given merchant account. The test Auth Token can be reused as needed only in the certification environment.
In production, the merchant's Lighthouse Transaction Manager Account Administrator will provide an Auth Token for your interface. An Auth Token in production is valid only for a single Access Token Exchange for a specific merchant account within a limited number of days (1, 3, 7, 30, 60, or 90). Therefore, an Auth Token should never be stored by your application, and should be immediately discarded after an Access Token has been acquired.
If there is an Access Token Exchange failure in production, or if an Access Token has been revoked, the merchant's Lighthouse Transaction Manager Account Administrator will need to provide a new Auth Token for your interface. Therefore, Interfaces must be built to account for the fact that a new Access Token may be required if there is a security incident or compliance concern. In an event such as this, the Lighthouse Transaction Manager Account Administrator will provide a new Auth Token for your interface. After a new Access Token has been generated for the affected account, the Account Administrator can revoke the old one. This ensures the merchant can continue processing transactions.
Once you have your Access Token, you can run transactions against each of the supported endpoints for your integration.
This information must be added to the header of all API requests.
InterfaceVersion: The version of the program or application that is sending requests.
InterfaceName: The name of the program or application that is sending requests.
CompanyName: The vendor or partner that designed and certified the interface.
AccessToken: The security credential received from the Access Token Exchange API.
There are a few different request body schemas available to your integration depending on what you are trying to accomplish. In each of the explanations bulleted below, when following the link, be sure to choose the appropriate Request Body Schema item and matching item in the Request Samples Example Drop Down on the right side of the screen. This will show you the required and optional parameters for your request as well as an example payload.
- UTG Controlled Device: Used when processing a card present transaction via a UTG controlled device. This option simplifies the integration as the EMV contact and contactless payment processing flows as well as the associated certifications are handled by Shift4.
- Commerce Engine For On Premise: Used by on premise based POS/PMS vendors to process card present transactions. The transaction request is sent from the POS/PMS running at the merchant location directly to the Commerce Engine device running on the same local network. This option simplifies the integration as the EMV contact and contactless payment processing flows as well as the associated certifications are handled by Shift4.
- Commerce Engine For Cloud URL: Used by cloud based POS/PMS vendors to process card present transactions. The transaction request is sent from the POS/PMS cloud directly to the Shift4 host and the Shift4 host routes the transaction request down to the appropriate payment device running at the merchant location. This option simplifies the integration as the EMV contact and contactless payment processing flows as well as the associated certifications are handled by Shift4.
- GTV Token: Used when a credit card has been tokenized by Shift4 using our Global Token Vault. This allows you to simply pass the tokenized card value for payment.
- Legacy TrueToken: Used when a credit card has been tokenized by Shift4 using our Legacy TrueToken vault. The Legacy TrueToken vault solution has been replaced with our Global Token Vault (GTV) solution. This request body type should not be utilized by newly integrating vendors. The GTV Token body type should be utilized instead. This remains in the documentation for reference purposes.
- P2PE - ID TECH - EMV/MSR/Manual: Used when processing a request with ID Tech P2PE encrypted readers. This body schema is used for both magstripe only (SecureMag, SREDKey, etc) as well as EMV capable devices (August, VP3300, etc).
- P2PE - TDES DUKPT - MSR/Manual: Used when processing a magstripe or manually entered transaction via an interface vendor controlled payment device.
- P2PE - TDES DUKPT - EMV: Used when processing an EMV transaction via an interface vendor controlled payment device using TDES DUKPT.
- P2PE - On-Guard SDE - EMV: Used when processing an EMV transaction via an interface vendor controlled payment device using Ingenico On-Guard SDE AES 256 DUKPT.
- P2PE - TDES DUKPT - MSR/Manual: Used when processing a magstripe or manually entered transaction via an interface vendor controlled payment device using TDES DUKPT.
- P2PE - On-Guard SDE - MSR/Manual: Used when processing a magstripe or manually entered transaction via an interface vendor controlled payment device using Ingenico On-Guard SDE AES 256 DUKPT.
- P2PE - AES - Manual: Used when processing a manual card entry request with AES encryption with a pre-shared key.
- Card Number Unencrypted: Used when the credit card has been tokenized by a 3rd party or yourself securely and you need to charge the card by passing the raw credit card information.
- Wallet/3D Secure Using i4Go: Used when processing a request via i4Go that includes Apple Pay, Google Pay or 3D Secure data. i4Go is utilized to obtain the appropriate Wallet/3D Secure data, simplifying the integration.
- 3D Secure Using Card Number: Used when processing a request that includes 3D Secure data. With this flow the interface vendor is responsible for obtaining the 3D Secure data.
- 3D Secure Using GTV Token: Used when processing a request that includes 3D Secure data and using a stored GTV token. With this flow the interface vendor is responsible for obtaining the 3D Secure data.
- 3D Secure Using Legacy TrueToken: Used when processing a request that includes 3D Secure data and using a stored Legacy TrueToken. With this flow the interface vendor is responsible for obtaining the 3D Secure data.
- Apple Pay: Used when processing an Apple Pay transaction online or in app. With this flow the interface vendor is responsible for obtaining the Apple Pay data.
- Google Pay: Used when processing an Google Pay transaction online or in app. With this flow the interface vendor is responsible for obtaining the Google Pay data.
- Incremental: Used when incrementing the authorization on an existing transaction. A few examples are below:
- A restaurant merchant using a traditional table payment flow where the guest enters a tip after authorization.
- A restaurant merchant that has a customer add additional food/drinks to their check after the initial authorization.
- A restaurant merchant running a bar tab.
- A hotel merchant that has a guest extending their stay.