개발자센터
키움페이 개발가이드 1.0통합결제연동(LINK)

통합결제연동(LINK)

통합결제연동 메뉴얼 다운로드

통합결제연동 내용과 관련한 대략적인 설명 텍스트를 입력해주세요.

※ 주의사항 설명 텍스트를 입력해주세요.

개발 프로세스

키움페이 통합결제의 기본적 흐름은 다음과 같이 이루어져요.

용어 정리

키움페이의 통합결제연동 서비스를 사용하는 과정에 필요한 결제수단 및 용어 설명을 제공해요.

통합결제연동 제공 결제수단

결제방식결제수단
URL 연동
신용카드D,K(일반/수기/월자동), 휴대폰(일반/월자동), 계좌이체, 상품권, 티머니, 가상계좌, 카카오페이

결제결과 통지

통지방법설명
WEB 통지
결제가 성공한 경우, 가맹점의 결제결과 처리 URL을 호출하는 방식(HTTP, HTTPS)

결제결과 처리 URL 작성 안내

  1. 1고객이 키움페이 결제 페이지에서 결제가 성공하면, 키움페이 시스템은 가맹점이 정한 특정 페이지에 결제 결과를 통보해요.
  2. 2가맹점은 DB처리하는 페이지를 가맹점의 WEB페이지 언어에 맞게 작성하여, 그 해당하는 URL을 키움페이 관리자에게 알려주어야 하며, 이 페이지의 접근은 특정 IP에서만 접근이 가능해야 해요.※ 키움페이 서버 IP 대역은 별도로 문의해주세요.
  3. 3가맹점의 DB처리 페이지는 결제수단에 따라 해당 Parameter를 개발언어의 특성에 맞게 해당변수에 저장한 후, 실제 구매내역과 금액과 주문번호 등을 확인하여 서비스를 제공할 수 있도록 DB작업을 수행해요.
  4. 4정상적으로 DB처리가 완료 되면 DB처리 페이지에서 아래와 같이 HTML을 출력할 수 있어요.
  5. 5키움페이 시스템에서는 아래 HTML이 확인되면 정상 거래 건으로 인지해요.
결제결과 처리 URL
  1. <html/>
  2. <body/>
  3. <RESULT/>SUCCESS</RESULT/>
  4. </body/>
  5. </html/>

※ 결제 결과 페이지에는 반드시 <RESULT/>SUCCESS</RESULT/>가 포함되어 있어야 해요.

해당 페이지가 존재하지 않거나 위와 같이 정상처리가 되지 않아도 고객의 결제는 정상 승인처리 되며, 가맹점의 개발 담당자에게 해당 건에 대한 통지 실패 메일이 발송돼요. 해당 건에 대한 처리는 가맹점에서 내부적으로 처리해 주셔야 해요.

결제결과 재통지 안내

  1. 1과금은 됐지만 결제 결과값 통지를 실패하게 되면 고객은 결제를 다시 수행해야 해요.
  2. 2이러한 불편을 해소하기 위해, 키움페이 시스템에서는 가맹점의 DB처리 URL에 재통지를 보내고 있어요. 거래번호(DAOUTRX)처럼 유일한 값에 DB 중복체크가 반드시 필요해요.
  3. 3재 통지주기는 거래가 일어난 시점부터 3분 단위로 1시간동안 통지해요.
  4. 4통지실패 메일 발송 시점은 재 통지 10번 이후에 발송돼요.
  5. 51시간 이내에 재 통지가 성공되면 더이상 통지하지 않아요.

KIWOOM_ENC(결제요청 HASH 값) 구하기

결제창 연동 전 KIWOOM_ENC 요청/응답 항목에 대해 안내해요.

구분항목명길이내용비고
요청
PAYMETHOD
10
(필수)결제수단(TOTAL:통합결제창)
TOTAL 고정
TYPE
1
(필수)결제방식(P:PC/M:모바일/W:웹뷰)
CPID
20
(필수)가맹점ID
키움페이에서 부여
ORDERNO
50
(필수)주문번호
AMOUNT
10
(필수)결제금액
응답
RESULTCODE
4
0000:정상, 나머지코드 에러
ERRORMESSAGE
제한없음
에러메시지
KIWOOM_ENC
제한없음
결제요청HASH값

전송 필수항목

모든 항목이 POST방식을 사용하고 있나요?

PAYMETHOD(결제수단)의 항목이 TOTAL(통합결제창) 고정인가요?

참고 예시

아래에 예시용 코드를 제공해드려요. 참고용으로만 사용하시고, 각 언어와 환경에 맞도록 구성해주세요.

