서버 연동

에러 코드

point3가 반환하는 코드를 출처별로 정리했습니다. 처리 기준은 HTTP 상태 코드와 응답 본문의 코드를 함께 보고 판단하세요. 사용자 안내 문구는 message 원문 대신 코드별로 가맹점이 정한 문구를 사용하는 것을 권장합니다.

결과가 불확실하면 성공·실패로 추정하지 마세요

5xx, 타임아웃, 네트워크 오류, 응답 유실은 결과가 확정되지 않은 상태입니다. 같은 요청을 무조건 반복하거나 실패로 처리하지 말고 상태 조회 API로 확인하세요.

HTTP 상태 코드 공통 기준

상태 코드	의미	재시도	처리
`200`	정상 응답	-	응답 본문의 `status`로 결과 판단
`202`	처리 중	조회	잠시 기다렸다가 상태 조회
`400`	요청 형식 오류	안 함	요청값 수정
`401`	인증 실패	안 함	API 키 확인
`404`	리소스 없음	안 함	`sessionId` 확인
`409`	현재 상태에서 처리 불가 (결제 취소 API)	코드별	본문의 `result.code` 확인
`422`	요청 거절	안 함	결제 승인: 승인 기한 만료. 결제 취소: 거절로 처리하고 코드 기록
`500`	서버 오류	조회	결과 미확정. 상태 조회로 확인
`503`	일시 사용 불가	조회	결제 세션 API: `error.eob`가 있으면 EOB 점검. 결제 취소 API: 결과 미확정이므로 상태 조회

결제 세션·결제 승인 API

결제 세션 API와 결제 승인 API의 오류 응답은 error.type과 error.code를 포함합니다.

오류 응답 형식
{
  "error": {
    "type": "authenticationError",
    "code": "authenticationRequired",
    "message": "인증에 실패했습니다."
  }
}

HTTP	`error.type`	`error.code`	처리
`400`	`invalidRequestError`	`invalidRequest`	요청 형식과 필수 필드 확인
`401`	`authenticationError`	`authenticationRequired`	`Authorization` 헤더와 API 키 확인
`404`	`notFoundError`	`resourceMissing`	`sessionId` 확인
`422`	`invalidRequestError`	`paymentCaptureExpired`	결제 승인 기한 만료. 새 결제 세션으로 다시 시작
`500`	`apiError`	`internalError`	결과 미확정. 결제 세션 조회
`503`	`serviceUnavailableError`	`temporarilyUnavailable`	`error.eob`가 있으면 `endsAt` 이후 재요청, 없으면 잠시 후 결제 세션 조회

error.eob는 결제 세션 API에서만 반환되며 startsAt, endsAt, timeZone을 포함합니다. EOB 점검 중 응답 예시는 EOB 점검 시간을 참고하세요.

결제 승인 결과 코드

결제 승인 API가 200으로 응답하면 outcome.code로 결과를 구분합니다.

`status`	`outcome.type`	`outcome.code`	의미	처리
`captured`	`succeeded`	`PAYMENT_CAPTURED`	결제 성공	주문 완료
`failed`	`declined`	`PAYMENT_METHOD_DECLINED`	결제 수단 승인 거절	다른 결제 수단 안내
`failed`	`paymentMethodUnavailable`	`PAYMENT_METHOD_UNAVAILABLE`	결제 수단 사용 불가	다른 결제 수단 안내
`failed`	`serviceUnavailable`	`PAYMENT_SERVICE_UNAVAILABLE_HOURS`	은행·기관 점검 또는 운영시간 외	다른 계좌 선택 또는 점검 종료 후 새 결제
`failed`	`rejected`	`PAYMENT_CAPTURE_REJECTED`	승인 요청 거절	실패 안내
`failed`	`failed`	`PAYMENT_METHOD_LIMIT_EXCEEDED`	결제 수단의 이체 한도 초과	다른 결제 수단 또는 금액 안내
`failed`	`failed`	`PAYMENT_CAPTURE_ALREADY_FAILED`	이미 실패한 결제	실패로 처리하고 새 결제

failed의 outcome.message에는 은행이 반환한 사유가 담길 수 있습니다. 화면 분기는 outcome.code로 하세요.

202 응답은 PAYMENT_CAPTURE_PROCESSING이며, 잠시 기다렸다가 결제 세션을 조회합니다.

결제 취소 API

결제 취소 API의 오류 응답은 result.code를 포함합니다.

오류 응답 형식
{
  "status": 409,
  "timestamp": "2026-08-21T00:00:00.000Z",
  "result": {
    "code": "REFUND_DUPLICATE_REQUEST",
    "message": "동일한 Idempotency-Key로 요청이 이미 접수되었습니다"
  }
}

409 응답

