API Specification

KSPAY결제 연동을 위해 제공되는 API입니다.

문의
- 기술문의: pgmodule@ksnet.co.kr
- 사업문의: ksnet001@ksnet.co.kr

0.1. API 사용 안내

API 사용을 위해서는 KSNET PG사업부에 가맹점 등록 및 인증키 발급이 필요합니다.

https프로토콜만 허용되며, 공식적으로 지원하는 TLS버전은 1.2버전 이상입니다. (TLS1.2/1.3)

요청 파라미터의 Method는 POST, Content-Type은 application/json; charset=utf-8을 사용하셔야 합니다.

KSNET과 카드사 및 일부 은행의 경우 문자 인코딩을 EUC-KR로 사용합니다. 따라서, 파라미터를 UTF-8을 전달하더라도 EUC-KR로 표현 가능한 문자여야 합니다.

API URL 형식은 {API 서버}/kspay/webfep/{API URI} 입니다.

API 서버
- 운영 서버: https://pay.ksnet.co.kr
- 개발 서버: https://paydev.ksnet.co.kr

0.2. API 인증

인증키 설정 예시

curl -v -X POST https://pgdev.ksnet.co.kr/kspay/webfep/api/v1/card/cancel \
  -H 'Content-Type: application/json' \
  -H 'Authorization: pgapi Mjk5OTE5OTk5OTpNQTAxOkE0RTc2QkRBMzM3RENDQTk1Mjk4RkI0OTVBODREMzY5'  \
  -D ...

API 사용을 위해 HTTP Request Header에 인증키 설정이 필요

인증키 획득 절차

Step.1 - KSTA Login
Step.2 - PG Shop info : PG상점정보 > 상점정보 > 상점아이디 입력 > Search > 해당 상점아이디 Click
Step.3 - Check 'pgapi' key info : 하단 pgapi항목에서 키값을 획득하실 수 있습니다.

0.3. API 응답

응답 예시

{
  "aid": "API 요청 고유값",
  "code": "API 응답 코드",
  "message": "API 응답 메시지",
  "data": {
    ...
  }
}

API 표준 응답은 다음과 같습니다.

http status : 200 OK

Content-Type: application/json;charset=utf-8

aid: 매 요청에 대하여 KSNET에서 부여하는 고유한 문자열입니다.
code: 요청에 대한 응답 코드입니다.
- A0200: 처리 성공 (유일한 성공값으로, A0200외 다른 값은 실패를 의미합니다.)
- A0201: 처리 실패 (처리 실패의 경우 반드시 data 항목의 응답코드와 응답메시지를 확인하시기 바랍니다.)
- A0400: 요청 파라미터 오류
- A0401: 인증 오류
- A0403: 프로토콜 오류
- A0500: 서버 오류 (KSNET 기술팀 문의)
- A0999: 기타 오류
message: 코드보다 상세한 내용이 담긴 응답값입니다.
data: API별 세부 응답 값으로, JSON객체로 구성됩니다. 일부 API는 null값을 응답할 수도 있습니다.

1. 카드 API

1.1. 카드결제 취소

카드 결제를 취소할 수 있는 API입니다.

매입 전 취소는 승인 취소로 처리되어 바로 환불이 이루어지지만, 매입된 거래건 또는 부분취소 거래건에 대해서는 +1~3영업일이 소요될 수 있습니다.

부분취소는 최대 9회까지 가능한 점을 참고해 주시기 바라며, 취소는 결제일 기준 6개월까지만 가능합니다.

HTTP Request

POST /kspay/webfep/api/v1/card/cancel

요청 파라미터

신용카드 결제 취소 요청 예시

{
    "mid": "2999199999",
    "payload": "KST20240604S031",
    "cancelType": "FULL",
    "orgTradeKeyType": "TID",
    "orgTradeKey": "189189008016",
    "orgTradeDate": "",
    "cancelTotalAmount": "",
    "cancelTaxAmount":"",
    "cancelTaxFreeAmount": "",
    "cancelSeq": ""
}

Name	Size	Description
mid^*필수	10	상점아이디 `계약 완료 후 사업부를 통해 전달받은 상점아이디`
payload	2048	가맹점데이터 `API 응답에 돌려받을 가맹점의 데이터`
cancelType^*필수	10	취소 처리구분 -`FULL: 전체취소` -`PARTIAL: 부분취소`
orgTradeKeyType^*필수	20	거래키 구분 -`TID: 거래번호취소` -`ORDER_NUMB: 주문번호취소`
orgTradeKey^*필수	50	원거래 키 `원거래 구분에 해당하는 TID 혹은 ORDER_NUMB 값`
orgTradeDate	8	원거래일자 `주문번호 취소 시 설정 필요(yyyyMMdd)`
cancelTotalAmount	9	취소 총금액 `부분취소 시에만 사용하는 필수값`
cancelTaxAmount	9	취소 과세금액 `부분취소 시 취소 총금액 중 과세금액이 있을 경우 설정 복합과세 상점의 경우에만 가능, 사업부 문의 필요`
cancelTaxFreeAmount	9	취소 면세금액 `부분취소 시 취소 총금액 중 면세금액이 있을 경우 설정`
cancelSeq	1	취소 일련번호 `부분취소 시에만 사용하는 필수값이며,` `해당 회차 부분취소 일련번호로 사용(1~9)`

응답 파라미터

신용카드 결제 취소 응답 예시

# 성공응답
{
  "aid":"WFVCCSE00000000000054321",
  "code":"A0200",
  "message":"Success",
  "data": {
    "payload": "KST20240604S031",
    "tid":"189189008016",
    "tradeDateTime":"20240604120147",
    "cancelAmount":"50004",
    "respCode":"0000",
    "respMessage":"승인취소완료/매입취소요청",
    "issuerCardType":"HYUNDAI",
    "issuerCardName":"현대카드",
    "purchaseCardType":"HYUNDAI",
    "purchaseCardName":"현대카드",
    "approvalNumb":"00876543",
    "cardNumb":"40176201XXXX825X",
    "expiryDate":"",
    "installMonth":"03"
}}

# 실패응답
{
  "aid":"WFVCCSE00000000000054320",
  "code":"A0201",
  "message":"Fail",
  "data": {
    "payload": "KST20240604S027",
    "tid":"Lbd124090990",
    "tradeDateTime":"20240604102151",
    "cancelAmount":"",
    "respCode":"7003",
    "respMessage":"취소거절기간경과/Tel:1544-6030",
    "issuerCardType":"UNDEFINED",
    "issuerCardName":"미등록카드사",
    "purchaseCardType":"UNDEFINED",
    "purchaseCardName":"미등록카드사",
    "approvalNumb":"7003",
    "cardNumb":"",
    "expiryDate":"",
    "installMonth":""
}}

Name	Size	Description
data.payload	2048	가맹점데이터
data.tid	12	PG거래번호
data.tradeDateTime	14	거래일시(yyyyMMddHHmmss)
data.cancelAmount	9	취소된금액
data.respCode	4	응답코드
data.respMessage	40	응답메시지
data.issuerCardType	20	발급사타입
data.issuerCardName	20	발급사명
data.purchaseCardType	20	매입사타입
data.purchaseCardName	20	매입사명
data.approvalNumb	12	승인번호
data.cardNumb	20	카드번호
data.expiryDate	4	유효기간
data.installMonth	2	할부개월수

1.2. 카드 인증

카드번호/유효기간/생년월일/비밀번호로 카드 소유자 인증을 진행하는 API입니다.

결제가 아닌 단순 인증만 진행하므로 유의하여 사용하시기 바랍니다.

서비스를 위해서는 사업부를 통해 별도의 계약이 필요합니다.

HTTP Request

POST /kspay/webfep/api/v1/card/cert

요청 파라미터

카드 인증 요청 예시

{
    "mid": "2999199999",
    "payload": "KST20240604S011",
    "orderNumb": "M20240604103105",
    "userName": "홍길동",
    "productName": "핑크테디",
    "cardNumb": "4017620101234567",
    "expiryDate": "3012",
    "password2": "99",
    "userInfo": "680102"
}

Name	Size	Description
mid^*필수	10	상점아이디 `계약 완료 후 사업부를 통해 전달받은 상점아이디`
payload	2048	가맹점데이터 `API 응답에 돌려받을 가맹점의 데이터`
orderNumb^*필수	50	가맹점 주문번호
userName^*필수	50	주문자명
productType^*필수	20	상품구분 -`REAL: 실물상품` -`DIGITAL: 디지털컨텐츠`
productName^*필수	50	상품명
totalAmount^*필수	9	총금액
cardNumb^*필수	20	카드번호
expiryDate^*필수	4	유효기간 `연월(yyMM) 형태의 4자리 형식 사용`
installMonth^*필수	2	할부개월수
currencyType^*필수	3	통화타입 -`KRW: 원화` -`USD: 달러(모든 금액을 1달러=1000으로 표기)`
password2^*필수	2	카드비밀번호 앞2자리
userInfo^*필수	20	사용자정보 -`개인명의카드: 카드 소유자 생년월일 6자리(yyMMdd)` -`법인명의 법인카드: 사업자번호 10자리`

응답 파라미터

카드 인증 응답 예시

# 성공응답
{
  "aid":"WFVCCSE00000000000054111",
  "code":"A0200",
  "message":"Success",
  "data": {
    "payload": "KST20240604S011",
    "tid":"189189011016",
    "tradeDateTime":"20240604103147",
    "totalAmount":"50004",
    "respCode":"0000",
    "respMessage":"현대카드/OK: 00000000",
    "issuerCardType":"HYUNDAI",
    "issuerCardName":"현대카드",
    "purchaseCardType":"HYUNDAI",
    "purchaseCardName":"현대카드",
    "cardNumb":"40176201XXXX825X",
    "approvalNumb": "00000000",
    "expiryDate": "",
    "installMonth": "",
    "cardType":"CREDIT"
}}

# 실패응답
{
  "aid":"WFVCCSE00000000000054110",
  "code":"A0201",
  "message":"Fail",
  "data": {
    "payload": "KST20240604S027",
    "tid":"Lbd124090911",
    "tradeDateTime":"20240604103120",
    "totalAmount":"",
    "respCode":"6003",
    "respMessage":"비밀번호오류/비밀번호확인요망",
    "issuerCardType":"HYUNDAI",
    "issuerCardName":"현대카드",
    "purchaseCardType":"HYUNDAI",
    "purchaseCardName":"현대카드",
    "cardNumb":"",
    "approvalNumb": "",
    "expiryDate": "",
    "installMonth": "",
    "cardType":""
}}

Name	Size	Description
data.payload	2048	가맹점데이터
data.tid	12	PG거래번호
data.tradeDateTime	14	거래일시(yyyyMMddHHmmss)
data.totalAmount	9	총금액
data.respCode	4	응답코드
data.respMessage	40	응답메시지
data.issuerCardType	20	발급사타입
data.issuerCardName	20	발급사명
data.purchaseCardType	20	매입사타입
data.purchaseCardName	20	매입사명
data.approvalNumb	12	승인번호
data.cardNumb	20	카드번호
data.expiryDate	4	유효기간
data.installMonth	2	할부개월수
data.cardType	10	카드타입(CREDIT/CHECK/GIFT/PREPAID)

