TSP90 핀패드 제어 서비스

SP90 핀패드 단말기를 제어하기 위한 API 그룹입니다.

서비스 리스트

No.	서비스명	API명	비고
1	핀패드 초기화	`TSP90.Init`	포트 오픈 및 하드웨어 초기화
2	버전 정보 조회	`TSP90.GetVersion`	펌웨어/DLL 버전 획득
3	스피커 볼륨 조회	`TSP90.GetVolume`	1~10
4	버튼 볼륨 조회	`TSP90.GetButtonVolume`	1~10
5	밝기 조회	`TSP90.GetBright`	1~10
6	폰트 조회	`TSP90.GetFont`	설정된 폰트명 반환
7	스피커 볼륨 설정	`TSP90.SetVolume`	1~10
8	버튼 볼륨 설정	`TSP90.SetButtonVolume`	1~10
9	밝기 설정	`TSP90.SetBright`	1~10
10	폰트 설정	`TSP90.SetFont`	굴림체 / 엽서체
11	대기화면 설정	`TSP90.SetWindow`	대기 이미지/비디오 인덱스 지정
12	비밀번호 입력	`TSP90.Read`	비밀번호(최대 4자리) 입력
13	주민등록번호 입력	`TSP90.SSNRead`	주민번호(최대 13자리) 입력
14	다이얼로그 입력	`TSP90.ReadProcess`	화면 다이얼로그 문구 노출 모드
15	비다이얼로그 입력	`TSP90.ReadNDProcess`	다이얼로그 없는 입력 모드
16	자동 확인	`TSP90.PINAutoConfirmed`	최소 입력 충족 시 즉시 반환
17	입력 프로세스 강제종료	`TSP90.Off`	진행 중인 입력 즉시 취소
18	미디어 출력	`TSP90.MediaOut`	이미지/텍스트/음성 통합 출력
19	핀패드 폼(그리드) 출력	`TSP90.PinpadFormOut`	테이블 형태 Grid 데이터 출력

서비스 상태 코드 리스트

본 서비스에서 공통으로 사용되는 서비스 상태코드 리스트입니다. 응답 JSON 메시지 중 return 또는 return.returnValue 값에 해당합니다.

리턴코드	내용	상세 설명
0	성공	정상적으로 서비스를 호출했습니다.
-1	정의되지 않은 예외	로그 파일 확인이 필요합니다.
1	Fail(0) 리턴	핀패드 제어 DLL Method 호출 결과 Fail(0)이 리턴되었습니다.
2	PINOn Fail	`PINOn()` 호출 결과 Fail(0)이 리턴되었습니다.
3	PINStart Fail	`PINStart()` 호출 결과 Fail(0)이 리턴되었습니다.
4	PINRead Fail	`PINRead()` 호출 결과 Fail(0)이 리턴되었습니다.
5	PINStartSSN Fail	`PINStartSSN()` 호출 결과 Fail(0)이 리턴되었습니다.
6	이미지 파일 부재	`SetDefaultWindow()`에서 핀패드에 지정된 인덱스의 이미지 파일이 존재하지 않음(-1)이 리턴되었습니다.
7	하드웨어 에러	`SetDefaultWindow()`에서 하드웨어 에러(0)가 리턴되었습니다.
8	지원 범위 초과 파라미터	지원 범위를 벗어난 파라미터가 입력되었습니다.
9	유효하지 않은 파라미터	유효하지 않은 파라미터가 입력되었습니다.
10	사용자 취소	`ReadProcess()` 진행 중 사용자가 취소 버튼을 클릭했습니다.
11	유효하지 않은 데이터	핀패드에서 전달받은 데이터가 유효하지 않은 데이터입니다.
12	데이터 변환 실패	핀패드에서 전달받은 데이터를 변환하지 못했습니다.
13	폰트 데이터 변환 실패	파라미터로 전달받은 폰트 데이터 변환에 실패했습니다.
14	다이얼로그 데이터 변환 실패	파라미터로 전달받은 다이얼로그 메시지 데이터 변환에 실패했습니다.
15	이미지 리스트 변환 실패	파라미터로 전달받은 이미지 리스트 Array의 데이터 변환에 실패했습니다.
16	데이터 추출 실패	핀패드에서 전달받은 비밀번호/주민번호 데이터 추출에 실패했습니다.
17	작업 중복	이미 다른 입력 작업이 수행 중입니다.
18	취소/타임아웃 발생	핀패드 Read 중 사용자에 의한 취소 또는 타임아웃에 의한 취소가 발생했습니다.
19	Off 불가 상태	Off로 종료할 수 없는 입력 프로세스가 진행 중입니다.
101~121	Invoke 에러	핀패드 DLL 내부 메서드 호출 중 예외가 발생했습니다. (101: `PINInit`, 102: `GetPinpadVersion`, 103: `SetDefaultWindow`, 104: `GetVolume`, 105: `SetVolume`, 106: `GetBright`, 107: `SetBright`, 108: `GetFont`, 109: `SetFont`, 110: `PINOn`, 111: `PINStart`, 112: `PINRead`, 113: `PINOff`, 114: `PINStartSSN`, 115: `PINReadProcess`, 116: `PINReadProcessND`, 117: `PINAutoConfirmed`, 118: `MediaOut`, 119: `PinpadFormOut`, 120: `GetButtonVolume`, 121: `SetButtonVolume`)

