제휴사 OPEN API 명세

외부 유출에 주의 부탁드립니다.

Last Updated Date 2026-01-09

제휴사 → 토스 API

RSA Public Key 조회 API

Request

Response

Response Body Example

Response Body Example

입장SDK 토큰 발급 API

Request

Response

Response Body Example

Response Body Example

Response Body Example

약관 철회처리 API (얼굴입장 회원 탈퇴)

Request

Request Body Example

Response

Response Body Example

Response Body Example

Response Body Example

Response Body Example

연결된 기기 조회 API

Request

Request Param Example

Response

Response Body Example

Response Body Example

설정그룹 조회 API

Request

Request Param Example

Response

Response Body Example

Response Body Example

Response Body Example

Response Body Example

토스 → 제휴사 API

Host

회원 유효성 검증 API (얼굴입장 등록)

Request

Request Body Example

Response

Response Body Example

입장 권한 질의 API (얼굴입장 검증)

Request

Request Body Example

Response

Response Body Example

얼굴입장 등록완료 콜백 API (등록완료 콜백)

Request

Request Body Example

Response

Response Body Example

제휴사 → 토스 API

토스가 제휴사에 제공하는 API 입니다.

개발가이드가 수시로 업데이트 됩니다. 사전 예고없이 업데이트 될 수 있으니 지속적으로 확인해 주시길 부탁드립니다.

상위호환성을 고려하여 개발 부탁드립니다.

Host

•

https://facepass.toss.im 

◦

live, dev 모두 위 호스트로 접근하시면 됩니다. 

◦

client_id와 client_secret는 환경별로 각각 발급해드립니다.

Authorization

Access Token 발급

https://toss.im/tosscert/docs/guides/integration/easy#1-access-token-발급-api

위 문서 참고해주시면 됩니다

client_id와 client_secret은 따로 공유드리도록 하겠습니다

api-public*.toss.im 서버에 HTTP 요청시 Authorization header에 Bearer {{발급된 access token}} 형식으로 요청해주시면 됩니다

Response 형식

모든 응답은 아래 형식을 가지며, 아래 API 명세에 기술되어있는 응답은 success 객체의 타입을 나타냅니다.

정상 처리시 (실패 포함) Response Code는 200으로 고정되며 400/500 일 경우에는 연동/개발상 오류를 의미합니다.

name	type	description	required
resultType	“SUCCESS” \| “FAIL”	성공 여부	true
success	Object	성공 시 성공 응답	false
error	ErrorObject	실패 시 실패 사유 객체	false
error.errorCode	String	실패 코드	true
error.reason	String	실패 사유 메시지	true
error.*	-	deprecated 된 fields	-

성공 시 예시

{
    "resultType": "SUCCESS",
    "success": {
        "test": true
    }
}
JSON
복사

실패 시 예시

{
    "resultType": "FAIL",
    "success": null
    "error": {
		    "errorCode": "DUPLICATED_USERKEY",
		    "reason": "userKey 중복"
    }
}
JSON
복사

RSA Public Key 조회 API

Request

Method: POST

URL: /api/v1/rsa-public-key

Consume: application/json

Response

Produce: application/json

Response Fields:

name	type	description	required
rsaKey	String	Base 64로 인코딩된 RSA Public Key	true

Response Body Example

{
    "resultType": "SUCCESS",
    "success": {
        "rsaKey": ""
    }
}
JSON
복사

얼굴입장 등록 준비 API

(선택) 등록SDK를 통해 얼굴을 등록하는 경우 필요합니다 토스앱만 이용하는 제휴사의 경우 구현하지 않아도 됩니다

Request

Method: POST

URL: /api/v1/merchant/face-register-prepare

Consume: application/json

Request Fields:

•

2가지 케이스 중 한가지를 선택 가능합니다

◦

CI로 회원 DB를 관리하는 경우: 이름, 휴대폰번호 or 이메일, CI

◦

CI로 회원 DB를 관리하지 않는 경우: 이름, 휴대폰번호 or 이메일, 생년월일