1.3. 카드 비인증 결제

카드번호/유효기간으로 결제를 요청하는 비인증 승인 API입니다.

서비스를 위해서는 사업부를 통해 별도의 계약이 필요합니다.

HTTP Request

POST /kspay/webfep/api/v1/card/pay/noncert

요청 파라미터

카드 비인증 결제 요청 예시

{
    "mid": "2999199999",
    "payload": "KST20240604S021",
    "orderNumb": "M20240604103125",
    "userName": "홍길동",
    "userEmail": "test@test.com",
    "productType": "REAL",
    "productName": "핑크테디",
    "totalAmount": "1004",
    "cardNumb": "4017620101234567",
    "expiryDate": "3012",
    "installMonth": "00",
    "currencyType": "KRW"
}

Name	Size	Description
mid^*필수	10	상점아이디 `계약 완료 후 사업부를 통해 전달받은 상점아이디`
payload	2048	가맹점데이터 `API 응답에 돌려받을 가맹점의 데이터`
orderNumb^*필수	50	가맹점 주문번호
userName^*필수	50	주문자명
userEmail	50	주문자이메일
productType^*필수	10	상품구분 -`REAL: 실물상품` -`DIGITAL: 디지털컨텐츠`
productName^*필수	50	상품명
totalAmount^*필수	9	총금액
interestType^*필수	20	이자구분 -`PG: 카드사에서 제공하는 무이자 설정값(기본값)` -`MALL: 가맹점 별도 계약하여 진행하는 무이자 설정값` `(사업부 문의 필요)`
taxAmount	9	과세금액 `상품에 부과되는 세액(복합과세 상점의 경우에만 가능, 사업부 문의 필요)`
taxFreeAmount	9	면세금액 `면세금액이 없으면 총금액 전체 과세처리`
tax	9	세금 `세금항목이 없으면 일반과세 상점의 경우 10% 부가세 계산` `= (총금액-면세금액) / 11`
cardNumb^*필수	20	카드번호
expiryDate^*필수	4	유효기간 `연월(yyMM) 형태의 4자리 형식 사용`
installMonth^*필수	2	할부개월수
currencyType^*필수	3	통화타입 -`KRW: 원화` -`USD: 달러(모든 금액을 1달러=1000으로 표기)`

응답 파라미터

카드 비인증 결제 응답 예시

# 성공응답
{
  "aid":"WFVCCSE00000000000060121",
  "code":"A0200",
  "message":"Success",
  "data": {
    "payload": "KST20240604S021",
    "tid":"189189011016",
    "tradeDateTime":"20240604103121",
    "totalAmount":"1004",
    "respCode":"0000",
    "respMessage":"현대카드/OK: 00112345",
    "issuerCardType":"HYUNDAI",
    "issuerCardName":"현대카드",
    "purchaseCardType":"HYUNDAI",
    "purchaseCardName":"현대카드",
    "cardNumb":"40176201XXXX825X",
    "approvalNumb": "00112345",
    "expiryDate": "",
    "installMonth": "",
    "cardType":"CREDIT",
    "partCancelYn":"Y"
}}

# 실패응답
{
  "aid":"WFVCCSE00000000000060120",
  "code":"A0201",
  "message":"Fail",
  "data": {
    "payload": "KST20240604S020",
    "tid":"Lbd124090920",
    "tradeDateTime":"20240604103120",
    "totalAmount":"",
    "respCode":"8326",
    "respMessage":"승인거절/월사용한도초과",
    "issuerCardType":"HYUNDAI",
    "issuerCardName":"현대카드",
    "purchaseCardType":"HYUNDAI",
    "purchaseCardName":"현대카드",
    "cardNumb":"",
    "approvalNumb": "",
    "expiryDate": "",
    "installMonth": "",
    "cardType":"",
    "partCancelYn":""
}}

Name	Size	Description
data.payload	2048	가맹점데이터
data.tid	12	PG거래번호
data.tradeDateTime	14	거래일시(yyyyMMddHHmmss)
data.totalAmount	9	총금액
data.respCode	4	응답코드
data.respMessage	40	응답메시지
data.issuerCardType	20	발급사타입
data.issuerCardName	20	발급사명
data.purchaseCardType	20	매입사타입
data.purchaseCardName	20	매입사명
data.approvalNumb	12	승인번호
data.cardNumb	20	카드번호
data.expiryDate	4	유효기간
data.installMonth	2	할부개월수
data.cardType	10	카드타입(CREDIT/CHECK/GIFT/PREPAID)
data.partCancelYn	1	부분취소가능여부

1.4. 카드 구인증 결제

카드번호/유효기간/생년월일/비밀번호(앞2자리)로 결제를 요청하는 일반 인증 승인 API입니다.

서비스를 위해서는 사업부를 통해 별도의 계약이 필요합니다.

HTTP Request

POST /kspay/webfep/api/v1/card/pay/oldcert

요청 파라미터

카드 구인증 결제 요청 예시

{
    "mid": "2999199999",
    "payload": "KST20240604S022",
    "orderNumb": "M20240604103126",
    "userName": "홍길동",
    "userEmail": "test@test.com",
    "productType": "REAL",
    "productName": "핑크테디",
    "totalAmount": "1004",
    "cardNumb": "4017620101234567",
    "expiryDate": "3012",
    "installMonth": "00",
    "currencyType": "KRW",
    "password2": "99",
    "userInfo": "680102"
}

Name	Size	Description
mid^*필수	10	상점아이디 `계약 완료 후 사업부를 통해 전달받은 상점아이디`
payload	2048	가맹점데이터 `API 응답에 돌려받을 가맹점의 데이터입니다.`
orderNumb^*필수	50	가맹점 주문번호
userName^*필수	50	주문자명
userEmail	50	주문자이메일
productType^*필수	10	상품구분 -`REAL: 실물상품` -`DIGITAL: 디지털컨텐츠`
productName^*필수	50	상품명
totalAmount^*필수	9	총금액
taxAmount	9	과세금액 `상품에 부과되는 세액(복합과세 상점의 경우에만 가능, 사업부 문의 필요)`
taxFreeAmount	9	면세금액 `면세금액이 없으면 총금액 전체 과세처리`
tax	9	세금 `세금항목이 없으면 일반과세 상점의 경우 10% 부가세 계산` `= (총금액-면세금액) / 11`
cardNumb^*필수	20	카드번호
expiryDate^*필수	4	유효기간 `연월(yyMM) 형태의 4자리 형식 사용`
installMonth^*필수	2	할부개월수
currencyType^*필수	3	통화타입 -`KRW: 원화` -`USD: 달러(모든 금액을 1달러=1000으로 표기)`
password2^*필수	2	카드비밀번호 앞2자리
userInfo^*필수	10	사용자정보 -`개인명의카드: 카드 소유자 생년월일 6자리(yyMMdd)` -`법인명의 법인카드: 사업자번호 10자리`

응답 파라미터

카드 구인증 결제 응답 예시

# 성공응답
{
  "aid":"WFVCCSE00000000000060122",
  "code":"A0200",
  "message":"Success",
  "data": {
    "payload": "KST20240604S022",
    "tid":"189189011016",
    "tradeDateTime":"20240604103122",
    "totalAmount":"1004",
    "respCode":"0000",
    "respMessage":"현대카드/OK: 00212345",
    "issuerCardType":"HYUNDAI",
    "issuerCardName":"현대카드",
    "purchaseCardType":"HYUNDAI",
    "purchaseCardName":"현대카드",
    "cardNumb":"40176201XXXX825X",
    "approvalNumb": "00212345",
    "expiryDate": "",
    "installMonth": "",
    "cardType":"CREDIT",
    "partCancelYn":"Y"
}}

# 실패응답
{
  "aid":"WFVCCSE00000000000060123",
  "code":"A0201",
  "message":"Fail",
  "data": {
    "payload": "KST20240604S023",
    "tid":"Lbd124090923",
    "tradeDateTime":"20240604103123",
    "totalAmount":"",
    "respCode":"8326",
    "respMessage":"승인거절/월사용한도초과",
    "issuerCardType":"HYUNDAI",
    "issuerCardName":"현대카드",
    "purchaseCardType":"HYUNDAI",
    "purchaseCardName":"현대카드",
    "cardNumb":"",
    "approvalNumb": "",
    "expiryDate": "",
    "installMonth": "",
    "cardType":"",
    "partCancelYn":""
}}

Name	Size	Description
data.payload	2048	가맹점데이터
data.tid	12	PG거래번호
data.tradeDateTime	14	거래일시(yyyyMMddHHmmss)
data.totalAmount	9	총금액
data.respCode	4	응답코드
data.respMessage	40	응답메시지
data.issuerCardType	20	발급사타입
data.issuerCardName	20	발급사명
data.purchaseCardType	20	매입사타입
data.purchaseCardName	20	매입사명
data.approvalNumb	12	승인번호
data.cardNumb	20	카드번호
data.expiryDate	4	유효기간
data.installMonth	2	할부개월수
data.cardType	10	카드타입(CREDIT/CHECK/GIFT/PREPAID)
data.partCancelYn	1	부분취소가능여부

1.5. (hidden) 카드 빈 체크

신용카드는 일정한 규칙에 따라 신용카드번호가 부여되어 발급이 됩니다. 결제자가 소지하고 있는 카드가 실제 존재하는 카드번호가 맞는지 등을 확인하려고 할 때 Bin Check를 사용합니다.

카드 Bin Check는 실제 승인은 되지 않으며, 카드번호에 대해 확인하는 인증의 한 종류입니다.

HTTP Request

POST /kspay/webfep/api/v1/card/bincheck

요청 파라미터

신용카드 빈 체크 요청 예시

{
    "mid": "2999199999",
    "payload": "KST20240604S031",
    "cardNumb": "1111222233334444"
}

Name	Size	Description
mid^*필수	10	상점아이디 `계약 완료 후 사업부를 통해 전달받은 상점아이디`
payload	2048	가맹점데이터 `API 응답에 돌려받을 가맹점의 데이터`
cardNumb^*필수	16	카드번호

응답 파라미터

신용카드 빈 체크 응답 예시

# 성공응답
{
"aid":"WFVCBSN00000000002920623",
"code":"A0200",
"message":"Success",
"data": {
    "payload":"abce 350",
    "tid":"",
    "tradeDateTime":"20250213130252",
    "respCode":"0000",
    "respMessage":"해외카드 조회 OK",
    "issuerCardType":"ABROAD",
    "issuerCardName":"해외카드",
    "cardBin":"537722",
    "cardNation":"A",
    "cardBrand":"MASTER",
    "issuerCode":"25",
    "cardName":"해외 MASTER",
    "cardOwnerType":"1",
    "cardType":"0"
}}

