openapi: 3.2.0
info:
version: 1.7.57
title: Shift4 Payment Gift Cards API
contact:
url: https://www.shift4.com/contact-us/
servers:
- url: https://api.shift4test.com/api/rest/v1
description: Host Direct Test URL
- url: https://api.shift4api.net/api/rest/v1
description: Host Direct Production URL
tags:
- name: Gift Cards
paths:
/giftcards/activate:
servers:
- url: https://api.shift4test.com/api/rest/v1
description: Host Direct Test URL
- url: https://api.shift4api.net/api/rest/v1
description: Host Direct Production URL
- url: https://192.168.1.10:277/api/rest/v1
description: Locally Installed UTG URL
- url: https://192.168.1.20:8085/api/rest/v1
description: Commerce Engine For On Premise URL
- url: https://api.shift4test.com/api/rest/v1
description: Commerce Engine For Cloud Test URL
- url: https://api.shift4api.net/api/rest/v1
description: Commerce Engine For Cloud Production URL
post:
tags:
- Gift Cards
summary: Activate
operationId: activate
security:
- AccessToken: []
description: 'This function requests that a new gift card be activated for use or that a new gift card be loaded with 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.
'
parameters:
- $ref: '#/components/parameters/InterfaceVersion'
- $ref: '#/components/parameters/InterfaceName'
- $ref: '#/components/parameters/CompanyName'
- $ref: '#/components/parameters/AccessToken'
requestBody:
required: true
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/giftcards_activate_comengdevice'
- $ref: '#/components/schemas/giftcards_activate_comengcloud'
- $ref: '#/components/schemas/giftcards_activate_utgdevice'
- $ref: '#/components/schemas/giftcards_activate_token_gtv'
- $ref: '#/components/schemas/giftcards_activate_token_legacy'
- $ref: '#/components/schemas/giftcards_activate_p2pe_idtech'
- $ref: '#/components/schemas/giftcards_activate_p2pe_tdesdukpt_msr'
- $ref: '#/components/schemas/giftcards_activate_p2pe_onguardsde_msr'
- $ref: '#/components/schemas/giftcards_activate_unencryptedcard'
responses:
'200':
description: Transaction was processed
content:
application/json:
schema:
properties:
result:
type: array
items:
type: object
properties:
dateTime:
$ref: '#/components/schemas/DateTime'
amount:
$ref: '#/components/schemas/AmountGCResponse'
card:
$ref: '#/components/schemas/CardResponseGC'
device:
$ref: '#/components/schemas/DeviceOnlyTIDResponse'
merchant:
$ref: '#/components/schemas/MerchantResponse'
server:
$ref: '#/components/schemas/Server'
transaction:
type: object
properties:
authSource:
$ref: '#/components/schemas/TransactionAuthSource'
invoice:
$ref: '#/components/schemas/TransactionInvoice'
responseCode:
$ref: '#/components/schemas/TransactionResponseCode'
example:
result:
- dateTime: '2021-04-15T09:18:23.283-07:00'
amount:
total: 20
card:
number: XXXXXXXXXXXX1333
balance:
amount: 20
token:
value: '8058471748050009'
type: YC
device:
terminalId: '1742'
merchant:
mid: 15877
name: Merchant XYZ
server:
name: UTGAPI01CE
transaction:
authSource: E
invoice: '192030'
responseCode: A
'400':
description: Error
content:
application/json:
schema:
properties:
result:
type: array
items:
type: object
properties:
error:
$ref: '#/components/schemas/Error'
server:
$ref: '#/components/schemas/Server'
examples:
Error:
$ref: '#/components/examples/GiftCardActivateError'
'504':
$ref: '#/components/responses/TimeoutResponse'
/giftcards/allocate:
servers:
- url: https://api.shift4test.com/api/rest/v1
description: Host Direct Test URL
- url: https://api.shift4api.net/api/rest/v1
description: Host Direct Production URL
- url: https://192.168.1.10:277/api/rest/v1
description: Locally Installed UTG URL
post:
tags:
- Gift Cards
summary: Allocate
operationId: allocate
security:
- AccessToken: []
description: 'This function requests that a new gift card be allocated for use under a specific Program ID. The new card will be generated during the request and activated with the requested amount.
**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.
'
parameters:
- $ref: '#/components/parameters/InterfaceVersion'
- $ref: '#/components/parameters/InterfaceName'
- $ref: '#/components/parameters/CompanyName'
- $ref: '#/components/parameters/AccessToken'
requestBody:
required: true
content:
application/json:
schema:
required:
- dateTime
- amount
- transaction
properties:
dateTime:
$ref: '#/components/schemas/DateTime'
amount:
$ref: '#/components/schemas/AmountGC'
programId:
$ref: '#/components/schemas/ProgramId'
transaction:
type: object
required:
- invoice
properties:
invoice:
$ref: '#/components/schemas/TransactionInvoice'
example:
dateTime: '2021-04-15T09:18:23.283-07:00'
amount:
total: 25
programId: '95'
transaction:
invoice: '192029'
responses:
'200':
description: Transaction was processed
content:
application/json:
schema:
properties:
result:
type: array
items:
type: object
properties:
dateTime:
$ref: '#/components/schemas/DateTime'
amount:
$ref: '#/components/schemas/AmountGCResponse'
card:
type: object
properties:
number:
type: string
maxLength: 32
description: 'The gift card number that was created during the gift card allocate request.
'
type:
$ref: '#/components/schemas/CardTypeGCResp'
balance:
$ref: '#/components/schemas/CardBalance'
merchant:
$ref: '#/components/schemas/MerchantResponse'
programId:
$ref: '#/components/schemas/ProgramId'
server:
$ref: '#/components/schemas/Server'
transaction:
type: object
properties:
invoice:
$ref: '#/components/schemas/TransactionInvoice'
responseCode:
$ref: '#/components/schemas/TransactionResponseCode'
example:
result:
- dateTime: '2021-04-15T09:18:23.283-07:00'
amount:
total: 20
card:
number: '1000083000004141494'
type: GC
balance:
amount: 20
merchant:
mid: 15877
name: Merchant XYZ
programId: '95'
server:
name: UTGAPI01CE
transaction:
invoice: '192029'
responseCode: A
'400':
description: Error
content:
application/json:
schema:
properties:
result:
type: array
items:
type: object
properties:
error:
$ref: '#/components/schemas/Error'
server:
$ref: '#/components/schemas/Server'
example:
result:
- error:
longText: 'ALLOCATE Failed: Need sample error'
primaryCode: 9101
secondaryCode: 0
shortText: ALLOCATE FAILED
server:
name: U2API01CE
'504':
$ref: '#/components/responses/TimeoutResponse'
/giftcards/deactivate:
servers:
- url: https://api.shift4test.com/api/rest/v1
description: Host Direct Test URL
- url: https://api.shift4api.net/api/rest/v1
description: Host Direct Production URL
- url: https://192.168.1.10:277/api/rest/v1
description: Locally Installed UTG URL
- url: https://192.168.1.20:8085/api/rest/v1
description: Commerce Engine For On Premise URL
- url: https://api.shift4test.com/api/rest/v1
description: Commerce Engine For Cloud Test URL
- url: https://api.shift4api.net/api/rest/v1
description: Commerce Engine For Cloud Production URL
post:
tags:
- Gift Cards
summary: Deactivate
operationId: deactivate
security:
- AccessToken: []
description: 'This function requests that an active gift card be deactivated so that it can’t be used to process transactions. A balance will remain on the gift card (if supported by the processor). If you want to return the card''s current balance back to the customer, use the [Cashout](/apis/payments-platform-rest/openapi/gift-cards/cashout) endpoint instead.
**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.
'
parameters:
- $ref: '#/components/parameters/InterfaceVersion'
- $ref: '#/components/parameters/InterfaceName'
- $ref: '#/components/parameters/CompanyName'
- $ref: '#/components/parameters/AccessToken'
requestBody:
required: true
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/giftcards_deactivate_comengdevice'
- $ref: '#/components/schemas/giftcards_deactivate_comengcloud'
- $ref: '#/components/schemas/giftcards_deactivate_utgdevice'
- $ref: '#/components/schemas/giftcards_deactivate_token_gtv'
- $ref: '#/components/schemas/giftcards_deactivate_token_legacy'
- $ref: '#/components/schemas/giftcards_deactivate_p2pe_idtech'
- $ref: '#/components/schemas/giftcards_deactivate_p2pe_tdesdukpt_msr'
- $ref: '#/components/schemas/giftcards_deactivate_p2pe_onguardsde_msr'
- $ref: '#/components/schemas/giftcards_deactivate_unencryptedcard'
responses:
'200':
description: Transaction was processed
content:
application/json:
schema:
properties:
result:
type: array
items:
type: object
properties:
dateTime:
$ref: '#/components/schemas/DateTime'
card:
$ref: '#/components/schemas/CardResponseDeact'
device:
$ref: '#/components/schemas/DeviceOnlyTIDResponse'
merchant:
$ref: '#/components/schemas/MerchantResponse'
server:
$ref: '#/components/schemas/Server'
transaction:
type: object
properties:
authSource:
$ref: '#/components/schemas/TransactionAuthSource'
invoice:
$ref: '#/components/schemas/TransactionInvoice'
responseCode:
$ref: '#/components/schemas/TransactionResponseCode'
universalToken:
$ref: '#/components/schemas/UniversalToken'
example:
result:
- dateTime: '2021-04-15T09:18:23.283-07:00'
card:
entryMode: '1'
number: XXXXXXXXXXXX1333
present: Y
deactivationReason: lost or stolen
balance:
amount: 20
token:
value: 0009hfqbt8b396x1
type: YC
device:
terminalId: '1742'
merchant:
mid: 15877
name: Merchant XYZ
server:
name: UTGAPI01CE
transaction:
authSource: E
invoice: '192032'
responseCode: A
'400':
$ref: '#/components/responses/CardTokenErrorResponse'
'504':
$ref: '#/components/responses/TimeoutResponse'
/giftcards/cashout:
servers:
- url: https://api.shift4test.com/api/rest/v1
description: Host Direct Test URL
- url: https://api.shift4api.net/api/rest/v1
description: Host Direct Production URL
- url: https://192.168.1.10:277/api/rest/v1
description: Locally Installed UTG URL
- url: https://192.168.1.20:8085/api/rest/v1
description: Commerce Engine For On Premise URL
- url: https://api.shift4test.com/api/rest/v1
description: Commerce Engine For Cloud Test URL
- url: https://api.shift4api.net/api/rest/v1
description: Commerce Engine For Cloud Production URL
post:
deprecated: true
tags:
- Gift Cards
summary: Cashout
operationId: cashout
security:
- AccessToken: []
description: "This function requests that an active gift card be deactivated so that it can’t be used to process transactions. Any current balance is removed from the card so that the funds can be returned to the consumer as cash. \n\n**This endpoint has been deprecated and should no longer be used. It has been replaced by the [Gift Card Cashback](/apis/payments-platform-rest/openapi/gift-cards/cashback) endpoint.**\n\n**Integration Methods:**\n- Host Direct\n- Locally Installed UTG\n- Commerce Engine For On Premise\n- Commerce Engine For Cloud\n\nSee 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.\n\nSee the [JSON Body Schemas](/guides/quickstart#json-body-schemas) for more details on the various JSON body formats.\n"
parameters:
- $ref: '#/components/parameters/InterfaceVersion'
- $ref: '#/components/parameters/InterfaceName'
- $ref: '#/components/parameters/CompanyName'
- $ref: '#/components/parameters/AccessToken'
requestBody:
required: true
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/giftcards_cashout_comengdevice'
- $ref: '#/components/schemas/giftcards_cashout_comengcloud'
- $ref: '#/components/schemas/giftcards_cashout_utgdevice'
- $ref: '#/components/schemas/giftcards_cashout_token_gtv'
- $ref: '#/components/schemas/giftcards_cashout_token_legacy'
- $ref: '#/components/schemas/giftcards_cashout_p2pe_idtech'
- $ref: '#/components/schemas/giftcards_cashout_p2pe_tdesdukpt_msr'
- $ref: '#/components/schemas/giftcards_cashout_p2pe_onguardsde_msr'
- $ref: '#/components/schemas/giftcards_cashout_unencryptedcard'
responses:
'200':
description: Transaction was processed
content:
application/json:
schema:
properties:
result:
type: array
items:
type: object
properties:
dateTime:
$ref: '#/components/schemas/DateTime'
amount:
$ref: '#/components/schemas/AmountGCResponse'
card:
$ref: '#/components/schemas/CardResponseCashout'
device:
$ref: '#/components/schemas/DeviceOnlyTIDResponse'
merchant:
$ref: '#/components/schemas/MerchantResponse'
server:
$ref: '#/components/schemas/Server'
transaction:
type: object
properties:
authSource:
$ref: '#/components/schemas/TransactionAuthSource'
invoice:
$ref: '#/components/schemas/TransactionInvoice'
responseCode:
$ref: '#/components/schemas/TransactionResponseCode'
universalToken:
$ref: '#/components/schemas/UniversalToken'
example:
result:
- dateTime: '2021-04-15T09:18:23.283-07:00'
amount:
total: 20
card:
entryMode: '1'
number: XXXXXXXXXXXX1333
present: Y
deactivationReason: lost or stolen
token:
value: 0009hfqbt8b396x1
type: YC
device:
terminalId: '1742'
merchant:
mid: 15877
name: Merchant XYZ
server:
name: UTGAPI01CE
transaction:
authSource: E
invoice: '192034'
responseCode: A
'400':
$ref: '#/components/responses/CardTokenErrorResponse'
'504':
$ref: '#/components/responses/TimeoutResponse'
/giftcards/cashback:
servers:
- url: https://api.shift4test.com/api/rest/v1
description: Host Direct Test URL
- url: https://api.shift4api.net/api/rest/v1
description: Host Direct Production URL
- url: https://192.168.1.10:277/api/rest/v1
description: Locally Installed UTG URL
- url: https://192.168.1.20:8085/api/rest/v1
description: Commerce Engine For On Premise URL
- url: https://api.shift4test.com/api/rest/v1
description: Commerce Engine For Cloud Test URL
- url: https://api.shift4api.net/api/rest/v1
description: Commerce Engine For Cloud Production URL
post:
tags:
- Gift Cards
summary: Cashback
operationId: cashback
security:
- AccessToken: []
description: "This function requests that an active gift card be deactivated so that it can’t be used to process transactions. Any current balance is removed from the card so that the funds can be returned to the consumer as cash. \n\n**This endpoint replaces the [Gift Card Cashout](/apis/payments-platform-rest/openapi/gift-cards/cashout) endpoint.**\n\n**Integration Methods:**\n- Host Direct\n- Locally Installed UTG\n- Commerce Engine For On Premise\n- Commerce Engine For Cloud\n\nSee 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.\n\nSee the [JSON Body Schemas](/guides/quickstart#json-body-schemas) for more details on the various JSON body formats.\n"
parameters:
- $ref: '#/components/parameters/InterfaceVersion'
- $ref: '#/components/parameters/InterfaceName'
- $ref: '#/components/parameters/CompanyName'
- $ref: '#/components/parameters/AccessToken'
requestBody:
required: true
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/giftcards_cashout_comengdevice'
- $ref: '#/components/schemas/giftcards_cashout_comengcloud'
- $ref: '#/components/schemas/giftcards_cashout_utgdevice'
- $ref: '#/components/schemas/giftcards_cashout_token_gtv'
- $ref: '#/components/schemas/giftcards_cashout_token_legacy'
- $ref: '#/components/schemas/giftcards_cashout_p2pe_idtech'
- $ref: '#/components/schemas/giftcards_cashout_p2pe_tdesdukpt_msr'
- $ref: '#/components/schemas/giftcards_cashout_p2pe_onguardsde_msr'
- $ref: '#/components/schemas/giftcards_cashout_unencryptedcard'
responses:
'200':
description: Transaction was processed
content:
application/json:
schema:
properties:
result:
type: array
items:
type: object
properties:
dateTime:
$ref: '#/components/schemas/DateTime'
amount:
$ref: '#/components/schemas/AmountGCResponse'
card:
$ref: '#/components/schemas/CardResponseCashout'
device:
$ref: '#/components/schemas/DeviceOnlyTIDResponse'
merchant:
$ref: '#/components/schemas/MerchantResponse'
server:
$ref: '#/components/schemas/Server'
transaction:
type: object
properties:
authSource:
$ref: '#/components/schemas/TransactionAuthSource'
invoice:
$ref: '#/components/schemas/TransactionInvoice'
responseCode:
$ref: '#/components/schemas/TransactionResponseCode'
universalToken:
$ref: '#/components/schemas/UniversalToken'
example:
result:
- dateTime: '2021-04-15T09:18:23.283-07:00'
amount:
total: 20
card:
entryMode: '1'
number: XXXXXXXXXXXX1333
present: Y
deactivationReason: lost or stolen
token:
value: 0009hfqbt8b396x1
type: YC
device:
terminalId: '1742'
merchant:
mid: 15877
name: Merchant XYZ
server:
name: UTGAPI01CE
transaction:
authSource: E
invoice: '192034'
responseCode: A
'400':
$ref: '#/components/responses/CardTokenErrorResponse'
'504':
$ref: '#/components/responses/TimeoutResponse'
/giftcards/reactivate:
servers:
- url: https://api.shift4test.com/api/rest/v1
description: Host Direct Test URL
- url: https://api.shift4api.net/api/rest/v1
description: Host Direct Production URL
- url: https://192.168.1.10:277/api/rest/v1
description: Locally Installed UTG URL
- url: https://192.168.1.20:8085/api/rest/v1
description: Commerce Engine For On Premise URL
- url: https://api.shift4test.com/api/rest/v1
description: Commerce Engine For Cloud Test URL
- url: https://api.shift4api.net/api/rest/v1
description: Commerce Engine For Cloud Production URL
post:
tags:
- Gift Cards
summary: Reactivate
operationId: reactivate
security:
- AccessToken: []
description: 'This function requests that a previously deactivated gift card be reactivated. If there was a balance remaining on the gift card at the time of deactivation, the balance will again become available for use. Funds cannot be added to a gift card during a Reactivate request.
**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.
'
parameters:
- $ref: '#/components/parameters/InterfaceVersion'
- $ref: '#/components/parameters/InterfaceName'
- $ref: '#/components/parameters/CompanyName'
- $ref: '#/components/parameters/AccessToken'
requestBody:
required: true
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/giftcards_reactivate_comengdevice'
- $ref: '#/components/schemas/giftcards_reactivate_comengcloud'
- $ref: '#/components/schemas/giftcards_reactivate_utgdevice'
- $ref: '#/components/schemas/giftcards_reactivate_token_gtv'
- $ref: '#/components/schemas/giftcards_reactivate_token_legacy'
- $ref: '#/components/schemas/giftcards_reactivate_p2pe_idtech'
- $ref: '#/components/schemas/giftcards_reactivate_p2pe_tdesdukpt_msr'
- $ref: '#/components/schemas/giftcards_reactivate_p2pe_onguardsde_msr'
- $ref: '#/components/schemas/giftcards_reactivate_unencryptedcard'
responses:
'200':
description: Transaction was processed
content:
application/json:
schema:
properties:
result:
type: array
items:
type: object
properties:
dateTime:
$ref: '#/components/schemas/DateTime'
card:
$ref: '#/components/schemas/CardResponseGC'
device:
$ref: '#/components/schemas/DeviceOnlyTIDResponse'
merchant:
$ref: '#/components/schemas/MerchantResponse'
server:
$ref: '#/components/schemas/Server'
transaction:
type: object
properties:
authSource:
$ref: '#/components/schemas/TransactionAuthSource'
invoice:
$ref: '#/components/schemas/TransactionInvoice'
responseCode:
$ref: '#/components/schemas/TransactionResponseCode'
universalToken:
$ref: '#/components/schemas/UniversalToken'
example:
result:
- dateTime: '2021-04-15T09:18:23.283-07:00'
card:
number: XXXXXXXXXXXX1333
balance:
amount: 30
token:
value: 0009hfqbt8b396x1
type: YC
device:
terminalId: '1742'
merchant:
mid: 15877
name: Merchant XYZ
server:
name: UTGAPI01CE
transaction:
authSource: E
invoice: '192033'
responseCode: A
'400':
$ref: '#/components/responses/CardTokenErrorResponse'
'504':
$ref: '#/components/responses/TimeoutResponse'
/giftcards/reload:
servers:
- url: https://api.shift4test.com/api/rest/v1
description: Host Direct Test URL
- url: https://api.shift4api.net/api/rest/v1
description: Host Direct Production URL
- url: https://192.168.1.10:277/api/rest/v1
description: Locally Installed UTG URL
- url: https://192.168.1.20:8085/api/rest/v1
description: Commerce Engine For On Premise URL
- url: https://api.shift4test.com/api/rest/v1
description: Commerce Engine For Cloud Test URL
- url: https://api.shift4api.net/api/rest/v1
description: Commerce Engine For Cloud Production URL
post:
tags:
- Gift Cards
summary: Reload
operationId: reload
security:
- AccessToken: []
description: '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.
'
parameters:
- $ref: '#/components/parameters/InterfaceVersion'
- $ref: '#/components/parameters/InterfaceName'
- $ref: '#/components/parameters/CompanyName'
- $ref: '#/components/parameters/AccessToken'
requestBody:
required: true
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/giftcards_reload_comengdevice'
- $ref: '#/components/schemas/giftcards_reload_comengcloud'
- $ref: '#/components/schemas/giftcards_reload_utgdevice'
- $ref: '#/components/schemas/giftcards_reload_token_gtv'
- $ref: '#/components/schemas/giftcards_reload_token_legacy'
- $ref: '#/components/schemas/giftcards_reload_p2pe_idtech'
- $ref: '#/components/schemas/giftcards_reload_p2pe_tdesdukpt_msr'
- $ref: '#/components/schemas/giftcards_reload_p2pe_onguardsde_msr'
- $ref: '#/components/schemas/giftcards_reload_unencryptedcard'
responses:
'200':
description: Transaction was processed
content:
application/json:
schema:
properties:
result:
type: array
items:
type: object
properties:
dateTime:
$ref: '#/components/schemas/DateTime'
amount:
$ref: '#/components/schemas/AmountGCResponse'
card:
$ref: '#/components/schemas/CardResponseGC'
device:
$ref: '#/components/schemas/DeviceOnlyTIDResponse'
merchant:
$ref: '#/components/schemas/MerchantResponse'
server:
$ref: '#/components/schemas/Server'
transaction:
type: object
properties:
authSource:
$ref: '#/components/schemas/TransactionAuthSource'
authorizationCode:
$ref: '#/components/schemas/TransactionAuthorizationCode'
invoice:
$ref: '#/components/schemas/TransactionInvoice'
responseCode:
$ref: '#/components/schemas/TransactionResponseCode'
universalToken:
$ref: '#/components/schemas/UniversalToken'
example:
result:
- dateTime: '2021-04-15T09:18:23.283-07:00'
amount:
total: 20
card:
number: XXXXXXXXXXXX1333
balance:
amount: 30
token:
value: 0009hfqbt8b396x1
type: YC
device:
terminalId: '1742'
merchant:
mid: 15877
name: Merchant XYZ
server:
name: UTGAPI01CE
transaction:
authSource: E
invoice: '192031'
responseCode: A
'400':
$ref: '#/components/responses/CardTokenErrorResponse'
'504':
$ref: '#/components/responses/TimeoutResponse'
/giftcards/balance:
servers:
- url: https://api.shift4test.com/api/rest/v1
description: Host Direct Test URL
- url: https://api.shift4api.net/api/rest/v1
description: Host Direct Production URL
- url: https://192.168.1.10:277/api/rest/v1
description: Locally Installed UTG URL
- url: https://192.168.1.20:8085/api/rest/v1
description: Commerce Engine For On Premise URL
- url: https://api.shift4test.com/api/rest/v1
description: Commerce Engine For Cloud Test URL
- url: https://api.shift4api.net/api/rest/v1
description: Commerce Engine For Cloud Production URL
post:
tags:
- Gift Cards
summary: Balance
operationId: balance
security:
- AccessToken: []
description: 'This function requests that a gift card''s balance, masked card number, expiration date, and discount percentage be returned. Merchants may be required to pay a fee for an inquiry request depending on their processor agreement.
**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.
'
parameters:
- $ref: '#/components/parameters/InterfaceVersion'
- $ref: '#/components/parameters/InterfaceName'
- $ref: '#/components/parameters/CompanyName'
- $ref: '#/components/parameters/AccessToken'
requestBody:
required: true
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/giftcards_balance_comengdevice'
- $ref: '#/components/schemas/giftcards_balance_comengcloud'
- $ref: '#/components/schemas/giftcards_balance_utgdevice'
- $ref: '#/components/schemas/giftcards_balance_token_gtv'
- $ref: '#/components/schemas/giftcards_balance_token_legacy'
- $ref: '#/components/schemas/giftcards_balance_p2pe_idtech'
- $ref: '#/components/schemas/giftcards_balance_p2pe_tdesdukpt_msr'
- $ref: '#/components/schemas/giftcards_balance_p2pe_onguardsde_msr'
- $ref: '#/components/schemas/giftcards_balance_unencryptedcard'
responses:
'200':
description: Transaction was processed
content:
application/json:
schema:
properties:
result:
type: array
items:
type: object
properties:
dateTime:
$ref: '#/components/schemas/DateTime'
card:
$ref: '#/components/schemas/CardResponseDeact'
device:
$ref: '#/components/schemas/DeviceOnlyTIDResponse'
merchant:
$ref: '#/components/schemas/MerchantResponse'
server:
$ref: '#/components/schemas/Server'
transaction:
type: object
properties:
authSource:
$ref: '#/components/schemas/TransactionAuthSource'
invoice:
$ref: '#/components/schemas/TransactionInvoice'
responseCode:
$ref: '#/components/schemas/TransactionResponseCode'
universalToken:
$ref: '#/components/schemas/UniversalToken'
history:
type: array
description: 'Returned if `RETURNHIST` is sent in `apiOptions`.
'
items:
type: object
properties:
dateTime:
$ref: '#/components/schemas/DateTime'
amount:
$ref: '#/components/schemas/AmountTotalOnly'
transactionType:
type: string
enum:
- Sale
- Activate
- Allocate
- Deactivate
- Cashback
- Reactivate
- Reload
- Balance
- Cancel
description: 'The gift card transaction type
'
examples:
Active:
summary: Active Card
value:
result:
- dateTime: '2019-04-15T16:10:44.000-07:00'
card:
balance:
amount: 20
entryMode: M
number: XXXXXXXXXXXX1333
token:
value: 1333jd4nmj9p787m
type: YC
merchant:
mid: 15877
name: Merchant XYZ
server:
name: U2API01CE
transaction:
authSource: E
invoice: '6241932450'
responseCode: A
history:
- dateTime: '2019-04-12T08:13:23.000-07:00'
amount:
total: 80
transactionType: Sale
- dateTime: '2019-03-12T08:10:44.000-07:00'
amount:
total: 100
transactionType: Activate
Inactive:
summary: Inactive Card
value:
result:
- dateTime: '2021-04-15T09:18:23.283-07:00'
card:
balance:
amount: 24.33
deactivationReason: lost or stolen
entryMode: M
number: XXXXXXXXXXXX8774
present: Y
token:
value: 87743q5p3ffhv67y
type: YC
merchant:
mid: 15877
name: Merchant XYZ
server:
name: U2API01CE
transaction:
authSource: E
invoice: '192029'
responseCode: A
'400':
$ref: '#/components/responses/CardTokenErrorResponse'
'504':
$ref: '#/components/responses/TimeoutResponse'
/giftcards/cancel:
servers:
- url: https://api.shift4test.com/api/rest/v1
description: Host Direct Test URL
- url: https://api.shift4api.net/api/rest/v1
description: Host Direct Production URL
- url: https://192.168.1.10:277/api/rest/v1
description: Locally Installed UTG URL
- url: https://192.168.1.20:8085/api/rest/v1
description: Commerce Engine For On Premise URL
- url: https://api.shift4test.com/api/rest/v1
description: Commerce Engine For Cloud Test URL
- url: https://api.shift4api.net/api/rest/v1
description: Commerce Engine For Cloud Production URL
post:
tags:
- Gift Cards
summary: Cancel
operationId: cancel
security:
- AccessToken: []
description: 'This function attempts to undo the last /giftcards/* request that was made against a gift card or private label card. For example, an Activate or Reload request may eligible for cancellation. Some processors do not support this functionality. This endpoint cannot be used to cancel a sale or authorization against a gift card - the Void request should be used for that scenario.
**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.
'
parameters:
- $ref: '#/components/parameters/InterfaceVersion'
- $ref: '#/components/parameters/InterfaceName'
- $ref: '#/components/parameters/CompanyName'
- $ref: '#/components/parameters/AccessToken'
requestBody:
required: true
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/giftcards_cancel_token_gtv'
- $ref: '#/components/schemas/giftcards_cancel_token_legacy'
responses:
'200':
description: Transaction was processed
content:
application/json:
schema:
properties:
result:
type: array
items:
type: object
properties:
dateTime:
$ref: '#/components/schemas/DateTime'
amount:
$ref: '#/components/schemas/AmountGCResponse'
card:
$ref: '#/components/schemas/CardResponseGC'
device:
$ref: '#/components/schemas/DeviceOnlyTIDResponse'
merchant:
$ref: '#/components/schemas/MerchantResponse'
transaction:
type: object
properties:
invoice:
$ref: '#/components/schemas/TransactionInvoice'
responseCode:
$ref: '#/components/schemas/TransactionResponseCode'
server:
$ref: '#/components/schemas/Server'
'400':
$ref: '#/components/responses/CardTokenErrorResponse'
'504':
$ref: '#/components/responses/TimeoutResponse'
components:
schemas:
P2PEType0102IDTECH:
type: object
required:
- data
- format
properties:
data:
$ref: '#/components/schemas/P2PEData'
format:
$ref: '#/components/schemas/P2PEFormatIDTech'
giftcards_deactivate_utgdevice:
title: UTG Controlled Device
type: object
required:
- dateTime
- device
- card
- transaction
properties:
dateTime:
$ref: '#/components/schemas/DateTime'
card:
type: object
required:
- deactivationReason
- present
properties:
deactivationReason:
$ref: '#/components/schemas/CardDeactivationReason'
present:
$ref: '#/components/schemas/CardPresent'
device:
type: object
required:
- terminalId
properties:
terminalId:
$ref: '#/components/schemas/DeviceTerminalId'
promptCardSecurityCode:
$ref: '#/components/schemas/DevicePromptCardSecurityCode'
transaction:
type: object
required:
- invoice
properties:
invoice:
$ref: '#/components/schemas/TransactionInvoice'
example:
dateTime: '2021-04-15T09:18:23.283-07:00'
card:
deactivationReason: Stolen
present: N
device:
terminalId: '1742'
transaction:
invoice: '192029'
TransactionResponseCode:
type: string
minLength: 1
maxLength: 1
readOnly: true
example: A
enum:
- A
- C
- D
- e
- f
- P
- R
- X
- S
- I
description: "Code indicating the Shift4 host response. \n\nValue | Description | Details\n-------|---------------------------------------------------------------------------------------|--------\nA | Approved | The transaction is approved.\nC | 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.)\nD | 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.\ne | [Error](/guides/appendices/error-codes) | There is an error condition.\nf | [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.\nP | [Partial approval](/guides/advanced-concepts/partial-approval) | A partial approval has occurred. Check `amount.total` for the approved amount.\nR | Voice referral | The transaction requires a voice referral.\n[blank]| Status is unknown | The approval status is unknown.\nX | Expired card | There is an error condition due to the card being expired.\nS | 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.\nI | 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.\nJ | 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.\n"
DeviceCapability:
type: object
writeOnly: true
description: '**Conditional: Required when using a non-UTG-controlled device.**
'
properties:
contactlessEMV:
$ref: '#/components/schemas/DeviceCapabilityContactlessEMV'
contactlessMSR:
$ref: '#/components/schemas/DeviceCapabilityContactlessMSR'
EMV:
$ref: '#/components/schemas/DeviceCapabilityEMV'
manualEntry:
$ref: '#/components/schemas/DeviceCapabilityManualEntry'
magstripe:
$ref: '#/components/schemas/DeviceCapabilityMagstripe'
PIN:
$ref: '#/components/schemas/DeviceCapabilityPIN'
quickChip:
$ref: '#/components/schemas/DeviceCapabilityQuickChip'
signature:
$ref: '#/components/schemas/DeviceCapabilitySignature'
giftcards_balance_p2pe_tdesdukpt_msr:
title: P2PE - TDES DUKPT - MSR/Manual
type: object
required:
- dateTime
- card
- transaction
- p2pe
- device
properties:
dateTime:
$ref: '#/components/schemas/DateTime'
card:
type: object
required:
- present
properties:
present:
$ref: '#/components/schemas/CardPresent'
transaction:
type: object
required:
- invoice
properties:
invoice:
$ref: '#/components/schemas/TransactionInvoice'
device:
type: object
required:
- manufacturer
- model
- serialNumber
- capability
properties:
manufacturer:
$ref: '#/components/schemas/DeviceManufacturer'
model:
$ref: '#/components/schemas/DeviceModel'
serialNumber:
$ref: '#/components/schemas/DeviceSerialNumber'
capability:
$ref: '#/components/schemas/DeviceCapability'
p2pe:
$ref: '#/components/schemas/P2PEType05TDESDUKPTMSR'
apiOptions:
$ref: '#/components/schemas/ApiOptionsGCBalance'
example:
dateTime: '2021-04-15T09:18:23.283-07:00'
card:
present: Y
device:
manufacturer: PAX
model: A930
serialNumber: '1170301234'
capability:
contactlessEMV: Y
contactlessMSR: Y
EMV: Y
magstripe: Y
manualEntry: Y
quickChip: Y
p2pe:
data: 44188C9A20DD2092254F7FEB0AABD531D86EA10DA37E5540C25B53658BA4FBB903828F835A7287481F6FB5C17A879ECC9768D4C12F99532A
format: '05'
ksn: FFFF49517300010000C9
transaction:
invoice: '192029'
P2PEType03OnguardSDEMSR:
type: object
description: 'See [P2PE Format 03 Ingenico On-Guard SDE](/guides/core-concepts/p2pe-format#ingenico-on-guard-sde---format-03) for more information.
'
required:
- data
- format
properties:
data:
$ref: '#/components/schemas/P2PEDataOnguardSDEMSR'
format:
$ref: '#/components/schemas/P2PEFormatOnguardSDE'
UISuppressFinalResult:
type: boolean
example: 'true'
description: 'When `true`, the terminal suppresses the final transaction result screen.
'
giftcards_cashout_p2pe_onguardsde_msr:
title: P2PE - On-Guard SDE - MSR/Manual
type: object
required:
- dateTime
- card
- transaction
- p2pe
- device
properties:
dateTime:
$ref: '#/components/schemas/DateTime'
card:
type: object
required:
- deactivationReason
- present
properties:
deactivationReason:
$ref: '#/components/schemas/CardDeactivationReason'
present:
$ref: '#/components/schemas/CardPresent'
transaction:
type: object
required:
- invoice
properties:
invoice:
$ref: '#/components/schemas/TransactionInvoice'
device:
type: object
required:
- manufacturer
- model
- serialNumber
- capability
properties:
manufacturer:
$ref: '#/components/schemas/DeviceManufacturer'
model:
$ref: '#/components/schemas/DeviceModel'
serialNumber:
$ref: '#/components/schemas/DeviceSerialNumber'
capability:
$ref: '#/components/schemas/DeviceCapability'
p2pe:
$ref: '#/components/schemas/P2PEType03OnguardSDEMSR'
amount:
type: object
properties:
total:
$ref: '#/components/schemas/AmountTotalGCCashback'
example:
dateTime: '2023-12-13T09:18:23.283-07:00'
card:
deactivationReason: Stolen
present: Y
device:
manufacturer: Ingenico
model: Axium DX8000
serialNumber: 20ACCD801843
capability:
contactlessEMV: Y
contactlessMSR: N
EMV: Y
manualEntry: Y
magstripe: Y
PIN: Y
quickChip: Y
signature: Y
p2pe:
data: FFFF495A0000000200000005:4:0128:F48C880DE0DAF549E642C5CC25E65ADF9947E7EB0636DB80C4A490B4C0930AEF64B7201505343CED533A2AE9AFABFE6453875F705519A8109362197CA3BD8DA0FE90DB3F954B9CDA0DB58BDA3330862ADD28CB31EFDA7C641575E33D395D8BFF72EBF0B1FF9630DB0EAB080FE8C9B2FAC28127CDC48CA9F7D532D5BDE4CCE270
format: '03'
transaction:
invoice: '192029'
CardNumberGC:
type: string
maxLength: 32
example: 2664654648774
description: 'The payment card number. This field will always be masked when returned in a response.
'
Error:
type: object
properties:
code:
$ref: '#/components/schemas/ErrorCode'
severity:
$ref: '#/components/schemas/ErrorSeverity'
shortText:
$ref: '#/components/schemas/ErrorShortText'
longText:
$ref: '#/components/schemas/ErrorLongText'
primaryCode:
$ref: '#/components/schemas/ErrorPrimaryCode'
secondaryCode:
$ref: '#/components/schemas/ErrorSecondaryCode'
CardResponseGC:
type: object
properties:
number:
$ref: '#/components/schemas/CardMaskedNumberGC'
type:
$ref: '#/components/schemas/CardTypeGCResp'
balance:
$ref: '#/components/schemas/CardBalance'
token:
$ref: '#/components/schemas/CardTokenGCResponse'
giftcards_reactivate_p2pe_idtech:
title: P2PE - ID TECH - MSR/Manual
type: object
required:
- dateTime
- card
- transaction
- p2pe
properties:
dateTime:
$ref: '#/components/schemas/DateTime'
card:
type: object
required:
- present
properties:
present:
$ref: '#/components/schemas/CardPresent'
transaction:
type: object
required:
- invoice
properties:
invoice:
$ref: '#/components/schemas/TransactionInvoice'
p2pe:
$ref: '#/components/schemas/P2PEType0102IDTECH'
example:
dateTime: '2021-04-15T09:18:23.283-07:00'
card:
present: Y
p2pe:
data: 02B600C0170018009292;000442******0006=3012?*61A0453AB7145F1FA7685D2F27A745E129525EDAEA5BB7DBBAF49A5F876E3EE5000000000000000000000000000000000000000034343454343631383439629949500100382003E6FF4D03
format: '01'
transaction:
invoice: '192029'
MerchantName:
type: string
maxLength: 22
example: Merchant XYZ
description: 'The merchant’s business name as configured with Shift4.
'
giftcards_activate_comengdevice:
title: Commerce Engine For On Premise
type: object
required:
- dateTime
- amount
- card
- transaction
properties:
dateTime:
$ref: '#/components/schemas/DateTime'
amount:
$ref: '#/components/schemas/AmountGC'
card:
type: object
required:
- present
properties:
present:
$ref: '#/components/schemas/CardPresent'
device:
type: object
properties:
terminalId:
$ref: '#/components/schemas/DeviceTerminalIdComEng'
transaction:
type: object
required:
- invoice
properties:
invoice:
$ref: '#/components/schemas/TransactionInvoice'
ui:
type: object
properties:
language:
$ref: '#/components/schemas/UILanguageRequest'
mode:
$ref: '#/components/schemas/UIMode'
suppressFinalResult:
$ref: '#/components/schemas/UISuppressFinalResult'
example:
dateTime: '2021-04-15T09:18:23.283-07:00'
amount:
total: 25
card:
present: Y
transaction:
invoice: '192029'
CardTokenSerialNumber:
description: '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.
'
type: string
maxLength: 10
example: '266'
ProgramId:
type: string
maxLength: 16
example: '123529291'
description: 'The ID value for the program you are allocating a gift card under.
'
giftcards_balance_p2pe_onguardsde_msr:
title: P2PE - On-Guard SDE - MSR/Manual
type: object
required:
- dateTime
- card
- transaction
- p2pe
- device
properties:
dateTime:
$ref: '#/components/schemas/DateTime'
card:
type: object
required:
- present
properties:
present:
$ref: '#/components/schemas/CardPresent'
transaction:
type: object
required:
- invoice
properties:
invoice:
$ref: '#/components/schemas/TransactionInvoice'
device:
type: object
required:
- manufacturer
- model
- serialNumber
- capability
properties:
manufacturer:
$ref: '#/components/schemas/DeviceManufacturer'
model:
$ref: '#/components/schemas/DeviceModel'
serialNumber:
$ref: '#/components/schemas/DeviceSerialNumber'
capability:
$ref: '#/components/schemas/DeviceCapability'
p2pe:
$ref: '#/components/schemas/P2PEType03OnguardSDEMSR'
apiOptions:
$ref: '#/components/schemas/ApiOptionsGCBalance'
example:
dateTime: '2023-12-13T09:18:23.283-07:00'
card:
present: Y
device:
manufacturer: Ingenico
model: Axium DX8000
serialNumber: 20ACCD801843
capability:
contactlessEMV: Y
contactlessMSR: N
EMV: Y
manualEntry: Y
magstripe: Y
PIN: Y
quickChip: Y
signature: Y
p2pe:
data: FFFF495A0000000200000005:4:0128:F48C880DE0DAF549E642C5CC25E65ADF9947E7EB0636DB80C4A490B4C0930AEF64B7201505343CED533A2AE9AFABFE6453875F705519A8109362197CA3BD8DA0FE90DB3F954B9CDA0DB58BDA3330862ADD28CB31EFDA7C641575E33D395D8BFF72EBF0B1FF9630DB0EAB080FE8C9B2FAC28127CDC48CA9F7D532D5BDE4CCE270
format: '03'
transaction:
invoice: '192029'
giftcards_cashout_comengdevice:
title: Commerce Engine For On Premise
type: object
required:
- dateTime
- card
- transaction
properties:
dateTime:
$ref: '#/components/schemas/DateTime'
card:
type: object
required:
- deactivationReason
- present
properties:
deactivationReason:
$ref: '#/components/schemas/CardDeactivationReason'
present:
$ref: '#/components/schemas/CardPresent'
device:
type: object
properties:
terminalId:
$ref: '#/components/schemas/DeviceTerminalIdComEng'
transaction:
type: object
required:
- invoice
properties:
invoice:
$ref: '#/components/schemas/TransactionInvoice'
amount:
type: object
properties:
total:
$ref: '#/components/schemas/AmountTotalGCCashback'
ui:
type: object
properties:
language:
$ref: '#/components/schemas/UILanguageRequest'
mode:
$ref: '#/components/schemas/UIMode'
suppressFinalResult:
$ref: '#/components/schemas/UISuppressFinalResult'
example:
dateTime: '2021-04-15T09:18:23.283-07:00'
card:
deactivationReason: Stolen
present: N
transaction:
invoice: '192029'
ErrorSeverity:
type: string
enum:
- Info
- Error
- Alert
readOnly: true
example: Info
description: '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 |
'
P2PEType05TDESDUKPTMSR:
type: object
description: 'See [P2PE Format 05 TDES DUKPT](/guides/core-concepts/p2pe-format#tdes-dukpt---format-05) for more information.
'
required:
- data
- format
- ksn
properties:
data:
$ref: '#/components/schemas/P2PEData'
format:
$ref: '#/components/schemas/P2PEFormatType05'
ksn:
$ref: '#/components/schemas/P2PEKSN'
giftcards_cashout_p2pe_tdesdukpt_msr:
title: P2PE - TDES DUKPT - MSR/Manual
type: object
required:
- dateTime
- card
- transaction
- p2pe
- device
properties:
dateTime:
$ref: '#/components/schemas/DateTime'
card:
type: object
required:
- deactivationReason
- present
properties:
deactivationReason:
$ref: '#/components/schemas/CardDeactivationReason'
present:
$ref: '#/components/schemas/CardPresent'
transaction:
type: object
required:
- invoice
properties:
invoice:
$ref: '#/components/schemas/TransactionInvoice'
device:
type: object
required:
- manufacturer
- model
- serialNumber
- capability
properties:
manufacturer:
$ref: '#/components/schemas/DeviceManufacturer'
model:
$ref: '#/components/schemas/DeviceModel'
serialNumber:
$ref: '#/components/schemas/DeviceSerialNumber'
capability:
$ref: '#/components/schemas/DeviceCapability'
p2pe:
$ref: '#/components/schemas/P2PEType05TDESDUKPTMSR'
amount:
type: object
properties:
total:
$ref: '#/components/schemas/AmountTotalGCCashback'
example:
dateTime: '2021-04-15T09:18:23.283-07:00'
card:
deactivationReason: Stolen
present: Y
device:
manufacturer: PAX
model: A930
serialNumber: '1170301234'
capability:
contactlessEMV: Y
contactlessMSR: Y
EMV: Y
magstripe: Y
manualEntry: Y
quickChip: Y
p2pe:
data: 44188C9A20DD2092254F7FEB0AABD531D86EA10DA37E5540C25B53658BA4FBB903828F835A7287481F6FB5C17A879ECC9768D4C12F99532A
format: '05'
ksn: FFFF49517300010000C9
transaction:
invoice: '192029'
giftcards_cashout_p2pe_idtech:
title: P2PE - ID TECH - MSR/Manual
type: object
required:
- dateTime
- card
- transaction
- p2pe
properties:
dateTime:
$ref: '#/components/schemas/DateTime'
card:
type: object
required:
- deactivationReason
- present
properties:
deactivationReason:
$ref: '#/components/schemas/CardDeactivationReason'
present:
$ref: '#/components/schemas/CardPresent'
transaction:
type: object
required:
- invoice
properties:
invoice:
$ref: '#/components/schemas/TransactionInvoice'
p2pe:
$ref: '#/components/schemas/P2PEType0102IDTECH'
amount:
type: object
properties:
total:
$ref: '#/components/schemas/AmountTotalGCCashback'
example:
dateTime: '2021-04-15T09:18:23.283-07:00'
card:
deactivationReason: Stolen
present: N
p2pe:
data: 02B600C0170018009292;000442******0006=3012?*61A0453AB7145F1FA7685D2F27A745E129525EDAEA5BB7DBBAF49A5F876E3EE5000000000000000000000000000000000000000034343454343631383439629949500100382003E6FF4D03
format: '01'
transaction:
invoice: '192029'
giftcards_cashout_comengcloud:
title: Commerce Engine For Cloud
type: object
required:
- dateTime
- device
- card
- transaction
properties:
dateTime:
$ref: '#/components/schemas/DateTime'
card:
type: object
required:
- deactivationReason
- present
properties:
deactivationReason:
$ref: '#/components/schemas/CardDeactivationReason'
present:
$ref: '#/components/schemas/CardPresent'
device:
$ref: '#/components/schemas/DeviceComEngCloud'
transaction:
type: object
required:
- invoice
properties:
invoice:
$ref: '#/components/schemas/TransactionInvoice'
amount:
type: object
properties:
total:
$ref: '#/components/schemas/AmountTotalGCCashback'
ui:
type: object
properties:
language:
$ref: '#/components/schemas/UILanguageRequest'
mode:
$ref: '#/components/schemas/UIMode'
suppressFinalResult:
$ref: '#/components/schemas/UISuppressFinalResult'
example:
dateTime: '2021-04-15T09:18:23.283-07:00'
card:
deactivationReason: Stolen
present: N
device:
cloud: true
manufacturer: PAX
serialNumber: '1170301234'
transaction:
invoice: '192029'
giftcards_reactivate_p2pe_tdesdukpt_msr:
title: P2PE - TDES DUKPT - MSR/Manual
type: object
required:
- dateTime
- card
- transaction
- p2pe
- device
properties:
dateTime:
$ref: '#/components/schemas/DateTime'
card:
type: object
required:
- present
properties:
present:
$ref: '#/components/schemas/CardPresent'
transaction:
type: object
required:
- invoice
properties:
invoice:
$ref: '#/components/schemas/TransactionInvoice'
device:
type: object
required:
- manufacturer
- model
- serialNumber
- capability
properties:
manufacturer:
$ref: '#/components/schemas/DeviceManufacturer'
model:
$ref: '#/components/schemas/DeviceModel'
serialNumber:
$ref: '#/components/schemas/DeviceSerialNumber'
capability:
$ref: '#/components/schemas/DeviceCapability'
p2pe:
$ref: '#/components/schemas/P2PEType05TDESDUKPTMSR'
example:
dateTime: '2021-04-15T09:18:23.283-07:00'
card:
present: Y
device:
manufacturer: PAX
model: A930
serialNumber: '1170301234'
capability:
contactlessEMV: Y
contactlessMSR: Y
EMV: Y
magstripe: Y
manualEntry: Y
quickChip: Y
p2pe:
data: 44188C9A20DD2092254F7FEB0AABD531D86EA10DA37E5540C25B53658BA4FBB903828F835A7287481F6FB5C17A879ECC9768D4C12F99532A
format: '05'
ksn: FFFF49517300010000C9
transaction:
invoice: '192029'
AmountTotal:
type: number
maxLength: 14
example: 160
description: '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:
type: object
properties:
deactivationReason:
$ref: '#/components/schemas/CardDeactivationReason'
entryMode:
$ref: '#/components/schemas/CardEntryMode'
expirationDate:
$ref: '#/components/schemas/CardExpirationDateResponse'
number:
$ref: '#/components/schemas/CardMaskedNumberGC'
present:
$ref: '#/components/schemas/CardPresent'
type:
$ref: '#/components/schemas/CardTypeGCResp'
token:
$ref: '#/components/schemas/CardTokenGCResponse'
AmountGCResponse:
type: object
description: 'Object containing information regarding the amount being added onto the card or removed from the card.
'
required:
- total
properties:
total:
$ref: '#/components/schemas/AmountTotalGCResponse'
DeviceCapabilityManualEntry:
type: string
enum:
- Y
- N
example: Y
description: '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.
'
giftcards_reload_p2pe_idtech:
title: P2PE - ID TECH - MSR/Manual
type: object
required:
- dateTime
- amount
- card
- transaction
- p2pe
properties:
dateTime:
$ref: '#/components/schemas/DateTime'
amount:
$ref: '#/components/schemas/AmountGC'
card:
type: object
required:
- present
properties:
present:
$ref: '#/components/schemas/CardPresent'
transaction:
type: object
required:
- invoice
properties:
invoice:
$ref: '#/components/schemas/TransactionInvoice'
p2pe:
$ref: '#/components/schemas/P2PEType0102IDTECH'
example:
dateTime: '2021-04-15T09:18:23.283-07:00'
amount:
total: 25
card:
present: Y
p2pe:
data: 02B600C0170018009292;000442******0006=3012?*61A0453AB7145F1FA7685D2F27A745E129525EDAEA5BB7DBBAF49A5F876E3EE5000000000000000000000000000000000000000034343454343631383439629949500100382003E6FF4D03
format: '01'
transaction:
invoice: '192029'
giftcards_cancel_token_legacy:
title: Legacy TrueToken
type: object
required:
- dateTime
- card
- transaction
properties:
dateTime:
$ref: '#/components/schemas/DateTime'
card:
type: object
required:
- token
properties:
token:
$ref: '#/components/schemas/CardTokenRequired'
transaction:
type: object
required:
- invoice
properties:
invoice:
$ref: '#/components/schemas/TransactionInvoice'
example:
dateTime: '2021-04-15T09:18:23.283-07:00'
card:
token:
value: 87743q5p3ffhv67y
serialNumber: '123456'
transaction:
invoice: '192029'
giftcards_balance_token_gtv:
title: GTV Token
type: object
required:
- dateTime
- card
- transaction
properties:
dateTime:
$ref: '#/components/schemas/DateTime'
card:
type: object
required:
- present
- token
properties:
expirationDate:
$ref: '#/components/schemas/CardExpirationDateGC'
present:
$ref: '#/components/schemas/CardPresent'
token:
$ref: '#/components/schemas/CardTokenRequired'
transaction:
type: object
required:
- invoice
properties:
invoice:
$ref: '#/components/schemas/TransactionInvoice'
apiOptions:
$ref: '#/components/schemas/ApiOptionsGCBalance'
example:
dateTime: '2021-04-15T09:18:23.283-07:00'
card:
present: Y
expirationDate: 1225
token:
value: '8900004710343233'
transaction:
invoice: '192029'
giftcards_activate_token_legacy:
title: Legacy TrueToken
type: object
required:
- dateTime
- amount
- card
- transaction
properties:
dateTime:
$ref: '#/components/schemas/DateTime'
amount:
$ref: '#/components/schemas/AmountGC'
card:
type: object
required:
- present
- token
properties:
expirationDate:
$ref: '#/components/schemas/CardExpirationDateGC'
present:
$ref: '#/components/schemas/CardPresent'
token:
$ref: '#/components/schemas/CardTokenRequiredLegacy'
transaction:
type: object
required:
- invoice
properties:
invoice:
$ref: '#/components/schemas/TransactionInvoice'
example:
dateTime: '2021-04-15T09:18:23.283-07:00'
amount:
total: 25
card:
expirationDate: 1225
present: Y
token:
value: 87743q5p3ffhv67y
serialNumber: '123456'
transaction:
invoice: '192029'
CardDeactivationReason:
type: string
maxLength: 32
example: Lost or Stolen
description: "In a Gift Card [Deactivate](/apis/payments-platform-rest/openapi/gift-cards/deactivate) or [Cashout](/apis/payments-platform-rest/openapi/gift-cards/cashout) request, specifies the reason for deactivation. In a Gift Card redemption or inquiry response, specifies the reason for denial sent by the processor. \n"
giftcards_reload_p2pe_onguardsde_msr:
title: P2PE - On-Guard SDE - MSR/Manual
type: object
required:
- dateTime
- amount
- card
- transaction
- p2pe
- device
properties:
dateTime:
$ref: '#/components/schemas/DateTime'
amount:
$ref: '#/components/schemas/AmountGC'
card:
type: object
required:
- present
properties:
present:
$ref: '#/components/schemas/CardPresent'
transaction:
type: object
required:
- invoice
properties:
invoice:
$ref: '#/components/schemas/TransactionInvoice'
device:
type: object
required:
- manufacturer
- model
- serialNumber
- capability
properties:
manufacturer:
$ref: '#/components/schemas/DeviceManufacturer'
model:
$ref: '#/components/schemas/DeviceModel'
serialNumber:
$ref: '#/components/schemas/DeviceSerialNumber'
capability:
$ref: '#/components/schemas/DeviceCapability'
p2pe:
$ref: '#/components/schemas/P2PEType03OnguardSDEMSR'
example:
dateTime: '2023-12-13T09:18:23.283-07:00'
amount:
total: 25
card:
present: Y
device:
manufacturer: Ingenico
model: Axium DX8000
serialNumber: 20ACCD801843
capability:
contactlessEMV: Y
contactlessMSR: N
EMV: Y
manualEntry: Y
magstripe: Y
PIN: Y
quickChip: Y
signature: Y
p2pe:
data: FFFF495A0000000200000005:4:0128:F48C880DE0DAF549E642C5CC25E65ADF9947E7EB0636DB80C4A490B4C0930AEF64B7201505343CED533A2AE9AFABFE6453875F705519A8109362197CA3BD8DA0FE90DB3F954B9CDA0DB58BDA3330862ADD28CB31EFDA7C641575E33D395D8BFF72EBF0B1FF9630DB0EAB080FE8C9B2FAC28127CDC48CA9F7D532D5BDE4CCE270
format: '03'
transaction:
invoice: '192029'
AmountCheckTotal:
type: number
maxLength: 14
writeOnly: true
example: 200
description: '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.
'
giftcards_reactivate_token_legacy:
title: Legacy TrueToken
type: object
required:
- dateTime
- card
- transaction
properties:
dateTime:
$ref: '#/components/schemas/DateTime'
card:
type: object
required:
- present
- token
properties:
expirationDate:
$ref: '#/components/schemas/CardExpirationDateGC'
present:
$ref: '#/components/schemas/CardPresent'
token:
$ref: '#/components/schemas/CardTokenRequiredLegacy'
transaction:
type: object
required:
- invoice
properties:
invoice:
$ref: '#/components/schemas/TransactionInvoice'
example:
dateTime: '2021-04-15T09:18:23.283-07:00'
card:
present: Y
expirationDate: 1225
token:
value: 87743q5p3ffhv67y
serialNumber: '123456'
transaction:
invoice: '192029'
Server:
type: object
readOnly: true
properties:
name:
$ref: '#/components/schemas/ServerName'
giftcards_deactivate_token_legacy:
title: Legacy TrueToken
type: object
required:
- dateTime
- card
- transaction
properties:
dateTime:
$ref: '#/components/schemas/DateTime'
card:
type: object
required:
- deactivationReason
- present
- token
properties:
deactivationReason:
$ref: '#/components/schemas/CardDeactivationReason'
present:
$ref: '#/components/schemas/CardPresent'
token:
$ref: '#/components/schemas/CardTokenRequiredLegacy'
expirationDate:
$ref: '#/components/schemas/CardExpirationDateGC'
transaction:
type: object
required:
- invoice
properties:
invoice:
$ref: '#/components/schemas/TransactionInvoice'
example:
dateTime: '2021-04-15T09:18:23.283-07:00'
card:
deactivationReason: Stolen
expirationDate: 1225
present: N
token:
value: 87743q5p3ffhv67y
serialNumber: '123456'
transaction:
invoice: '192029'
DeviceCapabilityPIN:
type: string
enum:
- Y
- N
example: Y
description: '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.
'
MerchantMID:
type: number
maxLength: 10
example: 15877
description: 'The merchant ID associated with the merchant account.
'
giftcards_cashout_token_legacy:
title: Legacy TrueToken
type: object
required:
- dateTime
- card
- transaction
properties:
dateTime:
$ref: '#/components/schemas/DateTime'
card:
type: object
required:
- deactivationReason
- present
- token
properties:
deactivationReason:
$ref: '#/components/schemas/CardDeactivationReason'
present:
$ref: '#/components/schemas/CardPresent'
token:
$ref: '#/components/schemas/CardTokenRequiredLegacy'
expirationDate:
$ref: '#/components/schemas/CardExpirationDateGC'
securityCode:
$ref: '#/components/schemas/CardSecurityCodeGC'
transaction:
type: object
required:
- invoice
properties:
invoice:
$ref: '#/components/schemas/TransactionInvoice'
amount:
type: object
properties:
total:
$ref: '#/components/schemas/AmountTotalGCCashback'
example:
dateTime: '2021-04-15T09:18:23.283-07:00'
card:
deactivationReason: Stolen
expirationDate: 1225
present: N
token:
value: 87743q5p3ffhv67y
serialNumber: '123456'
transaction:
invoice: '192029'
DeviceTerminalIdComEng:
type: string
maxLength: 32
example: '1742'
description: "This field is optional and is for backwards compatibility with existing vendors that are used to processing via UTG controlled devices.\n\nSince Commerce Engine is running directly on the payment device it does not require a `device.terminalId` to be specified. \n"
ServerName:
type: string
maxLength: 50
example: TM01CE
description: 'The name of the server that processed the request.
'
CardTokenGCResponse:
type: object
properties:
value:
$ref: '#/components/schemas/CardTokenValueGC'
giftcards_balance_comengdevice:
title: Commerce Engine For On Premise
type: object
required:
- dateTime
- card
- transaction
properties:
dateTime:
$ref: '#/components/schemas/DateTime'
card:
type: object
required:
- present
properties:
present:
$ref: '#/components/schemas/CardPresent'
device:
type: object
properties:
terminalId:
$ref: '#/components/schemas/DeviceTerminalIdComEng'
transaction:
type: object
required:
- invoice
properties:
invoice:
$ref: '#/components/schemas/TransactionInvoice'
apiOptions:
$ref: '#/components/schemas/ApiOptionsGCBalance'
ui:
type: object
properties:
language:
$ref: '#/components/schemas/UILanguageRequest'
mode:
$ref: '#/components/schemas/UIMode'
suppressFinalResult:
$ref: '#/components/schemas/UISuppressFinalResult'
example:
dateTime: '2021-04-15T09:18:23.283-07:00'
card:
present: Y
transaction:
invoice: '192029'
giftcards_cashout_unencryptedcard:
title: Card Number Unencrypted
type: object
required:
- dateTime
- card
- transaction
properties:
dateTime:
$ref: '#/components/schemas/DateTime'
card:
type: object
required:
- deactivationReason
- number
- present
properties:
deactivationReason:
$ref: '#/components/schemas/CardDeactivationReason'
present:
$ref: '#/components/schemas/CardPresent'
number:
$ref: '#/components/schemas/CardNumberGC'
expirationDate:
$ref: '#/components/schemas/CardExpirationDateGC'
securityCode:
$ref: '#/components/schemas/CardSecurityCodeGC'
transaction:
type: object
required:
- invoice
properties:
invoice:
$ref: '#/components/schemas/TransactionInvoice'
amount:
type: object
properties:
total:
$ref: '#/components/schemas/AmountTotalGCCashback'
example:
dateTime: '2021-04-15T09:18:23.283-07:00'
card:
deactivationReason: Stolen
expirationDate: 1230
number: '2664654648774'
present: N
transaction:
invoice: '192029'
giftcards_reactivate_utgdevice:
title: UTG Controlled Device
type: object
required:
- dateTime
- device
- card
- transaction
properties:
dateTime:
$ref: '#/components/schemas/DateTime'
card:
type: object
required:
- present
properties:
present:
$ref: '#/components/schemas/CardPresent'
device:
type: object
required:
- terminalId
properties:
terminalId:
$ref: '#/components/schemas/DeviceTerminalId'
promptCardSecurityCode:
$ref: '#/components/schemas/DevicePromptCardSecurityCode'
transaction:
type: object
required:
- invoice
properties:
invoice:
$ref: '#/components/schemas/TransactionInvoice'
example:
dateTime: '2021-04-15T09:18:23.283-07:00'
card:
present: Y
device:
terminalId: '1742'
transaction:
invoice: '192029'
giftcards_deactivate_p2pe_onguardsde_msr:
title: P2PE - On-Guard SDE - MSR/Manual
type: object
required:
- dateTime
- card
- transaction
- p2pe
- device
properties:
dateTime:
$ref: '#/components/schemas/DateTime'
card:
type: object
required:
- deactivationReason
- present
properties:
deactivationReason:
$ref: '#/components/schemas/CardDeactivationReason'
present:
$ref: '#/components/schemas/CardPresent'
transaction:
type: object
required:
- invoice
properties:
invoice:
$ref: '#/components/schemas/TransactionInvoice'
device:
type: object
required:
- manufacturer
- model
- serialNumber
- capability
properties:
manufacturer:
$ref: '#/components/schemas/DeviceManufacturer'
model:
$ref: '#/components/schemas/DeviceModel'
serialNumber:
$ref: '#/components/schemas/DeviceSerialNumber'
capability:
$ref: '#/components/schemas/DeviceCapability'
p2pe:
$ref: '#/components/schemas/P2PEType03OnguardSDEMSR'
example:
dateTime: '2023-12-13T09:18:23.283-07:00'
card:
deactivationReason: Stolen
present: Y
device:
manufacturer: Ingenico
model: Axium DX8000
serialNumber: 20ACCD801843
capability:
contactlessEMV: Y
contactlessMSR: N
EMV: Y
manualEntry: Y
magstripe: Y
PIN: Y
quickChip: Y
signature: Y
p2pe:
data: FFFF495A0000000200000005:4:0128:F48C880DE0DAF549E642C5CC25E65ADF9947E7EB0636DB80C4A490B4C0930AEF64B7201505343CED533A2AE9AFABFE6453875F705519A8109362197CA3BD8DA0FE90DB3F954B9CDA0DB58BDA3330862ADD28CB31EFDA7C641575E33D395D8BFF72EBF0B1FF9630DB0EAB080FE8C9B2FAC28127CDC48CA9F7D532D5BDE4CCE270
format: '03'
transaction:
invoice: '192029'
CardMaskedNumberGC:
type: string
maxLength: 32
example: XXXXXXXXXXXX8774
description: 'The card number field will always be masked when returned in a response.
'
DateTime:
type: string
format: ISO 8601
example: '2024-05-21T09:18:23.283-07:00'
description: '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
'
TransactionInvoice:
type: string
maxLength: 10
example: 0510093358
description: '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.**
'
CardSecurityCodeValueGC:
type: string
maxLength: 4
writeOnly: true
example: '333'
description: '**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.
'
ErrorLongText:
type: string
maxLength: 255
readOnly: true
example: Card type not recognized
description: 'Extended error message that is returned if an error condition exists.
'
DevicePromptCardSecurityCode:
type: string
minLength: 1
maxLength: 1
enum:
- Y
- N
example: Y
description: '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.**
'
giftcards_balance_unencryptedcard:
title: Card Number Unencrypted
type: object
required:
- dateTime
- card
- transaction
properties:
dateTime:
$ref: '#/components/schemas/DateTime'
card:
type: object
required:
- present
- number
properties:
present:
$ref: '#/components/schemas/CardPresent'
number:
$ref: '#/components/schemas/CardNumberGC'
expirationDate:
$ref: '#/components/schemas/CardExpirationDateGC'
securityCode:
$ref: '#/components/schemas/CardSecurityCodeGC'
transaction:
type: object
required:
- invoice
properties:
invoice:
$ref: '#/components/schemas/TransactionInvoice'
apiOptions:
$ref: '#/components/schemas/ApiOptionsGCBalance'
example:
dateTime: '2021-04-15T09:18:23.283-07:00'
card:
expirationDate: 1230
number: '2664654648774'
present: Y
transaction:
invoice: '192029'
DeviceCapabilityMagstripe:
type: string
enum:
- Y
- N
example: Y
description: '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.
'
giftcards_deactivate_token_gtv:
title: GTV Token
type: object
required:
- dateTime
- card
- transaction
properties:
dateTime:
$ref: '#/components/schemas/DateTime'
card:
type: object
required:
- deactivationReason
- present
- token
properties:
deactivationReason:
$ref: '#/components/schemas/CardDeactivationReason'
present:
$ref: '#/components/schemas/CardPresent'
token:
$ref: '#/components/schemas/CardTokenRequired'
expirationDate:
$ref: '#/components/schemas/CardExpirationDateGC'
transaction:
type: object
required:
- invoice
properties:
invoice:
$ref: '#/components/schemas/TransactionInvoice'
example:
dateTime: '2021-04-15T09:18:23.283-07:00'
card:
deactivationReason: Stolen
expirationDate: 1225
present: N
token:
value: '8900004710343233'
transaction:
invoice: '192029'
BalanceAmount:
type: number
readOnly: true
maxLength: 14
example: 24.33
description: '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.
'
DeviceCapabilityEMV:
type: string
enum:
- Y
- N
example: Y
description: '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.
'
CardEntryMode:
type: string
minLength: 1
maxLength: 1
enum:
- '1'
- '2'
- C
- E
- M
- Q
- R
example: M
description: "**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**\n\nThe method used to capture a payment card in an authorization/sale request. \n\nValue|Description\n-----|-----------\n1 | Track 1 Only or Dual Track (Track 1 & 2)\n2 | Track 2 Only\nC | EMV Contactless via card or mobile wallet\nE | EMV Chip\nM | Manual Entry\nQ | QR Code\nR | Contactless MSD\n"
ErrorCode:
type: integer
maxLength: 5
readOnly: true
example: 64100
description: '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.**
'
CardTypeGCResp:
type: string
enum:
- GC
- YC
example: YC
description: "An abbreviation used to specify the type of card that was used when processing a transaction.\n\nValue| Description\n-----|------------\nGC | Gift Card\nYC | IT’S YOUR CARD \n"
ApiOptionsGCBalance:
type: array
items:
type: string
example:
- RETURNHIST
writeOnly: true
description: 'API Options modify the request being made.
Value | Description |
-----------|------------------------------------------------------------|
RETURNHIST | Return the gift card usage history in the `history` array. |
'
AmountTotalOnly:
type: object
description: 'Object containing information regarding the amount being requested. The `total` field within the object is required and specifies the amount being requested.
Note: For merchants that are configured to allow multiple currencies, the amount fields can specify up to three decimal places. However, the number of decimal places can not exceed the number allowed for the specified currency. See the [Currency Codes](/guides/appendices/currency-codes) section for details.
'
required:
- total
properties:
total:
$ref: '#/components/schemas/AmountTotal'
ErrorSecondaryCode:
type: integer
maxLength: 4
readOnly: true
example: 0
description: 'This code supplements the code specified in the `error.primaryCode` field to provide additional information about the error that occurred.
'
CardResponseDeact:
type: object
properties:
deactivationReason:
$ref: '#/components/schemas/CardDeactivationReason'
entryMode:
$ref: '#/components/schemas/CardEntryMode'
expirationDate:
$ref: '#/components/schemas/CardExpirationDateResponse'
number:
$ref: '#/components/schemas/CardMaskedNumberGC'
present:
$ref: '#/components/schemas/CardPresent'
type:
$ref: '#/components/schemas/CardTypeGCResp'
balance:
$ref: '#/components/schemas/CardBalance'
token:
$ref: '#/components/schemas/CardTokenGCResponse'
giftcards_balance_p2pe_idtech:
title: P2PE - ID TECH - MSR/Manual
type: object
required:
- dateTime
- card
- transaction
- p2pe
properties:
dateTime:
$ref: '#/components/schemas/DateTime'
card:
type: object
required:
- present
properties:
present:
$ref: '#/components/schemas/CardPresent'
transaction:
type: object
required:
- invoice
properties:
invoice:
$ref: '#/components/schemas/TransactionInvoice'
p2pe:
$ref: '#/components/schemas/P2PEType0102IDTECH'
apiOptions:
$ref: '#/components/schemas/ApiOptionsGCBalance'
example:
dateTime: '2021-04-15T09:18:23.283-07:00'
card:
present: Y
p2pe:
data: 02B600C0170018009292;000442******0006=3012?*61A0453AB7145F1FA7685D2F27A745E129525EDAEA5BB7DBBAF49A5F876E3EE5000000000000000000000000000000000000000034343454343631383439629949500100382003E6FF4D03
format: '01'
transaction:
invoice: '192029'
CardTokenValueGC:
description: '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.
'
type: string
maxLength: 16
example: 87743q5p3ffhv67y
giftcards_cashout_token_gtv:
title: GTV Token
type: object
required:
- dateTime
- card
- transaction
properties:
dateTime:
$ref: '#/components/schemas/DateTime'
card:
type: object
required:
- deactivationReason
- present
- token
properties:
deactivationReason:
$ref: '#/components/schemas/CardDeactivationReason'
present:
$ref: '#/components/schemas/CardPresent'
token:
$ref: '#/components/schemas/CardTokenRequired'
expirationDate:
$ref: '#/components/schemas/CardExpirationDateGC'
securityCode:
$ref: '#/components/schemas/CardSecurityCodeGC'
transaction:
type: object
required:
- invoice
properties:
invoice:
$ref: '#/components/schemas/TransactionInvoice'
amount:
type: object
properties:
total:
$ref: '#/components/schemas/AmountTotalGCCashback'
example:
dateTime: '2021-04-15T09:18:23.283-07:00'
card:
deactivationReason: Stolen
expirationDate: 1225
present: N
token:
value: '8900004710343233'
transaction:
invoice: '192029'
giftcards_deactivate_comengcloud:
title: Commerce Engine For Cloud
type: object
required:
- dateTime
- device
- card
- transaction
properties:
dateTime:
$ref: '#/components/schemas/DateTime'
card:
type: object
required:
- deactivationReason
- present
properties:
deactivationReason:
$ref: '#/components/schemas/CardDeactivationReason'
present:
$ref: '#/components/schemas/CardPresent'
device:
$ref: '#/components/schemas/DeviceComEngCloud'
transaction:
type: object
required:
- invoice
properties:
invoice:
$ref: '#/components/schemas/TransactionInvoice'
ui:
type: object
properties:
language:
$ref: '#/components/schemas/UILanguageRequest'
mode:
$ref: '#/components/schemas/UIMode'
suppressFinalResult:
$ref: '#/components/schemas/UISuppressFinalResult'
example:
dateTime: '2021-04-15T09:18:23.283-07:00'
card:
deactivationReason: Stolen
present: N
device:
cloud: true
manufacturer: PAX
serialNumber: '1170301234'
transaction:
invoice: '192029'
giftcards_reactivate_comengcloud:
title: Commerce Engine For Cloud
type: object
required:
- dateTime
- device
- card
- transaction
properties:
dateTime:
$ref: '#/components/schemas/DateTime'
card:
type: object
required:
- present
properties:
present:
$ref: '#/components/schemas/CardPresent'
device:
$ref: '#/components/schemas/DeviceComEngCloud'
transaction:
type: object
required:
- invoice
properties:
invoice:
$ref: '#/components/schemas/TransactionInvoice'
ui:
type: object
properties:
language:
$ref: '#/components/schemas/UILanguageRequest'
mode:
$ref: '#/components/schemas/UIMode'
suppressFinalResult:
$ref: '#/components/schemas/UISuppressFinalResult'
example:
dateTime: '2021-04-15T09:18:23.283-07:00'
card:
present: Y
device:
cloud: true
manufacturer: PAX
serialNumber: '1170301234'
transaction:
invoice: '192029'
giftcards_reload_unencryptedcard:
title: Card Number Unencrypted
type: object
required:
- dateTime
- amount
- card
- transaction
properties:
dateTime:
$ref: '#/components/schemas/DateTime'
amount:
$ref: '#/components/schemas/AmountGC'
card:
type: object
required:
- present
- number
properties:
present:
$ref: '#/components/schemas/CardPresent'
number:
$ref: '#/components/schemas/CardNumberGC'
expirationDate:
$ref: '#/components/schemas/CardExpirationDateGC'
securityCode:
$ref: '#/components/schemas/CardSecurityCodeGC'
transaction:
type: object
required:
- invoice
properties:
invoice:
$ref: '#/components/schemas/TransactionInvoice'
example:
dateTime: '2021-04-15T09:18:23.283-07:00'
amount:
total: 25
card:
present: Y
number: '2664654648774'
expirationDate: 1230
transaction:
invoice: '192029'
TransactionAuthorizationCode:
type: string
maxLength: 6
example: '198399'
description: '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.
'
P2PEFormatType05:
type: string
minLength: 2
maxLength: 2
enum:
- '05'
example: '05'
description: '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)
'
AmountGC:
type: object
description: 'Object containing information regarding the amount being added onto the card or removed from the card.
'
required:
- total
properties:
total:
$ref: '#/components/schemas/AmountTotalGC'
checkTotal:
$ref: '#/components/schemas/AmountCheckTotal'
UIMode:
type: string
enum:
- light
- dark
example: dark
description: 'Set the UI to light mode by sending `light` or dark mode by sending `dark`
'
DeviceTerminalIdRequired:
type: string
maxLength: 32
example: '1742'
description: '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:
title: GTV Token
type: object
required:
- dateTime
- card
- transaction
properties:
dateTime:
$ref: '#/components/schemas/DateTime'
card:
type: object
required:
- token
properties:
token:
$ref: '#/components/schemas/CardTokenRequired'
transaction:
type: object
required:
- invoice
properties:
invoice:
$ref: '#/components/schemas/TransactionInvoice'
example:
dateTime: '2021-04-15T09:18:23.283-07:00'
card:
token:
value: '8900004710343233'
transaction:
invoice: '192029'
MerchantResponse:
type: object
properties:
mid:
$ref: '#/components/schemas/MerchantMID'
name:
$ref: '#/components/schemas/MerchantName'
giftcards_activate_unencryptedcard:
title: Card Number Unencrypted
type: object
required:
- dateTime
- amount
- card
- transaction
properties:
dateTime:
$ref: '#/components/schemas/DateTime'
amount:
$ref: '#/components/schemas/AmountGC'
card:
type: object
required:
- present
- number
properties:
present:
$ref: '#/components/schemas/CardPresent'
number:
$ref: '#/components/schemas/CardNumberGC'
expirationDate:
$ref: '#/components/schemas/CardExpirationDateGC'
securityCode:
$ref: '#/components/schemas/CardSecurityCodeGC'
transaction:
type: object
required:
- invoice
properties:
invoice:
$ref: '#/components/schemas/TransactionInvoice'
example:
dateTime: '2021-04-15T09:18:23.283-07:00'
amount:
total: 25
card:
present: Y
number: '2664654648774'
expirationDate: 1230
transaction:
invoice: '192029'
giftcards_cashout_utgdevice:
title: UTG Controlled Device
type: object
required:
- dateTime
- device
- card
- transaction
properties:
dateTime:
$ref: '#/components/schemas/DateTime'
card:
type: object
required:
- deactivationReason
- present
properties:
deactivationReason:
$ref: '#/components/schemas/CardDeactivationReason'
present:
$ref: '#/components/schemas/CardPresent'
device:
type: object
required:
- terminalId
properties:
terminalId:
$ref: '#/components/schemas/DeviceTerminalId'
promptCardSecurityCode:
$ref: '#/components/schemas/DevicePromptCardSecurityCode'
transaction:
type: object
required:
- invoice
properties:
invoice:
$ref: '#/components/schemas/TransactionInvoice'
amount:
type: object
properties:
total:
$ref: '#/components/schemas/AmountTotalGCCashback'
example:
dateTime: '2021-04-15T09:18:23.283-07:00'
card:
deactivationReason: Stolen
present: N
device:
terminalId: '1742'
transaction:
invoice: '192029'
giftcards_activate_token_gtv:
title: GTV Token
type: object
required:
- dateTime
- amount
- card
- transaction
properties:
dateTime:
$ref: '#/components/schemas/DateTime'
amount:
$ref: '#/components/schemas/AmountGC'
card:
type: object
required:
- present
- token
properties:
expirationDate:
$ref: '#/components/schemas/CardExpirationDateGC'
present:
$ref: '#/components/schemas/CardPresent'
token:
$ref: '#/components/schemas/CardTokenRequired'
transaction:
type: object
required:
- invoice
properties:
invoice:
$ref: '#/components/schemas/TransactionInvoice'
example:
dateTime: '2021-04-15T09:18:23.283-07:00'
amount:
total: 25
card:
expirationDate: 1225
present: Y
token:
value: '8900004710343233'
transaction:
invoice: '192029'
AmountTotalGCResponse:
type: number
maxLength: 14
example: 20
description: "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. \n\nFor [Cashout](/apis/payments-platform-rest/openapi/gift-cards/cashout) requests, this is the amount of cash that should be provided to the customer.\n"
giftcards_deactivate_unencryptedcard:
title: Card Number Unencrypted
type: object
required:
- dateTime
- card
- transaction
properties:
dateTime:
$ref: '#/components/schemas/DateTime'
card:
type: object
required:
- deactivationReason
- present
- number
properties:
deactivationReason:
$ref: '#/components/schemas/CardDeactivationReason'
present:
$ref: '#/components/schemas/CardPresent'
number:
$ref: '#/components/schemas/CardNumberGC'
expirationDate:
$ref: '#/components/schemas/CardExpirationDateGC'
securityCode:
$ref: '#/components/schemas/CardSecurityCodeGC'
transaction:
type: object
required:
- invoice
properties:
invoice:
$ref: '#/components/schemas/TransactionInvoice'
example:
dateTime: '2021-04-15T09:18:23.283-07:00'
card:
deactivationReason: Stolen
expirationDate: 1230
number: '2664654648774'
present: N
transaction:
invoice: '192029'
giftcards_reload_comengdevice:
title: Commerce Engine For On Premise
type: object
required:
- dateTime
- amount
- card
- transaction
properties:
dateTime:
$ref: '#/components/schemas/DateTime'
amount:
$ref: '#/components/schemas/AmountGC'
card:
type: object
required:
- present
properties:
present:
$ref: '#/components/schemas/CardPresent'
device:
type: object
properties:
terminalId:
$ref: '#/components/schemas/DeviceTerminalIdComEng'
transaction:
type: object
required:
- invoice
properties:
invoice:
$ref: '#/components/schemas/TransactionInvoice'
ui:
type: object
properties:
language:
$ref: '#/components/schemas/UILanguageRequest'
mode:
$ref: '#/components/schemas/UIMode'
suppressFinalResult:
$ref: '#/components/schemas/UISuppressFinalResult'
example:
dateTime: '2021-04-15T09:18:23.283-07:00'
amount:
total: 25
card:
present: Y
transaction:
invoice: '192029'
CardTokenRequired:
type: object
required:
- value
properties:
value:
$ref: '#/components/schemas/CardTokenValue'
DeviceSerialNumber:
type: string
maxLength: 64
example: '1170301234'
description: 'Specifies the serial number of the device.
'
AmountTotalGCCashback:
type: number
maxLength: 14
example: 20
description: '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:
type: integer
maxLength: 4
readOnly: true
example: 9842
description: '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:
title: UTG Controlled Device
type: object
required:
- dateTime
- device
- card
- transaction
properties:
dateTime:
$ref: '#/components/schemas/DateTime'
card:
type: object
required:
- present
properties:
present:
$ref: '#/components/schemas/CardPresent'
device:
type: object
required:
- terminalId
properties:
terminalId:
$ref: '#/components/schemas/DeviceTerminalId'
promptCardSecurityCode:
$ref: '#/components/schemas/DevicePromptCardSecurityCode'
transaction:
type: object
required:
- invoice
properties:
invoice:
$ref: '#/components/schemas/TransactionInvoice'
apiOptions:
$ref: '#/components/schemas/ApiOptionsGCBalance'
example:
dateTime: '2021-04-15T09:18:23.283-07:00'
card:
present: Y
device:
terminalId: '1742'
transaction:
invoice: '192029'
P2PEFormatIDTech:
type: string
minLength: 2
maxLength: 2
enum:
- '01'
- '02'
example: '01'
description: '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)
'
DeviceModel:
type: string
maxLength: 50
example: A800
description: '**Conditional: Required when using a non-UTG-controlled device.**
Specifies the model of the device.
'
giftcards_reactivate_p2pe_onguardsde_msr:
title: P2PE - On-Guard SDE - MSR/Manual
type: object
required:
- dateTime
- card
- transaction
- p2pe
- device
properties:
dateTime:
$ref: '#/components/schemas/DateTime'
card:
type: object
required:
- present
properties:
present:
$ref: '#/components/schemas/CardPresent'
transaction:
type: object
required:
- invoice
properties:
invoice:
$ref: '#/components/schemas/TransactionInvoice'
device:
type: object
required:
- manufacturer
- model
- serialNumber
- capability
properties:
manufacturer:
$ref: '#/components/schemas/DeviceManufacturer'
model:
$ref: '#/components/schemas/DeviceModel'
serialNumber:
$ref: '#/components/schemas/DeviceSerialNumber'
capability:
$ref: '#/components/schemas/DeviceCapability'
p2pe:
$ref: '#/components/schemas/P2PEType03OnguardSDEMSR'
example:
dateTime: '2023-12-13T09:18:23.283-07:00'
card:
present: Y
device:
manufacturer: Ingenico
model: Axium DX8000
serialNumber: 20ACCD801843
capability:
contactlessEMV: Y
contactlessMSR: N
EMV: Y
manualEntry: Y
magstripe: Y
PIN: Y
quickChip: Y
signature: Y
p2pe:
data: FFFF495A0000000200000005:4:0128:F48C880DE0DAF549E642C5CC25E65ADF9947E7EB0636DB80C4A490B4C0930AEF64B7201505343CED533A2AE9AFABFE6453875F705519A8109362197CA3BD8DA0FE90DB3F954B9CDA0DB58BDA3330862ADD28CB31EFDA7C641575E33D395D8BFF72EBF0B1FF9630DB0EAB080FE8C9B2FAC28127CDC48CA9F7D532D5BDE4CCE270
format: '03'
transaction:
invoice: '192029'
giftcards_reload_token_legacy:
title: Legacy TrueToken
type: object
required:
- dateTime
- amount
- card
- transaction
properties:
dateTime:
$ref: '#/components/schemas/DateTime'
amount:
$ref: '#/components/schemas/AmountGC'
card:
type: object
required:
- present
- token
properties:
expirationDate:
$ref: '#/components/schemas/CardExpirationDateGC'
present:
$ref: '#/components/schemas/CardPresent'
token:
$ref: '#/components/schemas/CardTokenRequiredLegacy'
transaction:
type: object
required:
- invoice
properties:
invoice:
$ref: '#/components/schemas/TransactionInvoice'
example:
dateTime: '2021-04-15T09:18:23.283-07:00'
amount:
total: 25
card:
present: Y
expirationDate: 1225
token:
value: 87743q5p3ffhv67y
serialNumber: '123456'
transaction:
invoice: '192029'
giftcards_reload_token_gtv:
title: GTV Token
type: object
required:
- dateTime
- amount
- card
- transaction
properties:
dateTime:
$ref: '#/components/schemas/DateTime'
amount:
$ref: '#/components/schemas/AmountGC'
card:
type: object
required:
- present
- token
properties:
expirationDate:
$ref: '#/components/schemas/CardExpirationDateGC'
present:
$ref: '#/components/schemas/CardPresent'
token:
$ref: '#/components/schemas/CardTokenRequired'
transaction:
type: object
required:
- invoice
properties:
invoice:
$ref: '#/components/schemas/TransactionInvoice'
example:
dateTime: '2021-04-15T09:18:23.283-07:00'
amount:
total: 25
card:
present: Y
expirationDate: 1225
token:
value: '8900004710343233'
transaction:
invoice: '192029'
DeviceCapabilityQuickChip:
type: string
enum:
- Y
- N
example: Y
description: '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.
'
CardTokenRequiredLegacy:
type: object
required:
- value
properties:
value:
$ref: '#/components/schemas/CardTokenValue'
serialNumber:
$ref: '#/components/schemas/CardTokenSerialNumber'
giftcards_reload_comengcloud:
title: Commerce Engine For Cloud
type: object
required:
- dateTime
- amount
- device
- card
- transaction
properties:
dateTime:
$ref: '#/components/schemas/DateTime'
amount:
$ref: '#/components/schemas/AmountGC'
card:
type: object
required:
- present
properties:
present:
$ref: '#/components/schemas/CardPresent'
device:
$ref: '#/components/schemas/DeviceComEngCloud'
transaction:
type: object
required:
- invoice
properties:
invoice:
$ref: '#/components/schemas/TransactionInvoice'
ui:
type: object
properties:
language:
$ref: '#/components/schemas/UILanguageRequest'
mode:
$ref: '#/components/schemas/UIMode'
suppressFinalResult:
$ref: '#/components/schemas/UISuppressFinalResult'
example:
dateTime: '2021-04-15T09:18:23.283-07:00'
amount:
total: 25
card:
present: Y
device:
cloud: true
manufacturer: PAX
serialNumber: '1170301234'
transaction:
invoice: '192029'
CardPresent:
type: string
enum:
- Y
- N
example: Y
description: '**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`.
'
giftcards_reactivate_token_gtv:
title: GTV Token
type: object
required:
- dateTime
- card
- transaction
properties:
dateTime:
$ref: '#/components/schemas/DateTime'
card:
type: object
required:
- present
- token
properties:
expirationDate:
$ref: '#/components/schemas/CardExpirationDateGC'
present:
$ref: '#/components/schemas/CardPresent'
token:
$ref: '#/components/schemas/CardTokenRequired'
transaction:
type: object
required:
- invoice
properties:
invoice:
$ref: '#/components/schemas/TransactionInvoice'
example:
dateTime: '2021-04-15T09:18:23.283-07:00'
card:
present: Y
expirationDate: 1225
token:
value: '8900004710343233'
transaction:
invoice: '192029'
giftcards_reactivate_comengdevice:
title: Commerce Engine For On Premise
type: object
required:
- dateTime
- card
- transaction
properties:
dateTime:
$ref: '#/components/schemas/DateTime'
card:
type: object
required:
- present
properties:
present:
$ref: '#/components/schemas/CardPresent'
device:
type: object
properties:
terminalId:
$ref: '#/components/schemas/DeviceTerminalIdComEng'
transaction:
type: object
required:
- invoice
properties:
invoice:
$ref: '#/components/schemas/TransactionInvoice'
ui:
type: object
properties:
language:
$ref: '#/components/schemas/UILanguageRequest'
mode:
$ref: '#/components/schemas/UIMode'
suppressFinalResult:
$ref: '#/components/schemas/UISuppressFinalResult'
example:
dateTime: '2021-04-15T09:18:23.283-07:00'
card:
present: Y
transaction:
invoice: '192029'
DeviceCapabilitySignature:
type: string
enum:
- Y
- N
example: Y
description: '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.
'
CardBalance:
type: object
readOnly: true
properties:
amount:
$ref: '#/components/schemas/BalanceAmount'
DeviceOnlyTIDResponse:
type: object
properties:
terminalId:
$ref: '#/components/schemas/DeviceTerminalIdRequired'
P2PEKSN:
type: string
maxLength: 20
example: 6299495001100E200041
description: 'The key serial number which was used to encrypt the P2PE data.
'
giftcards_activate_comengcloud:
title: Commerce Engine For Cloud
type: object
required:
- dateTime
- amount
- card
- device
- transaction
properties:
dateTime:
$ref: '#/components/schemas/DateTime'
amount:
$ref: '#/components/schemas/AmountGC'
card:
type: object
required:
- present
properties:
present:
$ref: '#/components/schemas/CardPresent'
device:
$ref: '#/components/schemas/DeviceComEngCloud'
transaction:
type: object
required:
- invoice
properties:
invoice:
$ref: '#/components/schemas/TransactionInvoice'
ui:
type: object
properties:
language:
$ref: '#/components/schemas/UILanguageRequest'
mode:
$ref: '#/components/schemas/UIMode'
suppressFinalResult:
$ref: '#/components/schemas/UISuppressFinalResult'
example:
dateTime: '2021-04-15T09:18:23.283-07:00'
amount:
total: 25
card:
present: Y
device:
cloud: true
manufacturer: PAX
serialNumber: '1170301234'
transaction:
invoice: '192029'
giftcards_deactivate_p2pe_idtech:
title: P2PE - ID TECH - MSR/Manual
type: object
required:
- dateTime
- card
- transaction
- p2pe
properties:
dateTime:
$ref: '#/components/schemas/DateTime'
card:
type: object
required:
- deactivationReason
- present
properties:
deactivationReason:
$ref: '#/components/schemas/CardDeactivationReason'
present:
$ref: '#/components/schemas/CardPresent'
transaction:
type: object
required:
- invoice
properties:
invoice:
$ref: '#/components/schemas/TransactionInvoice'
p2pe:
$ref: '#/components/schemas/P2PEType0102IDTECH'
example:
dateTime: '2021-04-15T09:18:23.283-07:00'
card:
deactivationReason: Stolen
present: N
p2pe:
data: 02B600C0170018009292;000442******0006=3012?*61A0453AB7145F1FA7685D2F27A745E129525EDAEA5BB7DBBAF49A5F876E3EE5000000000000000000000000000000000000000034343454343631383439629949500100382003E6FF4D03
format: '01'
transaction:
invoice: '192029'
AmountTotalGC:
type: number
maxLength: 14
example: 20
description: 'The amount which should be added to the card''s balance. Amount cannot be zero.
'
DeviceManufacturer:
type: string
enum:
- Ingenico
- Innowi
- PAX
- Verifone
- Castles
- Miura
example: PAX
description: 'Specifies the company which manufactured the device.
'
giftcards_activate_p2pe_tdesdukpt_msr:
title: P2PE - TDES DUKPT - MSR/Manual
type: object
required:
- dateTime
- amount
- card
- transaction
- p2pe
- device
properties:
dateTime:
$ref: '#/components/schemas/DateTime'
amount:
$ref: '#/components/schemas/AmountGC'
card:
type: object
required:
- present
properties:
present:
$ref: '#/components/schemas/CardPresent'
transaction:
type: object
required:
- invoice
properties:
invoice:
$ref: '#/components/schemas/TransactionInvoice'
device:
type: object
required:
- manufacturer
- model
- serialNumber
- capability
properties:
manufacturer:
$ref: '#/components/schemas/DeviceManufacturer'
model:
$ref: '#/components/schemas/DeviceModel'
serialNumber:
$ref: '#/components/schemas/DeviceSerialNumber'
capability:
$ref: '#/components/schemas/DeviceCapability'
p2pe:
$ref: '#/components/schemas/P2PEType05TDESDUKPTMSR'
example:
dateTime: '2021-04-15T09:18:23.283-07:00'
amount:
total: 25
card:
present: Y
device:
manufacturer: PAX
model: A930
serialNumber: '1170301234'
capability:
contactlessEMV: Y
contactlessMSR: Y
EMV: Y
magstripe: Y
manualEntry: Y
quickChip: Y
p2pe:
data: 44188C9A20DD2092254F7FEB0AABD531D86EA10DA37E5540C25B53658BA4FBB903828F835A7287481F6FB5C17A879ECC9768D4C12F99532A
format: '05'
ksn: FFFF49517300010000C9
transaction:
invoice: '192029'
CardExpirationDateResponse:
type: integer
minLength: 3
maxLength: 4
format: MMYY
example: 1230
description: "**Conditional: Requires API Option \"RETURNEXPDATE\".**\n\nCard expiration date in MMYY format. This value will only be populated if \"RETURNEXPDATE\" is included in the `apiOptions` array. \n"
P2PEFormatOnguardSDE:
type: string
minLength: 2
maxLength: 2
enum:
- '03'
example: '03'
description: 'Classifies the type of payment device being used for P2PE.
Value|Description
-----|-----------
03 | Ingenico Onguard SDE Format
'
DeviceCapabilityContactlessMSR:
type: string
enum:
- Y
- N
example: Y
description: '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.
'
P2PEData:
type: string
maxLength: 2048
example: 027101801F2D1E00939B%*432100******1119^VS/DUAL TRACK^2212******?*;432100******1119=2212******?*CECE3FCE7781142BEC8D0E267AE89F5D3C7E235BF1A70E637951E8D93003E5A2586C336CA4A3B31F6639B04005BB12A716D8BC4D3AB125C27AB11A9DDC02816569D42A20B036EE5E2C71CB70565FB43B000000000000000000000000000000000000000000000000000000000000000000000000000000003434345434363138343962994950010038200415953903
description: 'The full output of a P2PE keypad/magnetic swipe reader (MSR).
'
giftcards_balance_comengcloud:
title: Commerce Engine For Cloud
type: object
required:
- dateTime
- device
- card
- transaction
properties:
dateTime:
$ref: '#/components/schemas/DateTime'
card:
type: object
required:
- present
properties:
present:
$ref: '#/components/schemas/CardPresent'
device:
$ref: '#/components/schemas/DeviceComEngCloud'
transaction:
type: object
required:
- invoice
properties:
invoice:
$ref: '#/components/schemas/TransactionInvoice'
apiOptions:
$ref: '#/components/schemas/ApiOptionsGCBalance'
ui:
type: object
properties:
language:
$ref: '#/components/schemas/UILanguageRequest'
mode:
$ref: '#/components/schemas/UIMode'
suppressFinalResult:
$ref: '#/components/schemas/UISuppressFinalResult'
example:
dateTime: '2021-04-15T09:18:23.283-07:00'
card:
present: Y
device:
cloud: true
manufacturer: PAX
serialNumber: '1170301234'
transaction:
invoice: '192029'
P2PEDataOnguardSDEMSR:
type: string
maxLength: 2048
example: FFFF495A0000000200000005:4:0128:F48C880DE0DAF549E642C5CC25E65ADF9947E7EB0636DB80C4A490B4C0930AEF64B7201505343CED533A2AE9AFABFE6453875F705519A8109362197CA3BD8DA0FE90DB3F954B9CDA0DB58BDA3330862ADD28CB31EFDA7C641575E33D395D8BFF72EBF0B1FF9630DB0EAB080FE8C9B2FAC28127CDC48CA9F7D532D5BDE4CCE270
description: "Track information encrypted with AES 256 DUKPT. Contains the following information, separated by colons:\n \n|Value | Description\n|----------------|------------\n|ksn | The key serial number (24 byte hex)\n|track indicator | `1` = track 1 only
`2` = track 2 only
`3` = manual entry
`4` = dual track
\n|length | The length of the encrypted data\n|encrypted data | Encrypted track/manual entry data\n\nDual Track Example: `FFFF495A0000000200000005:4:0128:F48C880DE0DAF549E642C5CC25E65ADF9947E7EB0636DB80C4A490B4C0930AEF64B7201505343CED533A2AE9AFABFE6453875F705519A8109362197CA3BD8DA0FE90DB3F954B9CDA0DB58BDA3330862ADD28CB31EFDA7C641575E33D395D8BFF72EBF0B1FF9630DB0EAB080FE8C9B2FAC28127CDC48CA9F7D532D5BDE4CCE270`\n\nManual entry Example: `FFFF495A0000000200000006:3:0032:E394820DB97AF927B9B5E05F356750BBF5DFCCB3BC18B87E8FC3C9BC596229E7`\n"
UILanguageRequest:
type: string
example: en
description: '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.
'
giftcards_reload_p2pe_tdesdukpt_msr:
title: P2PE - TDES DUKPT - MSR/Manual
type: object
required:
- dateTime
- amount
- card
- transaction
- p2pe
- device
properties:
dateTime:
$ref: '#/components/schemas/DateTime'
amount:
$ref: '#/components/schemas/AmountGC'
card:
type: object
required:
- present
properties:
present:
$ref: '#/components/schemas/CardPresent'
transaction:
type: object
required:
- invoice
properties:
invoice:
$ref: '#/components/schemas/TransactionInvoice'
device:
type: object
required:
- manufacturer
- model
- serialNumber
- capability
properties:
manufacturer:
$ref: '#/components/schemas/DeviceManufacturer'
model:
$ref: '#/components/schemas/DeviceModel'
serialNumber:
$ref: '#/components/schemas/DeviceSerialNumber'
capability:
$ref: '#/components/schemas/DeviceCapability'
p2pe:
$ref: '#/components/schemas/P2PEType05TDESDUKPTMSR'
example:
dateTime: '2021-04-15T09:18:23.283-07:00'
amount:
total: 25
card:
present: Y
device:
manufacturer: PAX
model: A930
serialNumber: '1170301234'
capability:
contactlessEMV: Y
contactlessMSR: Y
EMV: Y
magstripe: Y
manualEntry: Y
quickChip: Y
p2pe:
data: 44188C9A20DD2092254F7FEB0AABD531D86EA10DA37E5540C25B53658BA4FBB903828F835A7287481F6FB5C17A879ECC9768D4C12F99532A
format: '05'
ksn: FFFF49517300010000C9
transaction:
invoice: '192029'
UniversalToken:
type: object
properties:
value:
$ref: '#/components/schemas/UniversalTokenValue'
DeviceTerminalId:
type: string
maxLength: 32
example: '1742'
description: '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:
title: P2PE - TDES DUKPT - MSR/Manual
type: object
required:
- dateTime
- card
- transaction
- p2pe
- device
properties:
dateTime:
$ref: '#/components/schemas/DateTime'
card:
type: object
required:
- deactivationReason
- present
properties:
deactivationReason:
$ref: '#/components/schemas/CardDeactivationReason'
present:
$ref: '#/components/schemas/CardPresent'
transaction:
type: object
required:
- invoice
properties:
invoice:
$ref: '#/components/schemas/TransactionInvoice'
device:
type: object
required:
- manufacturer
- model
- serialNumber
- capability
properties:
manufacturer:
$ref: '#/components/schemas/DeviceManufacturer'
model:
$ref: '#/components/schemas/DeviceModel'
serialNumber:
$ref: '#/components/schemas/DeviceSerialNumber'
capability:
$ref: '#/components/schemas/DeviceCapability'
p2pe:
$ref: '#/components/schemas/P2PEType05TDESDUKPTMSR'
example:
dateTime: '2021-04-15T09:18:23.283-07:00'
card:
deactivationReason: Stolen
present: Y
device:
manufacturer: PAX
model: A930
serialNumber: '1170301234'
capability:
contactlessEMV: Y
contactlessMSR: Y
EMV: Y
magstripe: Y
manualEntry: Y
quickChip: Y
p2pe:
data: 44188C9A20DD2092254F7FEB0AABD531D86EA10DA37E5540C25B53658BA4FBB903828F835A7287481F6FB5C17A879ECC9768D4C12F99532A
format: '05'
ksn: FFFF49517300010000C9
transaction:
invoice: '192029'
giftcards_deactivate_comengdevice:
title: Commerce Engine For On Premise
type: object
required:
- dateTime
- card
- transaction
properties:
dateTime:
$ref: '#/components/schemas/DateTime'
card:
type: object
required:
- deactivationReason
- present
properties:
deactivationReason:
$ref: '#/components/schemas/CardDeactivationReason'
present:
$ref: '#/components/schemas/CardPresent'
device:
type: object
properties:
terminalId:
$ref: '#/components/schemas/DeviceTerminalIdComEng'
transaction:
type: object
required:
- invoice
properties:
invoice:
$ref: '#/components/schemas/TransactionInvoice'
ui:
type: object
properties:
language:
$ref: '#/components/schemas/UILanguageRequest'
mode:
$ref: '#/components/schemas/UIMode'
suppressFinalResult:
$ref: '#/components/schemas/UISuppressFinalResult'
example:
dateTime: '2021-04-15T09:18:23.283-07:00'
card:
deactivationReason: Stolen
present: N
transaction:
invoice: '192029'
giftcards_reload_utgdevice:
title: UTG Controlled Device
type: object
required:
- dateTime
- amount
- device
- card
- transaction
properties:
dateTime:
$ref: '#/components/schemas/DateTime'
amount:
$ref: '#/components/schemas/AmountGC'
card:
type: object
required:
- present
properties:
present:
$ref: '#/components/schemas/CardPresent'
device:
type: object
required:
- terminalId
properties:
terminalId:
$ref: '#/components/schemas/DeviceTerminalId'
promptCardSecurityCode:
$ref: '#/components/schemas/DevicePromptCardSecurityCode'
transaction:
type: object
required:
- invoice
properties:
invoice:
$ref: '#/components/schemas/TransactionInvoice'
example:
dateTime: '2021-04-15T09:18:23.283-07:00'
amount:
total: 25
card:
present: Y
device:
terminalId: '1742'
transaction:
invoice: '192029'
CardSecurityCodeGC:
type: object
properties:
value:
$ref: '#/components/schemas/CardSecurityCodeValueGC'
giftcards_activate_utgdevice:
title: UTG Controlled Device
type: object
required:
- dateTime
- amount
- device
- card
- transaction
properties:
dateTime:
$ref: '#/components/schemas/DateTime'
amount:
$ref: '#/components/schemas/AmountGC'
card:
type: object
required:
- present
properties:
present:
$ref: '#/components/schemas/CardPresent'
device:
type: object
required:
- terminalId
properties:
terminalId:
$ref: '#/components/schemas/DeviceTerminalId'
promptCardSecurityCode:
$ref: '#/components/schemas/DevicePromptCardSecurityCode'
transaction:
type: object
required:
- invoice
properties:
invoice:
$ref: '#/components/schemas/TransactionInvoice'
example:
dateTime: '2021-04-15T09:18:23.283-07:00'
amount:
total: 25
card:
present: Y
device:
terminalId: '1742'
transaction:
invoice: '192029'
ErrorShortText:
type: string
maxLength: 16
readOnly: true
example: NOT IN CARDRANGE
description: 'Abbreviated error message that is always returned if an error condition exists
'
DeviceComEngCloud:
type: object
required:
- cloud
- manufacturer
- serialNumber
properties:
cloud:
$ref: '#/components/schemas/DeviceCloud'
manufacturer:
$ref: '#/components/schemas/DeviceManufacturer'
serialNumber:
$ref: '#/components/schemas/DeviceSerialNumber'
giftcards_activate_p2pe_idtech:
title: P2PE - ID TECH - MSR/Manual
type: object
required:
- dateTime
- amount
- card
- transaction
- p2pe
properties:
dateTime:
$ref: '#/components/schemas/DateTime'
amount:
$ref: '#/components/schemas/AmountGC'
card:
type: object
required:
- present
properties:
present:
$ref: '#/components/schemas/CardPresent'
transaction:
type: object
required:
- invoice
properties:
invoice:
$ref: '#/components/schemas/TransactionInvoice'
p2pe:
$ref: '#/components/schemas/P2PEType0102IDTECH'
example:
dateTime: '2021-04-15T09:18:23.283-07:00'
amount:
total: 25
card:
present: Y
p2pe:
data: 02B600C0170018009292;000442******0006=3012?*61A0453AB7145F1FA7685D2F27A745E129525EDAEA5BB7DBBAF49A5F876E3EE5000000000000000000000000000000000000000034343454343631383439629949500100382003E6FF4D03
format: '01'
transaction:
invoice: '192029'
giftcards_reactivate_unencryptedcard:
title: Card Number Unencrypted
type: object
required:
- dateTime
- card
- transaction
properties:
dateTime:
$ref: '#/components/schemas/DateTime'
card:
type: object
required:
- present
- number
properties:
present:
$ref: '#/components/schemas/CardPresent'
number:
$ref: '#/components/schemas/CardNumberGC'
expirationDate:
$ref: '#/components/schemas/CardExpirationDateGC'
securityCode:
$ref: '#/components/schemas/CardSecurityCodeGC'
transaction:
type: object
required:
- invoice
properties:
invoice:
$ref: '#/components/schemas/TransactionInvoice'
example:
dateTime: '2021-04-15T09:18:23.283-07:00'
card:
expirationDate: 1230
number: '2664654648774'
present: Y
transaction:
invoice: '192029'
LighthouseDataResponse:
type: string
example: eyJwYXltZW50SWQiOiI4NWM0MWNhNy01NzVjLTQzNGUtODIyZi0xYzZlOTE0ZDAzODYiLCJyZW1haW5pbmdBbW91bnQiOjB9
description: 'Base64 encoded JSON formatted data that will be returned from Lighthouse to be passed back to SkyTab. This data will contain variable information.
'
TransactionAuthSource:
type: string
minLength: 1
maxLength: 1
readOnly: true
example: E
enum:
- E
- O
- A
- F
description: "In a response, a code returned by the processor to indicate which host issued the response.\n\nValue | Description \n-------|----------------------------\nE | Engine (Online)\nO | Offline\nA | APM (Online)\nF | Payment Platform (Online)\n"
UniversalTokenValue:
type: string
maxLength: 50
example: 97032276-5944-00000001-16985FD179D
description: 'An identifier for a card or payment account across all Shift4 merchants.
'
giftcards_activate_p2pe_onguardsde_msr:
title: P2PE - On-Guard SDE - MSR/Manual
type: object
required:
- dateTime
- amount
- card
- transaction
- p2pe
- device
properties:
dateTime:
$ref: '#/components/schemas/DateTime'
amount:
$ref: '#/components/schemas/AmountGC'
card:
type: object
required:
- present
properties:
present:
$ref: '#/components/schemas/CardPresent'
transaction:
type: object
required:
- invoice
properties:
invoice:
$ref: '#/components/schemas/TransactionInvoice'
device:
type: object
required:
- manufacturer
- model
- serialNumber
- capability
properties:
manufacturer:
$ref: '#/components/schemas/DeviceManufacturer'
model:
$ref: '#/components/schemas/DeviceModel'
serialNumber:
$ref: '#/components/schemas/DeviceSerialNumber'
capability:
$ref: '#/components/schemas/DeviceCapability'
p2pe:
$ref: '#/components/schemas/P2PEType03OnguardSDEMSR'
example:
dateTime: '2023-12-13T09:18:23.283-07:00'
amount:
total: 25
card:
present: Y
device:
manufacturer: Ingenico
model: Axium DX8000
serialNumber: 20ACCD801843
capability:
contactlessEMV: Y
contactlessMSR: N
EMV: Y
manualEntry: Y
magstripe: Y
PIN: Y
quickChip: Y
signature: Y
p2pe:
data: FFFF495A0000000200000005:4:0128:F48C880DE0DAF549E642C5CC25E65ADF9947E7EB0636DB80C4A490B4C0930AEF64B7201505343CED533A2AE9AFABFE6453875F705519A8109362197CA3BD8DA0FE90DB3F954B9CDA0DB58BDA3330862ADD28CB31EFDA7C641575E33D395D8BFF72EBF0B1FF9630DB0EAB080FE8C9B2FAC28127CDC48CA9F7D532D5BDE4CCE270
format: '03'
transaction:
invoice: '192029'
CardTokenValue:
description: '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.
'
type: string
maxLength: 16
example: '8048471746471119'
DeviceCapabilityContactlessEMV:
type: string
enum:
- Y
- N
example: Y
description: '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.
'
DeviceCloud:
type: boolean
example: true
description: '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.
'
CardExpirationDateGC:
type: integer
minLength: 3
maxLength: 4
format: MMYY
example: 1230
description: '**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.
'
giftcards_balance_token_legacy:
title: Legacy TrueToken
type: object
required:
- dateTime
- card
- transaction
properties:
dateTime:
$ref: '#/components/schemas/DateTime'
card:
type: object
required:
- present
- token
properties:
expirationDate:
$ref: '#/components/schemas/CardExpirationDateGC'
present:
$ref: '#/components/schemas/CardPresent'
token:
$ref: '#/components/schemas/CardTokenRequiredLegacy'
transaction:
type: object
required:
- invoice
properties:
invoice:
$ref: '#/components/schemas/TransactionInvoice'
apiOptions:
$ref: '#/components/schemas/ApiOptionsGCBalance'
example:
dateTime: '2021-04-15T09:18:23.283-07:00'
card:
present: Y
expirationDate: 1225
token:
value: 87743q5p3ffhv67y
serialNumber: '123456'
transaction:
invoice: '192029'
parameters:
AccessToken:
required: true
name: AccessToken
in: header
schema:
type: string
format: uuid
maxLength: 52
example: EA79FB05-3AA7-4500-AF9A-73F986FF2C1D
description: '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`.
'
CompanyName:
required: true
name: CompanyName
in: header
schema:
type: string
maxLength: 26
example: PAWS
description: '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: $ % : ^ - ~ ` < > , ? “ ” ‘ ’ { } [ ] \ + =
'
InterfaceName:
required: true
name: InterfaceName
in: header
schema:
type: string
maxLength: 25
example: ForwardPOS
description: '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: $ % : ^ - ~ ` < > , ? “ ” ‘ ’ { } [ ] \ + =
'
InterfaceVersion:
required: true
name: InterfaceVersion
in: header
schema:
type: string
maxLength: 11
example: '2.1'
description: 'Refers to the version of the program or application that is sending requests to Shift4. The following special characters are not allowed: $ % : ^ - ~ < > , ? “ ” ‘ ’ { } [ ] \ + =
'
responses:
TimeoutResponse:
description: Timeout
content:
application/json:
schema:
properties:
result:
type: array
items:
type: object
properties:
error:
$ref: '#/components/schemas/Error'
lighthouse:
type: object
properties:
data:
$ref: '#/components/schemas/LighthouseDataResponse'
server:
$ref: '#/components/schemas/Server'
example:
result:
- error:
primaryCode: 9951
secondaryCode: 0
shortText: RESPONSE TIMEOUT
longText: Timeout waiting for response across the internet
lighthouse:
data: eyJwYXltZW50SWQiOiI4NWM0MWNhNy01NzVjLTQzNGUtODIyZi0xYzZlOTE0ZDAzODYiLCJyZW1haW5pbmdBbW91bnQiOjB9
server:
name: U2API01CE
CardTokenErrorResponse:
description: Error
content:
application/json:
schema:
properties:
result:
type: array
items:
type: object
properties:
error:
$ref: '#/components/schemas/Error'
server:
$ref: '#/components/schemas/Server'
example:
result:
- error:
primaryCode: 9846
secondaryCode: 0
shortText: BAD UNIQUE ID
longText: Unique Identifier(8048471746471119) not found for Merchant 0000057984 ENGINE01CE
server:
name: U2API01CE
examples:
GiftCardActivateError:
summary: Gift Card Activate Failed
value:
result:
- error:
primaryCode: 9101
secondaryCode: 0
shortText: ACTIVATE FAILED
longText: 'ACTIVATE FAILED iyc_activateCard: Invalid card or serial number 222 Mid(444444) Invoice(6200007001) ENGINE01CE'
server:
name: U2API01CE
securitySchemes:
AccessToken:
type: apiKey
name: AccessToken
in: header
description: "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. \n\nExample:\n ```\n AccessToken: EA79FB05-3AA7-4500-AF9A-73F986FF2C1D\n ```\n"
HMAC-SHA256:
type: http
scheme: hmac-sha256
description: "Authentication using HMAC-256 signatures as the authorization scheme.\n\nSent in the `Authorization` header in the following format:\n\n`Authorization`: **HMAC-SHA256** `Credential`={value}&`Signature`={value}\n\n| Argument | Description |\n|---------------|--------------------------------------------------|\n| HMAC-SHA256 | Authorization scheme. |\n| Credential | The ID of the key used to compute the signature. |\n| Signature | base64 encoded HMACSHA256 value. |\n\nExample: \n ```\n Authorization: HMAC-SHA256 Credential=AESKEY1&Signature=8SFtIc6zQlswxAZqDKXL+BpRmlDvIWyjOwU8wdl0zK4=\n ```\n"