KPN Logo

API 공통 응답 형식

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

json
POST {EndPoint URL}/api/v1/
Content-Type: application/json
{
  "code": "200",
  "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--통신 결과 코드 (성공코드 200, 그 외 실패코드). 거래 결과는 data.replyCode로 판단
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
}

브랜드페이(BrandPay) 공통 형식

적용 범위

아래 내용은 브랜드페이(BrandPay) API에 한정됩니다. 위 공통 응답 형식과 별개로, 브랜드페이는 자체 응답 wrapper와 경로 규칙을 따릅니다.

공통 응답 wrapper 구조

브랜드페이의 모든 API 응답은 아래와 같은 공통 wrapper(JSON)로 감싸져 반환됩니다.

필수
조건부 필수
key타입최대크기필수설명
codeString--응답 코드. 200 = 성공, B*** = 브랜드페이 에러, 4XX/5XX = HTTP 표준 에러
messageString--응답 설명
statusString--HTTP 상태 문자열 (OK, BAD_REQUEST, UNAUTHORIZED 등)
requestIdString--요청 추적용 ID
requestAtString--요청 수신 시각 (ISO 8601)
responseAtString--응답 반환 시각 (ISO 8601)
dataObject--성공 시 API별 상세 응답 객체. 에러 시 null

성공 응답 예시 (전체 wrapper)

json
{
  "code": "200",
  "message": "정상처리",
  "status": "OK",
  "requestId": "6a87119e-83b7-45bd-ae86-7714d321eaa6",
  "requestAt": "2026-04-15T10:30:00",
  "responseAt": "2026-04-15T10:30:00.123",
  "data": { }
}

브랜드페이 에러 응답 예시 (전체 wrapper)

json
{
  "code": "B003",
  "message": "만료된 Access Token입니다",
  "status": "UNAUTHORIZED",
  "requestId": "1702b914-e140-4b01-8b8e-30a43161a18b",
  "requestAt": "2026-04-15T10:30:00",
  "responseAt": "2026-04-15T10:30:00.087",
  "data": null
}
code=200은 통신 성공일 뿐

code가 200인 것은 HTTP 통신 성공을 의미할 뿐, 실제 처리 결과는 아닙니다. 실제 비즈니스 결과는 data 내부의 status 또는 replyCode로 확인해야 합니다. 에러 응답인 경우 data는 null이며, code에 에러 코드(B*** 등)가 담깁니다.

API 경로 규칙

  • 진입: POST /v1/transaction/init 호출로 transactionId를 발급받습니다 (유효 30분).
  • 이후 모든 API: 발급받은 transactionId를 이후 API 경로(또는 후속 단계)에 부착하여 호출합니다. (예: POST /brandpay/v1/.../{transactionId})
  • 결제는 하나의 세트: transaction/init → payments/checkout → payments/approval은 **동일한 transactionId**로 호출해야 합니다. 세트가 끝나거나 30분이 지나면 새 transaction/init으로 다시 시작합니다.
다음 단계

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