Device Gateway API

Request to provide the next list of commands to be executed on a device

post

This method is used by TSH to request the pending commands to be executed on a device. It is used for reading/updating the content of a device (e.g. topup). The TES has to return the list of commands that needs to be executed on the device after checking the previous commands responses.

Header parameters

x-actor-idstring · max: 32Required

HTTP header identifying the actor initiating the request.

Body

issuerIdstring · min: 1 · max: 16Required

The Card Issuer Identifier. Unique for each card issuer.

cardIdstring · min: 1 · max: 48Required

The Card Identifier. Unique for each card.

purchaseIdstring · min: 1 · max: 64Optional

The Purchase Identifier. Unique for each purchase. It is provided when the call is related to topup initiated from wallet.

deviceIdstring · min: 1 · max: 48Required

The Device Identifier. Unique for each device.

operationstring · enumOptional

The operation for which the commands are requested

Possible values:

responseTimeMsnumber · doubleOptional

Total time of all executed commands listed in responses array in milliseconds.

statusCodenumberOptional

Status code to the request

Status code	Description
0	OK
111	Missing mandatory parameter
112	Bad parameter format
113	Unknown issuer
117	Unknown device
118	Unknown session
119	Unknown virtual card
159	Card is blacklisted
160	Card is deleted
162	Card has unsufficient balance
163	Card product not eligible
167	Card is already provisioned
172	Invalid card, unsupported system code
173	Invalid card, unsupported service
177	Invalid card, invalid area data
178	Invalid card, card status is in-station
191	Card is expired
192	Reader mode attempt exceeded allowed threshold
221	Device or wallet server not accessible
231	Device unexpected error
232	Device out of memory error
321	Operation already on-going for this device
322	Time to live of the operation expired
323	Operation incomplete
911	Operation failed
921	Unexpected server error

statusMessagestringOptional

Textual status message

Responses

200

getCardCommands response payload

application/json

500

Internal Server Error

post

/getCardCommands

POST /tes/devicegtwapi/1/0/getCardCommands HTTP/1.1
x-actor-id: text
Content-Type: application/json
Accept: */*
Content-Length: 318

{
  "requestHeader": {
    "requestId": "text",
    "sessionId": "text",
    "generationDateTime": "2026-06-16T09:13:50.733Z"
  },
  "issuerId": "text",
  "cardId": "text",
  "purchaseId": "text",
  "deviceId": "text",
  "operation": "READ_BALANCE",
  "responses": [
    {
      "id": "text",
      "name": "text",
      "value": "text"
    }
  ],
  "responseTimeMs": 1,
  "statusCode": 1,
  "statusMessage": "text"
}

{
  "responseHeader": {
    "responseId": "text",
    "sessionId": "text",
    "generationDateTime": "2026-06-16T09:13:50.733Z",
    "statusCode": 1,
    "statusMessage": "text"
  },
  "commands": [
    {
      "id": "text",
      "name": "text",
      "value": "text"
    }
  ]
}

Request to provide the next list of commands to be executed on a device for parking a card

post

This method is used by TSH to request the pending commands to be executed on a device. It is used for parking a card (meaning reading the current balance of a card for storing it on server side). The TES has to return the list of commands that needs to be executed on the device after checking the previous commands responses. Once the card has been parked on TES side, the TES has to return the card balance to TSH on last response.

Header parameters

x-actor-idstring · max: 32Required

HTTP header identifying the actor initiating the request.

Body

issuerIdstring · min: 1 · max: 16Required

The Card Issuer Identifier. Unique for each card issuer.

cardIdstring · min: 1 · max: 48Required

The Card Identifier. Unique for each card.

deviceIdstring · min: 1 · max: 48Required

The Device Identifier. Unique for each device.

operationstring · enumOptional

The operation for which the commands are requested

Possible values:

responseTimeMsnumber · doubleOptional

Total time of all executed commands listed in responses array in milliseconds.

statusCodenumberOptional

Status code to the request

Status code	Description
0	OK
111	Missing mandatory parameter
112	Bad parameter format
113	Unknown issuer
117	Unknown device
118	Unknown session
119	Unknown virtual card
159	Card is blacklisted
160	Card is deleted
162	Card has unsufficient balance
163	Card product not eligible
167	Card is already provisioned
172	Invalid card, unsupported system code
173	Invalid card, unsupported service
177	Invalid card, invalid area data
178	Invalid card, card status is in-station
191	Card is expired
192	Reader mode attempt exceeded allowed threshold
221	Device or wallet server not accessible
231	Device unexpected error
232	Device out of memory error
321	Operation already on-going for this device
322	Time to live of the operation expired
323	Operation incomplete
911	Operation failed
921	Unexpected server error

statusMessagestringOptional

Textual status message

Responses

200

getParkCardCommands response payload

application/json

500

Internal Server Error

post

/getParkCardCommands

POST /tes/devicegtwapi/1/0/getParkCardCommands HTTP/1.1
x-actor-id: text
Content-Type: application/json
Accept: */*
Content-Length: 298

