Shift4 Gift Cards API
The Gift Cards API from Shift4 — 9 operation(s) for gift cards.
Shift4 Gift Cards API is one of 21 APIs that Shift4 publishes on the APIs.io network, described by a machine-readable OpenAPI specification.
Tagged areas include Gift Cards. The published artifact set on APIs.io includes an OpenAPI specification, API documentation, and an API reference.
This API exposes 9 operations across 9 paths, and defines 138 schemas. It is described by OpenAPI 3.2.0, at version 1.7.57.
Requests are made against 2 base URLs: https://api.shift4test.com/api/rest/v1, https://api.shift4api.net/api/rest/v1.
9 operations
9 paths
138 schemas
9 POST
Metadata
The identity and technical contract details declared by the specification.
Authentication & Security 2
Shift4 Gift Cards API declares
2 security schemes
for authenticating requests.
An API key is passed in the header as AccessToken (AccessToken).
It uses HTTP hmac-sha256 authentication (HMAC-SHA256).
AccessToken— A security credential used to authenticate API requests and all [i4Go®](https://s4-myportal.s3.amazonaws.com/downloads/documentation/i4go/i4go%20technical%20re…HMAC-SHA256— Authentication using HMAC-256 signatures as the authorization scheme. Sent in the Authorization header in the following format: Authorization: HMAC-SHA256 Cred…
Paths & Operations 9
Across 9 paths, the API surfaces 9 operations — 9 POST. Each is listed below with its method, path, parameters, and response codes.
Gift Cards 9
POST
/giftcards/activate
Activate
POST
/giftcards/allocate
Allocate
POST
/giftcards/deactivate
Deactivate
POST
/giftcards/cashoutdeprecated
Cashout
POST
/giftcards/cashback
Cashback
POST
/giftcards/reactivate
Reactivate
POST
/giftcards/reload
Reload
POST
/giftcards/balance
Balance
POST
/giftcards/cancel
Cancel
Schemas 138
The contract defines 138 schemas that model the data the API accepts and returns. The most detailed are CardResponseDeact (8 properties), DeviceCapability (8 properties), CardResponseCashout (7 properties), giftcards_balance_comengcloud (6 properties). Each schema is shown below with its type and property counts.
P2PEType0102IDTECH
object
2 properties
2 required
giftcards_deactivate_utgdevice
object
4 properties
4 required
TransactionResponseCode
string
Code indicating the Shift4 host response. Value | Description | Details -------|-------------------------------------------------------------------------------…
DeviceCapability
object
Conditional: Required when using a non-UTG-controlled device.
8 properties
giftcards_balance_p2pe_tdesdukpt_msr
object
6 properties
5 required
P2PEType03OnguardSDEMSR
object
See [P2PE Format 03 Ingenico On-Guard SDE](/guides/core-concepts/p2pe-formatingenico-on-guard-sde---format-03) for more information.
2 properties
2 required
UISuppressFinalResult
boolean
When true, the terminal suppresses the final transaction result screen.
giftcards_cashout_p2pe_onguardsde_msr
object
6 properties
5 required
CardNumberGC
string
The payment card number. This field will always be masked when returned in a response.
Error
object
6 properties
CardResponseGC
object
4 properties
giftcards_reactivate_p2pe_idtech
object
4 properties
4 required
MerchantName
string
The merchant’s business name as configured with Shift4.
giftcards_activate_comengdevice
object
6 properties
4 required
CardTokenSerialNumber
string
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…
ProgramId
string
The ID value for the program you are allocating a gift card under.
giftcards_balance_p2pe_onguardsde_msr
object
6 properties
5 required
giftcards_cashout_comengdevice
object
6 properties
3 required
ErrorSeverity
string
Severity level of the error. | Severity | Description | | -------- | ---------------------------------------------------------------- | | Info | Action not req…
P2PEType05TDESDUKPTMSR
object
See [P2PE Format 05 TDES DUKPT](/guides/core-concepts/p2pe-formattdes-dukpt---format-05) for more information.
3 properties
3 required
giftcards_cashout_p2pe_tdesdukpt_msr
object
6 properties
5 required
giftcards_cashout_p2pe_idtech
object
5 properties
4 required
giftcards_cashout_comengcloud
object
6 properties
4 required
giftcards_reactivate_p2pe_tdesdukpt_msr
object
5 properties
5 required
AmountTotal
number
The amount being charged for a particular transaction. If other amount fields are sent, they must be included in the total amount. Amount cannot be zero.
CardResponseCashout
object
7 properties
AmountGCResponse
object
Object containing information regarding the amount being added onto the card or removed from the card.
1 property
1 required
DeviceCapabilityManualEntry
string
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…
giftcards_reload_p2pe_idtech
object
5 properties
5 required
giftcards_cancel_token_legacy
object
3 properties
3 required
giftcards_balance_token_gtv
object
4 properties
3 required
giftcards_activate_token_legacy
object
4 properties
4 required
CardDeactivationReason
string
In a Gift Card [Deactivate](/apis/payments-platform-rest/openapi/gift-cards/deactivate) or [Cashout](/apis/payments-platform-rest/openapi/gift-cards/cashout) r…
giftcards_reload_p2pe_onguardsde_msr
object
6 properties
6 required
AmountCheckTotal
number
Optional field specifying the total amount of the entire bill/invoice that this transaction is part of. It can be larger than amount.total in scenarios where t…
giftcards_reactivate_token_legacy
object
3 properties
3 required
Server
object
1 property
giftcards_deactivate_token_legacy
object
3 properties
3 required
DeviceCapabilityPIN
string
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 current…
MerchantMID
number
The merchant ID associated with the merchant account.
giftcards_cashout_token_legacy
object
4 properties
3 required
DeviceTerminalIdComEng
string
This field is optional and is for backwards compatibility with existing vendors that are used to processing via UTG controlled devices. Since Commerce Engine i…
ServerName
string
The name of the server that processed the request.
CardTokenGCResponse
object
1 property
giftcards_balance_comengdevice
object
6 properties
3 required
giftcards_cashout_unencryptedcard
object
4 properties
3 required
giftcards_reactivate_utgdevice
object
4 properties
4 required
giftcards_deactivate_p2pe_onguardsde_msr
object
5 properties
5 required
CardMaskedNumberGC
string
The card number field will always be masked when returned in a response.
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 ex…
TransactionInvoice
string
10-digit invoice number assigned by the interface to identify a transaction. An invoice number serves as a unique key that identifies a transaction within a ba…
CardSecurityCodeValueGC
string
Conditional: May be required for gift card transactions. The three- or four-digit Card Security Code associated with gift card. This value may be required for…
ErrorLongText
string
Extended error message that is returned if an error condition exists.
DevicePromptCardSecurityCode
string
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 t…
giftcards_balance_unencryptedcard
object
4 properties
3 required
DeviceCapabilityMagstripe
string
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…
giftcards_deactivate_token_gtv
object
3 properties
3 required
BalanceAmount
number
The balance remaining on the card. Depending on which processor is being used, the balance may be returned for a gift card, debit card, EBT card, or other stor…
DeviceCapabilityEMV
string
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 trans…
CardEntryMode
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 Tran…
ErrorCode
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: Th…
CardTypeGCResp
string
An abbreviation used to specify the type of card that was used when processing a transaction. Value| Description -----|------------ GC | Gift Card YC | IT’S YO…
ApiOptionsGCBalance
array
API Options modify the request being made. Value | Description | -----------|------------------------------------------------------------| RETURNHIST | Return…
AmountTotalOnly
object
Object containing information regarding the amount being requested. The total field within the object is required and specifies the amount being requested. Not…
1 property
1 required
ErrorSecondaryCode
integer
This code supplements the code specified in the error.primaryCode field to provide additional information about the error that occurred.
CardResponseDeact
object
8 properties
giftcards_balance_p2pe_idtech
object
5 properties
4 required
CardTokenValueGC
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 t…
giftcards_cashout_token_gtv
object
4 properties
3 required
giftcards_deactivate_comengcloud
object
5 properties
4 required
giftcards_reactivate_comengcloud
object
5 properties
4 required
giftcards_reload_unencryptedcard
object
4 properties
4 required
TransactionAuthorizationCode
string
The authorization code provided by the consumer’s issuing bank. It is provided in a response if an online authorization or sale request is approved. Following…
P2PEFormatType05
string
Classifies the type of payment device being used for P2PE. Value|Description -----|----------- 05 | [Shift4 TDES DUKPT format](/guides/core-concepts/p2pe-forma…
AmountGC
object
Object containing information regarding the amount being added onto the card or removed from the card.
2 properties
1 required
UIMode
string
Set the UI to light mode by sending light or dark mode by sending dark
DeviceTerminalIdRequired
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.
giftcards_cancel_token_gtv
object
3 properties
3 required
MerchantResponse
object
2 properties
giftcards_activate_unencryptedcard
object
4 properties
4 required
giftcards_cashout_utgdevice
object
5 properties
4 required
giftcards_activate_token_gtv
object
4 properties
4 required
AmountTotalGCResponse
number
For [Activate](/apis/payments-platform-rest/openapi/gift-cards/activate), [Allocate](/apis/payments-platform-rest/openapi/gift-cards/allocate) or [Reload](/api…
giftcards_deactivate_unencryptedcard
object
3 properties
3 required
giftcards_reload_comengdevice
object
6 properties
4 required
CardTokenRequired
object
1 property
1 required
DeviceSerialNumber
string
Specifies the serial number of the device.
AmountTotalGCCashback
number
The amount you want to get back from the gift card. If this field is not sent then the full balance of the card will be returned as cash.
ErrorPrimaryCode
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.
giftcards_balance_utgdevice
object
5 properties
4 required
P2PEFormatIDTech
string
Classifies the type of payment device being used for P2PE. Value|Description -----|----------- 01 | IDTech Enhanced Encryption format (Keyboard Mode) 02 | IDTe…
DeviceModel
string
Conditional: Required when using a non-UTG-controlled device. Specifies the model of the device.
giftcards_reactivate_p2pe_onguardsde_msr
object
5 properties
5 required
giftcards_reload_token_legacy
object
4 properties
4 required
giftcards_reload_token_gtv
object
4 properties
4 required
DeviceCapabilityQuickChip
string
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 al…
CardTokenRequiredLegacy
object
2 properties
1 required
giftcards_reload_comengcloud
object
6 properties
5 required
CardPresent
string
Conditional: Send in the initial authorization/sale request Indicates whether a card was present (‘Y’) or not (‘N’) at the time a transaction took place. This…
giftcards_reactivate_token_gtv
object
3 properties
3 required
giftcards_reactivate_comengdevice
object
5 properties
3 required
DeviceCapabilitySignature
string
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…
CardBalance
object
1 property
DeviceOnlyTIDResponse
object
1 property
P2PEKSN
string
The key serial number which was used to encrypt the P2PE data.
giftcards_activate_comengcloud
object
6 properties
5 required
giftcards_deactivate_p2pe_idtech
object
4 properties
4 required
AmountTotalGC
number
The amount which should be added to the card's balance. Amount cannot be zero.
DeviceManufacturer
string
Specifies the company which manufactured the device.
giftcards_activate_p2pe_tdesdukpt_msr
object
6 properties
6 required
CardExpirationDateResponse
integer
Conditional: Requires API Option "RETURNEXPDATE". Card expiration date in MMYY format. This value will only be populated if "RETURNEXPDATE" is included in the…
P2PEFormatOnguardSDE
string
Classifies the type of payment device being used for P2PE. Value|Description -----|----------- 03 | Ingenico Onguard SDE Format
DeviceCapabilityContactlessMSR
string
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 disa…
P2PEData
string
The full output of a P2PE keypad/magnetic swipe reader (MSR).
giftcards_balance_comengcloud
object
6 properties
4 required
P2PEDataOnguardSDEMSR
string
Track information encrypted with AES 256 DUKPT. Contains the following information, separated by colons: |Value | Description |----------------|------------ |k…
UILanguageRequest
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 configur…
giftcards_reload_p2pe_tdesdukpt_msr
object
6 properties
6 required
UniversalToken
object
1 property
DeviceTerminalId
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.
giftcards_deactivate_p2pe_tdesdukpt_msr
object
5 properties
5 required
giftcards_deactivate_comengdevice
object
5 properties
3 required
giftcards_reload_utgdevice
object
5 properties
5 required
CardSecurityCodeGC
object
1 property
giftcards_activate_utgdevice
object
5 properties
5 required
ErrorShortText
string
Abbreviated error message that is always returned if an error condition exists
DeviceComEngCloud
object
3 properties
3 required
giftcards_activate_p2pe_idtech
object
5 properties
5 required
giftcards_reactivate_unencryptedcard
object
3 properties
3 required
LighthouseDataResponse
string
Base64 encoded JSON formatted data that will be returned from Lighthouse to be passed back to SkyTab. This data will contain variable information.
TransactionAuthSource
string
In a response, a code returned by the processor to indicate which host issued the response. Value | Description -------|---------------------------- E | Engine…
UniversalTokenValue
string
An identifier for a card or payment account across all Shift4 merchants.
giftcards_activate_p2pe_onguardsde_msr
object
6 properties
6 required
CardTokenValue
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 t…
DeviceCapabilityContactlessEMV
string
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 f…
DeviceCloud
boolean
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…
CardExpirationDateGC
integer
Conditional: Send in the request for manually entered or token transactions if the card has an expiration date. This field should not be specified when using a…
giftcards_balance_token_legacy
object
4 properties
3 required
Specification
The full machine-readable OpenAPI contract behind this narrative.
Source
More from Shift4 12
Other APIs Shift4 publishes across the network.
Shift4 3D Secure API
Shift4 ACH API
Shift4 Batches API
Shift4 Cards API
Shift4 Checkout Sessions API
Shift4 Credentials API
Shift4 DCC API
Shift4 Devices API
Shift4 Merchants API
Shift4 Mode API
Shift4 OCT API
Shift4 Payment Links API
#Gift Cards
Where this information came from
This is an independent, third-party profile of Shift4 Gift Cards API, published by API Evangelist. We do not operate, host, resell, or support these APIs, and we are not affiliated with or endorsed by the company unless stated above. Everything here is built from publicly available information — the company's own site, developer portal, documentation, public repositories, and the specifications it publishes for public use. Nothing is obtained by breaching a system, defeating an access control, or using credentials.
The Kin Score and Agent Readiness rating are independently calculated assessments of a company's public API artifacts, scored against a published rubric. They are not certifications, endorsements, security assessments, or audits.
Corrections, re-scores, and removal are free — no partnership or purchase required, and you do not need to justify the request. A removed company is recorded as unrated, never scored zero for having asked. Acknowledgement within one business day; removal within two.
info@apievangelist.com
·
Read the full data-sourcing policy →
On a security or compliance team? Put security in the subject line and
you will get a person, not a form — we will tell you exactly which public URLs this profile was built from.