🔍

4. 포인트관리

원하는 목차 항목을 누르면 해당 내용으로 이동합니다.

•

목차

4.1. 포인트 잔액조회

4.2. 포인트 지급내역조회

4.3. 포인트 지급을 위한 사전 포인트 등록

4.4. 포인트 관리 원장 조회

4.5. 포인트 일괄 지급

4.5.1 포인트 일괄 지급 확인

*update history

ver	변경일자	변경내용
v0.1	2024.05.27	포인트 종류 용어변경 (무상포인트→ 장부형포인트, 유상포인트→정산포인트)
v0.2	2025.01.08	포인트 일괄 지급 api추가

4.1. 포인트 잔액조회

회원별 잔여 포인트를 조회하기 위해 사용하는 API 입니다.

•

전제조건

◦

이용사가 사용하는 포인트의 종류는 N개인 경우에 해당함 
(이용사가 사용하는 포인트의 종류가 1개인 경우, 상점=이용사)

sequenceDiagram
	autonumber
	회원 ->> 이용사플랫폼(app/web) : 포인트 잔액조회 시
	이용사플랫폼(app/web) ->> Server(이용사) : 포인트 잔액조회 요청
	Server(이용사) ->> 하이픈 : 포인트잔액조회API
	하이픈 -->> Server(이용사) : 잔액 응답
	Server(이용사) -->> 이용사플랫폼(app/web): 잔액 응답
	이용사플랫폼(app/web) -->> 회원 : 잔액표기
  
Mermaid
복사

•

HTTP Header Information

URL	요청 도메인 + /point/rmdAmt
Method	POST
Content-Type	Application/json; charset=UTF-8
Authorization	Bearer + 스페이스 1byte + 이용사토큰

•

Request

No	항목	항목명	필수	TYPE	길이	설명
1	uscoSno	이용사번호	Y	Long
2	mbrID	회원ID	Y	string	100	이용사의 회원 ID
3	exPrspDt	만료예정일 지정	N	Long		미입력시 : 30일

{
  "uscoSno": "이용사번호",
  "mbrID": "이용사 회원ID",
  "exPrspDt": "만료예정일 지정"
}
JSON
복사

•

Response

No	항목	항목명	필수	TYPE	길이	설명
1	sucsFalr		Y	String		성공 실패 여부
2	rsltCd		Y	String		응답 코드 ‘HCO000’이 아닌 경우는 모두 오류입니다.
3	rsltMesg		Y	String		응답 메시지
4	rsltObj		N	JSON		API별 응답 데이터
4-1	uscoSno	이용사번호	Y	Long
4-2	mbrID	회원ID	Y	string	100	이용사의 회원 ID
4-3	mbrNm	회원명	Y	String	50
4-4	rmdAmt	총 포인트 (총 잔액)	Y	Long
4-5	ttlPsbAmt	총 포인트 (사용가능 잔액)	Y	Long
4-6	ttlExAmt	총 포인트 (소멸예정 잔액)	Y	Long		exPrspDt 값
4-7	payAmt	정산 포인트 (총 잔액)	Y	Long
4-8	psbPAmt	정산 포인트 (사용가능 잔액)	Y	Long
4-9	exPAmt	정산포인트 (소멸예정 잔액)	Y	Long		exPrspDt 값
4-10	freeAmt	장부형 포인트 (총 잔액)	Y	Long
4-11	psbFAmt	장부형 포인트 (사용가능 잔액)	Y	Long
4-12	exFAmt	장부형 포인트 (소멸예정 잔액)	Y	Long		exPrspDt 값