•

모든 파라미터가 넘어갈 경우 CI값의 우선순위가 높습니다

name	type	description	required
merchantUserKey	String	제휴사 유저 unique id	true
encryptedCI	String	암호화된 CI 값 (AES256 암호화 후 Base64 인코딩)	true
encryptedName	String	암호화된 회원 이름 (AES256 암호화 후 Base64 인코딩) 암호화전 스펙: 50Byte	true
encryptedPhoneNumber	String	암호화된 휴대폰번호 (AES256 암호화 후 Base64 인코딩) 암호화전 스펙: 10~11자리 숫자	encryptedPhoneNumber / encryptedEmail 둘 중 하나는 필수입니다
encryptedEmail	String	암호화된 이메일 (AES256 암호화 후 Base64 인코딩) 암호화전 스펙: 50Byte	encryptedPhoneNumber / encryptedEmail 둘 중 하나는 필수입니다
encryptedKey	String	암호화된 AES Key	true
iv	String	암호화에 사용된 IV값	true

name	type	description	required
merchantUserKey	String	제휴사 유저 unique id	true
encryptedName	String	암호화된 회원 이름 (AES256 암호화 후 Base64 인코딩) 암호화전 스펙: 50Byte	true
encryptedPhoneNumber	String	암호화된 휴대폰번호 (AES256 암호화 후 Base64 인코딩) 암호화전 스펙: 10~11자리 숫자	encryptedPhoneNumber / encryptedEmail 둘 중 하나는 필수입니다
encryptedEmail	String	암호화된 이메일 (AES256 암호화 후 Base64 인코딩) 암호화전 스펙: 50Byte	encryptedPhoneNumber / encryptedEmail 둘 중 하나는 필수입니다
encryptedBirthDate	String	암호화된 생년월일 (AES256 암호화 후 Base64 인코딩) 암호화전 스펙: 8자리 숫자	true
encryptedKey	String	암호화된 AES Key	true
iv	String	암호화에 사용된 IV값	true

Request Body Example

{
    "merchantUserKey": "000001",
    "encryptedCI": "dGVzdCBjaQ==",
    "encryptedName": "yntOiPixdnrGhknQJ0Q/N4JcQiRdLjUFgxItJrenrddr1L8xlBCZxmnpH8T+5vuAfA==", // 홍길동
    "encryptedPhoneNumber": "yntOiPixdnrGhknQJ0Q/N4JcQiRd8524WJim+QkMvOk0Pg7fw/URAvxf0sVMzw5cY94N", // 01012341234
    "encryptedKey": "",
    "iv": ""
}
JSON
복사

{
    "merchantUserKey": "000001",
    "encryptedName": "yntOiPixdnrGhknQJ0Q/N4JcQiRdLjUFgxItJrenrddr1L8xlBCZxmnpH8T+5vuAfA==", // 홍길동
    "encryptedPhoneNumber": "yntOiPixdnrGhknQJ0Q/N4JcQiRd8524WJim+QkMvOk0Pg7fw/URAvxf0sVMzw5cY94N", // 01012341234
    "encryptedBirthDate": "yntOiPixdnrGhknQJ0Q/N4JcQiRd8Zy6XJqk/QkchaAMDskygSdVAPzLUzppkOkV", // 20250101
    "encryptedKey": "",
    "iv": ""
}
JSON
복사

Response

Produce: application/json

Response Fields:

name	type	description	required
completed	Boolean	처리 여부	true
txId	String	얼굴등록시 유저정보 맵핑시켜주기 위한 transactionId	true
token	String	등록SDK에서 API 사용을 위한 accessToken (유효기간 1시간)	true

Response Body Example

{
    "resultType": "SUCCESS",
    "success": {
        "completed": true,
        "txId": "88a72dae-c1dc-43ee-b470-8c280416ce12",
        "token": "eyJraWQiOiJjZXJ0IiwiYWxnIj ... "
    }
}
JSON
복사

