--- title: "Reload" method: POST path: "/giftcards/reload" tags: ["Gift Cards"] --- # Reload `POST /giftcards/reload` This function requests that an active gift card be loaded with additional funds. **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 - GiftcardsReloadComengdevice - `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 - `amount` AmountGC, required — Object containing information regarding the amount being added onto the card or removed from the card. - `total` number, required — The amount which should be added to the card's balance. Amount cannot be zero. - `checkTotal` 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 the check is being split or if a portion of the check was already paid in cash or another form of payment. - `card` object, required - `present` 'Y' | 'N', required — **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 should be set appropriately in the initial authorization/sale request. In subsequent requests, this field should be left blank or should not be sent. **Note:** Subsequent request here does not apply to the secondary request for card on file type transactions or reuse of the same card. An example of a subsequent request would be a capture after an authorization. You would not include `card.present` in the capture, which is the subsequent request. Another example is when performing an incremental authorization where you perform an authorization, followed by an incremental authorization then a capture. The second authorization (incremental) and the capture are the subsequent requests where you would not include `card.present`. - `device` object - `terminalId` 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 is running directly on the payment device it does not require a `device.terminalId` to be specified. - `transaction` object, required - `invoice` string, required — 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 batch in Shift4's Gateway. **Note: For US and Canadian processing: Although the invoice number is sent as a JSON string it is a numeric value. No alpha characters are allowed.** **For processing outside of the US and Canada alpha characters are allowed.** - `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. - GiftcardsReloadComengcloud - `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 - `amount` AmountGC, required — Object containing information regarding the amount being added onto the card or removed from the card. - `total` number, required — The amount which should be added to the card's balance. Amount cannot be zero. - `checkTotal` 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 the check is being split or if a portion of the check was already paid in cash or another form of payment. - `card` object, required - `present` 'Y' | 'N', required — **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 should be set appropriately in the initial authorization/sale request. In subsequent requests, this field should be left blank or should not be sent. **Note:** Subsequent request here does not apply to the secondary request for card on file type transactions or reuse of the same card. An example of a subsequent request would be a capture after an authorization. You would not include `card.present` in the capture, which is the subsequent request. Another example is when performing an incremental authorization where you perform an authorization, followed by an incremental authorization then a capture. The second authorization (incremental) and the capture are the subsequent requests where you would not include `card.present`. - `device` DeviceComEngCloud, 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. - `transaction` object, required - `invoice` string, required — 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 batch in Shift4's Gateway. **Note: For US and Canadian processing: Although the invoice number is sent as a JSON string it is a numeric value. No alpha characters are allowed.** **For processing outside of the US and Canada alpha characters are allowed.** - `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. - GiftcardsReloadUtgdevice - `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 - `amount` AmountGC, required — Object containing information regarding the amount being added onto the card or removed from the card. - `total` number, required — The amount which should be added to the card's balance. Amount cannot be zero. - `checkTotal` 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 the check is being split or if a portion of the check was already paid in cash or another form of payment. - `card` object, required - `present` 'Y' | 'N', required — **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 should be set appropriately in the initial authorization/sale request. In subsequent requests, this field should be left blank or should not be sent. **Note:** Subsequent request here does not apply to the secondary request for card on file type transactions or reuse of the same card. An example of a subsequent request would be a capture after an authorization. You would not include `card.present` in the capture, which is the subsequent request. Another example is when performing an incremental authorization where you perform an authorization, followed by an incremental authorization then a capture. The second authorization (incremental) and the capture are the subsequent requests where you would not include `card.present`. - `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. - `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.** - `transaction` object, required - `invoice` string, required — 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 batch in Shift4's Gateway. **Note: For US and Canadian processing: Although the invoice number is sent as a JSON string it is a numeric value. No alpha characters are allowed.** **For processing outside of the US and Canada alpha characters are allowed.** - GiftcardsReloadTokenGtv - `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 - `amount` AmountGC, required — Object containing information regarding the amount being added onto the card or removed from the card. - `total` number, required — The amount which should be added to the card's balance. Amount cannot be zero. - `checkTotal` 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 the check is being split or if a portion of the check was already paid in cash or another form of payment. - `card` object, required - `expirationDate` 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 an encrypted device.** Card expiration date in MMYY format. - `present` 'Y' | 'N', required — **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 should be set appropriately in the initial authorization/sale request. In subsequent requests, this field should be left blank or should not be sent. **Note:** Subsequent request here does not apply to the secondary request for card on file type transactions or reuse of the same card. An example of a subsequent request would be a capture after an authorization. You would not include `card.present` in the capture, which is the subsequent request. Another example is when performing an incremental authorization where you perform an authorization, followed by an incremental authorization then a capture. The second authorization (incremental) and the capture are the subsequent requests where you would not include `card.present`. - `token` CardTokenRequired, required - `value` string, required — 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. - `transaction` object, required - `invoice` string, required — 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 batch in Shift4's Gateway. **Note: For US and Canadian processing: Although the invoice number is sent as a JSON string it is a numeric value. No alpha characters are allowed.** **For processing outside of the US and Canada alpha characters are allowed.** - GiftcardsReloadTokenLegacy - `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 - `amount` AmountGC, required — Object containing information regarding the amount being added onto the card or removed from the card. - `total` number, required — The amount which should be added to the card's balance. Amount cannot be zero. - `checkTotal` 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 the check is being split or if a portion of the check was already paid in cash or another form of payment. - `card` object, required - `expirationDate` 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 an encrypted device.** Card expiration date in MMYY format. - `present` 'Y' | 'N', required — **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 should be set appropriately in the initial authorization/sale request. In subsequent requests, this field should be left blank or should not be sent. **Note:** Subsequent request here does not apply to the secondary request for card on file type transactions or reuse of the same card. An example of a subsequent request would be a capture after an authorization. You would not include `card.present` in the capture, which is the subsequent request. Another example is when performing an incremental authorization where you perform an authorization, followed by an incremental authorization then a capture. The second authorization (incremental) and the capture are the subsequent requests where you would not include `card.present`. - `token` CardTokenRequiredLegacy, required - `value` string, required — 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. - `serialNumber` 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 specify the serial number for the account where the card token is stored. - `transaction` object, required - `invoice` string, required — 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 batch in Shift4's Gateway. **Note: For US and Canadian processing: Although the invoice number is sent as a JSON string it is a numeric value. No alpha characters are allowed.** **For processing outside of the US and Canada alpha characters are allowed.** - GiftcardsReloadP2peIdtech - `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 - `amount` AmountGC, required — Object containing information regarding the amount being added onto the card or removed from the card. - `total` number, required — The amount which should be added to the card's balance. Amount cannot be zero. - `checkTotal` 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 the check is being split or if a portion of the check was already paid in cash or another form of payment. - `card` object, required - `present` 'Y' | 'N', required — **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 should be set appropriately in the initial authorization/sale request. In subsequent requests, this field should be left blank or should not be sent. **Note:** Subsequent request here does not apply to the secondary request for card on file type transactions or reuse of the same card. An example of a subsequent request would be a capture after an authorization. You would not include `card.present` in the capture, which is the subsequent request. Another example is when performing an incremental authorization where you perform an authorization, followed by an incremental authorization then a capture. The second authorization (incremental) and the capture are the subsequent requests where you would not include `card.present`. - `transaction` object, required - `invoice` string, required — 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 batch in Shift4's Gateway. **Note: For US and Canadian processing: Although the invoice number is sent as a JSON string it is a numeric value. No alpha characters are allowed.** **For processing outside of the US and Canada alpha characters are allowed.** - `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) - GiftcardsReloadP2peTdesdukptMsr - `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 - `amount` AmountGC, required — Object containing information regarding the amount being added onto the card or removed from the card. - `total` number, required — The amount which should be added to the card's balance. Amount cannot be zero. - `checkTotal` 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 the check is being split or if a portion of the check was already paid in cash or another form of payment. - `card` object, required - `present` 'Y' | 'N', required — **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 should be set appropriately in the initial authorization/sale request. In subsequent requests, this field should be left blank or should not be sent. **Note:** Subsequent request here does not apply to the secondary request for card on file type transactions or reuse of the same card. An example of a subsequent request would be a capture after an authorization. You would not include `card.present` in the capture, which is the subsequent request. Another example is when performing an incremental authorization where you perform an authorization, followed by an incremental authorization then a capture. The second authorization (incremental) and the capture are the subsequent requests where you would not include `card.present`. - `transaction` object, required - `invoice` string, required — 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 batch in Shift4's Gateway. **Note: For US and Canadian processing: Although the invoice number is sent as a JSON string it is a numeric value. No alpha characters are allowed.** **For processing outside of the US and Canada alpha characters are allowed.** - `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. - GiftcardsReloadP2peOnguardsdeMsr - `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 - `amount` AmountGC, required — Object containing information regarding the amount being added onto the card or removed from the card. - `total` number, required — The amount which should be added to the card's balance. Amount cannot be zero. - `checkTotal` 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 the check is being split or if a portion of the check was already paid in cash or another form of payment. - `card` object, required - `present` 'Y' | 'N', required — **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 should be set appropriately in the initial authorization/sale request. In subsequent requests, this field should be left blank or should not be sent. **Note:** Subsequent request here does not apply to the secondary request for card on file type transactions or reuse of the same card. An example of a subsequent request would be a capture after an authorization. You would not include `card.present` in the capture, which is the subsequent request. Another example is when performing an incremental authorization where you perform an authorization, followed by an incremental authorization then a capture. The second authorization (incremental) and the capture are the subsequent requests where you would not include `card.present`. - `transaction` object, required - `invoice` string, required — 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 batch in Shift4's Gateway. **Note: For US and Canadian processing: Although the invoice number is sent as a JSON string it is a numeric value. No alpha characters are allowed.** **For processing outside of the US and Canada alpha characters are allowed.** - `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 - GiftcardsReloadUnencryptedcard - `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 - `amount` AmountGC, required — Object containing information regarding the amount being added onto the card or removed from the card. - `total` number, required — The amount which should be added to the card's balance. Amount cannot be zero. - `checkTotal` 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 the check is being split or if a portion of the check was already paid in cash or another form of payment. - `card` object, required - `present` 'Y' | 'N', required — **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 should be set appropriately in the initial authorization/sale request. In subsequent requests, this field should be left blank or should not be sent. **Note:** Subsequent request here does not apply to the secondary request for card on file type transactions or reuse of the same card. An example of a subsequent request would be a capture after an authorization. You would not include `card.present` in the capture, which is the subsequent request. Another example is when performing an incremental authorization where you perform an authorization, followed by an incremental authorization then a capture. The second authorization (incremental) and the capture are the subsequent requests where you would not include `card.present`. - `number` string, required — The payment card number. This field will always be masked when returned in a response. - `expirationDate` 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 an encrypted device.** Card expiration date in MMYY format. - `securityCode` CardSecurityCodeGC - `value` 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 requests depending on a card's settings. It should not be stored by the interface. - `transaction` object, required - `invoice` string, required — 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 batch in Shift4's Gateway. **Note: For US and Canadian processing: Although the invoice number is sent as a JSON string it is a numeric value. No alpha characters are allowed.** **For processing outside of the US and Canada alpha characters are allowed.** ## Response `200` Transaction was processed - object - `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 - `amount` AmountGCResponse — Object containing information regarding the amount being added onto the card or removed from the card. - `total` number, required — For [Activate](/apis/payments-platform-rest/openapi/gift-cards/activate), [Allocate](/apis/payments-platform-rest/openapi/gift-cards/allocate) or [Reload](/apis/payments-platform-rest/openapi/gift-cards/reload) requests, this is the amount which was added to the card's balance. For [Cashout](/apis/payments-platform-rest/openapi/gift-cards/cashout) requests, this is the amount of cash that should be provided to the customer. - `card` CardResponseGC - `number` string — The card number field will always be masked when returned in a response. - `type` 'GC' | 'YC' — An abbreviation used to specify the type of card that was used when processing a transaction. Value| Description -----|------------ GC | Gift Card YC | IT’S YOUR CARD - `balance` CardBalance - `amount` 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 stored value card. - `token` CardTokenGCResponse - `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. - `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. - `transaction` object - `authSource` 'E' | 'O' | 'A' | 'F' — In a response, a code returned by the processor to indicate which host issued the response. Value | Description -------|---------------------------- E | Engine (Online) O | Offline A | APM (Online) F | Payment Platform (Online) - `authorizationCode` 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 a referral response, it is also specified in [Manual Sale](/apis/payments-platform-rest/openapi/transactions/manualsale) requests. - `invoice` 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 batch in Shift4's Gateway. **Note: For US and Canadian processing: Although the invoice number is sent as a JSON string it is a numeric value. No alpha characters are allowed.** **For processing outside of the US and Canada alpha characters are allowed.** - `responseCode` 'A' | 'C' | 'D' | 'e' | 'f' | 'P' | 'R' | 'X' | 'S' | 'I' — Code indicating the Shift4 host response. Value | Description | Details -------|---------------------------------------------------------------------------------------|-------- A | Approved | The transaction is approved. C | Approved | The transaction is approved without requiring additional authorization because it is less than or equal to a ceiling amount. (The ceiling amount is the original authorization amount multiplied by the tolerance per the merchant’s settings with Shift4.) D | Declined | The transaction is declined. Note: Shift4 automatically declines AVS/CSC failures if the [POSHANDLEAVSFAIL Api Option](/guides/appendices/api-options#poshandleavsfail) was not sent in the request. e | [Error](/guides/appendices/error-codes) | There is an error condition. f | [AVS or CSC failure](/guides/response-handling/understanding-avs-and-csc-verification)| An AVS or CSC failure has occurred (credit card only). Note: This value will only be returned if the [POSHANDLEAVSFAIL Api Option](/guides/appendices/api-options#poshandleavsfail) was sent in the request. P | [Partial approval](/guides/advanced-concepts/partial-approval) | A partial approval has occurred. Check `amount.total` for the approved amount. R | Voice referral | The transaction requires a voice referral. [blank]| Status is unknown | The approval status is unknown. X | Expired card | There is an error condition due to the card being expired. S | SCA Online PIN required | The contactless EMV transaction requires strong customer authentication to continue. The terminal must gather the online PIN if supported by the device form factor and CVM list then resubmit the transaction request. I | SCA Interface switch required | The contactless EMV transaction requires strong customer authentication to continue. The terminal must look at the form factor indicator to determine if the transaction should be declined, switched to EMV contact or tapped again using CDCVM. J | Soft decline after exemption request | Transaction was soft declined. Returned when requesting an exemption by sending `transaction.exemptionAction = 02` and the card issuer rejects the exemption. - `universalToken` UniversalToken - `value` string — An identifier for a card or payment account across all Shift4 merchants. ## 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)