デバイスゲートウェイAPI
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.
HTTP header identifying the actor initiating the request.
The Card Issuer Identifier. Unique for each card issuer.
The Card Identifier. Unique for each card.
The Purchase Identifier. Unique for each purchase. It is provided when the call is related to topup initiated from wallet.
The Device Identifier. Unique for each device.
The operation for which the commands are requested
Total time of all executed commands listed in responses array in milliseconds.
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 |
Textual status message
getCardCommands response payload
Internal Server Error
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-01-01T00:00:00.000Z"
},
"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-01-01T00:00:00.000Z",
"statusCode": 1,
"statusMessage": "text"
},
"commands": [
{
"id": "text",
"name": "text",
"value": "text"
}
]
}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.
HTTP header identifying the actor initiating the request.
The Card Issuer Identifier. Unique for each card issuer.
The Card Identifier. Unique for each card.
The Device Identifier. Unique for each device.
The operation for which the commands are requested
Total time of all executed commands listed in responses array in milliseconds.
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 |
Textual status message
getParkCardCommands response payload
Internal Server Error
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-01-01T00:00:00.000Z"
},
"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-01-01T00:00:00.000Z",
"statusCode": 1,
"statusMessage": "text"
},
"commands": [
{
"id": "text",
"name": "text",
"value": "text"
}
],
"cardData": {
"balanceAmount": 1
}
}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.
HTTP header identifying the actor initiating the request.
The Card Issuer Identifier. Unique for each card issuer.
The Device Identifier. Unique for each device.
The operation for which the commands are requested
Total time of all executed commands listed in responses array in milliseconds.
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"
}
]
}
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 |
Textual status message
getReaderModeCommands response payload
The Card Account Identifier. Unique for each card account.
Internal Server Error
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-01-01T00:00:00.000Z"
},
"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-01-01T00:00:00.000Z",
"statusCode": 1,
"statusMessage": "text"
},
"commands": [
{
"id": "text",
"name": "text",
"value": "text"
}
],
"cardAccountId": "text",
"cardData": {
"balanceAmount": 1
}
}最終更新
役に立ちましたか？