연동 준비하기

현금영수증 API 연동을 시작하기 전에 알아야 할 준비사항과 기본 정보를 안내합니다.

환경별 키 정보

테스트베드와 상용 환경은 분리되어 있으며, 각각 별도의 상점 ID를 사용합니다.

환경	상점 ID	용도
테스트베드	공용 테스트 상점ID	개발 및 테스트 (실제 국세청 전송 안 함)
상용 환경	가맹점 전용 상점ID	실제 운영 서비스 (국세청 전송)

가맹점 전용 키 발급 (계약 후)

헥토파이낸셜과 계약 후 상용 환경에서 사용할 다음 정보를 발급받습니다.

항목	설명
상점 ID (mid)	가맹점 고유 식별자 (10자리)

서버 연동 환경

서버 주소 및 네트워크 정보

현금영수증 API는 두 개의 도메인을 사용합니다. 대부분의 API는 domain을 사용하며, 일부 조회 API는 domain2를 사용합니다.

API (domain)

등록, 취소, 상태조회 등 일반 API에 사용합니다.

환경	도메인	IP 주소	프로토콜
테스트베드	tcash.settlebank.co.kr	61.252.169.42	HTTPS(TCP/443)
상용	cash.settlebank.co.kr	14.34.14.21 (Main) 61.252.169.53 (DR)	HTTPS(TCP/443)

API (domain2)

발급오류내역 조회, 재처리 결과내역 조회 API에 사용합니다.

환경	도메인	IP 주소	프로토콜
테스트베드	tb-nspay.settlebank.co.kr	61.252.169.42	HTTPS(TCP/443)
상용	nspay.settlebank.co.kr	14.34.14.21 (Main) 61.252.169.53 (DR)	HTTPS(TCP/443)

NOTE

IDC 이중화 구성

• 헥토파이낸셜 PG 시스템은 주센터(Main)와 보조센터(DR)로 이중화되어 있습니다. • Main 센터 장애 시 DR로 자동 전환되므로, 상용 환경의 Main/DR IP 모두 방화벽에서 허용해야 합니다. • DNS Lookup 접속 권장 - 센터 전환 시 자동으로 처리됩니다.

개발 환경 요구사항

현금영수증 API 연동은 서버 to 서버 방식입니다.

구분	역할
백엔드 (필수)	현금영수증 등록/취소/조회 API 호출

NOTE

서버 전용 API

현금영수증 API는 백엔드 서버에서만 호출하는 API입니다. 프론트엔드에서 직접 호출하지 않습니다.

API 연동 정보

현금영수증 API는 별도의 암호화를 사용하지 않으며, 일반 파라미터 형식으로 전송합니다.

구분	내용
인코딩	UTF-8
메소드	GET 또는 POST
데이터 형식	application/x-www-form-urlencoded

처리 방식

현금영수증 등록은 D+1 일괄 처리 방식입니다.

구분	설명
등록/취소	API 호출 즉시 승인번호 발급
국세청 전송	D+1일 00시에 전일 내역 일괄 전송
오류 조회	D+1일 13시 이후 조회 가능

NOTE

상세한 처리 프로세스

등록부터 오류 재처리까지 상세한 단계별 흐름은 '전체 연동 플로우' 문서를 참고하세요.

주의사항

운영환경 테스트 주의

운영환경 테스트 주의: 운영환경에서 테스트 시 실제 국세청으로 데이터가 전송됩니다. 반드시 테스트베드에서 테스트를 완료해야 합니다.

잘못 등록된 데이터 처리

운영에서 잘못 등록된 데이터는 가맹점에서 취소 요청으로 처리해야 합니다. 데이터를 삭제하는 방법은 없습니다.

API 요청 주의사항

GET 또는 POST method 사용
UTF-8 인코딩 필수
파라미터는 연동규격서에 명시된 것만 사용
특수문자, HTML 태그 사용 금지

브라우저 및 프로토콜 요구사항

HTTPS 필수
안전한 암호화 통신 보장

자동 재처리 가맹점

헥토파이낸셜에서는 자동 재처리 서비스를 제공합니다.

구분	설명
자동 재처리 가맹점	오류 발생 시 헥토파이낸셜에서 자동으로 재처리 데이터 생성 및 국세청 전송
일반 가맹점	오류 발생 시 가맹점에서 직접 재처리 등록 API 호출 필요

NOTE