Name	Size	Description
data.payload	2048	가맹점데이터
data.tid	12	PG거래번호
data.tradeDateTime	14	거래일시(yyyyMMddHHmmss)
data.respCode	4	응답코드
data.respMessage	40	응답메시지
data.issuerCardType	20	발급사타입
data.issuerCardName	20	발급사명
data.cardBin	8	카드빈(6~8자리)
data.cardNation	1	국가(L:국내카드, A:해외카드, X:신용카드 아님)
data.cardBrand	*	브랜드명
data.issuerCode	2	카드코드(00: 신용카드 아님, 26: 해외, xx:국내)
data.cardName	*	카드이름
data.cardOwnerType	1	일반/법인구분(1: 일반, 2: 법인, 9: 구분 안됨)
data.cardType	2	카드타입(00: 신용, 03: 체크, 04: 선불, 13: 기프트)

2. 계좌이체 API

2.1. 계좌이체 취소

계좌이체 결제를 취소할 수 있는 API입니다.

결제 당일 취소는 즉시 처리되지만 결제 당일이 아닌 경우 계좌이체 기관에 따라 +1~3영업일이 소요될 수 있습니다.

취소가능 기간은 결제기관별로 상이하며, 3~6개월까지 가능합니다.

HTTP Request

POST /kspay/webfep/api/v1/account/cancel

요청 파라미터

실시간 계좌이체 취소 요청 예시

{
    "mid": "2999199990",
    "payload": "KST20240604S221",
    "cancelType": "FULL",
    "orgTradeKeyType": "TID",
    "orgTradeKey": "289189002031",
    "orgTradeDate": "",
    "cancelTotalAmount": "",
    "cancelSeq": ""
}

Name	Size	Description
mid^*필수	10	상점아이디 `계약 완료 후 사업부를 통해 전달받은 상점아이디`
payload	2048	가맹점데이터 `API 응답에 돌려받을 가맹점의 데이터`
cancelType^*필수	10	취소처리구분 -`FULL: 전체취소` -`PARTIAL: 부분취소`
orgTradeKeyType^*필수	10	거래키구분 -`TID: 거래번호취소` -`ORDER_NUMB: 주문번호취소`
orgTradeKey^*필수	50	원거래 키 `원거래 구분에 해당하는 TID 혹은 ORDER_NUMB 값`
orgTradeDate	8	원거래일자 `주문번호 취소 시 설정 필요(yyyyMMdd)`
cancelTotalAmount	9	취소 총금액 `부분취소 시에만 사용하는 필수값`
cancelSeq	1	취소일련번호 `부분취소 시에만 사용하는 필수값이며,` `해당 회차 부분취소 일련번호로 사용(1~9)`

응답 파라미터

실시간 계좌이체 취소 응답 예시

# 성공응답
{
  "aid":"WFVCCSE00000000000054221",
  "code":"A0200",
  "message":"Success",
  "data": {
    "payload": "KST20240604S221",
    "tid":"289189002031",
    "tradeDateTime":"20240604120227",
    "cancelAmount":"1004",
    "respCode":"000",
    "respMessage":"농협은행/OK:이체취소",
    "agencyType":"5",
    "agencyName":"금융결제원",
    "approvalNumb":"011"
    }
}

# 실패응답
{
  "aid":"WFVCCSE00000000000054220",
  "code":"A0201",
  "message":"Fail",
  "data": {
    "payload": "KST20240604S220",
    "tid":"Lbd124092990",
    "tradeDateTime":"20240604120220",
    "cancelAmount":"",
    "respCode":"994",
    "respMessage":"취소거절/취소원거래없음",
    "agencyType":"5",
    "agencyName":"금융결제원",
    "approvalNumb":""
    }
}

Name	Size	Description
data.payload	2048	가맹점데이터
data.tid	12	PG거래번호
data.tradeDateTime	14	거래일시(yyyyMMddHHmmss)
data.cancelAmount	9	취소된금액
data.respCode	4	응답코드
data.respMessage	40	응답메시지
data.agencyType	1	대행사구분
data.agencyName	20	대행사명
data.approvalNumb	12	승인번호

2.2. (hidden) 마이통장 취소

마이통장 결제를 취소할 수 있는 API입니다.

HTTP Request

POST /kspay/webfep/api/v1/mymoney/cancel

요청 파라미터

마이통장 취소 요청 예시

{
    "mid": "2999199990",
    "payload": "",
    "cancelType": "FULL",
    "orgTradeKeyType": "TID",
    "orgTradeKey": "B88409000000",
    "orgTradeDate": "",
    "cancelTotalAmount": "",
    "cancelSeq": ""
}

Name	Size	Description
mid^*필수	10	상점아이디 `계약 완료 후 사업부를 통해 전달받은 상점아이디`
payload	2048	가맹점데이터 `API 응답에 돌려받을 가맹점의 데이터`
cancelType^*필수	10	취소처리구분 -`FULL: 전체취소` -`PARTIAL: 부분취소`
orgTradeKeyType^*필수	10	거래키구분 -`TID: 거래번호취소` -`ORDER_NUMB: 주문번호취소`
orgTradeKey^*필수	50	원거래 키 `원거래 구분에 해당하는 TID 혹은 ORDER_NUMB 값`
orgTradeDate	8	원거래일자 `주문번호 취소 시 설정 필요(yyyyMMdd)`
cancelTotalAmount	9	취소 총금액 `부분취소 시에만 사용하는 필수값`
cancelSeq	1	취소일련번호 `부분취소 시에만 사용하는 필수값이며,` `해당 회차 부분취소 일련번호로 사용(1~9)`

응답 파라미터

마이통장 취소 응답 예시

# 성공응답
{
  "aid":"WFVCCSE00000000000054221",
  "code":"A0200",
  "message":"Success",
  "data": {
    "payload": "KST20240604S221",
    "tid":"B8840900000",
    "tradeDateTime":"20240604120227",
    "cancelAmount":"1004",
    "respCode":"000",
    "respMessage":"농협은행/OK:이체취소",
    "agencyType":"5",
    "agencyName":"금융결제원",
    "approvalNumb":"011"
    }
}

# 실패응답
{
  "aid":"WFVCCSE00000000000054220",
  "code":"A0201",
  "message":"Fail",
  "data": {
    "payload": "KST20240604S220",
    "tid":"Lbd124092990",
    "tradeDateTime":"20240604120220",
    "cancelAmount":"",
    "respCode":"994",
    "respMessage":"취소거절/취소원거래없음",
    "agencyType":"5",
    "agencyName":"금융결제원",
    "approvalNumb":""
    }
}

Name	Size	Description
data.payload	2048	가맹점데이터
data.tid	12	PG거래번호
data.tradeDateTime	14	거래일시(yyyyMMddHHmmss)
data.cancelAmount	9	취소된금액
data.respCode	4	응답코드
data.respMessage	40	응답메시지
data.agencyType	1	대행사구분
data.agencyName	20	대행사명
data.approvalNumb	12	승인번호

3. 가상계좌 API

3.1. 일회성 가상계좌 발급

일회성 가상계좌를 발급합니다.

PG사업부를 통해 발급되는 가상계좌에 적용될 부가기능을 설정하실 수 있습니다.

※ 부가기능
1. 입금마감기한 설정
2. 중복 주문번호로 생성 거절
3. 입금금액 일치 확인
4. 입금자명 확인
5. 입금계좌 재입금 금지

HTTP Request

POST /kspay/webfep/api/v1/vaccount/issue/onetime

요청 파라미터

일회성 가상계좌 발급 요청 예시

{
    "mid": "2999199999",
    "orderNumb": "KST20240619S130",
    "userName": "홍길동",
    "userEmail": "honggildong@naver.com",
    "productType": "",
    "productName": "required",
    "totalAmount": "999999999",
    "payload": "1a2b3c",
    "bankType": "IBK",
    "closeDateTime": ""
}

Name	Size	Description
mid^*필수	10	상점아이디 `계약 완료 후 사업부를 통해 전달받은 상점아이디`
payload	2048	가맹점데이터 `API 응답에 돌려받을 가맹점의 데이터`
orderNumb^*필수	50	가맹점 주문번호
userName^*필수	50	주문자명
userEmail	50	주문자이메일
productType^*필수	20	상품구분 -`REAL: 실물상품` -`DIGITAL: 디지털컨텐츠`
productName^*필수	50	상품명
totalAmount^*필수	9	총금액 -`최소 결제 금액은 100원`
bankType^*필수	20	은행 타입
closeDateTime	14	마감 일시 `입금 마감 기한을 일시 포맷(yyyyMMddHHmmss)으로 세팅` `(계약 가맹점만 사용 가능)`

응답 파라미터

일회성 가상계좌 발급 응답 예시

# 성공응답
{
    "aid": "WF2VIOD00000000000002067",
    "code": "A0200",
    "message": "Success",
    "data": {
        "payload": "1a2b3c",
        "tid": "689390031732",
        "tradeDateTime": "20240619155551",
        "totalAmount": "999999999",
        "respCode": "0000",
        "respMessage": "계좌요청완료",
        "bankType": "IBK",
        "bankName": "기업은행",
        "virtualAccountNumb": "48100047997525",
        "accountHolder": "테스트그룹10(주)"
    }}

# 실패응답
{
    "aid": "WF1VIOD00000000000002468",
    "code": "A0400",
    "message": "Invalid request data format totalAmount",
    "data": {
        "payload": "1a2b3c",
        "tid": "",
        "tradeDateTime": "",
        "totalAmount": "",
        "respCode": "",
        "respMessage": "",
        "bankType": "",
        "bankName": "",
        "virtualAccountNumb": "",
        "accountHolder": ""
    }}

Name	Size	Description
data.payload	2048	가맹점데이터
data.tid	12	PG거래번호
data.tradeDateTime	14	거래일시(yyyyMMddHHmmss)
data.totalAmount	9	총금액
data.respCode	4	응답코드
data.respMessage	40	응답메시지
data.bankType	20	은행 타입
data.bankName	20	은행 이름
data.virtualAccountNumb	15	가상계좌번호
data.accountHolder	30	예금주

3.2. 가상계좌 회수

기발급된 미입금 가상계좌를 회수합니다.

회수는 발급일 기준 6개월까지만 가능합니다.

※ 참고
가상계좌 회수는 환불이 아닙니다. 가상계좌 거래는 은행을 통해 진행하므로 환불이 제공되지 않음을 참고해주시기 바랍니다.

HTTP Request

POST /kspay/webfep/api/v1/vaccount/recall

요청 파라미터

가상계좌 회수 요청 예시

{
    "mid": "2999199999",
    "payload": "1a2b3c",
    "orgTradeKeyType": "TID",
    "orgTradeKey": "689390032375",
    "orgTradeDate": ""
}

Name	Size	Description
mid^*필수	10	상점아이디 `계약 완료 후 사업부를 통해 전달받은 상점아이디`
payload	2048	가맹점데이터 `API 응답에 돌려받을 가맹점의 데이터`
orgTradeKeyType*	10	거래키구분 -`TID: 거래번호취소` -`ORDER_NUMB: 주문번호취소`
orgTradeKey^*필수	50	원거래 키 `원거래 구분에 해당하는 TID 혹은 ORDER_NUMB 값`
orgTradeDate	8	원거래일자 `주문번호 취소시 설정필요(yyyyMMdd)`