입장SDK 토큰 발급 API

(선택) 입장SDK를 통해 얼굴입장 하는 경우 필요합니다 통합앱으로 얼굴입장 이용하는 제휴사의 경우 구현하지 않아도 됩니다

Request

Method: POST

URL: /api/v1/merchant/verify-token

Consume: application/json

Response

Produce: application/json

Response Fields:

name	type	description	required
token	String	입장SDK에서 API 사용을 위한 accessToken (유효기간 1시간)	true

Response Body Example

{
    "resultType": "SUCCESS",
    "success": {
        "token": "eyJraWQiOiJjZXJ0IiwiYWxnIj ... "
    }
}
JSON
복사

암호화 테스트 API

얼굴입장 등록 준비 API, 입장 권한 질의 API 호출에 사용되는 암호화 방식의 테스트를 위해 제공합니다.

Request

Method: POST

URL: /api/v1/merchant/encryption-test

Consume: application/json

Request Fields:

name	type	description	required
encryptedData	String	암호화된 데이터 (AES256 암호화 후 Base64 인코딩)	true
encryptedKey	String	암호화된 AES Key (Base64 인코딩)	true
iv	String	암호화에 사용된 IV값 (Base64 인코딩)	true

Request Body Example

{
    "encryptedData": "yntOiPixdnrGhknQJ0Q/N4JcQiRdLjUFgxItJrenrddr1L8xlBCZxmnpH8T+5vuAfA==", // 홍길동
    "encryptedKey": "",
    "iv": ""
}
JSON
복사

Response

Produce: application/json

Response Fields:

name	type	description	required
success	Boolean	성공 여부	true

Response Body Example

{
    "resultType": "SUCCESS",
    "success": {
        "success": true
    }
}
JSON
복사

얼굴 등록 상태 확인 API

Request

Method: POST

URL: /api/v1/merchant/face-register-exist

Consume: application/json

Request Fields:

name	type	description	required
merchantUserKey	String	제휴사 유저 unique id	true

Request Body Example

{
    "merchantUserKey": "000001",
}
JSON
복사

Response

Produce: application/json

Response Fields:

name	type	description	required
registered	Boolean	등록 여부	true
registeredTs	String	등록일시	false
auditStatus	"WAITING" \| "SUCCESS" \| "FAILURE" \| "CANCELED" \| "HOLDING"	검수상태 (대기중/검증성공/검증실패/검증취소/검증보류)	false

Response Body Example

{
    "resultType": "SUCCESS",
    "success": {
        "registered": true,
        "registeredTs": "2024-01-01 00:00:00",
        "auditStatus": "SUCCESS"
    }
}
JSON
복사

약관 철회처리 API (얼굴입장 회원 탈퇴)

Request

Method: POST

URL: /api/v1/merchant/face-unregister

Consume: application/json

Request Fields:

name	type	description	required
merchantUserKey	String	제휴사 유저 unique id	true

Request Body Example

{
    "merchantUserKey": "000001"
}
JSON
복사

Response

Produce: application/json

Response Fields:

name	type	description	required
completed	Boolean	처리 여부	true

Response Body Example

{
    "resultType": "SUCCESS",
    "success": {
        "completed": true
    }
}
JSON
복사

등록 이력 조회 API

Request

Method: POST

URL: /api/v1/merchant/face-register-history

Consume: application/json

Request Fields:

name	type	description	required
merchantUserKey	String	제휴사 유저 unique id	false
name	String	유저 이름 (50Byte)	false
phoneNumber	String	유저 휴대폰번호(10~11자리 숫자)	false
email	String	유저 이메일 (50Byte)	false
startTs	String	조회범위 시작일시	true
endTs	String	조회범위 종료일시	true
size	Number	조회할 레코드 갯수 (기존값 10)	false
nextCursor	String	해당 값이 있다면, 해당 id 바로 뒤 레코드 부터 조회	false

Request Body Example

