Search
Duplicate
1️⃣

연동가이드

연동 흐름도

sequenceDiagram
	autonumber
  사용자 ->> 상점: 주문 요청
	alt 서명(Non UI)
		상점 ->> 하이픈: 서명키값 요청 API 호출
		note right of 상점: 주문번호, 핸드폰번호, 상점ID, 가격
		하이픈 ->> 상점: 서명키값 반환
		note right of 상점: 서명키값 등 주문정보 쿠키 저장 
	end
	alt 결제정보등록(UI)
		상점 ->> 하이픈: 바로계좌결제 Login 창 호출
		하이픈 ->> 하이픈: (가입 및) 결제 정보 등록
		하이픈 ->> 상점: 결제 정보 URL 리다이렉트
	end
	alt 결제완료(Non UI)
		상점 ->> 하이픈: 결제완료 API 호출
		하이픈 ->> 하이픈: 출금 및 결제 완료 처리
		하이픈 ->> 상점: 결제 완료 응답
	end
	상점 ->> 사용자: 주문 완료
Mermaid
복사

1. 서명값생성(Non-UI)

결제 정보를 검증하기 위한 검증값을 생성하는 API입니다. 해당 API를 먼저 호출 한 후 결제창 UI를 실행해야 하며, 응답으로 받은 signVl값을 Form 파라메터의 signVl(서명값) 에 넣어줘야 합니다.
•
요청 헤더 정보
URL
도메인 + /barotongjang/sign
Method
POST
Content-Type
Application/json; charset=UTF-8
•
요청 메시지 상세
항목
항목명
필수
TYPE
길이
설명
비고
ordNo
주문번호
Y
string
50
상점의 주문번호 입력
특수문자 불가
mrstSno
상점일련번호
Y
bigint
바로계좌결제에게 부여받은 상점일련번호
rqsAmt
요청금액
Y
bigint
거래 금액
mbtlNo
핸드폰번호
N
string
50(평문)
미 입력시 검증대상 제외
AES 암호화 후 전송
•
응답 메시지 상세
항목
항목명
필수
TYPE
길이
설명
비고
ordNo
주문번호
Y
string
50
상점의 주문번호 입력
요청값의 echo
mrstSno
상점일련번호
Y
bigint
바로계좌결제에게 부여받은 상점일련번호
요청값의 echo
rqsAmt
요청금액
Y
bigint
거래 금액
요청값의 echo
mbtlNo
핸드폰번호
N
string
50(평문)
미 입력시 검증대상 제외
요청값의 echo
signVl
서명값
Y
string
제한없음
바로계좌결제에서 생성한 서명 값

2. 결제등록(UI)

위의 내용을 참고하여 연동합니다.

3. 결제완료(Non-UI)

결제등록 된 거래에 대해 실제 고객계좌에서 출금을 하는 API입니다. 해당 API가 호출 되지 않으면 고객계좌에서 출금되지 않습니다.
•
요청 헤더 정보
URL
요청 도메인 + /barotongjang/settlement/approval/confirm
Method
POST
Content-Type
Application/json; charset=UTF-8
Authorization
Bearer + 스페이스 1byte + 가맹점 access token
•
요청 메시지 상세
항목
항목명
필수
TYPE
길이
설명
비고
mbrSno
회원일련번호
Y
bigint
회원의 일련번호
mrstSno
상점일련번호
Y
bigint
바로계좌결제에게 부여받은 상점일련번호
trAprvNo
거래승인번호
Y
string
20
결제등록 결과값 중 거래승인번호
stlmWyDcmtNo
결제수단식별번호
Y
string
40
결제등록 결과값 중 결제수단식별번호
ordNo
주문번호
Y
string
50
상점의 주문번호 입력
특수문자 불가
•
응답 메시지 상세
항목
항목명
필수
TYPE
길이
설명
비고
mbrSno
회원일련번호
Y
bigint
mrstSno
상점일련번호
Y
bigint
trDt
거래일자
N
string
8
trTm
거래시간
N
string
6
pcsAmt
처리금액
Y
bigint
trAprvNo
거래승인번호
Y
string
20
stlmWyDcmtNo
결제수단식별번호
Y
string
40
prdNm
상품명
N
string
100
ordNo
주문번호
Y
string
50
상점의 주문번호 입력
특수문자 불가
cshRcptIsnYn
현금영수증발급여부
Y
string
1
cshRcptTrUnqNo
현금영수증거래고유번호
N
string
cshRcptAprvNo
현금영수증승인번호
N
string
cshRcptMsg1
현금영수증메세지1
N
string
cshRcptMsg2
현금영수증메세지2
N
string
svAmt
공급가액
Y
bigint
vatAmt
부가세액
Y
bigint
tfAmt
면세금액
Y
bigint
tpAmt
봉사료
Y
bigint
dnxDscd
소득공제구분코드
N
bigint
0 : 소득공제 / 1 : 지출증빙

