POS 연동

연동 설정 페이지는 이용 조건을 충족하는 HandyCafe 서버를 Ödeal D2D 단말기에 연결합니다. 이용 가능 여부는 HandyCafe 클라우드를 통해 확인됩니다. 카페가 Ödeal을 사용할 수 없는 경우 메뉴와 페이지가 완전히 숨겨집니다.

시작하기 전에

활성 HandyCafe 클라우드 구독, Ödeal 판매자 키, Ödeal 시크릿 키가 필요합니다. 또한 Ödeal의 Cihazlarım 영역에서 단말기를 생성해야 합니다. 그 단말기에 지정한 이름이 바로 externalDeviceKey가 됩니다. 먼저 Stage 환경에서 시작하세요. Ödeal이 운영 환경 자격 증명과 콜백 설정을 승인한 뒤에만 Production으로 전환하세요.

Ödeal 설정

설정을 열고 연동을 선택합니다.
Ödeal 계정에 Ödeal에서 받은 판매자 키와 시크릿 키를 입력합니다. HandyCafe는 이 값을 HandyCafe 클라우드로 직접 전송합니다. 값은 암호화되며 로컬 데이터베이스에 저장되지도, 다시 표시되지도 않습니다.
연결 테스트를 선택합니다. 새 키가 입력되어 있으면 HandyCafe가 먼저 키를 안전하게 저장한 뒤 Ödeal API 연결을 테스트합니다. 이 테스트는 Ödeal 계정만 확인합니다. 단말기가 페어링되었거나 온라인 상태라는 것을 증명하지는 않습니다.
단말기를 추가합니다. 알아보기 쉬운 로컬 장치 이름을 입력합니다. Ödeal 장치 이름(externalDeviceKey) 항목에는 Ödeal에서 생성한 장치 이름을 그대로 입력합니다. 이어서 선택 항목인 PaxID, 환경, 결제 대기 시간, 고객 도시, 고객 구역, 세션 부가세율, 주문 부가세율을 입력합니다.
POS 연동 활성화를 켜고 저장을 선택합니다.
Stage 환경에서 현금 영수증 발행과 카드 결제를 각각 완료해 단말기 페어링과 두 정산 경로를 확인합니다.

이번 릴리스에서는 서버당 활성 Ödeal 단말기를 하나만 지원합니다. 캐셔용 단말기 선택 기능이 제공되기 전에 결제가 의도하지 않은 단말기로 전달되는 것을 막기 위해서입니다.

HandyCafe는 클라우드가 새 자격 증명 쌍을 검증하기 전에 단말기 목록을 로컬에 저장합니다. Ödeal이 자격 증명을 거부해도 단말기 이름이나 페어링 항목은 사라지지 않습니다. 새 자격 증명이 필요한 단말기는 선택한 환경에서 해당 자격 증명이 검증될 때까지 비활성 상태로 저장됩니다.

연동 페이지는 단말기 목록을 로컬 SQLite 데이터베이스에서 직접 읽어 클라우드를 기다리지 않고 표시합니다. 클라우드 요청이 필요한 것은 암호화된 자격 증명 상태와 원격 제공자 권한뿐입니다.

Ödeal이 설정을 거부하면 HandyCafe는 Ödeal이 반환한 설명을 표시합니다. 조직 프로필을 찾을 수 없다는 응답은 판매자 키와 시크릿 키 쌍이 선택한 Stage 또는 Production 환경의 어떤 조직에도 속하지 않는다는 뜻입니다.

결제 동작

활성 결제 수단이 현금이나 카드일 때 PC 세션 정산, 콘솔 세션 정산, 단독 주문 마감은 멱등성이 보장된 장바구니를 Ödeal로 전송합니다. 현금은 Ödeal 문서에 정의된 CASH 결제 옵션으로 전송됩니다. 단말기는 카드 결제 화면을 열지 않고 현금 결제를 기록한 뒤 세금 영수증 또는 e-Archive 영수증을 출력합니다. 카드는 CREDITCARD로 전송되며, 고객이 단말기에서 결제를 완료하는 동안 HandyCafe는 콜백 결과를 기다립니다. 현금과 카드가 함께 포함된 정산에서는 두 결제 옵션이 각각의 금액과 함께 전송됩니다.

카드와 가맹점 계약이 지원하는 경우 고객은 단말기에서 할부 옵션을 선택할 수 있습니다. HandyCafe는 보고된 할부 개월 수를 로컬 판매 기록에 저장합니다. 로컬 판매는 Ödeal이 거래를 확정한 뒤에만 반영됩니다. 확정 이후 로컬 기록에 실패하면 HandyCafe가 당일 취소를 요청합니다. 취소가 실패하면 수동 대사 오류가 발생하므로 Ödeal 거래 보고서에서 확인해야 합니다. 현금과 카드가 아닌 결제 수단 유형은 기존 HandyCafe 정산 흐름을 그대로 따릅니다.