※ 위의 코드는 예시 및 참고용으로만 사용해주세요.
호출 사용 예시
  1. String apiURL = “https://apitest.kiwoompay.co.kr/pay/hash”;
  2. URL url = new URL(apiURL);
  3. HttpURLConnection conn = (HttpURLConnection) url.openConnection();
  4. conn.setRequestMethod(“POST”);
  5. conn.setRequestProperty(“Content-Type”, “application/json;charset=EUC-KR”);
CURL 호출 사용 예시
  1. curl -X POST https://apitest.kiwoompay.co.kr/pay/hash \
  2. -H “Content-Type: application/json; charset=EUC-KR” \
  3. -d '{“PAYMETHOD”:“TOTAL”,“TYPE”:“P”,“CPID”:“CTS18179”,“ORDERNO”:“ORDER_1234”,“AMOUNT”:“1000”}'
응답값 예시
  1. {“RESULTCODE”:“0000”,“ERRORMESSAGE”:“SUCCESS”,“KIWOOM_ENC”:“ZmFlMTg3ZTA3YTA5NGViNTFmYmU1Zjlm....”}

통합결제 연동 URL

분류URL
운영
https://api.kiwoompay.co.kr/pay/linkEnc
개발
https://apitest.kiwoompay.co.kr/pay/linkEnc

결제요청 항목

키움페이의 통합결제연동 서비스를 사용하는 과정에 필요한 필수 파라미터를 안내해요.

※ 결제수단 별 추가 파라미터는 메뉴얼을 참고해주세요.

결제수단(PAYMETHOD)

PAYMETHOD결제수단PAYMETHOD결제수단
KT
폰빌(일반)
BANK
계좌이체(일반)
KT-BATCH
폰빌(월자동)
CULTURE
문화상품권(일반)
MOBILE
휴대폰(일반)
BOOKNLIFE
도서문화상품권(일반)
MOBILE-BATCH
휴대폰(월자동)
HAPPYMONEY
해피머니상품권(일반)
CARDK
신용카드K(일반)
MOBILEPOP
모바일팝(일반)
CARDK-SUGI
신용카드K(수기)
TEENCASH
틴캐시(일반)
CARDK-BATCH
신용카드K(월자동)
EGGMONEY
에그머니상품권(일반)
CARD
신용카드(일반)
GAMECARD
게임문화상품권(일반)
CARD-SUGI
신용카드(수기)
TMONEY
티머니(일반)
CARD-BATCH
신용카드(월자동)
KAKAOPAY
카카오페이(일반)
VACCT
가상계좌(일반)

결제요청 파라미터(공통)

구분항목명길이내용비고
필수
KIWOOM_ENC
1024
결제요청HASH값
링크 참고
PAYMETHOD
10
결제수단
상단 표 참고
TYPE
1
결제방식(P:PC/M:모바일/W:웹뷰)
CPID
20
가맹점ID
키움페이에서 부여
ORDERNO
50
주문번호
PRODUCTTYPE
2
상품구분(1: 디지털, 2: 실물)
AMOUNT
10
결제금액
PRODUCTNAME
50
상품명
PRODUCTCODE
10
상품코드
USERID
30
고객 ID
응답
EMAIL
100
고객 이메일
USERNAME
50
고객명
RESERVEDINDEX1
20
예약항목1
월자동 사용불가
RESERVEDINDEX2
20
예약항목2
월자동 사용불가
RESERVEDSTRING
500
예약스트링
RETURNURL
1024
결제 성공 후, 이동할 URL(새 창)
HOMEURL
1024
결제 성공 후, 이동할 URL(결제 창)
DIRECTRESULTFLAG
1024
키움페이 결제 완료 창 없이 HOMEURL로 바로 이동
Y / N
SET_LOGO
1024
결제 창 하단 상점로고(기본값:키움페이로고)

결제응답 통보 항목

결제가 완료되면 아래의 항목들을 상점의 URL로 전송해요.

※ 결제수단 별 추가 파라미터는 메뉴얼을 참고해주세요.

결제요청 파라미터(공통)

구분항목명길이내용비고
공통
PAYMETHOD
10
결제수단
링크 참고
CPID
20
가맹점ID
키움페이에서 부여
DAOUTRX
20
다우거래번호
키움페이에서 부여
ORDERNO
50
주문번호
AMOUNT
10
결제금액
SETTDATE
14
결제일시(YYYYMMDDhh24miss)
EMAIL
100
고객 이메일
USERID
30
고객 ID
USERNAME
50
고객명
PRODUCTCODE
10
상품코드
PRODUCTNAME
50
상품명
RESERVEDINDEX1
20
예약항목1
RESERVEDINDEX2
20
예약항목2
RESERVEDSTRING
500
예약스트링

더 알아보기

통합 API결제 테스트