응답 파라미터

가상계좌 회수 응답 예시

# 성공응답
{
    "aid": "WF2VRSE00000000000005457",
    "code": "A0200",
    "message": "Success",
    "data": {
        "payload": "1a2b3c",
        "tid": "689390032375",
        "tradeDateTime": "20240620100323",
        "cancelAmount": "999999999",
        "respCode": "0000",
        "respMessage": "계좌취소완료",
        "bankType": "IBK",
        "bankName": "기업은행",
        "virtualAccountNumb": "48100047997589"
}}

# 실패응답
{
    "aid": "WF1VRSE00000000000000639",
    "code": "A0201",
    "message": "Failed",
    "data": {
        "payload": "1a2b3c",
        "tid": "689390032376",
        "tradeDateTime": "20240620100345",
        "cancelAmount": "",
        "respCode": "P10O",
        "respMessage": "원거래검색실패/거래확인요망",
        "bankType": "UNDEFINED",
        "bankName": "미등록은행",
        "virtualAccountNumb": ""
}}

Name	Size	Description
data.tid	12	PG거래번호
data.tradeDateTime	14	거래일시(yyyyMMddHHmmss)
data.cancelAmount	9	취소금액
data.respCode	4	응답코드
data.respMessage	40	응답메시지
data.payload	2048	가맹점데이터
data.bankType	20	은행 타입
data.bankName	20	은행 이름
data.virtualAccountNumb	15	가상계좌번호

3.3. (hidden) 영구 가상계좌 발급

영구성 가상계좌 발급 요청에 대한 API입니다.

HTTP Request

POST /kspay/webfep/api/v1/vaccount/permanent

요청 파라미터

영구성 가상계좌 발급 요청 예시

{
    "mid": "2999199994",
    "orderNumb": "carrot12212",
    "orderName": "김토끼",
    "goodName": "당근12kg",
    "totalAmount": "1004",
    "payload": "",
    "bankType": "11",
    "virtAccountType": "2",
    "escrowType": "",
    "closeDateTime": "20240624100000",
    "virtAccountNumb": "10185164017326"
}

Name	Size	Description
mid^*필수	10	상점아이디 `계약 완료 후 사업부를 통해 전달받은 상점아이디`
payload	2048	가맹점데이터 `API 응답에 돌려받을 가맹점의 데이터`
orderNumb^*필수	50	가맹점 주문번호
userName^*필수	50	주문자명
productName^*필수	50	상품명
totalAmount^*필수	9	결제금액
bankType^*필수	20	은행타입 `은행타입표를 참고하여 가상계좌 발급을 원하는 은행 타입을 세팅`
virtAccountType^*필수	1	가상계좌 구분자 -`0: 일반 가상계좌` -`2: 영구성 가상계좌`
escrowType	1	에스크로 구분자 -`0: 적용 안함` -`1: 에스크로 적용`
closeDateTime	14	마감일시 `가상계좌 마감일시 세팅 옵션 설정시 필수값(YYYYMMDDHHMISS)`
virtAccountNumb^*필수	15	가상계좌번호 `영구성 가상계좌 발급 시 필수` `사업부를 통해 발급받은 가상계좌로만 사용이 가능하며,` `발급이 필요할 시 사업부 연락`

응답 파라미터

영구성 가상계좌 발급 응답 예시

# 성공응답
{
    "aid": "WFVVPSI00000000003100223",
    "code": "A0200",
    "message": "Success",
    "data": {
        "payload": "",
        "tid": "689449000007",
        "tradeDateTime": "20240624094405",
        "totalAmount": "1004",
        "respCode": "0000",
        "respMessage": "계좌요청완료",
        "bankType": "NONGHYUP",
        "bankName": "농협중앙",
        "virtualAccountNumb": "10185164017326",
        "accountHolder": "(T)우체국쇼핑"
    }
}


# 실패응답
{
    "aid": "WFVVPSI00000000003100222",
    "code": "A0201",
    "message": "Fail",
    "data": {
        "payload": "",
        "tid": "689449000006",
        "tradeDateTime": "20240624094116",
        "totalAmount": "1004",
        "respCode": "B013",
        "respMessage": "발급거절/마감일자정보없음",
        "bankType": "NONGHYUP",
        "bankName": "농협중앙",
        "virtualAccountNumb": "",
        "accountHolder": ""
    }
}

Name	Size	Description
data.payload	2048	가맹점데이터
data.tid	12	PG거래번호
data.tradeDateTime	14	거래일시(yyyyMMddHHmmss)
data.totalAmount	9	취소된금액
data.respCode	4	응답코드
data.respMessage	40	응답메시지
data.bankType	20	은행타입
data.bankName	20	은행명
data.virtualAccountNumb	15	가상계좌번호
data.accountHolder	30	예금주명

가상계좌 은행 타입

은행명	타입	코드
기업은행	IBK	03
국민은행	KB	04
하나은행	HANA	05
농협중앙	NONGHYUP	11
우리은행	WOORI	20
SC제일은행	SC	23
신한은행	SHINHAN	26
대구은행	DGB	31
부산은행	BNK	32
광주은행	KJ	34
전북은행	JB	37
경남은행	KN	39
우체국	EPOST	71

3.4. (hidden) 환불계좌 등록

발급한 가상계좌에 입금 완료된 상태에서 환불 받을 계좌번호를 확인하고 케이에스넷에 등록합니다.

HTTP Request

POST /kspay/webfep/api/v1/vaccount/regist

요청 파라미터

환불계좌 등록 요청 예시

{
  "accountNumb":"11602918218538"
  ,"bankCode":"20"
  ,"mid":"2999199999"
  ,"orgTradeKey":"689409000009"
  ,"payload":""
}

Name	Size	Description
mid^*필수	10	상점아이디 `계약 완료 후 사업부를 통해 전달받은 상점아이디`
payload	2048	가맹점데이터 `API 응답에 돌려받을 가맹점의 데이터`
orgTradeKey^*필수	50	원거래 키 `원거래 구분에 해당하는 TID`
bankCode^*필수	20	은행코드
accountNumb^*필수	20	계좌번호 `환불 입금 받을 계좌번호`

응답 파라미터

환불계좌 등록 응답 예시

# 성공응답
{
  "aid":"WFVVRSE00000000003119107",
  "code":"A0200",
  "message":"Success",
  "data": {
    "payload":"",
    "tid":"A89409000001",
    "tradeDateTime":"20240620095421",
    "respCode":"0000",
    "respMessage":"계좌조회성공( 1)/인증성공",
    "name":"홍길동"
  }
}

# 실패응답
{
  "aid":"WF1VRSE00000000000000695",
  "code":"A0201",
  "message":"Fail",
  "data": {
    "payload":"",
    "tid":"A89400000221",
    "tradeDateTime":"20240620102256",
    "respCode":"",
    "respMessage":"계좌조회실패( 3)/통신중장애발생",
    "name":""
  }
}

Name	Size	Description
data.payload	2048	가맹점데이터
data.tid	12	PG거래번호
data.tradeDateTime	14	거래일시(yyyyMMddHHmmss)
data.respCode	4	응답코드
data.respMessage	40	응답메시지
data.name	22	예금주

환불계좌등록 오류 응답코드

Error Code	Meaning
0000	정상조회
0001	전문형식불일치
0007	출금or입금은행코드 오류
0009	결제원 타임아웃
0111	날짜오류
0115	CMS계좌 처리불가
0116	주민번호 또는 사업자번호 상이
0122	조회대상계좌오류
0123	거래금액오류(예금계좌 외 계좌일경우 - 적금계좌등..)
0124	해당은행오류응답(타행환거래불가,CMS계좌,등...)
0126	조회대상계좌오류
0131	미등록된업체모계좌
0132	업체모계좌오류
0145	조회대상은행장애
0146	금결원장애
0199	기타오류(새마을금고확인요)

3.5. (hidden) 가상계좌 환불

입금 된 상태의 가상계좌를 환불합니다.

환불 전 가상계좌 환불등록은 필수입니다.

HTTP Request

POST /kspay/webfep/api/v1/vaccount/refund

요청 파라미터

가상계좌 환불 요청 예시

{
  "cancelSeq":""
  ,"cancelTotalAmount":"1004"
  ,"cancelType":"FULL"
  ,"mid":"2999199999"
  ,"orgTradeKey":"689409000009"
  ,"payload":""
}

Name	Size	Description
mid^*필수	10	상점아이디 `계약 완료 후 사업부를 통해 전달받은 상점아이디`
payload	2048	가맹점데이터 `API 응답에 돌려받을 가맹점의 데이터`
cancelType^*필수	10	취소 처리구분 -`FULL: 전체취소` -`PARTIAL: 부분취소`
orgTradeKey^*필수	50	원거래 키 `원거래 구분에 해당하는 TID 혹은 ORDER_NUMB 값`
cancelTotalAmount	9	취소 총금액 `부분취소 시에만 사용하는 필수값`
cancelSeq	1	취소 일련번호 `부분취소 시에만 사용하는 필수값이며,` `해당 회차 부분취소 일련번호로 사용(1~9)`

응답 파라미터

가상계좌 환불 응답 예시

# 성공응답
{
  "aid":"WFVVRSE00000000003119108",
  "code":"A0200",
  "message":"Success",
  "data": {
  "payload":"",
  "tid":"689409000009",
  "status":"O",
  "tradeDateTime":"20240620095620",
  "respCode":"0000",
  "cancelAmount":"1004",
  "respMessage":"우리은행/OK:환불성공"
  }
}

# 실패응답
{
  "aid":"WFVVRSE00000000003119115",
  "code":"A0201",
  "message":"Fail",
  "data": {
    "payload":"",
    "tid":"689409000013",
    "status":"X",
    "tradeDateTime":"20240620102129",
    "respCode":"P10O",
    "cancelAmount":"",
    "respMessage":"원거래검색실패/거래확인요망"
  }
}

Name	Size	Description
data.payload	2048	가맹점데이터
data.tid	12	PG거래번호
data.status	1	성공여부
data.tradeDateTime	14	거래일시(yyyyMMddHHmmss)
data.respCode	4	응답코드
data.cancelAmount	9	환불금액
data.respMessage	40	응답메시지

가상계좌 환불 에러 응답코드

Error Code	Meaning
0000	환불성공(기환불거래)
P1D1	계좌인증오류 거래확인요망
P12G	부분취소금액오류 취소금액확인요망
P113	부분취소SEQ오류
P10O	거래데이타없음
P10G	취소불가거래
P10A	취소구분오류
P002	미등록상점
AT01	환불등록완료
A013	취소거절 환불계좌미등록
A012	취소거절 이체잔액부족
A006	이체불가시간 10분후 재시도

3.6. (hidden) 가상계좌 상점 정보 변경

발급한 가상계좌에 대해 상점정보(상점아이디, 예금주명) 변경을 원할 시에 사용되는 API입니다.

HTTP Request