4. 결제취소(Non-UI)

결제가 완료된 거래에 대해 취소하고자 할 때 호출하는 API 입니다.
•
요청 헤더 정보
URL
요청 도메인 + /barotongjang/settlement/cancel
Method
POST
Content-Type
Application/json; charset=UTF-8
Authorization
Bearer + 스페이스 1byte + 가맹점 access token
•
요청 메시지 상세
항목
항목명
필수
TYPE
길이
설명
비고
mbrSno
회원일련번호
Y
bigint
결제등록 결과값 중 회원일련번호
mrstSno
상점일련번호
Y
bigint
결제등록 결과값 중 상점일련번호
ogtrDt
원거래일자
Y
string
8
결제등록 결과값 중 거래일자
yyyyMMdd
ogtrTm
원거래시각
Y
string
6
결제등록 결과값 중 거래시각
HHmmss
ogtrAprvAmt
원거래승인금액
Y
bigint
결제등록 결과값 중 처리일자
ogtrAprvNo
원거래승인번호
Y
string
20
결제등록 결과값 중 승인번호
ogtrOrdNo
원거래주문번호
Y
string
50
결제등록 결과값 중 주문번호
•
응답 메시지 상세
항목
항목명
필수
TYPE
길이
설명
비고
mbrSno
회원일련번호
Y
bigint
mrstSno
상점일련번호
Y
bigint
pcsAmt
처리금액
Y
bigint
trAprvNo
거래승인번호
Y
string
20
stlmWyDcmtNo
결제수단식별번호
Y
string
40
ordNo
주문번호
Y
string
50
상점의 주문번호 입력
prdNm
상품명
N
string
100
cshRcptIsnYn
현금영수증발급여부
Y
string
cshRcptTrUnqNo
현금영수증거래고유번호
N
string
cshRcptAprvNo
현금영수증승인번호
N
string
cshRcptMsg1
현금영수증메세지1
N
string
cshRcptMsg2
현금영수증메세지2
N
string
ogtrDt
원거래 일자
Y
string
8
yyyyMMdd
ogtrTm
원거래 시각
Y
string
6
HHmmss
trDt
취소거래 일자
Y
string
8
trTm
취소거래 시각
Y
string
6

5. 정산상세내역 조회