1. 핀패드 초기화

API명

TSP90.Init

정의

TSP90 핀패드 디바이스 통신 포트를 열고 하드웨어를 초기화합니다.

호출 예시

{
  "service": "TSP90.Init",
  "requestKey": "REQ_PIN_INIT_01",
  "param": {}
}

param
- 전달할 파라미터 정보가 없습니다.

응답 예시

{
  "service": "TSP90.Init",
  "requestKey": "REQ_PIN_INIT_01",
  "statusCode": "0000",
  "return": 0
}

return
- 서비스 상태 코드입니다. (0: 성공, 그 외: 에러 코드)

2. 버전 정보 조회

API명

TSP90.GetVersion

정의

핀패드 장치 펌웨어 및 제어 DLL(TSP90Wrapper.dll)의 버전 정보를 조회합니다.

호출 예시

{
  "service": "TSP90.GetVersion",
  "requestKey": "REQ_PIN_VER_01",
  "param": {}
}

param
- 전달할 파라미터 정보가 없습니다.

응답 예시

{
  "service": "TSP90.GetVersion",
  "requestKey": "REQ_PIN_VER_01",
  "statusCode": "0000",
  "return": {
    "returnValue": 0,
    "version": "2.0.3.4"
  }
}

returnValue
- 서비스 상태 코드입니다. (0: 성공, 그 외: 에러 코드)
version
- 핀패드 장치 펌웨어 및 제어 DLL 버전 문자열입니다.

3. 스피커 볼륨 조회

API명

TSP90.GetVolume

정의

현재 핀패드 본체 스피커에 설정된 볼륨 수치를 조회합니다.

호출 예시

{
  "service": "TSP90.GetVolume",
  "requestKey": "REQ_PIN_VOL_01",
  "param": {}
}

param
- 전달할 파라미터 정보가 없습니다.

응답 예시

{
  "service": "TSP90.GetVolume",
  "requestKey": "REQ_PIN_VOL_01",
  "statusCode": "0000",
  "return": {
    "returnValue": 0,
    "volume": "5"
  }
}

returnValue
- 서비스 상태 코드입니다. (0: 성공, 그 외: 에러 코드)
volume
- 현재 설정된 스피커 볼륨 수치입니다. (1 ~ 10)

4. 버튼 볼륨 조회

API명

TSP90.GetButtonVolume

정의

핀패드 키패드 터치 시 발생하는 버튼 비프음의 볼륨 수치를 조회합니다.

호출 예시