POST /kspay/webfep/api/v1/vaccount/revise

요청 파라미터

가상계좌 상점 정보 변경 요청 예시

{
    "accoNumb":"1002452412345",
    "bankType":"WOORI",
    "mid":"2999199999",
    "payload":"test932io3h2323t",
    "userName":"고길동"
}

Name	Size	Description
mid^*필수	10	상점아이디 `계약 완료 후 사업부를 통해 전달받은 상점아이디`
payload	2048	가맹점데이터 `API 응답에 돌려받을 가맹점의 데이터`
userName	50	예금주명 `변경할 예금주명` `해당 값이 없으면 null값으로 초기화되오니 주의`
bankType^*필수	20	은행타입 `기관코드 탭의 은행 별 타입표를 참고하셔서 가상계좌의 기관 타입을 세팅`
accountNumb^*필수	15	계좌번호 `정보를 변경할 가상 계좌번호`

응답 파라미터

가상계좌 상점 정보 변경 응답 예시

# 성공응답
{
    "aid": "WF2CISC00000000000009863",
    "code": "A0200",
    "message": "Success",
    "data": {
        "payload":"test932io3h2323t",
        "tid":"681546522001",
        "tradeDateTime":"20240704161728",
        "respCode":"0000",
        "respMessage":"성공",
        "virtualAccountNumb":"1002457456888",
        "accountHolder":"고길동"
    }
}

# 실패응답
{
    "aid":"WFVVRSE00000000003297857",
    "code":"A0201",
    "message":"Fail",
    "data": {
        "payload":"test932io3h2323t",
        "tid":"VYm573081729",
        "tradeDateTime":"20240704161728",
        "respCode":"",
        "respMessage":"잠시후 재시도/Tel:1544-6030",
        "virtualAccountNumb":"",
        "accountHolder":""
    }
}

Name	Size	Description
data.tid	12	PG거래번호
data.tradeDateTime	14	거래일시(yyyyMMddHHmmss)
data.payload	2048	가맹점데이터
data.respCode	4	응답코드
data.respMessage	40	응답메시지
data.virtualAccountNumb	15	가상계좌 번호
data.accountHolder	50	예금주명

4. 현금영수증 API

4.1. 현금영수증 발급

현금영수증을 발급하실 수 있습니다.

현금영수증 자진발급의 경우 '"userInfoType"="PHONE_NUMB", "userInfo"="0100001234"’를 전달해 주시면 가능합니다.

HTTP Request

POST /kspay/webfep/api/v1/cashbill/issue

요청 파라미터

현금영수증 발급 요청 예시

{
    "mid": "2999199999",
    "orderNumb": "carrot_1234",
    "userName": "kspay",
    "userEmail": "",
    "productType": "REAL",
    "productName": "당근10kg",
    "totalAmount": "1004",
    "taxAmount": "0",
    "payload": "",
    "userInfoType": "PHONE_NUMB",
    "userInfo": "0100001234",
    "issueUsageType": "DEDUCTION"
}

Name	Size	Description
mid^*필수	10	상점아이디 `계약 완료 후 사업부를 통해 전달받은 상점아이디`
payload	2048	가맹점데이터 `API 응답에 돌려받을 가맹점의 데이터`
orderNumb^*필수	50	가맹점 주문번호 `가맹점 주문번호는 일별 유니크한 주문번호 생성을 권장`
userName^*필수	50	주문자명
userEmail	50	주문자이메일
productType^*필수	*	상품구분 `판매 상품에 대한 구분값으로 아래 타입 중 하나를 사용` -`REAL : 실물상품` -`DIGITAL : 디지털컨텐츠`
productName^*필수	50	상품명
totalAmount^*필수	9	총금액 `최소 결제 금액은 100원`
taxAmount^*필수	9	과세금액 `상품에 부과되는 세액`
userInfoType^*필수	20	사용자 정보 구분 `현금영수증 발급 사용자 구분값으로 아래 타입 중 하나를 사용` -`PHONE_NUMB : 휴대폰번호` -`BIZ_NUMB : 사업자번호`
userInfo^*필수	20	사용자 정보 `사용자 정보 구분에 맞는 휴대폰번호 혹은 사업자번호 값`
issueUsageType^*필수	20	발급 용도 구분 `현금영수증 발급 용도 구분값으로 아래 타입 중 하나를 사용` -`DEDUCTION : 소득공제` -`EXPENDITURE : 지출증빙`

응답 파라미터

현금영수증 발급 응답 예시

# 성공응답
{
    "aid": "WF2CISC00000000000009863",
    "code": "A0200",
    "message": "Success",
    "data": {
        "payload": "",
        "tid": "H89380014172",
        "tradeDateTime": "20240618134644",
        "totalAmount": "1004",
        "respCode": "0000",
        "respMessage": "현금승인정상/OK: 551031651",
        "cashbillNumb": "551031651",
        "cashbillMessage": "상담센터:국번없이126/www.hometax.go.kr"
    }
}

# 실패응답
{
    "aid": "WF2CISC00000000000009950",
    "code": "A0201",
    "message": "Fail",
    "data": {
        "payload": "",
        "tid": "H89380014336",
        "tradeDateTime": "20240618140603",
        "totalAmount": "1004",
        "respCode": "5510",
        "respMessage": "기발급완료/재발급불가",
        "cashbillNumb": "551034870",
        "cashbillMessage": ""
    }
}

Name	Size	Description
data.payload	2048	가맹점데이터
data.tid	12	PG거래번호
data.tradeDateTime	14	거래일시(yyyyMMddHHmmss)
data.totalAmount	9	총금액
data.respCode	4	응답코드
data.respMessage	40	응답메시지
data.cashbillNumb	9	현금영수증 번호
data.cashbillMessage	40	현금영수증 메시지

4.2. 현금영수증 발급 취소

기발급된 현금영수증을 발급 취소합니다.

취소는 발급일 기준 6개월까지만 가능합니다.

HTTP Request

POST /kspay/webfep/api/v1/cashbill/cancel

요청 파라미터

현금영수증 발급 취소 요청 예시

{
    "mid": "2999199999",
    "payload": "KST20240604S011",
    "orgTradeKeyType": "TID",
    "orgTradeKey": "H89540016262",
    "orgTradeDate": "20240704"
}

Name	Size	Description
mid^*필수	10	상점아이디 `계약 완료 후 사업부를 통해 전달받은 상점아이디`
payload	2048	가맹점데이터 `API 응답에 돌려받을 가맹점의 데이터`
orgTradeKeyType^*필수	50	거래키구분 -`TID: 결제 응답으로 부여받은 tid 값` -`ORDER_NUMB: 결제 요청 시 생성한 가맹점 주문번호`
orgTradeKey^*필수	50	원거래키 `원거래 구분에 해당하는 TID 혹은 ORDER_NUMB 값`
orgTradeDate	8	원거래일자

응답 파라미터

현금영수증 발급 취소 응답 예시

# 성공응답
{
    "aid": "WF1CCSE00000000000001574",
    "code": "A0200",
    "message": "Success",
    "data": {
        "payload": "",
        "tid": "H89540016262",
        "tradeDateTime": "20240704151122",
        "cancelAmount": "",
        "respCode": "0000",
        "respMessage": "현금취소정상/취소551705749",
        "cashbillNumb": "551705749",
        "cashbillMessage": "상담센터:국번없이126/www.hometax.go.kr"
    }
}

# 실패응답
{
    "aid": "WF2CCSE00000000000002125",
    "code": "A0200",
    "message": "Fail",
    "data": {
        "payload": "KST20240604S011",
        "tid": "H89540016262",
        "tradeDateTime": "20240704151501",
        "cancelAmount": "",
        "respCode": "P10Q",
        "respMessage": "취소거절",
        "cashbillNumb": "",
        "cashbillMessage": ""
    }
}

Name	Size	Description
data.payload	2048	가맹점데이터
data.tid	12	PG거래번호
data.tradeDateTime	14	거래일시(yyyyMMddHHmmss)
data.cancelAmount	9	취소금액
data.respCode	4	응답코드
data.respMessage	40	응답메시지
data.cashbillNumb	9	현금영수증 번호
data.cashbillMessage	40	현금영수증 메시지

4.3. (hidden) NPAY 현금영수증 발급 가능 금액 조회

네이버페이 현금영수증 발급 금액 조회 API입니다.

HTTP Request

POST /kspay/webfep/api/v1/npay/cash/amount

요청 파라미터

네이버페이 현금영수증 금액 조회 요청 예시

{
  "mid":"2999199999",
  "npayPartnerId":"",
  "npaymentId":"",
  "orgTradeDate":"20240101",
  "orgTradeKey":"187547032079",
  "payload":""
}

Name	Size	Description
mid^*필수	10	상점아이디 `계약 완료 후 사업부를 통해 전달받은 상점아이디`
payload	2048	가맹점데이터 `API 응답에 돌려받을 가맹점의 데이터`
orgTradeKey^*필수	50	원거래 키 `원거래 구분에 해당하는 TID 값`
orgTradeDate^*필수	8	원거래일자 `주문번호 취소시 설정필요(yyyyMMdd)`
npaymentId	50	네이버페이ID `포인트거래시 네이버페이의 npaymentid`
npayPartnerId	50	네이버페이 파트너ID `네이버 별도 계약으로 파트너id를 발급받은 가맹점` `(사용시 KSNET에 별도 요청)`

응답 파라미터

네이버페이 현금영수증 금액 조회 응답 예시

# 성공응답
{
  "aid":"WF1NCAC00000000000004063",
  "code":"A0200",
  "message":"Success",
  "data": {
    "payload":"",
    "tid":"",
    "tradeDateTime":"",
    "respCode":"0000",
    "respMessage":"성공",
    "npointCashAmount":"286800",
    "giftCardCashAmount":"0",
    "primaryCashAmount":"0",
    "envDepositCashAmount":"0",
    "primaryPayMeans":"",
    "totalCashAmount":"286800",
    "supplyCashAmount":"260728",
    "vatCashAmount":"26072"
  }
}


# 실패응답
{
  "aid":"WFVNCAI00000000003100260",
  "code":"A0400",
  "message":"Invalid request data format",
  "data": {
    "payload":"",
    "tid":"",
    "tradeDateTime":"",
    "respCode":"",
    "respMessage":"",
    "npointCashAmount":"",
    "giftCardCashAmount":"",
    "primaryCashAmount":"",
    "envDepositCashAmount":"",
    "primaryPayMeans":"",
    "totalCashAmount":"",
    "supplyCashAmount":"",
    "vatCashAmount":""
    }
}

Name	Size	Description
data.payload	2048	가맹점데이터
data.tid	12	PG거래번호
data.tradeDateTime	14	거래일시(yyyyMMddHHmmss)
data.respCode	4	응답코드
data.respMessage	40	응답메시지
data.npointCashAmount	9	네이버페이 포인트/머니 결제금액중 현금영수증 발생 대상 금액
data.giftCardCashAmount	9	기프트카드 결제 금액중 현금영수증 발행 대상 금액
data.primaryCashAmount	9	현금성 주 결제 수단 결제 금액 중 현금영수증 발행 대상 금액
data.envDepositCashAmount	9	현금성 결제 금액 중 컵 보증금, 현금영수증 발행 제외 대상 금액
data.primaryPayMeans	9	결제에 사용된 현금성 주 결제수단
data.totalCashAmount	9	현금영수증 발행대상 총 금액
data.supplyCashAmount	9	현금성 총 공급가
data.vatCashAmount	9	현금성 총 부가세