정산상세내역을 조회하기 위한 서비스
가맹점 Access token 사용 시
> 요청 파라미터 중 mrstSno(상점일련번호) 값 필수, slsAgnSno, submrstSnoLst 값 미입력
영업대행사 Access token 사용 시
> 요청 파라미터 중 slsAgnSno(영업대행사일련번호) 값 필수, mrstSno 미입력
> subMrstSnoLst(하위상점일련번호리스트) 값은 선택이며, 미입력 시 모든 하위 상점내역
•
요청 헤더 정보
URL
요청 도메인 + /exactcalculation/detail/ext/get
Method
POST
Content-Type
Application/json; charset=UTF-8
Authorization
Bearer + 스페이스 1byte + 가맹점 access token 또는 Bearer + 스페이스 1byte + 영업대행사 access token
•
요청 메시지 상세
항목
항목명
필수
TYPE
길이
설명
mrstSno
상점일련번호
N
bigint
별도 안내
slsAgnSno
영업대행사일련번호
N
bigint
별도 안내
submrstSnoLst
하위상점일련번호리스트
N
bigint
예시 - ”subMrstSnoLst” : [1,2,3]
stTrDt
시작거래일자
N*
String
8
조회 시작 일자
endTrDt
마지막거래일자
N*
String
8
조회 마지막 일자
stRomParnDt
시작입금예정일자
N*
String
8
시작 입금 예정 일자
endRomParnDt
마지막입금예정일자 
N*
String 
8 
마지막 입금 예정 일자 
stRomDt
시작입금일자 
N*
String 
8 
시작 입금 일자 (실제로 가맹점에 정산금을 입금한 시작일자)
endRomDt
마지막입금일자 
N*
String 
8 
마지막 입금 일자  (실제로 가맹점에 정산금을 입금한 마지막일자)
pagNo
페이지번호
Y
Int
조회 시 시작 페이지 번호  (첫 조회 시 값 : 0)
pagSz
페이지데이터사이즈
Y
int
조회 시 전달 받을 데이터 수  (기본 값 : 100)
** [변경사항] : trDt1 > stTrDt, trDt2 > endTrDt
•
필수값 N* : 3개의 일자(거래일자/ 입금예정일자/입금일자) 중 1개는 필수값
•
일자의 최대 조회기간은 1개월이며, 그 이상 조회를 원하시면 하이픈 전산(paytech@hyphen.im)으로 연락부탁드립니다.
•
응답 메시지 상세
항목
항목명
필수
TYPE
길이
설명
lstSize
조회 데이터 크기
Y
bigint
반복부 – xclDtlLstList
trSno
거래일련번호
Y
bigint
하이픈 거래 일련번호
mrstSno
상점일련번호
Y
bigint
trDt
거래일자
Y
string
8
romParnDt
입금예정일자
Y
string
8
romDt
입금일자
Y
string
8
trDscdNm
거래구분명
Y
string
2
결제/취소
aprvNo
승인번호
Y
string
20
ordNo
주문번호
Y
string
50
amt
금액
Y
bigint
fee
수수료
Y
bigint
vat
부가세
Y
bigint
mrstRomAmt
상점입금액
Y
bigint

[참고] 응답코드

업무구분
코드값
성공실패
메시지
공통  (COmmon)
HCO000
success
정상 처리 되었습니다.
HCO001
fail
채번원장 조회 실패입니다.
HCO002
fail
채번유형 오류입니다.
HCO003
fail
올바르지 않은 거래구분코드입니다.
HCO004
fail
올바르지 않은 거래상세구분코드입니다.
HCO005
fail
검색조건에 해당하는 내용이 없습니다.
HCO006
fail
올바르지 않은 연동거래상세구분코드입니다.
HCO007
fail
올바르지 않은 API 요청입니다.
HCO008
fail
URL 호출에 실패하였습니다.
HCO009
fail
복호화에 실패하였습니다.
HCO010
fail
메일 발송에 실패하였습니다.
HCO011
fail
입력값 오류 :
HCO012
fail
이용사 요청값 인증오류에요
HCO013
fail
회원일련번호 요청값 인증오류에요
HCO014
fail
데이터 복호화를 실패했어요
HCO015
fail
비밀번호 복호화를 실패했어요
HCO016
fail
데이터 암호화를 실패했어요
HCO017
fail
올바르지 않은 이메일 주소에요.
HCO018
fail
토큰 내 회원정보 오류에요. 다시 로그인 해주세요.
HCO019
fail
올바르지 않은 상태코드입니다.
HCO020
fail
서비스 처리 오류
HCO021
fail
기관 통신 오류
HCO999
fail
알 수 없는 오류입니다.
HCO888
fail
추후에 오류 지정