테스트 및 단말기 작업

연결 테스트는 Ödeal 판매자 자격 증명과 API 접근만 확인합니다. 영수증을 출력하거나 카드를 청구하지 않으며, externalDeviceKey가 단말기와 페어링되었음을 증명하지도 않습니다.

제공된 D2D API 문서에는 별도의 테스트 영수증 출력이나 테스트 청구 엔드포인트가 정의되어 있지 않습니다. 인수 테스트는 Stage 환경에서 일반 장바구니로 진행합니다. 현금 장바구니를 보내 출력된 영수증을 확인한 다음, 카드 장바구니를 보내 단말기에서 일시불 또는 할부 거래를 완료합니다. 카드 정보는 Ödeal이 제공한 Stage 테스트 카드만 사용하세요.

Ödeal 인수 테스트 항목에는 일일 마감과 마지막 영수증 재출력이 포함되어 있지만, 이는 단말기에서 수행하는 작업입니다. D2D 문서에 이에 해당하는 원격 API 호출이 없으므로 HandyCafe는 원격 버튼으로 제공하지 않습니다.

원격 활성화 및 비활성화

HandyCafe 관리자는 대시보드의 Admin > Admin Settings > POS Providers에서 Ödeal을 제어합니다. 전역 스위치가 최상위 제어 수단입니다. 국가 기본값은 TR처럼 두 자리 ISO 코드를 사용합니다. 카페 단위 제어로 특정 라이선스에 대해 Ödeal을 명시적으로 열거나 닫을 수 있습니다. 카페별 결정은 국가 기본값보다 우선합니다. 카페별 결정을 초기화하면 해당 카페는 다시 국가 설정을 따릅니다.

결정 순서는 전역 스위치, 카페별 결정, 국가 기본값 순입니다. 전역 스위치를 끄면 모든 카페에서 Ödeal이 닫힙니다. 카페를 명시적으로 닫으면 그 국가가 열려 있어도 페이지가 숨겨집니다. 카페를 명시적으로 열면 그 국가가 기본 목록에 없어도 페이지를 사용할 수 있습니다. 접근을 끄면 새 장바구니 생성이 즉시 차단됩니다. 이미 대기 중인 거래는 계속 조회하거나 취소할 수 있으므로 진행 중이던 결제가 중간에 멈춰 버리지 않습니다.

서버는 HandyCafe 클라우드를 통해 이용 가능 여부를 확인하고, 마지막으로 검증에 성공한 국가 및 카페 결정을 캐시에 보관합니다. 제공자 카탈로그는 자격 증명이 유효하지 않을 때 구조화된 error.code와 함께 HTTP 200을 반환합니다. 데스크톱은 이 응답을 받으면 자격 증명을 갱신하고 다시 시도합니다. 일시적인 인증 실패나 네트워크 오류가 관리자의 활성화 결정을 비활성화로 잘못 해석하지 않으므로 연동 메뉴는 안정적으로 유지됩니다. 이후 응답이 성공하면 관리자의 비활성화 결정을 포함해 캐시가 즉시 갱신됩니다. 이전에 검증된 결정이 없는 상태에서 카페 국가를 알 수 없거나, 구독이 비활성이거나, 제공자가 비활성화되어 있으면 페이지는 계속 숨겨집니다. 캐시된 표시 상태를 사용하더라도 새 Ödeal 작업은 항상 클라우드에서 다시 승인을 받습니다. 동기화된 카페 프로필에 국가가 없으면 라이선스에 저장된 국가를 사용합니다.

보안 및 복구

Ödeal 자격 증명은 배포 볼트 키로 HandyCafe 클라우드에서 암호화됩니다. 콜백 요청은 설정된 요청 키 또는 Ödeal 판매자 및 시크릿 헤더로 인증됩니다. 장바구니 참조 코드는 주문이나 세션마다 일정하게 유지됩니다. 같은 정산을 반복해도 두 번 청구되지 않습니다.

Ödeal 취소는 단말기 정산 배치가 마감되기 전, Ödeal의 당일 규정에 따라서만 가능합니다. 결제가 완료되기 전이라면 대기 중인 장바구니를 따로 삭제할 수 있습니다. Ödeal D2D는 일반적인 환불 기능을 제공하지 않습니다. 취소 가능 시간이 지난 경우에는 Ödeal 백오피스와 거래 보고서를 이용하세요.

Ödeal D2D에는 문서화된 원격 Z 리포트나 일일 마감 기능이 없습니다. 일일 마감은 단말기에서 완료하세요. HandyCafe는 대사를 위해 거래 보고서를 읽을 수 있으며 Ödeal에서 오는 페이백 콜백을 기록합니다.