응답코드	응답내역
0000	정상조회 (Success)
N001	유효하지 않은 네이버 결제key (InvalidPaymentId)
N002	취소가 정상적으로 완료되지 않아 조회 불가(CancelNotComplete)
N003	조회 실패 (Fail)
N004	서비스 점검중 (MaintenanceOngoing)
N999	기타오류

5. 휴대폰 결제 API

5.1. 휴대폰 결제 취소

휴대폰 결제를 취소할 수 있는 API입니다.

취소는 통신사 기준에 따라 결제 당월만 가능합니다.

HTTP Request

POST /kspay/webfep/api/v1/mobile/cancel

요청 파라미터

휴대폰 결제 취소 요청 예시

{
    "mid": "2999199999",
    "payload": "",
    "orgTradeKeyType": "TID",
    "orgTradeKey": "M88609000001",
    "orgTradeDate": ""
}

Name	Size	Description
mid^*필수	10	상점아이디 `계약 완료 후 사업부를 통해 전달받은 상점아이디`
payload	2048	가맹점데이터 `API 응답에 돌려받을 가맹점의 데이터`
orgTradeKeyType^*필수	10	거래키 구분 -`TID : 거래번호취소` -`ORDER_NUMB : 주문번호취소`
orgTradeKey^*필수	50	원거래 키 `원거래 구분에 해당하는 TID 혹은 ORDER_NUMB 값`
orgTradeDate	8	원거래일자 `주문번호 취소시 설정필요(yyyyMMdd)`

응답 파라미터

휴대폰 결제 취소 응답 예시

# 성공응답
{
    "aid": "WFVMCSB00000000002964314",
    "code": "A0200",
    "message": "Success",
    "data": {
        "payload": "",
        "tid": "M88609000001",
        "tradeDateTime": "20240401092136",
        "cancelAmount": "",
        "respCode": "0000",
        "respMessage": "취소성공",
        "approvalNumb": ""
    }
}

# 실패응답
{
    "aid": "WFVMCSD00000000000762223",
    "code": "A0201",
    "message": "Fail",
    "data": {
        "payload": "",
        "tid": "M88609000005",
        "tradeDateTime": "20240619114339",
        "cancelAmount": "",
        "respCode": "P10O",
        "respMessage": "원거래없음 원거래확인요망",
        "approvalNumb": ""
    }
}

Name	Size	Description
data.payload	2048	가맹점데이터
data.tid	12	PG거래번호
data.tradeDateTime	14	거래일시(yyyyMMddHHmmss)
data.cancelAmount	9	취소된금액
data.respCode	4	응답코드
data.respMessage	40	응답메시지
data.approvalNumb	9	승인번호

6. 빌링결제 API

6.1. 카드 등록

빌링결제를 위한 카드를 등록하는 API입니다.

HTTP Request

POST /kspay/webfep/api/v1/billing/regist

요청 파라미터

빌링결제 카드 등록 요청 예시

{
    "mid": "2999199999",
    "payload": "KST20240604S031",
    "cardNumb": "57456311156777456",
    "expiryDate": "2806",
    "password2": "11",
    "userInfo": "960213"
}

Name	Size	Description
mid^*필수	10	상점아이디 `계약 완료 후 사업부를 통해 전달받은 상점아이디`
payload	2048	가맹점데이터 `API 응답에 돌려받을 가맹점의 데이터`
cardNumb^*필수	20	카드번호
expiryDate^*필수	4	유효기간 `연월(yyMM) 형태의 4자리 형식 사용`
password2^*필수	8	비밀번호 `주문번호 취소시 설정필요(yyyyMMdd)`
userInfo^*필수	9	사용자정보 -`개인명의카드: 카드 소유자 생년월일 6자리(yyMMdd)` -`법인명의 법인카드: 사업자번호 10자리`

응답 파라미터

빌링결제 카드 등록 응답 예시

# 성공응답
{
    "aid": "WF1BRSF00000000000004196",
    "code": "A0200",
    "message": "Success",
    "data": {
        "payload": "KST20240621S213",
        "tid": "189410128123",
        "tradeDateTime": "20240621144032",
        "totalAmount": "",
        "respCode": "0000",
        "respMessage": "비씨카드/OK: 00000000",
        "issuerCardType": "BC",
        "issuerCardName": "비씨카드",
        "purchaseCardType": "BC",
        "purchaseCardName": "비씨카드",
        "maskedCardNumb": "518092XXXXXX1097",
        "cardType": "CREDIT",
        "billingToken": "2181980149583879"
    }
}

# 실패응답
{
    "aid": "WF1BRSF00000000000004086",
    "code": "A0201",
    "message": "Fail",
    "data": {
        "payload": "KST20240604S031",
        "tid": "189410124972",
        "tradeDateTime": "20240621142810",
        "totalAmount": "",
        "respCode": "6003",
        "respMessage": "비밀번호오류/비밀번호확인요망",
        "issuerCardType": "ABROAD",
        "issuerCardName": "해외카드",
        "purchaseCardType": "SAMSUNG",
        "purchaseCardName": "삼성카드",
        "maskedCardNumb": "574563XXXXXX7745",
        "cardType": "CREDIT",
        "billingToken": ""
    }
}

Name	Size	Description
data.payload	2048	가맹점데이터
data.tid	12	PG거래번호
data.tradeDateTime	14	거래일시(yyyyMMddHHmmss)
data.totalAmount	9	금액(null)
data.respCode	4	응답코드
data.respMessage	40	응답메시지
data.issuerCardType	20	발급사타입
data.issuerCardName	20	발급사명
data.purchaseCardType	20	매입사타입
data.purchaseCardName	20	매입사명
data.maskedCardNumb	*	마스킹카드번호
data.cardType	10	카드타입(CREDIT/CHECK/GIFT/PREPAID)
data.billingToken	16	빌링키

6.2. 카드 등록 조회

등록된 카드정보를 조회하는 API입니다.

HTTP Request

POST /kspay/webfep/api/v1/billing/query

요청 파라미터

빌링결제 카드 등록 조회 요청 예시

{
    "mid": "2999199999",
    "payload": "KST20240622S088",
    "billingToken": "2124447819584736"
}

Name	Size	Description
mid^*필수	10	상점아이디 `계약 완료 후 사업부를 통해 전달받은 상점아이디`
payload	2048	가맹점데이터 `API 응답에 돌려받을 가맹점의 데이터`
billingToken^*필수	16	빌링 토큰 `카드 등록을 통해 부여받은 빌링 토큰을 사용`

응답 파라미터

빌링결제 카드 등록 조회 응답 예시

# 성공응답
{
    "aid": "WF1BQSF00000000000004280",
    "code": "A0200",
    "message": "Success",
    "data": {
        "payload": "KST20240622S088",
        "tid": "189410131626",
        "tradeDateTime": "20240621144913",
        "respCode": "0000",
        "respMessage": "카드등록조회/OK:조회성공",
        "issuerCardType": "BC",
        "issuerCardName": "비씨카드",
        "purchaseCardType": "BC",
        "purchaseCardName": "비씨카드",
        "maskedCardNumb": "459682XXXXXX9712",
        "billingToken": "2109294857338111",
        "cardType": "UNDEFINED"
    }
}

# 실패응답
{
    "aid": "WF2BQSF00000000000002104",
    "code": "A0201",
    "message": "Failed",
    "data": {
        "payload": "KST20240622S088",
        "tid": "RFDj20910272",
        "tradeDateTime": "20240621144727",
        "respCode": "7003",
        "respMessage": "카드정보없음/Tel:1544-6030",
        "issuerCardType": "UNDEFINED",
        "issuerCardName": "미등록카드사",
        "purchaseCardType": "UNDEFINED",
        "purchaseCardName": "미등록카드사",
        "maskedCardNumb": "",
        "billingToken": "2124447819584736",
        "cardType": "UNDEFINED"
    }
}

Name	Size	Description
data.payload	2048	가맹점데이터
data.tid	12	PG거래번호
data.tradeDateTime	14	거래일시(yyyyMMddHHmmss)
data.respCode	4	응답코드
data.respMessage	40	응답메시지
data.issuerCardType	20	발급사타입
data.issuerCardName	20	발급사명
data.purchaseCardType	20	매입사타입
data.purchaseCardName	20	매입사명
data.maskedCardNumb	*	마스킹카드번호
data.billingToken	16	빌링키
data.cardType	20	카드유형

6.3. 빌링결제 요청

빌링토큰으로 결제를 요청하는 API입니다.

결제 취소는 1.카드API - 카드결제취소를 사용하시기 바랍니다.

HTTP Request

POST /kspay/webfep/api/v1/billing/pay

요청 파라미터

빌링결제 요청 예시

{
    "mid": "2999199999",
    "orderNumb": "M20240621134556",
    "userName": "고길동",
    "userEmail": "test@test.com",
    "productType": "REAL",
    "productName": "바나나12kg",
    "totalAmount": "1004",
    "taxAmount":"0",
    "taxFreeAmount": "0",
    "payload": "KST20240604S021",
    "interestType": "PG",
    "billingToken": "2189411948372888",
    "installMonth": "00",
    "currencyType": "KRW"
}

Name	Size	Description
mid^*필수	10	상점아이디 `계약 완료 후 사업부를 통해 전달받은 상점아이디`
payload	2048	가맹점데이터 `API 응답에 돌려받을 가맹점의 데이터`
orderNumb^*필수	50	가맹점 주문번호
userName^*필수	50	주문자명
userEmail	50	주문자이메일
productType^*필수	10	상품구분 -`REAL: 실물상품` -`DIGITAL: 디지털컨텐츠`
productName^*필수	50	상품명
totalAmount^*필수	9	총금액
taxAmount	9	과세금액 `상품에 부과되는 세액(복합과세 상점의 경우에만 가능, 사업부 문의 필요)`
taxFreeAmount	9	면세금액 `면세금액이 없으면 총금액 전체 과세처리`
interestType^*필수	20	이자구분 -`PG: 카드사에서 제공하는 무이자 설정값(기본값)` -`MALL: 가맹점 별도 계약하여 진행하는 무이자 설정값` `(사업부 문의 필요)`
billingToken^*필수	20	빌링 토큰 `카드 등록을 통해 부여받은 빌링 토큰을 사용`
installMonth^*필수	2	할부개월수
currencyType^*필수	3	통화타입 -`KRW: 원화` -`USD: 달러(모든 금액을 1달러=1000으로 표기)`

응답 파라미터

빌링결제 응답 예시