{
    "sucsFalr": "성공실패여부(success/fail)",
    "rsltCd": "응답코드",
    "rsltMesg": "응답메시지",
    "rsltObj": {
			  "uscoSno": "이용사번호",
			  "mbrID": "이용사 회원ID",
			  "mbrNm": "회원명",
			  "rmdAmt": "총 포인트 (총 잔액)",
			  "ttlPsbAmt": "총 포인트 (사용가능 잔액)",
			  "ttlExAmt": "총 포인트 (소멸예정 잔액)",
			  "payAmt": "정산 포인트 (총 잔액)",
			  "psbPAmt": "정산 포인트 (사용가능 잔액)",
			  "exPAmt": "정산 포인트 (소멸예정 잔액)",
			  "freeAmt": "장부형 포인트 (총 잔액)",
			  "psbFAmt": "장부형 포인트 (사용가능 잔액)",
			  "exFAmt": "장부형 포인트 (소멸예정 잔액)"
			}
}
JSON
복사

4.2. 포인트 지급내역조회

•

이용사가 회원에 지급한 포인트를 조회하는 API 

sequenceDiagram
	autonumber
	회원 ->> 이용사플랫폼(app/web) : 포인트 지급내역 확인요청
이용사플랫폼(app/web) ->> Server(이용사) : 포인트 지급내역 확인요청
	Server(이용사) ->> 하이픈 : 포인트 지급내역 확인요청
	하이픈 -->> Server(이용사) : 포인트 지급내역 응답
	Server(이용사) -->> 이용사플랫폼(app/web): 포인트 지급내역 응답
이용사플랫폼(app/web) -->> 회원 : 포인트 지급내역 표기
Mermaid
복사

포인트 지급내역 조회 비정상 case

•

HTTP Header Information

URL	요청 도메인 + /point/rmdAmt/detail
Method	POST
Content-Type	Application/json; charset=UTF-8
Authorization	Bearer + 스페이스 1byte + 이용사토큰

•

Request

No	항목	항목명	필수	TYPE		설명
1	uscoSno	이용사번호	Y	Long
2	mbrID	회원ID	Y	string	100	이용사의 회원 ID

{
  "uscoSno": "이용사번호",
  "mbrID": "이용사 회원번호"
}
JSON
복사

•

Response

No	항목	항목명	필수	TYPE		설명
1	sucsFalr		Y	String		성공 실패 여부
2	rsltCd		Y	String		응답 코드 ‘HCO000’이 아닌 경우는 모두 오류입니다.
3	rsltMesg		Y	String		응답 메시지
4	ttlPayCnt	총 지급 승인 건 수	Y	Long
5	ttlPayCnclCnt	총 지급 취소 건 수	Y	Long
6	ttlPayAmt	총 지급 승인 금액	Y	Long
7	ttlPayCnclAmt	총 지급 취소 금액	Y	Long
8	rsltObj		N	JSON		API별 응답 데이터
8-1	uscoSno	이용사번호	Y	Long
8-2	mbrID	회원ID	Y	string	100	이용사의 회원 ID
8-3	mbrNm	회원명	Y	Long
		[rmdList]	Y
1)	trDtlDscd	포인트 종류	Y	String	2	정산포인트(”PP”), 장부형포인트(”PF”)
2)	lkgTrDtlDscd	포인트 구분코드	Y	String	2
3)	autoYn	지급구분	Y	String	1	자동(”Y”), 수동(”N”)
4)	payAmt	지급금액	Y	String
5)	useAmt	사용금액	Y	String
6)	expAmt	만료금액	Y	String
7)	rmdAmt	잔여금액	Y	String
8)	expDt	만료일자	Y	String	8	YYYYMMDD
9)	enrDtTm	등록일시	Y	String	15	YYYYMMDD hhmmss
10)	usPsbDt	사용가능일자	Y	String	8	YYYYMMDD

