KPN Logo

API 공통 응답 형식

API 응답의 경우 아래와 같은 공통 형식으로 리턴됩니다. 성공인 경우 API별 응답 데이터는 data 필드에 셋팅되어 전달됩니다.

json
POST {EndPoint URL}/api/v1/
Content-Type: application/json
{
  "code": "0000",
  "message": "정상처리",    
  "status": "OK",
  "requestId": "6a87119e-83b7-45bd-ae86-7714d321eaa6",
  "requestAt": "2024-09-27T22:45:54.0173497",
  "responseAt": "2024-09-27T22:45:54.1193342",
  "data": {
      상세 응답파라미터
  }
}

파라미터

필수
조건부 필수
key타입최대크기필수설명
codeString--에러코드 (성공코드 0000 이외 실패코드)
messageString--에러메시지 (실패인 경우 리턴됩니다.)
statusString--Status Code
requestIdString--transactionId
requestAtLocalDateTime--요청시간
responseAtLocalDateTime--응답시간
dataObject--응답 상세 데이터 (통신 성공인 경우 리턴)
에러 코드

에러 코드의 전체 목록은 에러 코드 레퍼런스에서 확인할 수 있습니다.

응답 예시

replyCode 확인 필수

일부 API는 응답의 data 영역에 replyCode를 포함합니다. 이 경우 HTTP 통신은 성공(code: 200)이더라도, 거래 처리 결과는 replyCode로 판단해야 합니다.

  • replyCode가 0000이면 거래 성공
  • replyCode가 0000이 아니면 거래 실패 (예: 8373, P549, P501 등)

replyCode는 결제 승인, 환불, 취소뿐만 아니라 빌키 삭제 등 다른 API에 동일하게 적용됩니다. 따라서 사용 중인 API의 데이터 영역에 replyCode가 있는지 꼭 확인해주세요!

성공 응답

replyCode가 없는 일반적인 API 응답 (결제창 생성 등)

json
{
  "code": "200",
  "message": "정상처리",
  "data": {
      "forwardUrl": "https://pay.firstpay.co.kr/pay_pc/{transactionId}",
      "forwardMUrl": "https://pay.firstpay.co.kr/pay_mob/{transactionId}"
  },
  "status": "OK",
  "requestId": "e17eca1f-5082-42b0-a0be-78cde6cfffd3",
  "requestAt": "2024-09-27T20:54:46.6915246",
  "responseAt": "2024-09-27T20:54:46.8832791"
}

실패 응답

HTTP 통신 자체가 실패한 경우 (code가 200이 아님)

API 오류 vs 거래 실패
  • SDK/API 오류: code가 400, 9731 등 (HTTP 통신 실패, data는 null)
  • 거래 실패: code가 200이지만 replyCode가 0000이 아님 (통신은 성공했으나 거래 처리 실패)

예시 1: 잘못된 요청 (400)

json
{
  "code": "400",
  "message": "잘못된요청입니다.",
  "status": "BAD_REQUEST",
  "requestId": "1702b914-e140-4b01-8b8e-30a43161a18b",
  "requestAt": "2024-09-27T21:01:49.8395827",
  "responseAt": "2024-09-27T21:01:49.8767239",
  "data": null
}

예시 2: 결제 결과 통보 서비스 - 통보 거래 데이터 조회 실패 (9731)

json
{
  "code": "9731",
  "message": "해당 통보 건 없음",
  "status": "ERROR",
  "requestId": "1702b914-e140-4b01-8b8e-30a43161a18b",
  "requestAt": "2024-09-27T21:01:49.8395827",
  "responseAt": "2024-09-27T21:01:49.8767239",
  "data": null
}
다음 단계

테스트 환경 설정을 완료했다면, 다음 문서를 참고하여 결제 연동을 시작하세요.