{
  "requestHeader": {
    "requestId": "text",
    "sessionId": "text",
    "generationDateTime": "2026-06-16T09:13:50.733Z"
  },
  "issuerId": "text",
  "cardId": "text",
  "deviceId": "text",
  "operation": "READ_BALANCE",
  "responses": [
    {
      "id": "text",
      "name": "text",
      "value": "text"
    }
  ],
  "responseTimeMs": 1,
  "statusCode": 1,
  "statusMessage": "text"
}

{
  "responseHeader": {
    "responseId": "text",
    "sessionId": "text",
    "generationDateTime": "2026-06-16T09:13:50.733Z",
    "statusCode": 1,
    "statusMessage": "text"
  },
  "commands": [
    {
      "id": "text",
      "name": "text",
      "value": "text"
    }
  ],
  "cardData": {
    "balanceAmount": 1
  }
}

Request to provide the next list of reader mode commands to be executed on a device

post

This method is used by TSH to request the pending reader mode commands to be executed on a device. It is used for reading/updating the content of an external device. The TES has to return the list of commands that needs to be executed on the device after checking the previous commands responses. Once the card has been ingested on TES side, the TES has to create a new card account and return the card balance and card account identifier to TSH on last response.

Header parameters

x-actor-idstring · max: 32Required

HTTP header identifying the actor initiating the request.

Body

issuerIdstring · min: 1 · max: 16Required

The Card Issuer Identifier. Unique for each card issuer.

deviceIdstring · min: 1 · max: 48Required

The Device Identifier. Unique for each device.

operationstring · enumOptional

The operation for which the commands are requested

Possible values:

responseTimeMsnumber · doubleOptional

Total time of all executed commands listed in responses array in milliseconds.

cardContentsobjectOptional

This object gives a description of the external SE. For FeliCa, the following can be provided:

"cardContents": {
	"cardServiceId" : "Test Service",
	"systemCode" : "FE00",
	"idm" : "1122334455667788",
	"pmm" : "0000000000000000",
	"areaCodeList" : [
		{
			"areaCode" : "0100",
			"keyVersion" : "6745"
		},
		{
			"areaCode" : "1000",
			"keyVersion" : "4567"
		}
	]
}

statusCodenumberOptional

Status code to the request

Status code	Description
0	OK
111	Missing mandatory parameter
112	Bad parameter format
113	Unknown issuer
117	Unknown device
118	Unknown session
119	Unknown virtual card
159	Card is blacklisted
160	Card is deleted
162	Card has unsufficient balance
163	Card product not eligible
167	Card is already provisioned
172	Invalid card, unsupported system code
173	Invalid card, unsupported service
177	Invalid card, invalid area data
178	Invalid card, card status is in-station
191	Card is expired
192	Reader mode attempt exceeded allowed threshold
221	Device or wallet server not accessible
231	Device unexpected error
232	Device out of memory error
321	Operation already on-going for this device
322	Time to live of the operation expired
323	Operation incomplete
911	Operation failed
921	Unexpected server error

statusMessagestringOptional

Textual status message

Responses

200

getReaderModeCommands response payload

application/json

cardAccountIdstring · min: 1 · max: 48Optional

The Card Account Identifier. Unique for each card account.

500

Internal Server Error

post

/getReaderModeCommands

POST /tes/devicegtwapi/1/0/getReaderModeCommands HTTP/1.1
x-actor-id: text
Content-Type: application/json
Accept: */*
Content-Length: 300

{
  "requestHeader": {
    "requestId": "text",
    "sessionId": "text",
    "generationDateTime": "2026-06-16T09:13:50.733Z"
  },
  "issuerId": "text",
  "deviceId": "text",
  "operation": "READ_BALANCE",
  "responses": [
    {
      "id": "text",
      "name": "text",
      "value": "text"
    }
  ],
  "responseTimeMs": 1,
  "cardContents": {},
  "statusCode": 1,
  "statusMessage": "text"
}

{
  "responseHeader": {
    "responseId": "text",
    "sessionId": "text",
    "generationDateTime": "2026-06-16T09:13:50.733Z",
    "statusCode": 1,
    "statusMessage": "text"
  },
  "commands": [
    {
      "id": "text",
      "name": "text",
      "value": "text"
    }
  ],
  "cardAccountId": "text",
  "cardData": {
    "balanceAmount": 1
  }
}

PreviousTransit API NextHealthcheck API

Last updated 4 months ago

Was this helpful?