{
    "merchantUserKey": "000001",
    "name": "홍길동",
	  "phoneNumber": "01012341234",
	  "email": "test@toss.im",
    "startTs": "2024-01-01T00:00:00",
    "endTs": "2024-01-02T00:00:00",
    "size": 10,
    "nextCursor": "100"
}
JSON
복사

Response

Produce: application/json

Response Fields:

name	type	description	required
items	Array	레코드 리스트	true
items.id	String	레코드 아이디	true
items.merchantUserKey	String	제휴사 유저 unique id	true
items.auditStatus	“WAITING” \| “SUCCESS” \| “FAILURE” \| “CANCELED” \| “HOLDING”	검수상태(대기중/성공/실패/취소/보류)	true
items.eventTs	String	처리일시	true
hasMore	Boolean	마지막 페이지 여부	true
size	Number	레코드 리스트 size	true
nextCursor	String	마지막 레코드 아이디. nextCursor로 사용	false

Response Body Example

{
    "resultType": "SUCCESS",
    "success": {
        "items": [
	          {
	              "id": "1",
	              "merchantUserKey": "000001",
	              "auditStatus": "SUCCESS",
	              "eventTs": "2024-01-02T00:00:00"
	          }
        ],
        "hasMore": false,
        "size": 10,
        "nextCursor": "100"
    }
}
JSON
복사

인증 이력 조회 API

Request

Method: POST

URL: /api/v1/merchant/face-verify-history

Consume: application/json

Request Fields:

name	type	description	required
merchantUserKey	String	제휴사 유저 unique id	false
status	String	인증상태	false
deviceId	String	인증 시도한 기기 id	false
transactionId	String	인증과정에 대한 transactionId	false
startTs	String	조회범위 시작일시	true
endTs	String	조회범위 종료일시	true
size	Number	조회할 레코드 갯수 (기존값 10)	false
nextCursor	String	해당 값이 있다면, 해당 id 바로 뒤 레코드 부터 조회	false

Request Body Example

{
    "merchantUserKey": "000001",
    "status": "SUCCESS",
    "deviceId": "IPAD001",
    "transactionId": "b5238b22-570d-4f80-8f1e-b0f311ab782d",
    "startTs": "2024-01-01T00:00:00",
    "endTs": "2024-01-02T00:00:00",
    "size": 10,
    "nextCursor": "100"
}
JSON
복사

Response

Produce: application/json

Response Fields:

name	type	description	required
items	Array	레코드 리스트	true
items.id	String	레코드 아이디	true
items.merchantUserKey	String	제휴사 유저 unique id	true
items.status	“SUCCESS” \| “FAIL”	인증상태(성공/실패)	true
items.resultCode	“FACE_NOT_FOUND” \| “FACE_DETECT_FAILED” \| “DUPLICATE_FACE” \| “MERCHANT_VALIDATION_FAILED” \| “UNKNOWN_ERROR”	실패 사유(얼굴을 못찾음/얼굴 확인 불가/중복된 얼굴 발견/가맹점 검증 실패/알수없는 에러)	false
items.customCode	String	가맹점 응답 코드	false
items.deviceId	String	인증 시도한 기기 id	true
items.params	JSON	입장시 사용된 파라미터	false
items.verifyTs	String	인증일시	true
items.transactionId	String	인증과정에 대한 transactionId (QR인증시엔 내려오지 않습니다)	false
hasMore	Boolean	마지막 페이지 여부	true
size	Number	레코드 리스트 size	true
nextCursor	String	마지막 레코드 아이디. nextCursor로 사용	false

Response Body Example