# 성공응답
{
  "aid":"WFVCCSE00000000000060121",
  "code":"A0200",
  "message":"Success",
  "data": {
    "payload": "KST20240604S021",
    "tid":"189189011016",
    "tradeDateTime":"20240604103121",
    "totalAmount":"1004",
    "respCode":"0000",
    "respMessage":"현대카드/OK: 00112345",
    "issuerCardType":"HYUNDAI",
    "issuerCardName":"현대카드",
    "purchaseCardType":"HYUNDAI",
    "purchaseCardName":"현대카드",
    "cardNumb":"40176201XXXX825X",
    "approvalNumb": "00112345",
    "expiryDate": "",
    "installMonth": "",
    "cardType":"CREDIT",
    "partCancelYn":"Y"
    }
}

# 실패응답
{
    "aid": "WF2BPSF00000000000002239",
    "code": "A0201",
    "message": "Fail",
    "data": {
        "payload": "KST20240621S987",
        "tid": "189411948333",
        "tradeDateTime": "20240621151001",
        "totalAmount": "1000",
        "respCode": "8373",
        "respMessage": "인터넷인증오류",
        "issuerCardType": "BC",
        "issuerCardName": "비씨카드",
        "purchaseCardType": "BC",
        "purchaseCardName": "비씨카드",
        "approvalNumb": "",
        "cardNumb": "498472XXXXXX1237",
        "expiryDate": "2911",
        "installMonth": "0",
        "cardType": "CREDIT"
    }
}

Name	Size	Description
data.payload	2048	가맹점데이터
data.tid	12	PG거래번호
data.tradeDateTime	14	거래일시(yyyyMMddHHmmss)
data.totalAmount	9	총금액
data.respCode	4	응답코드
data.respMessage	40	응답메시지
data.issuerCardType	20	발급사타입
data.issuerCardName	20	발급사명
data.purchaseCardType	20	매입사타입
data.purchaseCardName	20	매입사명
data.approvalNumb	12	승인번호
data.cardNumb	20	카드번호
data.expiryDate	4	유효기간
data.installMonth	2	할부개월수
data.cardType	10	카드타입(CREDIT/CHECK/GIFT/PREPAID)
data.partCancelYn	1	부분취소가능여부

6.4. 카드 등록 취소

등록된 카드를 해지하는 API입니다.

HTTP Request

POST /kspay/webfep/api/v1/billing/deregist

요청 파라미터

빌링결제 카드 등록 취소 요청 예시

{
    "mid": "2999199999",
    "payload": "KST20240621S072",
    "billingToken": "",
}

Name	Size	Description
mid^*필수	10	상점아이디 `계약 완료 후 사업부를 통해 전달받은 상점아이디`
payload	2048	가맹점데이터 `API 응답에 돌려받을 가맹점의 데이터`
billingToken^*필수	16	빌링 토큰 `카드 등록을 통해 부여받은 빌링 토큰을 사용`

응답 파라미터

빌링결제 카드 등록 취소 응답 예시

# 성공응답
{
    "aid": "WF1BDSF00000000000004507",
    "code": "A0200",
    "message": "Success",
    "data": {
        "payload": "KST20240622S121",
        "tid": "189123444222",
        "tradeDateTime": "20240621152631",
        "respCode": "0000",
        "respMessage": "카드등록해지/OK:해지성공",
        "billingToken": "2145410199887712"
    }
}

# 실패응답
{
    "aid": "WF1BDSF00000000000004504",
    "code": "A0201",
    "message": "Fail",
    "data": {
        "payload": "KST20240622S123",
        "tid": "RFnw10720382",
        "tradeDateTime": "20240621152604",
        "respCode": "7003",
        "respMessage": "카드정보없음/Tel:1544-6030",
        "billingToken": "2112315959998765"
    }
}

Name	Size	Description
data.payload	2048	가맹점데이터
data.tid	12	PG거래번호
data.tradeDateTime	14	거래일시(yyyyMMddHHmmss)
data.respCode	4	응답코드
data.respMessage	40	응답메시지
data.billingToken	16	빌링토큰

7. 기관 코드

7.1. 카드사 타입

카드명	타입	코드
비씨카드	BC	01
국민카드(or카카오체크)	KB	02
하나카드(구외환)	HANA	03
삼성카드	SAMSUNG	04
신한카드	SHINHA	05
현대카드	HYUNDAI	08
롯데카드	LOTTE	09
한미카드	HANMI	11
수협카드	SUHYUP	12
우리카드	WOORI	14
농협카드	NH	15
제주카드	JEJU	16
광주카드	GWANGJU	17
전북카드	JEONBUK	18
하나카드(구SK)	HANASK	24
해외카드	ABROAD	25
씨티카드	CITY	26
은련카드	UNIONPAY	30

7.2. 가상계좌 은행 타입

은행명	타입	코드
기업은행	IBK	03
국민은행	KB	04
하나은행	HANA	05
농협중앙	NONGHYUP	11
우리은행	WOORI	20
SC제일은행	SC	23
신한은행	SHINHAN	26
대구은행	DGB	31
부산은행	BNK	32
광주은행	KJ	34
전북은행	JB	37
경남은행	KN	39
우체국	EPOST	71

8. 부록

8.1. 개요

하기 옵션들은 관리자페이지인 KSTA에서 설정 가능한 옵션으로 고객지원센터(1544-6030)를 통해 해당 서비스 기능 추가 요청 해 주시기 바랍니다.

8.2. 신용카드 결제 옵션 – 승인중복체크/매입중복체크

승인중복체크
당일 거래 중에서 [상점 아이디/카드번호/주문번호/금액]이 같으면 중복승인으로 간주하고 승인이 허용되지 않게 하는 옵션 (거래마다 유니크한 주문번호 생성 필수)

매입중복체크
[상점 아이디/카드번호/금액]이 같으면 중복매입으로 간주하고 매입이 허용되지 않게 하는 옵션

8.3. 가상계좌 옵션 – 금액비교가능[수취 조회], 입금통보

금액 비교
발급된 가상계좌번호에 금액을 입금할 때 발급받은 가상 계좌의 금액과 일치한 금액만 입금 가능하도록 하는 옵션

- 금액 비교 기능은 현재 KSNET에서 서비스 중인 전 은행 가능합니다.
- 금액 비교 기능은 상점 정보에서 따로 요청을 해주셔야 이용 가능합니다.

8.4. 거래내역통보

PG 거래결과를 전송 받기위한 옵션으로 거래결과를 받으시려면 [결제수단, 상점아이디, 상점 IP/PORT 혹은 상점 URL]을 확인하셔서 KSNET 사업부로 요청하셔야 합니다.

결제수단으로는 신용카드, 계좌이체, 가상계좌 입금통보를 지원하고 있습니다.

이메일 : ksnet001@ksnet.co.kr
사업부 : 02-3420-5904 혹은 고객센터 : 1544-6030(15)

8.5. 테스트 및 거래내역에 대한 확인

아래의 관리자페이지 주소에 들어가시면 해당 거래내역에 대한 결과를 보실 수 있으며, 접속 계정 발급에 대한 문의는 영업담당자에게 문의해주시기 바랍니다.

관리자페이지 주소
(운영) https://ksta.ksnet.co.kr/
(개발) https://kstadev.ksnet.co.kr/

8.6. 영수증 조회 및 출력 페이지

신용카드 영수증 출력
https://ksta.ksnet.co.kr/mint/tsk/pgi01/mad/pgimad04m0.jsp?tr_no=111111111111
예) https://ksta.ksnet.co.kr/mint/tsk/pgi01/mad/pgimad04m0.jsp?tr_no=거래번호

신용카드 영수증 조회
https://ksta.ksnet.co.kr/mint/tsk/pgi01/mad/pgimad04m0.jsp

현금영수증 영수증 출력
https://ksta.ksnet.co.kr/ui/tsk/pgi01/pms/pgipms02m1.jsp?_m=p&tr_no=H12345647890
예) https://ksta.ksnet.co.kr/ui/tsk/pgi01/pms/pgipms02m1.jsp?_m=p&tr_no=거래번호

현금영수증 영수증 조회
https://ksta.ksnet.co.kr/ui/tsk/pgi01/pms/pgipms02m1.jsp

8.7. 에스크로 제도

2006년 4월 1일부터 에스크로 제도가 시작됨에 따라 추가되었으며, KSCROW는 가상계좌로 진행이 됩니다. 에스크로 내역은 KSPAY 관리자페이지에서 가상계좌 내역에서 처음 확인 된 다음 해당 가상계좌에 고객이 돈을 입금한 뒤 하루가 지나면 확인이 가능합니다. (은행을 통하기 때문에 입금 후 다음날 에스크로로 거래내역 확인 가능)

돈이 입금되면 KSPAY에서 메일을 통해 고객에게 받은 물건 구매여부 확인 메일을 보내 구매의사를 밝히면 정산에 들어가고, 거부의사를 밝히면 다시 환불을 거치도록 합니다.

9. 통합결제 API

9.1. 결제 개요

JavaScript를 통해 호출되는 API 연동방식으로 결제 방식은 두 단계로 구성됩니다.

1단계 결제창 요청은 결제수단에 알맞은 파라미터를 데이터로 요청하며, 결제키를 수신받는 단계입니다. 2단계 승인 요청은 수신받은 결제키, 금액, 응답 파라미터 등의 데이터로 승인을 요청합니다. 따라서, 2단계 승인 요청 성공 시에만 결제 발생합니다.

연동 페이지 방식은 PC, IFRAME, MOBILE 총 3가지로 구성되어 있습니다.
IFRAME은 PC와 MOBILE에서 가능하나, MOBILE의 리다이렉트 특성 상 PC에서만 권장드리고 있습니다.

연동 시 주의 사항으로는 PC, IFRAME의 경우에는 응답 callback 함수 내에 사용자 application을 구현하셔야 하며, MOBILE의 경우에는 callback 페이지 이동 후에 구현하셔야 합니다.

Demo Sample Module

https://pgdev.ksnet.co.kr/kspay/webfep/api/test/kspay_web_api_tester.jsp

9.2. 결제창 요청

결제창 요청 시에는 결제 방식 별 파라미터가 일부 상이합니다. 공통 파라미터와 결제 방식에 해당하는 파라미터를 함께 보내주시면 됩니다.

공통 항목

Name	Size	Description
system	4	서버구분 -`TEST: 개발서버 연동` -`REAL: 운영서버 연동`
winType^*필수	6	페이지방식 -`POPUP: POPUP 방식으로 PC에서 사용` -`IFRAME: IFRAME 방식` -`MOBILE: 페이지전환 방식으로 MOBILE에서 사용`
payAmount^*필수	9	총금액
productName^*필수	50	상품명
mid^*필수	10	상점아이디 계약 완료 후 사업부를 통해 전달받은 상점아이디
payMethod^*필수	15	연동방식 -`card: 일반카드` -`bank: 계좌이체` -`vbank: 가상계좌` -`phone: 휴대폰결제`
orderNumb^*필수	50	가맹점 주문번호
userName^*필수	50	주문자명
userPhonenumb	12	이동전화 KSPAY에서는 결제에 대한 안내 문자서비스를 제공하지 않으며, ‘-’ 사용 불가합니다. 예) 01011112222
userEmail	50	주문자이메일
payload	*	가맹점데이터 MOBILE에서만 사용, JSON타입 승인 응답 시 PC에서는 내부 Key 값으로 확인 가능하며, MOBILE에서는 payload.내부 Key 값의 방식으로 확인 가능합니다. 예) PC : xyz, MOBILE: payload.xyz
callbackUrl^*필수	*	콜백 Url 인증 후 응답 결과를 처리하기 위해 호출할 url로 MOBILE 페이지 전환방식의 경우, 필수값입니다.