{
    "sucsFalr": "성공실패여부(success/fail)",
    "rsltCd": "응답코드",
    "rsltMesg": "응답메시지",
    "rsltObj": {
				  "uscoSno": "이용사번호",
				  "mbrID": "이용사 회원ID",
				  "mbrNm": "회원명",
				  "ttpayCnt": "총 지급 승인 건 수",
				  "ttPayAmt": "총 지급 승인액",
				  "ttpayCnclCnt": "총 지급 취소 건 수",
				  "ttPayCnclAmt": "총 지급 취액",
				  "rmdList": [
				    {
				      "trDtlDscd": "포인트 종류",
				      "lkgTrDtlDscd": "포인트 구분코드",
				      "autoYn": "지급구분",
				      "payAmt": "지급금액",
				      "useAmt": "사용금액",
				      "expAmt": "만료금액",
				      "rmdAmt": "잔여금액",
				      "stcd": "상태코드",
				      "expDt": "만료일자",
				      "enrDt": "등록일시",
				      "usPsbDt": "사용가능일자"
				    }
				  ]
		}
}
JSON
복사

4.3. 포인트 지급을 위한 사전 포인트 등록

등록된 포인트 내역을 조회하기 위한 API 입니다.

사전 포인트를 등록해야 포인트를 지급할 수 있습니다.

•

HTTP Header Information

URL	요청 도메인 + /point/mngRgst
Method	POST
Content-Type	Application/json; charset=UTF-8
Authorization	Bearer + 스페이스 1byte + 이용사토큰

•

Request

No	항목	항목명	필수	TYPE		설명
1	uscoSno	이용사일련번호	Y	Long
2	mrstSno	상점일련번호	N	Long
3	pomngId	포인트ID	Y	String	100	이용사 포인트ID
4	poNm	포인트명	Y	String	50
5	kdcd	종류코드	N	String	1	default : 2 / 0 : 정액포인트, 1 : 정률포인트, 2: 즉시지급포인트
6	stcd	상태코드	N	String	2	default : 00 (정상) / 00 (정상), 02 : 적립대기, 11 : 적립, 22 : 적립중지, 91 : 만료
7	tpcd	대상유형코드	N	String	1	0 : 전체회원, 1 : 첫가입회원, 2 : 첫결제회원, 3 : 생일회원, 4 : 등급별회원
8	trDtlDscd	거래상세구분코드	Y	String	2	거래구분코드 sheet 참조
9	enrDt	등록일자	N	String	8	default : 현재 일자
10	enrTm	등록시간	N	String	6	default : 현재 시간

{
     "uscoSno": "이용사 일련번호",
     "mrstSno": "상점 일련번호",
     "pomngId": "이용사 포인트 id",
     "poNm": "포인트 명",
     "kdcd": "종류코드",
     "aplTgtVl": "적용대상값",
     "stcd": "상태코드",
     "tpcd": "유형코드",
     "trDtlDscd": "거래상세구분코드",
     "lkgTrDtlDscd": "연동상세구분코드",
     "enrDt": "등록일자",
     "enrTm": "등록시간"
}
JSON
복사

•

Response

No	항목	항목명	필수	TYPE	길이	설명
1	sucsFalr		Y	String		성공 실패 여부
2	rsltCd		Y	String		응답 코드 ‘HCO000’이 아닌 경우는 모두 오류입니다.
3	rsltMesg		Y	String		응답 메시지
4	rsltObj		N	JSON		API별 응답 데이터
5	uscoSno	이용사일련번호	Y	Long
6	mrstSno	상점일련번호	Y	Long
7	pomngId	포인트 일련번호	Y	String	100	이용사 포인트 일련번호
8	poNm	포인트명	Y	String	50
9	kdcd	종류코드	Y	String	1	default : 2 ( 즉시지급 포인트)
10	stcd	상태코드	Y	String	2	02 : 적립대기, 11 : 적립, 22 : 적립중지, 91 : 만료
11	tpcd	유형코드	Y	String	1	0 : 전체회원, 1 : 첫가입회원, 2 : 첫결제회원, 3 : 생일회원, 4 : 등급별회원
12	trDtlDscd	거래상세구분코드	Y	String	2	거래구분코드 sheet 참조
13	lkgTrDtlDscd	연동상세구분코드	N	String	2	거래구분코드 sheet 참조
14	enrDt	등록일자	Y	String	8
15	enrTm	등록시간	Y	String	6