{
  "service": "TSP90.GetButtonVolume",
  "requestKey": "REQ_PIN_BVOL_01",
  "param": {}
}

param
- 전달할 파라미터 정보가 없습니다.

응답 예시

{
  "service": "TSP90.GetButtonVolume",
  "requestKey": "REQ_PIN_BVOL_01",
  "statusCode": "0000",
  "return": {
    "returnValue": 0,
    "volume": "5"
  }
}

returnValue
- 서비스 상태 코드입니다. (0: 성공, 그 외: 에러 코드)
volume
- 현재 설정된 버튼음 볼륨 수치입니다. (1 ~ 10)

5. 밝기 조회

API명

TSP90.GetBright

정의

핀패드 LCD 화면의 밝기 수치를 조회합니다.

호출 예시

{
  "service": "TSP90.GetBright",
  "requestKey": "REQ_PIN_BRT_01",
  "param": {}
}

param
- 전달할 파라미터 정보가 없습니다.

응답 예시

{
  "service": "TSP90.GetBright",
  "requestKey": "REQ_PIN_BRT_01",
  "statusCode": "0000",
  "return": {
    "returnValue": 0,
    "bright": "8"
  }
}

returnValue
- 서비스 상태 코드입니다. (0: 성공, 그 외: 에러 코드)
bright
- 현재 설정된 LCD 화면 밝기 수치입니다. (1 ~ 10)

6. 폰트 조회

API명

TSP90.GetFont

정의

핀패드 LCD에 설정된 폰트 명칭을 조회합니다.

호출 예시

{
  "service": "TSP90.GetFont",
  "requestKey": "REQ_PIN_FONT_01",
  "param": {}
}

param
- 전달할 파라미터 정보가 없습니다.

응답 예시

{
  "service": "TSP90.GetFont",
  "requestKey": "REQ_PIN_FONT_01",
  "statusCode": "0000",
  "return": {
    "returnValue": 0,
    "font": "굴림체"
  }
}

returnValue
- 서비스 상태 코드입니다. (0: 성공, 그 외: 에러 코드)
font
- 현재 설정된 폰트 명칭입니다. (예: "굴림체", "엽서체")

7. 스피커 볼륨 설정

API명

TSP90.SetVolume

정의

핀패드 본체 스피커 볼륨 수치를 설정합니다.

호출 예시

{
  "service": "TSP90.SetVolume",
  "requestKey": "REQ_PIN_SETVOL_01",
  "param": {
    "volume": "7"
  }
}

volume
- 설정할 스피커 볼륨 수치입니다. (1 ~ 10)

응답 예시

{
  "service": "TSP90.SetVolume",
  "requestKey": "REQ_PIN_SETVOL_01",
  "statusCode": "0000",
  "return": 0
}

return
- 서비스 상태 코드입니다. (0: 성공, 그 외: 에러 코드)

8. 버튼 볼륨 설정

API명

TSP90.SetButtonVolume

정의

핀패드 버튼 터치 시 발생하는 비프음의 볼륨 수치를 설정합니다.

호출 예시

{
  "service": "TSP90.SetButtonVolume",
  "requestKey": "REQ_PIN_SETBVOL_01",
  "param": {
    "volume": "7"
  }
}

volume
- 설정할 버튼음 볼륨 수치입니다. (1 ~ 10)

응답 예시

{
  "service": "TSP90.SetButtonVolume",
  "requestKey": "REQ_PIN_SETBVOL_01",
  "statusCode": "0000",
  "return": 0
}

return
- 서비스 상태 코드입니다. (0: 성공, 그 외: 에러 코드)

9. 밝기 설정

API명

TSP90.SetBright

정의

핀패드 LCD 화면의 밝기 수치를 설정합니다.

호출 예시

{
  "service": "TSP90.SetBright",
  "requestKey": "REQ_PIN_SETBRT_01",
  "param": {
    "bright": "8"
  }
}

bright
- 설정할 LCD 화면 밝기 수치입니다. (1 ~ 10)

응답 예시