{
    "resultType": "SUCCESS",
    "success": {
        "items": [
	          {
	              "id": "1",
	              "merchantUserKey": "000001",
	              "status": "SUCCESS",
	              "resultCode": null,
	              "customCode": null,
	              "deviceId": "IPAD001",
	              "transactionId": "b5238b22-570d-4f80-8f1e-b0f311ab782d",
	              "params": {
	                  "floor": "5"
	              },
	              "verifiedTs": "2024-01-01T00:00:00"
	          },
	          {
	              "id": "2",
	              "merchantUserKey": "000002",
	              "status": "FAIL",
	              "resultCode": "FACE_NOT_FOUND",
	              "customCode": null,
	              "deviceId": "IPAD001",
	              "transactionId": "8850629f-df8d-4125-8d94-86f1bf39e470",
	              "params": {
	                  "floor": "5"
	              },
	              "verifiedTs": "2024-01-01T00:00:00"
	          },
	          {
	              "id": "3",
	              "merchantUserKey": "000003",
	              "status": "FAIL",
	              "resultCode": "MERCHANT_VALIDATION_FAILED",
	              "customCode": "TE0003",
	              "deviceId": "IPAD001",
	              "transactionId": "fb88e8ca-e477-4fc9-8ac9-85296047a395",
	              "params": {
	                  "floor": "5"
	              },
	              "verifiedTs": "2024-01-01T00:00:00"
	          }
        ],
        "hasMore": false,
        "size": 10,
        "nextCursor": "100"
    }
}
JSON
복사

기기 연결 인증번호 발급 API

Request

Method: POST

URL: /api/v1/merchant/init-device

Consume: application/json

Request Fields:

name	type	description	required
groupId	String	설정그룹 아이디	true
deviceName	String	기기 이름	false

Request Body Example

{
    "groupId": "01K18XV5C84N010K8SJ15RG90D",
    "deviceName": "TOSS-IPAD-01"
}
JSON
복사

Response

Produce: application/json

Response Fields:

name	type	description	required
verifyCode	String	인증번호	true
expireTs	String	인증번호 만료일시	true

Response Body Example

{
    "resultType": "SUCCESS",
    "success": {
        "verifyCode": "12345678",
        "expireTs": "2025-11-19T23:56:00"
    }
}
JSON
복사

연결된 기기 조회 API

Request

Method: GET

URL: /api/v1/merchant/connected-device

Consume: application/json

Request Fields:

name	type	description	required
groupId	String	설정그룹 아이디	true

Request Param Example

?groupId=01K18XV5C84N010K8SJ15RG90D
TypeScript
복사

Response

Produce: application/json

Response Fields:

name	type	description	required
devices	Array	연결된 기기 리스트	true
devices.deviceId	String	기기 아이디	true
devices.deviceName	String	기기 이름	false

Response Body Example

{
    "resultType": "SUCCESS",
    "success": {
		    "devices": [
				    {
						    "deviceId": "IPAD001",
						    "deviceName": "TOSS-IPAD-01"
				    }
		    ]
    }
}
JSON
복사

연결기기 삭제 API

Request

Method: POST

URL: /api/v1/merchant/deactivate-device

Consume: application/json

Request Fields:

name	type	description	required
groupId	String	설정그룹 아이디	true
deviceId	String	기기 아이디	deviceId / deviceName 둘 중 하나는 필수입니다
deviceName	String	기기 이름	deviceId / deviceName 둘 중 하나는 필수입니다

Request Body Example

{
    "groupId": "01K18XV5C84N010K8SJ15RG90D",
    "deviceId": "IPAD001"
}
JSON
복사

Response

Produce: application/json

Response Fields:

name	type	description	required
completed	Boolean	처리 여부	true

Response Body Example

{
    "resultType": "SUCCESS",
    "success": {
		    "completed": true
    }
}
JSON
복사

설정그룹 조회 API

Request

Method: GET

URL: /api/v1/merchant/device-group

Consume: application/json

Request Fields:

name	type	description	required
size	Number	조회할 레코드 갯수 (기본값 10)	false
nextCursor	String	해당 값이 있다면, 해당 id 바로 뒤 레코드 부터 조회	false

Request Param Example

?size=10&nextCursor=01K97Q5ZY0RZZT8D01NAAHNQMT
TypeScript
복사

Response

Produce: application/json

Response Fields:

