KSPAY API Specification
1. API 사용 안내
  • API 사용을 위해서는 KSNET PG사업부에 가맹점 등록 및 인증키 발급이 필요합니다.
  • 모든 API는 파라미터의 추가 및 변경이 발생할 가능성을 염두에 두시고 사용해 주시기 바랍니다.
  • 테스트서버를 제외하고는 https프로토콜만 허용되며, 공식적으로 지원하는 TLS버전은 1.2버전 이상입니다. (TLS1.2/1.3)
  • 요청 파라미터의 Method는 POST, Content-Type은 application/json; utf-8을 사용하셔야 합니다.
  • KSNET과 카드사 및 일부 은행의 경우 문자 인코딩을 EUC-KR로 사용합니다. 따라서, 파라미터를 UTF-8을 전달하더라도 EUC-KR로 표현 가능한 문자여야 합니다.
  • API URL 형식은 https://pay.ksnet.co.kr/kspay/webfep/{API명} 입니다.

※ 예시 (카드 결제 취소)
https://pay.ksnet.co.kr/kspay/webfep/api/v1/card/cancel

2. 인증
  • API 사용을 위해서는 HTTP Request Header에 아래와 같은 포맷의 인증키를 이용합니다.
  • 테스트상점(2999199999)의 경우 "Mjk5OTE5OTk5OTpNQTAxOkE0RTc2QkRBMzM3RENDQTk1Mjk4RkI0OTVBODREMzY5"를 키 값으로 사용하고 있습니다.
  • 신용카드 비(구)인증결제 테스트상점(2999199990)의 경우 "Mjk5OTE5OTk5MDpNQTAxOjNEMUVBOEVBRUM0NzA1MTFBMkIyNUVFMzQwRkI5ODQ4"를 키 값으로 사용하고 있습니다.
Request Header

 Authorization: 1{authType} 2{공백} 3{apiKey}


1. {authType}: "pgapi"문자열을 고정으로 사용합니다. ("" 제외)

2. {공백}: ASCII(0x20) 1byte 공백 문자입니다.

3. {apiKey}: PG 관리자 페이지 - PG상점정보 상세 조회 후 하단 apiKey 값을 사용.

※ pgapi 키 확인 방법

※ 예시 (테스트 상점)
Authorization: pgapi Mjk5OTE5OTk5OTpNQTAxOkE0RTc2QkRBMzM3RENDQTk1Mjk4RkI0OTVBODREMzY5

※ 주의
{apiKey}는 보안에 민감한 키값으로, 사용 및 관리중 외부 유출에 주의하시기 바랍니다.

3. 응답 형식
  • API 표준 응답은 다음과 같습니다.
Respone Body

 {

  "aid": "string",

  "code": "string",

  "message": "string",

  "data": { }

 }


1. aid: API Request ID의 약자로, 매 요청마다 부여되는 고유한 문자열입니다. 문의 시 'aid'값을 전해 주시면 보다 빠른 처리가 가능합니다.

2. code: 요청에 대한 응답 코드입니다.

  1. A0200: 처리 성공 (유일한 성공값으로, A0200외 다른 값은 실패를 의미합니다.)

  2. A0201: 처리 실패 (처리 실패의 경우 반드시 data 항목의 응답코드와 응답메시지를 확인하시기 바랍니다.)

  3. A0400: 요청 파라미터 오류

  4. A0401: 인증 오류

  5. A0403: 프로토콜 오류

  6. A0500: 서버 오류 (KSNET 기술팀 문의)

  7. A0999: 기타 오류

3. message: 코드보다 상세한 내용이 담긴 응답값입니다.

4. data: API별 세부 응답 값으로, JSON객체로 구성됩니다. 일부 API는 null값을 응답할 수도 있습니다.

4. 사용 예시


HTTP Request (카드 비인증 승인 요청)

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

 Host: pay.ksnet.co.kr

 Content-Type: application/json;

 Authorization: pgapi Mjk5OTE5OTk5OTpNQTAxOkE0RTc2QkRBMzM3RENDQTk1Mjk4RkI0OTVBODREMzY5


 {

  "mid":"2999199999",

  "orderNumb":"KSNET_TEST_ORDER_001",

  "userName":"PG Developer",

  "userEmail":"pgmodule@ksnet.co.kr",

  "productType":"REAL",

  "productName":"TEST_PRODUCT_X01",

  "totalAmount":"10000",

  "taxFreeAmount":"0",

  "payload":"Client_Payload_Data",

  "interestType":"PG",

  "cardNumb":"1234123412341234",

  "expiryDate":"9912",

  "installMonth":"0",

  "currencyType":"KRW"

 }

 

 

 

 

 



HTTP Response (카드 비인증 승인 응답)

 HTTP/1.1 200 OK

 Content-Type: application/json;


 {

  "aid":"WFT0503154132veW2gQfTnd3",

  "code":"A0200",

  "message":"Success",

  "data":{

   "tid":"17796900050",

   "tradeDateTime":"20210503154137",

   "totalAmount":"10000",

   "respCode":"99162137",

   "respMessage":"테스트승인정상 / OK: 99162137",

   "payload":"Client_Payload_Data",

   "issuerCardType":"UNDEFINED",

   "issuerCardName":"미등록카드사",

   "purchaseCardType":"UNDEFINED",

   "purchaseCardName":"미등록카드사",

   "approvalNumb":"99162137",

   "cardNumb":"123412XXXXXX1234",

   "expiryDate":"9912",

   "installMonth":"0",

   "cardType":"CREDIT",

   "partCancelYn":"N",

  }

 }


/kspay/webfep/doc/api-spec