{
    "sucsFalr": "성공실패여부(success/fail)",
    "rsltCd": "응답코드",
    "rsltMesg": "응답메시지",
    "rsltObj": {
				  "pntList": [
				    {
				      "uscoSno": "이용사 일련번호",
				      "mrstSno": "상점 일련번호",
				      "pomngId": "이용사 포인트 id",
				      "poNm": "포인트 명",
				      "kdcd": "종류코드",
				      "aplTgtVl": "적용대상값",
				      "stcd": "상태코드",
				      "tpcd": "유형코드",
				      "trDtlDscd": "거래상세구분코드",
				      "lkgTrDtlDscd": "포인트구분코드",
				      "enrDt": "등록일자",
				      "enrTm": "등록시간",
				    }
				  ]
		}
}
JSON
복사

4.4. 포인트 관리 원장 조회

등록된 포인트 내역을 조회하기 위한 API 입니다. 포인트 등록은 가능하지만, 수정(포인트 삭제)는 불가합니다.

•

HTTP Header Information

URL	요청 도메인 + /point/mngList
Method	POST
Content-Type	Application/json; charset=UTF-8
Authorization	Bearer + 스페이스 1byte + 이용사토큰

•

Request

No	항목	항목명	필수	TYPE	길이	설명
1	uscoSno	이용사번호	Y	Long
2	pomngId	포인트 고유 id	N	string	100	이용사의 회원 ID
3	lkgTrDtlDscd	포인트 구분코드	N	string	2

{
  "uscoSno": "이용사번호",
  "lkgTrDtlDscd": "이용사 회원번호",
  "pomngId": "포인트 고유 id"
}
JSON
복사

•

Response

No	항목	항목명	필수	TYPE	길이	설명
1	sucsFalr		Y	String		성공 실패 여부
2	rsltCd		Y	String		응답 코드 ‘HCO000’이 아닌 경우는 모두 오류입니다.
3	rsltMesg		Y	String		응답 메시지
4	rsltObj		N	JSON		API별 응답 데이터
5	pntList		Y	List[Object]
5.1	uscoSno	이용사일련번호	Y	Long
5.2	mrstSno	상점일련번호	Y	Long
5.3	pomngId	포인트 일련번호	Y	String	100	이용사 포인트 일련번호
5.4	poNm	포인트명	Y	String	50
5.5	kdcd	종류코드	Y	String	1	default : 2 ( 즉시지급 포인트)
5.6	stcd	상태코드	Y	String	2	02 : 적립대기, 11 : 적립, 22 : 적립중지, 91 : 만료
5.7	tpcd	유형코드	Y	String	1	0 : 전체회원, 1 : 첫가입회원, 2 : 첫결제회원, 3 : 생일회원, 4 : 등급별회원
5.8	lkgTrDtlDscd	포인트구분코드	Y	String	2	ex) 1P, 2P, P3
5.9	enrDt	등록일자	Y	String	8
5.10	enrTm	등록시간	Y	String	6

{
    "sucsFalr": "성공실패여부(success/fail)",
    "rsltCd": "응답코드",
    "rsltMesg": "응답메시지",
    "rsltObj": {
				  "pntList": [
				    {
				      "uscoSno": "이용사 일련번호",
				      "mrstSno": "상점 일련번호",
				      "pomngId": "이용사 포인트 id",
				      "poNm": "포인트 명",
				      "kdcd": "종류코드",
				      "aplTgtVl": "적용대상값",
				      "stcd": "상태코드",
				      "tpcd": "유형코드",
				      "lkgTrDtlDscd": "포인트구분코드",
				      "enrDt": "등록일자",
				      "enrTm": "등록시간",
				    }
				  ]
		}
}
JSON
복사

4.5. 포인트 일괄 지급