신용카드 항목

Name	Size	Description
showCard^*필수	50	신용카드 표시 옵션 카드사 별로 결제 창에 보이도록 설정 -`C: 전체카드사` -`C(04): 삼성카드` -`C(25): 해외카드`
currency^*필수	3	통화코드 미화 승인은 영업부 담당자와 문의하여 처리 하셔야 합니다. 순수 해외 카드만 미화 결제가 가능합니다. 미화로 결제 시 1000원이 1달러 입니다. 예) 55달러 = 55000으로 결제 -`KRW: 원화` -`USD: 미화`
installMonth^*필수	50	할부개월 수 선택할 수 있는 할부 개월 수 -`ALL(0:2:3:4:5:6:7:8:9:10:11:12): 0~12개월 할부`
interestType^*필수	50	가맹점부담 무이자할부 가맹점에서 무이자 할부 수수료를 전액 부담 시 설정. 카드사 또는 KSPAY에서 주최하는 무이자 행사만 이용하실 경우 또는 무이자 할부를 적용하지 않는 업체는 “NONE”로 설정하셔야 합니다. -`NONE: 무이자 미적용` -`ALL: 전체 무이자 적용` -`04(2:3): 삼성카드2,3개월 무이자 적용`
rtApp	30	앱 URL Scheme 예) Testapp://
storeCeoName	30	카카오페이 상점대표자명
storePhoneNo	15	카카오페이 연락처
storeAddress	100	카카오페이 주소
qpayType	1	간편결제표시구분 payMethod card(일반카드)일 경우 사용. -`0: 미표시` -`1: 표시(default: 1)`
taxData		복합과세 정보 복합과세 사용 시 상점아이디에 별도 셋팅이 필요하여 사업부서에 요청하셔야 합니다. 예) 결제금액 1000원, 면세금액 300원 DF3=636:64

가상계좌, 에스크로 항목

Name	Size	Description
escrow	1	온라인입금(가상계좌) 에스크로 사용 여부 고객에게 구매확인여부는 전자우편으로 확인을 하니 Email주소를 필수적으로 입력해주시길 바랍니다. 에스크로에 대한 추가적인 사항은 부록을 참고해주시길 바랍니다. -`0: 사용 안함` -`1: 사용`
virDenyBank		해당은행 미표시 사용하지 않는 은행을 선택화면에서 제거. -`04,20: 국민, 우리 제거`
virExpDt	8	가상계좌마감일자 데이터 설정 후 사업부서에 요청하여 사용가능 상점아이디에 대해 옵션을 설정한 곳만 사용가능 예) 20220803 ( YYYYMMDD )
virExpTm	6	가상계좌마감일시 데이터 설정 후 사업부서에 요청하여 사용가능 예) 235500 ( HHMMSS )

계좌이체 항목

Name	Size	Description
cashReceipt	1	계좌이체 시 현금영수증 발급 여부 계좌이체와 현금영수증 두가지에 대해 모두 계약이 되어있어야 사용 가능합니다. -`0: 발급 안함` -`1: 발급 사용`

휴대폰결제 항목

Name	Size	Description
goodType^*필수	1	상품유형 휴대폰 결제 시에 체크하는 값입니다. -`1: 실물` -`2: 디지털`

9.3. 승인 요청

승인요청 항목

통합결제 요청 예시

{ 
   "system":"R", 
   "winType":"P", 
   "mid":"2999199999", 
   "payAmount":"1004", 
   "payKey":"w1190e8ca60d25540725", 
   "rpyParamset":"cardno`merno`cardtype`partcanyn`pgnointtype`nointtype`closedate`closetime`receipttype`halbu`accohdnm`mobile`cbtrno`cbauthno`cbmsg1`cbmsg2`certitype"
}

Name	Size	Description
system^*필수	4	서버구분 -`T: 개발서버 연동` -`R: 운영서버 연동`
winType^*필수	6	페이지방식 -`P: POPUP 방식으로 PC에서 사용` -`I: IFRAME 방식` -`M: 페이지전환 방식으로 MOBILE에서 사용`
mid^*필수	10	상점아이디 계약 완료 후 사업부를 통해 전달받은 상점아이디
payAmount^*필수	9	총금액
payKey^*필수		결제 Key 값
rpyParamset		응답 파라미터 응답을 원하는 파라미터를 구분자 사용하여 임의로 설정 -`cardno: 카드번호` -`merno: 가맹점번호` -`cardtype: 카드타입(CHECK, CREDIT, GIFT 등)` -`partcanyn: 부분취소 가능여부(Y, N)` -`pgnointtype: pg카드사 무이자할부행사 적용여부(1:적용)` -`nointtype: 무이자할부(1:일반무이자, 2:상점부담무이자)` -`closedate: 가상계좌 마감일자` -`closetime: 가상계좌 마감일시` -`receipttype: 현금영수증타입(0:개인, 1:사업자)` -`halbu: 할부개월수` -`accohdnm: 예금주명` -`mobile: 휴대폰번호` -`cbtrno: 계좌이체 후 현금영수증 거래번호` -`cbauthno: 계좌이체 후 현금영수증 승인번호` -`cbmsg1: 계좌이체 후 현금영수증 메세지1` -`cbmsg2: 계좌이체 후 현금영수증 메세지2` -`certitype: 간편결제타입` `(S:SSG, M:MPI인증, I:ISP인증/KBAPP, L:LPAY, P:LPOINT, PC:PAYCO, K:KAKAO, NP:NPAY, NPP:NPOINT)`

승인응답 항목

통합결제 취소 응답 예시

# 성공응답
{
    "aid":"B1B000001", 
    "code":"A0200", 
    "message":"Success", 
    "data": { 
       "tid":"189750210753", 
       "tradeDateTime":"20240725162927", 
       "totalAmount":"1004", 
       "respCode":"0000", 
       "respMessage":"우리카드 /OK: 32662061 ", 
       "payload":"", 
       "issuerCardType":"BC", 
       "issuerCardName":"비씨카드", 
       "purchaseCardType":"BC", 
       "purchaseCardName":"비씨카드", 
       "issuerCardCode":"01 ", 
       "purchaseCardCode":"01 ", 
       "approvalNumb":"32662061 ", 
       "cardNumb":"910020XXXXXX9332", 
       "installMonth":"00", 
       "cardType":"CHECK", 
       "partCancelYn":"Y", 
       "merNo":"757415721 ", 
       "pgNointType":" ", 
       "nointType":"1", 
       "billingToken":" "
    }
}

# 실패응답
{
    "aid":"B2A000004", 
    "code":"A0400", 
    "message":"Failed", 
    "data": { 
       "tid":"189940154805", 
       "tradeDateTime":"20240813163643", 
       "totalAmount":"1004", 
       "respCode":"8327", 
       "respMessage":"체크계좌잔액부족/  ", 
       "payload":"", 
       "issuerCardType":"BC", 
       "issuerCardName":"비씨카드", 
       "purchaseCardType":"BC", 
       "purchaseCardName":"비씨카드", 
       "issuerCardCode":"01 ", 
       "purchaseCardCode":"01 ", 
       "approvalNumb":"", 
       "cardNumb":"910020XXXXXX9332", 
       "installMonth":"00", 
       "cardType":"CHECK", 
       "partCancelYn":"", 
       "merNo":"757415721 ", 
       "pgNointType":" ", 
       "nointType":"1", 
       "billingToken":" "
    }
}

Name	Size	Description
aid	10	API 요청 고유값
code	5	API 응답 코드
message	14	API 응답 메시지
data	*	아래 데이터의 object
data.tid	12	PG거래번호
data.tradeDateTime	14	거래일시(yyyyMMddHHmmss)
data.totalAmount	9	총금액
data.respCode	4	응답코드
data.respMessage	40	응답메시지
data.issuerCardType	20	발급사타입
data.issuerCardName	20	발급사명
data.purchaseCardType	20	매입사타입
data.purchaseCardName	20	매입사명
data.approvalNumb	12	승인번호
data.cardNumb	20	카드번호
data.installMonth	2	할부개월수
data.payload	*	가맹점데이터

*. (hidden) 포인트 API

*.1. (hidden) 포인트결제 취소

포인트 결제를 취소할 수 있는 API입니다.

HTTP Request

POST /kspay/webfep/api/v1/point/cancel

요청 파라미터

포인트 결제 취소 요청 예시

{
    "mid": "2999199999",
    "payload": "KST20240604S031",
    "cancelType": "FULL",
    "orgTradeKeyType": "TID",
    "orgTradeKey": "489189008016",
    "orgTradeDate": ""
}

Name	Size	Description
mid^*필수	10	상점아이디 `계약 완료 후 사업부를 통해 전달받은 상점아이디`
payload	2048	가맹점데이터 `API 응답에 돌려받을 가맹점의 데이터`
cancelType^*필수	10	취소 처리구분 -`FULL: 전체취소` -`PARTIAL: 부분취소`
orgTradeKeyType^*필수	20	거래키 구분 -`TID: 거래번호취소` -`ORDER_NUMB: 주문번호취소`
orgTradeKey^*필수	50	원거래 키 `원거래 구분에 해당하는 TID 혹은 ORDER_NUMB 값`
orgTradeDate	8	원거래일자 `주문번호 취소 시 설정 필요(yyyyMMdd)`

응답 파라미터

포인트 결제 취소 응답 예시

# 성공응답
{
  "aid":"WFVCCSE00000000000054321",
  "code":"A0200",
  "message":"Success",
  "data": {
    "payload": "KST20240604S031",
    "tid":"489189008016",
    "tradeDateTime":"20240604120147",
    "cancelAmount":"50004",
    "respCode":"0000",
    "respMessage":"승인취소완료/매입취소요청",
    "approvalNumb":"00876543"
}}

# 실패응답
{
  "aid":"WFVCCSE00000000000054320",
  "code":"A0201",
  "message":"Fail",
  "data": {
    "payload": "KST20240604S027",
    "tid":"Lbd124090990",
    "tradeDateTime":"20240604102151",
    "respCode":"7003",
    "respMessage":"취소거절기간경과/Tel:1544-6030",
    "approvalNumb":"7003"
}}

Name	Size	Description
data.payload	2048	가맹점데이터
data.tid	12	PG거래번호
data.tradeDateTime	14	거래일시(yyyyMMddHHmmss)
data.cancelAmount	9	취소된금액
data.respCode	4	응답코드
data.respMessage	40	응답메시지
data.approvalNumb	12	승인번호