{
  "service": "TSP90.SetBright",
  "requestKey": "REQ_PIN_SETBRT_01",
  "statusCode": "0000",
  "return": 0
}

return
- 서비스 상태 코드입니다. (0: 성공, 그 외: 에러 코드)

10. 폰트 설정

API명

TSP90.SetFont

정의

핀패드 LCD 화면 출력에 적용할 폰트를 설정합니다.

호출 예시

{
  "service": "TSP90.SetFont",
  "requestKey": "REQ_PIN_SETFONT_01",
  "param": {
    "font": "굴림체"
  }
}

font
- 설정할 폰트 명칭입니다. (예: "굴림체", "엽서체")

응답 예시

{
  "service": "TSP90.SetFont",
  "requestKey": "REQ_PIN_SETFONT_01",
  "statusCode": "0000",
  "return": 0
}

return
- 서비스 상태 코드입니다. (0: 성공, 그 외: 에러 코드)

11. 대기화면 설정

API명

TSP90.SetWindow

정의

입력 대기 상태일 때 핀패드 LCD 화면에 순환 표시할 이미지 또는 동영상을 지정합니다.

호출 예시

{
  "service": "TSP90.SetWindow",
  "requestKey": "REQ_PIN_SETWIN_01",
  "param": {
    "type": "1",
    "size": "0",
    "imageIndex": "[21,22,23]",
    "interval": "3"
  }
}

type
- 화면에 표시할 미디어 종류입니다. (1: 이미지, 2: 동영상)
size
- 설정할 대상 화면 영역입니다. (0: 대기화면)
imageIndex
- 핀패드에 내장/등록된 이미지 또는 비디오 인덱스 목록 배열 문자열입니다. (예: "[21,22,23]")
interval
- 미디어 간 순환 전환 인터벌 주기입니다. (초 단위, 예: 3)

응답 예시

{
  "service": "TSP90.SetWindow",
  "requestKey": "REQ_PIN_SETWIN_01",
  "statusCode": "0000",
  "return": 0
}

return
- 서비스 상태 코드입니다. (0: 성공, 그 외: 에러 코드)

12. 비밀번호 입력

API명

TSP90.Read

정의

고객에게 핀패드 키패드를 통한 비밀번호(숫자) 입력을 요청하고 암호화된 입력값을 수신합니다.

호출 예시

{
  "service": "TSP90.Read",
  "requestKey": "REQ_PIN_READ_01",
  "param": {
    "sound": "1",
    "min": "4",
    "max": "4"
  }
}

sound
- 키패드 입력 시 비프음 볼륨입니다. (1 ~ 10)
min
- 최소 입력 자리수입니다. (비밀번호의 경우 일반적으로 4)
max
- 최대 입력 자리수입니다. (비밀번호의 경우 일반적으로 4)

응답 예시

{
  "service": "TSP90.Read",
  "requestKey": "REQ_PIN_READ_01",
  "statusCode": "0000",
  "return": {
    "returnValue": 0,
    "password": "E2F5B6A8C9D01234..."
  }
}

returnValue
- 서비스 상태 코드입니다. (0: 성공, 그 외: 에러 코드)
password
- 핀패드 하드웨어에서 암호화되어 반환된 비밀번호 데이터 문자열입니다.

13. 주민등록번호 입력

API명

TSP90.SSNRead

정의

핀패드를 통해 13자리 주민등록번호를 안전하게 입력받습니다.

호출 예시

{
  "service": "TSP90.SSNRead",
  "requestKey": "REQ_PIN_SSN_01",
  "param": {
    "sound": "1",
    "min": "13",
    "max": "13"
  }
}

sound
- 키패드 입력 시 비프음 볼륨입니다. (1 ~ 10)
min
- 최소 입력 자리수입니다. (주민등록번호 13자리)
max
- 최대 입력 자리수입니다. (주민등록번호 13자리)

응답 예시