회원에게 포인트를 일괄적으로 등록하는 API입니다.

평균 소요 시간: 약 20초( 1000건 기준 )

최대 요청 가능 건수: 2,000건

•

사전 조건

◦

거래관리 > 거래통보 API를 먼저 사용하여 개별 처리 방식에 익숙해진 뒤 요청을 진행하시기 바랍니다.

•

요청 데이터

◦

개인정보는 보안상 제공받은 AES 암호화 키를 사용하여 AES 방식으로 암호화한 뒤 전송해야 합니다.

•

HTTP header information

URL	요청 도메인 + /settlement/notify/list
Method	POST
Content-Type	Application/json; charset=UTF-8
Authorization	Bearer + 스페이스 1byte + 이용사토큰

•

Request

No	항목	항목명	필수	TYPE	설명
1	settlementList	거래 정보 리스트	Y	List[Object]	거래 정보를 담은 리스트 (아래 settlementList 내부 항목 참고)
1.1	rqsDscd	요청구분코드	Y	string	C : 등록
1.2	uscoSno	이용사일련번호	Y	bigint	별도 안내
1.3	mrstNo	상점번호	N	string	정산대상 거래 시 입력 (충전,충전취소,환불,환불취소,지급,지급취소 시 공백)
1.4	mbrID	회원ID	Y	string	이용사의 회원 ID
1.5	tmnNo	단말기번호	N	string
1.6	trDscd	거래구분코드	Y	string(2)	거래구분코드 sheet 참조
1.7	trDtlDscd	거래상세구분코드	Y	string(2)	거래구분코드 sheet 참조
1.8	lkgTrDtlDscd	연동거래상세구분코드	N	string(2)	거래구분코드 sheet 참조
1.9	trDt	거래일자	Y	string	YYYYMMDD
1.1	trTm	거래시각	Y	String	HHMMSS
1.11	trAprvNo	거래승인번호	Y	String(20)	미입력시 자동채번
1.12	rqsAmt	요청금액	Y	String	고객이 결제한 금액
1.13	pcsAmt	처리금액	Y	String	잔액처리금액 (실제로 회원 충전처리한 금액)
1.14	trAfRmd	거래 후 잔액	N	String
1.15	ordNo	주문번호	N	String(50)	이용사의 거래고유번호 입력
1.16	prdNm	상품명	N	String
1.17	trUnqNo	거래고유번호	N	String	PG사를 통한 거래 시 기관에서 발급한 거래의 고유번호
1.18	trIsttCd	거래기관코드	N	String	거래와 연관 된 기관코드 (정산, 인출 시 은행코드)
1.19	trInf	거래정보	N	string	거래와 연관 된 정보, 계좌번호 등 (AES-256 암호화) / 포인트ID
1.2	ogtrDt	원거래일자	N	string	YYYYMMDD 취소거래시만 사용
1.21	ogtrTm	원거래시각	N	string	HHMMSS 취소거래시만 사용
1.22	ogtrAprvNo	원거래승인번호	N	string	취소거래시만 사용
1.23	usPsbDt	사용가능일자	N	string	YYYYMMDD 포인트 거래시만 사용 미입력시 포인트지급정보관리 조회 후 존재하면 해당 정보로 설정 포인트지급정보관리 원장에도 없을 경우 현재일자 자동입력
1.24	extDt	소멸일자	N	string	YYYYMMDD
2	reqId	요청 고유번호	Y	string(20)	4.5.1 포인트 일괄 지급 확인 요청 필드

	{
	    "reqId" : "ABCDE1234"
	    "settlementList": [
	        {
				    "rqsDscd": "요청구분코드",
						"uscoSno": "이용사일련번호",
						"mrstSno": "상점일련번호",
						"mbrID": "회원일련번호",
						"tmnNo": "단말기번호",
						"trDscd": "거래구분코드",
						"trDtlDscd": "거래상세구분코드",
						"lkgTrDtlDscd": "연동거래상세구분코드",
						"trDt": "거래일자",
						"trTm": "거래시각",
						"trAprvNo": "거래승인번호",
						"rqsAmt": "요청금액 - 고객결제금액",
						"pcsAmt": "처리금액 - 실처리금액",
						"trAfRmd": "거래후잔액",
						"ordNo": "주문번호",
						"prdNm": "상품명",
						"trUnqNo": "거래고유번호",
						"trIsttCd": "거래기관코드",
						"trInf": "거래정보",
						"ogtrDt": "원거래일자",
						"ogtrTm": "원거래시각",
						"ogtrAprvNo": "원거래승인번호"
		    } 
	]
}
JSON
복사