name	type	description	required
items	Array	레코드 리스트	true
items.groupId	String	설정그룹 아이디 (레코드 아이디)	true
items.deviceGroupName	String	설정그룹 이름	true
items.enableLiveness	Boolean	가짜 얼굴 차단 여부	true
items.shouldSuccessResultSkip	Boolean	성공 후 다음인식 자동시작	true
items.shouldFailResultSkip	Boolean	실패 후 다음인식 자동시작	true
items.tags	JSON	태그 정보 (key, value)	true
hasMore	Boolean	마지막 페이지 여부	true
size	Number	레코드 리스트 size	true
nextCursor	String	마지막 레코드 아이디. nextCursor로 사용	false

Response Body Example

{
    "resultType": "SUCCESS",
    "success": {
        "items": [
            {
                "groupId": "01K97Q5ZY0RZZT8D01NAAHNQMT",
                "deviceGroupName": "강훈테스트1",
                "enableLiveness": false,
                "shouldFailResultSkip": false,
                "shouldSuccessResultSkip": true,
                "tags": {
                    "층": "10",
                    "건물": "아크플레이스"
                }
            }
        ],
        "size": 10,
        "hasMore": true,
        "nextCursor": "01K97Q5ZY0RZZT8D01NAAHNQMT"
    }
}
JSON
복사

설정그룹 추가 API

Request

Method: POST

URL: /api/v1/merchant/create-device-group

Consume: application/json

Request Fields:

name	type	description	required
deviceGroupName	String	설정그룹 이름	true
enableLiveness	Boolean	가짜 얼굴 차단 여부	true
shouldSuccessResultSkip	Boolean	성공 후 다음인식 자동시작	true
shouldFailResultSkip	Boolean	실패 후 다음인식 자동시작	true
tags	JSON	태그 정보 (key, value)	false

Request Body Example

{
    "deviceGroupName": "설정그룹 이름",
    "enableLiveness": false,
    "shouldFailResultSkip": false,
    "shouldSuccessResultSkip": true,
    "tags": {
        "층": "10",
        "건물": "아크플레이스"
    }
}
JSON
복사

Response

Produce: application/json

Response Fields:

name	type	description	required
completed	Boolean	처리 여부	true
groupId	String	설정그룹 아이디	true

Response Body Example

{
    "resultType": "SUCCESS",
    "success": {
        "completed": true,
        "groupId": "01K97Q5ZY0RZZT8D01NAAHNQMT"
    }
}
JSON
복사

설정그룹 수정 API

Request

Method: POST

URL: /api/v1/merchant/modify-device-group

Consume: application/json

Request Fields:

name	type	description	required
groupId	String	설정그룹 아이디	true
deviceGroupName	String	설정그룹 이름	true
enableLiveness	Boolean	가짜 얼굴 차단 여부	true
shouldSuccessResultSkip	Boolean	성공 후 다음인식 자동시작	true
shouldFailResultSkip	Boolean	실패 후 다음인식 자동시작	true
tags	JSON	태그 정보 (key, value)	false

Request Body Example

{
    "groupId": "01K97Q5ZY0RZZT8D01NAAHNQMT"
    "deviceGroupName": "설정그룹 이름",
    "enableLiveness": false,
    "shouldFailResultSkip": false,
    "shouldSuccessResultSkip": true,
    "tags": {
        "층": "10",
        "건물": "아크플레이스"
    }
}
JSON
복사

Response

Produce: application/json

Response Fields:

name	type	description	required
completed	Boolean	처리 여부	true

Response Body Example

{
    "resultType": "SUCCESS",
    "success": {
        "completed": true
    }
}
JSON
복사

설정그룹 삭제 API

Request

Method: POST

URL: /api/v1/merchant/delete-device-group

Consume: application/json

Request Fields:

name	type	description	required
groupId	String	설정그룹 아이디	true

Request Body Example

{
    "groupId": "01K97Q5ZY0RZZT8D01NAAHNQMT"
}
JSON
복사

Response

Produce: application/json

Response Fields:

name	type	description	required
completed	Boolean	처리 여부	true