{
  "service": "TSP90.SSNRead",
  "requestKey": "REQ_PIN_SSN_01",
  "statusCode": "0000",
  "return": {
    "returnValue": 0,
    "idNumber": "8A9B0C1D2E3F4567..."
  }
}

returnValue
- 서비스 상태 코드입니다. (0: 성공, 그 외: 에러 코드)
idNumber
- 핀패드 하드웨어에서 암호화되어 반환된 주민등록번호 데이터 문자열입니다.

14. 다이얼로그 동반 입력

API명

TSP90.ReadProcess

정의

브라우저 화면에 취소 가능한 다이얼로그 창을 팝업하면서 핀패드 입력을 진행합니다. 사용자가 화면 다이얼로그의 [취소] 버튼을 누르면 입력을 중단하고 상태코드 10을 반환합니다.

호출 예시

{
  "service": "TSP90.ReadProcess",
  "requestKey": "REQ_PIN_PROC_01",
  "param": {
    "sound": "1",
    "min": "4",
    "max": "4",
    "dialogMessage": "핀패드에 비밀번호 4자리를 입력해주세요."
  }
}

sound
- 키패드 입력 시 비프음 볼륨입니다. (1 ~ 10)
min
- 최소 입력 자리수입니다.
max
- 최대 입력 자리수입니다.
dialogMessage
- 브라우저 화면 다이얼로그 팝업창에 표기할 안내 문구입니다.

응답 예시

{
  "service": "TSP90.ReadProcess",
  "requestKey": "REQ_PIN_PROC_01",
  "statusCode": "0000",
  "return": {
    "returnValue": 0,
    "data": "A1B2C3D4E5F6..."
  }
}

returnValue
- 서비스 상태 코드입니다. (0: 성공, 10: 사용자 취소, 그 외: 에러 코드)
data
- 핀패드에서 암호화되어 전달된 입력 데이터(비밀번호 또는 주민등록번호)입니다.

15. 비다이얼로그 입력

API명

TSP90.ReadNDProcess

정의

화면 다이얼로그 없이 동작하며, 고객이 핀패드 하드웨어 상의 [확인] 버튼을 누를 때까지 입력 세션을 대기합니다.

호출 예시

{
  "service": "TSP90.ReadNDProcess",
  "requestKey": "REQ_PIN_ND_01",
  "param": {
    "sound": "1",
    "min": "4",
    "max": "4"
  }
}

sound
- 키패드 입력 시 비프음 볼륨입니다. (1 ~ 10)
min
- 최소 입력 자리수입니다.
max
- 최대 입력 자리수입니다.

응답 예시

{
  "service": "TSP90.ReadNDProcess",
  "requestKey": "REQ_PIN_ND_01",
  "statusCode": "0000",
  "return": {
    "returnValue": 0,
    "data": "9876543210AB..."
  }
}

returnValue
- 서비스 상태 코드입니다. (0: 성공, 그 외: 에러 코드)
data
- 핀패드에서 암호화되어 전달된 입력 데이터입니다.

16. 자동 확인

API명

TSP90.PINAutoConfirmed

정의

min 파라미터 이상의 숫자가 이미 핀패드에 입력되어 있는 경우, 확인 버튼 입력 없이도 즉시 입력 과정을 종료하고 현재까지 입력된 데이터를 반환합니다. (핀패드에 입력된 값이 없는 경우 AutoConfirm을 호출하면 입력을 종료합니다.)

호출 예시

{
  "service": "TSP90.PINAutoConfirmed",
  "requestKey": "REQ_PIN_AUTOCONF_01",
  "param": {}
}

param
- 전달할 파라미터 정보가 없습니다.

응답 예시

{
  "service": "TSP90.PINAutoConfirmed",
  "requestKey": "REQ_PIN_AUTOCONF_01",
  "statusCode": "0000",
  "return": 0
}

return
- 서비스 상태 코드입니다. (0: 성공, 그 외: 에러 코드)

17. 입력 프로세스 강제종료

API명

TSP90.Off

정의