•

Response 

No	항목	항목명	필수	길이	TYPE	설명
1	sucsFalr		Y		String	성공 실패 여부
2	rsltCd		Y		String	응답 코드 ‘HCO000’이 아닌 경우는 모두 오류입니다.
3	rsltMesg		Y		String	응답 메시지
4	rsltObj		N		JSON	API별 응답 데이터
4-1	reqId	요청고유번호	Y	20	string	4.5.1 포인트 일괄 지급 확인 요청 필드

{
    "sucsFalr": "성공실패여부(success/fail)",
    "rsltCd": "응답코드",
    "rsltMesg": "응답메시지",
    "rsltObj": {
		    "reqId": "요청고유번호"
		}
}
JSON
복사

4.5.1 포인트 일괄 지급 확인

하이픈에 요청한 포인트 일괄 지급 상태를 확인하는 API입니다.

최대 처리 소요 시간: 1분

•

응답 방식

지급이 진행 중인 경우:

•

API는 처리 중 상태를 나타내는 오류 응답을 반환합니다.

•

상태가 완료될 때까지 일정 간격(예: 10초)을 두고 재시도하여 응답을 확인하시기 바랍니다.

•

지급이 완료된 경우:

◦

정상 응답을 반환하며, 지급 상태를 확인할 수 있습니다.

•

HTTP header information

URL	요청 도메인 + /settlement/notify/listChk
Method	POST
Content-Type	Application/json; charset=UTF-8
Authorization	Bearer + 스페이스 1byte + 이용사토큰

•

Request

No	항목	항목명	필수	TYPE	설명
1	reqId	요청 고유번호	Y	String	4.5 포인트 일괄 지급 API 응답 필드 “reqId” 데이터를 기입

	{
						 "reqId": "포인트일괄지급 API 응답필드",
	}
JSON
복사

•

Response 

No	항목	항목명	필수	TYPE	설명
1	sucsFalr		Y	String	성공 실패 여부
2	rsltCd		Y	String	응답 코드‘HCO000’이 아닌 경우는 모두 오류입니다.
3	rsltMesg		Y	String	응답 메시지
4	rsltObj		N	JSON	API별 응답 데이터
4-1	requestCnt	Y	Integer	요청한 총 건수	YYYYMMDDHHmmss
4-2	successCnt	Y	Integer	처리 성공 건수
4-3	failCnt	Y	Integer	처리 실패 건수
4-4	unCheckCnt	Y	Integer	알수 없는 오류 건수	관리자 문의
4-5	failData	N	Array	실패한 데이터 목록
4-5-1	mbrID	Y	String	실패한 회원 ID
4-5-2	errMsg	Y	String	실패 상세 메시지

{
    "sucsFalr": "success",
    "rsltCd": "HCO000",
    "rsltMesg": "정상으로 처리되었어요",
    "rsltObj": {
        "requestCnt": 1000,
        "successCnt": 998,
        "failCnt": 2,
        "unCheckCnt": 0,
        "failData": [
            {
                "mbrID": "1234",
                "errMsg": "이미 가입되셨어요"
            },
            {
                "mbrID": "5678",
							  "errMsg": "이미 가입되셨어요"
            }  
            ]
    }
}
JavaScript
복사