Response Body Example

{
    "resultType": "SUCCESS",
    "success": {
        "completed": true
    }
}
JSON
복사

토스 → 제휴사 API

제휴사 측에서 제공해야하는 API 입니다

Host

•

가맹점 API 서버의 host가 필요합니다

•

production, dev 각각 도메인주소 부탁드립니다

◦

[production] https://

◦

[dev] https://

회원 유효성 검증 API (얼굴입장 등록)

(선택) 토스앱을 통해 얼굴입장 등록하는 경우 필요합니다 SDK만 이용하는 제휴사의 경우 구현하지 않아도 됩니다

Request

Method: 가맹점 측에서 선택. 예시: POST

URL: 가맹점 측에서 선택. 예시: /v1/user/validate

Consume: application/json

Request Fields:

•

2가지 케이스 중 한가지를 선택 가능합니다

•

모든 파라미터가 넘어갈 경우 CI값의 우선순위가 높습니다

name	type	description	required
encryptedCI	String	암호화된 CI 값 (AES256 암호화 후 Base64 인코딩)	true
encryptedKey	String	암호화된 AES Key	true
iv	String	암호화에 사용된 IV값	true

name	type	description	required
encryptedName	String	암호화된 회원 이름 (AES256 암호화 후 Base64 인코딩) 암호화전 스펙: 50Byte	false
encryptedPhoneNumber	String	암호화된 휴대폰번호 (AES256 암호화 후 Base64 인코딩) 암호화전 스펙: 10~11자리 숫자	true
encryptedBirthDate	String	암호화된 생년월일 (AES256 암호화 후 Base64 인코딩) 암호화전 스펙: 8자리 숫자	false
encryptedKey	String	암호화된 AES Key	true
iv	String	암호화에 사용된 IV값	true

Request Body Example

{
    "encryptedCI": "dGVzdCBjaQ==",
    "encryptedKey": "",
    "iv": ""
}
JSON
복사

{
    "encryptedName": "yntOiPixdnrGhknQJ0Q/N4JcQiRdLjUFgxItJrenrddr1L8xlBCZxmnpH8T+5vuAfA==", // 홍길동
    "encryptedPhoneNumber": "yntOiPixdnrGhknQJ0Q/N4JcQiRd8524WJim+QkMvOk0Pg7fw/URAvxf0sVMzw5cY94N", // 01012341234
    "encryptedBirthDate": "yntOiPixdnrGhknQJ0Q/N4JcQiRd8Zy6XJqk/QkchaAMDskygSdVAPzLUzppkOkV", // 20250101
    "encryptedKey": "",
    "iv": ""
}
JSON
복사

Response

Produce: application/json

Response Fields:

name	type	description	required
merchantUserKey	String	가맹점측 사원번호,회원번호	true
encryptedName	String	암호화된 회원 이름 (AES256 암호화 후 Base64 인코딩) 암호화전 스펙: 50Byte	값이 있을 경우 이름 검증 플로우가 진행됩니다
encryptedBirthDate	String	암호화된 생년월일 (AES256 암호화 후 Base64 인코딩) 암호화전 스펙: 8자리 숫자	값이 있을 경우 생년월일 검증 플로우가 진행됩니다
encryptedKey	String	암호화된 AES Key	encryptedName / encryptedBirthDate 둘 중 하나의 값이 있을 경우 필수입니다
iv	String	암호화에 사용된 IV값	encryptedName / encryptedBirthDate 둘 중 하나의 값이 있을 경우 필수입니다
txId	String	얼굴등록시 유저정보 맵핑시켜주기 위한 transactionId	false (txId를 제휴사측에서 발행하는 경우에만 넣어주시면 됩니다)
message	String	성공,에러 발생시 메시지	false
code	String	응답코드	false

Response Body Example