현재 진행 중인 Read / SSNRead 세션을 강제로 취소하고 장치를 대기 상태로 복귀시킵니다.

호출 예시

{
  "service": "TSP90.Off",
  "requestKey": "REQ_PIN_OFF_01",
  "param": {}
}

param
- 전달할 파라미터 정보가 없습니다.

응답 예시

{
  "service": "TSP90.Off",
  "requestKey": "REQ_PIN_OFF_01",
  "statusCode": "0000",
  "return": 0
}

return
- 서비스 상태 코드입니다. (0: 성공, 그 외: 에러 코드)

18. 미디어 복합 출력

API명

TSP90.MediaOut

정의

핀패드 LCD 화면에 오디오, 비디오, 이미지, 텍스트를 지정한 위치 및 시간 동안 출력합니다.

호출 예시

{
  "service": "TSP90.MediaOut",
  "requestKey": "REQ_PIN_MEDIA_01",
  "param": {
    "audio": "0",
    "video": "0",
    "image": "0",
    "text": "1",
    "startLine": "1",
    "textAlign": "3",
    "fontsize": "16",
    "textStr": "한화생명 고객 안내 메시지",
    "time": "5"
  }
}

audio
- 재생할 오디오 파일 인덱스입니다. (0: 미사용)
video
- 재생할 비디오 파일 인덱스입니다. (0: 미사용)
image
- 출력할 이미지 파일 인덱스입니다. (0: 미사용)
text
- 텍스트 출력 여부입니다. (0: 미출력, 1: 출력)
startLine
- 텍스트 출력 시작 줄 번호입니다. (1부터 시작)
textAlign
- 텍스트 정렬 방식입니다. (1: 좌측 정렬, 2: 우측 정렬, 3: 가운데 정렬)
fontsize
- 글꼴 크기입니다. (예: 16)
textStr
- 핀패드 화면에 출력할 텍스트 본문 문자열입니다.
time
- 화면 노출 유지 시간입니다. (초 단위)

응답 예시

{
  "service": "TSP90.MediaOut",
  "requestKey": "REQ_PIN_MEDIA_01",
  "statusCode": "0000",
  "return": 0
}

return
- 서비스 상태 코드입니다. (0: 성공, 그 외: 에러 코드)

19. 핀패드 폼(그리드) 출력

API명

TSP90.PinpadFormOut

정의

핀패드 LCD에 표(Grid) 형태의 다중 셀/다중 행 데이터를 정렬하여 출력합니다.

주의사항

셀(Cell) 구분자는 |(파이프 기호), 행(Row) 구분자는 \n(줄바꿈)을 사용합니다.
예시 포맷: 항목1|항목2|항목3\n내용1|내용2|내용3\n
연속된 파이프 기호(||) 등으로 인해 열 개수가 초과될 경우 마지막 열 데이터가 핀패드 화면에서 누락될 수 있으므로 정확한 규격을 준수하시길 바랍니다.

호출 예시

{
  "service": "TSP90.PinpadFormOut",
  "requestKey": "REQ_PIN_FORM_01",
  "param": {
    "formType": "1",
    "textStr": "계약자|홍길동|납입금액|100,000원\n피보험자|김영희|보험상태|정상유지\n",
    "time": "60"
  }
}

formType
- 핀패드 LCD에 출력할 폼/그리드 유형 식별값입니다. (기본값: 1)
textStr
- 핀패드 화면에 그리드 표 형태로 출력할 데이터 문자열입니다.
- 셀(열) 구분자는 |(파이프), 행 구분자는 \n(줄바꿈)을 사용합니다.
time
- 핀패드 화면에 그리드 데이터를 표시 유지할 시간입니다. (초 단위)

응답 예시

{
  "service": "TSP90.PinpadFormOut",
  "requestKey": "REQ_PIN_FORM_01",
  "statusCode": "0000",
  "return": 0
}

return
- 서비스 상태 코드입니다. (0: 성공, 그 외: 에러 코드)

버전 #1