`result.code`	의미	처리
`REFUND_TEMPORARY_UNAVAILABLE`	외부 처리 결과 미확정. 일시 장애 시에는 `503`으로 반환	원래 키와 응답 식별값을 보존하고 상태 조회 후 처리 중인 항목만 재개
`REFUND_DUPLICATE_REQUEST`	동일 `Idempotency-Key`를 24시간 안에 재사용	상태 조회로 기존 요청 결과를 확인하고 새 취소를 만들지 않음
`REFUND_ACTIVE_REQUEST_EXISTS`	현재 처리 중인 취소 존재	새 취소를 만들지 않고 상태 조회 후 기존 처리를 재개
`REFUND_NOT_IN_REFUNDABLE_STATE`	취소 가능한 상태가 아님	결제·취소 상태를 확인하고 요청 종료
`EOB_WINDOW_BLOCKED`	23:30 이상 00:30 미만(KST) 요청	00:30 이후 새 취소 요청

그 외 오류 코드

HTTP	`result.code`	의미
`400`	`REFUND_VALIDATION_FAILED`	요청 형식 오류
`400`	`NON_POSITIVE_REFUND_AMOUNT`	취소 금액이 0 이하
`400`	`REFUND_TAX_BREAKDOWN_INVALID`	면세 금액·부가세 구성이 올바르지 않음
`404`	`REFUND_NOT_FOUND`	취소할 결제를 찾을 수 없음
`422`	`AMOUNT_EXCEEDS_REFUNDABLE`	취소 금액이 취소 가능 금액을 초과
`422`	`TAX_FREE_AMOUNT_EXCEEDS_REFUNDABLE`	면세 금액이 취소 가능 면세 금액을 초과
`422`	`VAT_EXCEEDS_REFUNDABLE`	부가세가 취소 가능 부가세를 초과

취소 실패 코드

취소 상태 조회 결과에서 failed인 취소 항목은 실패 사유 코드를 포함합니다.

코드	의미
`refundMethodDeclined`	환불 수단 승인 거절
`refundMethodUnavailable`	환불 수단 사용 불가
`refundServiceUnavailable`	은행 서비스 운영시간 외
`refundRejected`	환불 요청 거절
`refundFailed`	환불을 완료할 수 없음

취소 처리 흐름은 결제 취소를 참고하세요.

위임 인증 API

위임 인증 생성 API의 오류 응답은 result.code를 포함합니다. 어떤 오류든 위임 인증 없이 결제창을 열면 결제를 계속할 수 있습니다.

HTTP	`result.code`	처리
`400`	`HTTP_ERROR`	`payer_id` 형식과 추가 필드 확인
`401`	`HTTP_ERROR`	`Authorization` 헤더와 API 키 확인
`404`	`PAYER_NOT_FOUND`	저장된 `payerId`를 사용할 수 없음. 위임 인증 없이 결제창을 열고, 결제 후 새로 받은 `payerId` 저장
`503`		일시적 장애. 위임 인증 없이 결제창 열기

자세한 내용은 위임 인증 생성을 참고하세요.

결제창 코드

JavaScript SDK 결제

failUrl의 code 쿼리 파라미터로 전달됩니다. 결제 승인 API를 호출하지 않습니다.

코드	의미	안내 문구 예시
`PAYMENT_WINDOW_CLOSED`	사용자가 결제창을 닫음	결제창이 닫혔습니다.
`PAYER_DEACTIVATED`	구매자 탈퇴 완료	탈퇴가 완료되어 결제가 종료되었습니다.
`SESSION_EXPIRED`	결제 세션 만료	결제 세션이 만료되었습니다. 결제를 다시 시도해 주세요.
`INVALID_SESSION`	결제 세션 확인 불가	결제 세션 정보를 확인할 수 없습니다. 결제를 다시 시작하세요.
`PAYMENT_FAILED`	결제 요청 거절 (예: 금액이 수수료 이하)	결제 요청이 거절되었습니다.

JavaScript SDK 등록

failUrl의 code 쿼리 파라미터로 전달됩니다.

코드	의미
`REGISTRATION_CANCELLED`	사용자가 등록을 취소함
`AUTHENTICATION_EXPIRED`	인증 만료. 본인인증부터 다시 시작
`REGISTRATION_FAILED`	등록 실패
`REGISTRATION_RESULT_UNAVAILABLE`	등록 결과 확인 불가

SDK 초기화·호출 오류

failUrl로 전달되지 않고 SDK 호출에서 발생하는 오류 객체의 code로 확인합니다. try/catch로 처리하세요.

코드	원인
`INVALID_CLIENT_KEY`	`client_id`가 `client-...` 형식이 아님
`INVALID_PAYMENT_REQUEST`	요청값 누락 또는 SDK 호출 순서 오류. 위임 인증의 `authorization_url`을 가공했거나 등록 전용 위젯에 전달한 경우 포함
`PAYMENT_REQUEST_IN_PROGRESS`	결제나 등록이 진행 중인 상태에서 다시 요청
`BROWSER_NOT_READY`	문서 준비 상태, 보안 컨텍스트 또는 `crypto.randomUUID()` 미지원 (등록)

마지막 수정: 2026년 10월 27일

위임 인증 생성 결제