{
    "merchantUserKey": "000001",
    "encryptedName": "yntOiPixdnrGhknQJ0Q/N4JcQiRdLjUFgxItJrenrddr1L8xlBCZxmnpH8T+5vuAfA==", // 홍길동
    "encryptedBirthDate": "yntOiPixdnrGhknQJ0Q/N4JcQiRd8524WJim+QkMvOk0Pg7fw/URAvxf0sVMzw5cY94N", // 01012341234
    "encryptedKey": "",
    "iv": ""
    "txId": "88a72dae-c1dc-43ee-b470-8c280416ce12",
    "message": "성공",
    "code": ""
}
JSON
복사

입장 권한 질의 API (얼굴입장 검증)

(필수) 입장앱을 통해 입장시 사용하게 됩니다

Request

Method: 가맹점 측에서 선택. 예시: POST

URL: 가맹점 측에서 선택. 예시: /v1/access/permissions

Consume: application/json

Request Fields:

name	type	description	required
merchantUserKey	String	가맹점측 사원번호,회원번호	true
params	JSON	가맹점에 따라 다르게 설정	true

Request Body Example

{
    "merchantUserKey": "000001",
    "params": {
        "floor": "10", // 10층
        "gate": "A" // A게이트
    }
}

{
    "merchantUserKey": "000001",
    "params": {
        "floor": "5", // 5층
    }
}

{
    "merchantUserKey": "000001",
    "params": {
        "room": "5-3" // 5-3 회의실
    }
}
JSON
복사

Response

Produce: application/json

Response Fields:

•

응답 필드를 이용하여 커스텀한 안내문구를 설정할 수 있습니다

◦

customMessage

▪

여기에 문구를 입력하여 응답하는 경우 문자열 그대로 화면에 띄웁니다

▪

글자수 제한이 있습니다. 이를 초과하면 메시지 기본값이 노출되게 됩니다

•

반복형: 19자

•

검표형: 38자

▪

우선순위가 가장 높습니다

◦

code

▪

커스텀코드를 사용하는 경우 지정된 코드값을 담아서 보내시면 됩니다

▪

코드값에 대한 안내문구를 페이스패스 DB에 저장하여 사용합니다

▪

글자수 제한이 있습니다. 50Byte

◦

위 2개의 필드가 공란인 경우 기본 안내문구를 사용하게 됩니다

name	type	description	required
verified	Boolean	권한보유 여부	true
customMessage	String	입장 성공/실패 커스텀 메시지 (우선순위 가장 높음)	false
message	String	성공,에러 발생시 메시지	false
code	String	응답코드 (50Byte)	false

Response Body Example

// customMessage에 커스텀메시지를 입력하는 예시
{
    "verified": true,
    "customMessage": "{제휴사} 입장 확인.",
    "message": "성공",
    "code": null
}

// code에 커스텀코드를 입력하는 예시
{
    "verified": true,
    "customMessage": null,
    "message": "성공",
    "code": "A0001" // 맵핑된 안내문구가 출력됨
}

// 기본 응답 예시
{
    "verified": true,
    "customMessage": null,
    "message": "성공",
    "code": null
}
JSON
복사

얼굴입장 등록완료 콜백 API (등록완료 콜백)

(선택) 얼굴입장 등록완료 후 콜백이 필요한 경우에만 구현하시면 됩니다

Request

Method: 가맹점 측에서 선택. 예시: POST

URL: 가맹점 측에서 선택. 예시: /v1/callback/registered

Consume: application/json

Request Fields:

name	type	description	required
merchantUserKey	String	가맹점측 사원번호,회원번호	true
txId	String	얼굴등록시 유저정보 맵핑시켜주기 위한 transactionId	true
registered	Boolean	등록 여부	true

Request Body Example

{
    "merchantUserKey": "000001",
    "txId": "88a72dae-c1dc-43ee-b470-8c280416ce12",
    "registered": true
}
JSON
복사

Response

Produce: application/json

Response Fields:

name	type	description	required
message	String	성공,에러 발생시 메시지	false
code	String	응답코드	false

Response Body Example

{
    "message": "성공",
    "code": null
}
JSON
복사