SDK 에러 코드

결제위젯, 브랜드페이, 결제창 SDK v1은 더 이상 업데이트되지 않습니다. 토스페이먼츠 SDK v2 연동을 추천합니다.

결제위젯, 브랜드페이, 결제창 SDK를 사용할 때 발생할 수 있는 에러를 살펴보세요.

SDK 에러

결제위젯 SDK, 브랜드페이 SDK, 결제창 SDK를 사용할 때 발생할 수 있는 에러를 안내합니다. 에러 응답을 처리하는 방법도 살펴보세요.

failUrl로 전달되는 에러

결제위젯, 결제창의 requestPayment() 메서드로 결제 요청에 실패했을 때 failUrl로 전달되는 에러 목록입니다.

에러 코드	한글 메시지	영문 메시지
`PAY_PROCESS_CANCELED`	사용자에 의해 결제가 취소되었습니다.	Payment has been canceled by the customer.
`PAY_PROCESS_ABORTED`	결제 진행 중 승인에 실패하여 결제가 중단되었습니다.	Payment has been canceled or has not been processed.
`REJECT_CARD_COMPANY`	결제 승인이 거절되었습니다.	Payment was rejected.

브랜드페이의 requestPayment() 메서드로 결제 요청에 실패했을 때 failUrl로 전달되는 에러 목록입니다.

에러 코드	한글 메시지	영문 메시지
`FAILED_CARD_COMPANY`	카드사 점검 중으로 다른 카드를 이용해 주세요.	Please use another card while checking the credit card company system.
`MAINTAINED_METHOD`	현재 점검 중 입니다.	Under maintenance.
`INVALID_STOPPED_CARD`	정지된 카드 입니다.	This is a suspended card.
`INVALID_CARD_INFO_RE_REGISTER`	유효하지 않은 카드입니다. 카드 재등록 후 시도해주세요.	Invalid card. Please re-register the card and try again.
`INVALID_CARD_LOST_OR_STOLEN`	분실 혹은 도난 카드입니다.	This is a lost or stolen card
`DUPLICATED_ORDER_ID`	이미 승인 및 취소가 진행된 중복된 주문번호 입니다. 다른 주문번호로 진행해주세요.	This is a duplicate order id that has already been approved or canceled. Please proceed with a different order id.
`NOT_ALLOWED_BRANDPAY_METHOD`	삭제된 결제 수단이거나 가맹점에서 사용이 불가능한 결제 수단입니다.	The payment method has been deleted or cannot be used by the merchant.
`NOT_FOUND_METHOD`	존재하지 않는 결제 수단 입니다.	Not found payment method
`INVALID_REQUEST`	잘못된 요청입니다.	The bad request.
`NOT_SUPPORTED_METHOD`	지원되지 않는 결제 수단입니다.	This payment method is not supported.
`INVALID_PASSWORD`	결제 비밀번호가 일치하지 않습니다.	Incorrect password
`NOT_FOUND_CUSTOMER`	유효한 고객 정보가 없습니다.	There is no valid customer information.
`FAILED_DB_PROCESSING`	잘못된 요청 값으로 처리 중 DB 에러가 발생했습니다.	A DB error occurred while processing with an invalid request value.
`NOT_FOUND_METHOD_OWNERSHIP`	결제수단의 소유자가 아닙니다.	Not found method ownership
`NOT_FOUND_MERCHANT`	존재하지 않는 상점 정보 입니다.	Not found merchant id
`UNKNOWN_PAYMENT_ERROR`	결제에 실패했어요. 같은 문제가 반복된다면 은행이나 카드사로 문의해주세요.	Payment failed. If the same problem occurs, please contact your bank or credit card company.
`RESTRICTED_TRANSFER_ACCOUNT`	계좌는 등록 후 12시간 뒤부터 결제할 수 있습니다. 관련 정책은 해당 은행으로 문의해주세요.	You can withdraw from this bank account after 12 hours from initial register. For related policies, please contact your bank.
`FORBIDDEN_DORMANT_OR_WITHDRAWAL_CUSTOMER`	휴면고객이거나 탈퇴한 고객입니다.	You are a dormant customer or a member who has been withdrawn.
`FAILED_PAYMENT_INTERNAL_SYSTEM_PROCESSING`	결제가 완료되지 않았어요. 다시 시도해주세요.	Payment has not been completed. please try again.
`COMMON_ERROR`	일시적인 오류가 발생했습니다. 잠시 후 다시 시도해주세요.	This is temporary error. Please try again in a few minutes.
`INVALID_MAXIMUM_DISCOUNT_AMOUNT`	할인 적용 시 최대 금액을 넘으면 안 됩니다.	The maximum amount must not exceeded to apply the discount.
`NOT_FOUND_PAYMENT`	존재하지 않는 결제 정보 입니다.	Not found payment
`INVALID_REQUIRED_PARAM`	필수 파라미터가 누락되었습니다.	The required parameter is missing.
`SUSPECTED_PHISHING_PAYMENT`	결제에 실패했습니다. 피싱사고 의심 거래입니다.	Payment rejected due to suspected phishing scam.
`EXCEED_MAX_DISCOUNT_COUNT`	즉시 할인이 가능한 회수를 초과했습니다.	You have exceeded the number of times available for discount promotion.

결제(공통) SDK 에러

결제위젯 SDK, 브랜드페이 SDK, 결제창 SDK에서 제공하는 메서드 실행에 실패했을 때 발생하는 에러 목록입니다.

에러 코드	한글 에러 메시지	영문 에러 메시지
`BELOW_ZERO_AMOUNT`	금액은 0보다 커야 합니다.	The amount must be greater than 0.
`DUPLICATED_ORDER_ID`	이미 승인 및 취소가 진행된 중복된 주문번호 입니다. 다른 주문번호로 진행해주세요.	This is a duplicate order id that has already been approved or canceled. Please proceed with a different order id.
`EXCEED_MAX_DUE_DATE`	가상 계좌의 최대 유효만료 기간을 초과했습니다.	You have exceeded the maximum expiry period for your virtual account.
`EXCEED_MAX_VALID_HOURS`	가상 계좌의 최대 유효시간을 초과했습니다.	The maximum validity time of the virtual account has been exceeded.
`FORBIDDEN_REQUEST`	허용되지 않은 요청입니다.	This request is not allowed.
`INCORRECT_FAIL_URL_FORMAT`	잘못된 failUrl 입니다.	Invalid format: `failUrl`
`INCORRECT_SUCCESS_URL_FORMAT`	잘못된 successUrl 입니다.	Invalid format: `successUrl`
`INVALID_BANK`	유효하지 않은 은행입니다.	It is an Invalid bank.
`INVALID_CARD_COMPANY`	유효하지 않은 카드사입니다.	It is an invalid card company.
`INVALID_CARD_INSTALLMENT_PLANS_WITH_MAX_AND_SINGLE`	cardInstallmentPlan과 maxCardInstallmentPlan은 같이 사용할 수 없습니다.	cardInstallmentPlan and maxCardInstallmentPlan cannot be used together.
`INVALID_CUSTOMER_KEY`	고객키는 영문 대소문자, 숫자, 특수문자 -, _, =, ., @로 2자 이상 255자 이하여야 합니다.	The customer key must be at least 2 and maximum 255 upper and lower case alphabets, numbers, special characters (-, _, =, ., @).
`INVALID_DATE`	날짜 데이터가 잘못 되었습니다.	The date data is invalid.
`INVALID_EASY_PAY`	간편결제 입력정보가 올바르지 않습니다.	The easy payment input information is incorrect.
`INVALID_FLOW_MODE_PARAMETERS`	인증 창을 먼저 띄우려면 카드사 코드 또는 은행 코드 또는 간편결제수단이 같이 전달되어야 합니다.	If you want to open the payment authentication window first, the credit card company code, bank code, or easy payment method must be delivered together.
`INVALID_MINOR_UNIT_FOR_CURRENCY`	금액의 소수점 자릿수를 통화 기준에 맞춰주세요.	The number of minor units needs to be in accordance with the currency standard.
`INVALID_ORDER_ID`	`orderId`는 영문 대소문자, 숫자, 특수문자(-, _) 만 허용합니다. 6자 이상 64자 이하여야 합니다.	`orderId` must be at least 6 and maximum 64 characters including upper and lower case alphabets, numbers, special characters (-, _).
`INVALID_ORDER_NAME`	주문 이름은 100자 이하여야 합니다.	The order name must be 100 characters or less.
`INVALID_PHONE`	전화번호 형식에 맞지 않습니다. 전화번호에는 특수문자가 포함될 수 없습니다.	It doesn't fit the phone number format. Phone numbers cannot contain special characters.
`INVALID_SUCCESS_URL`	successUrl 값은 필수 값입니다.	The successUrl value is a required value.
`INVALID_URL`	url 은 http, https 를 포함한 주소 형식이어야 합니다.	url must be in address format including http and https.
`INVALID_VALID_HOURS_WITH_DUE_DATE_AND_SINGLE`	validHours와 dueDate는 같이 사용할 수 없습니다.	validHours and dueDate cannot be used together.
`PAY_PROCESS_CANCELED`	결제가 사용자에 의해 취소되었습니다.	Payment has been canceled by the customer
`USER_CANCEL`	취소되었습니다	-
`REJECT_PAYMENT_METHOD`	결제를 완료할 수 없습니다. PayPal 고객센터로 문의해주세요.	Payment failed. Contact PayPal customer service.
`REQUIRED_POSTAL_CODE`	우편번호가 필요한 국가입니다.	The specified country requires a postal code.
`INSUFFICIENT_PRIVILEGES`	요청에 대한 권한이 불충분합니다. 토스페이먼츠에 문의해주세요.	Insufficient privileges for requested resource.
`INVALID_REQUEST`	잘못된 요청입니다.	Bad request.
`VIRTUAL_ACCOUNT_CALLBACK_URL_DEPRECATED`	`virtualAccountCallbackUrl`은 더 이상 지원하지 않습니다. 개발자센터(https://developers.tosspayments.com)에서 가상계좌용 웹훅을 등록한 뒤 사용하세요.	`virtualAccountCallbackUrl` is not supported anymore. Please register your Deposit Callback url in our Developer Center (https://developers.tosspayments.com).
`INVALID_ACCOUNT_NUMBER`	계좌번호가 올바르지 않습니다.	Invalid account number
`INVALID_METADATA`	올바르지 않은 metadata 형식입니다.

결제위젯 SDK 에러

결제위젯 SDK 메서드 실행에 실패했을 때 발생하는 에러 목록입니다.

에러 코드	에러 메시지	설명
`INVALID_AMOUNT_VALUE`	결제금액이 올바르지 않습니다.	`renderPaymentMethods()` 또는 `updateAmount()`에 넘긴 결제금액 값이 숫자가 아니면 발생합니다.
`INVALID_CURRENCY`	잘못된 통화 값입니다.	`renderPaymentMethods()`에서 지원하지 않는 통화를 사용하면 발생합니다. 현재는 `KRW`, `USD`만 지원합니다.
`INVALID_SELECTOR`	`selector`에 해당하는 HTML 요소를 찾을 수 없습니다. `selector` 값을 다시 확인해주세요.	`renderPaymentMethods()`를 실행했을 때 CSS 선택자를 찾을 수 없을 때 발생합니다.
`NEED_AGREEMENT_WITH_REQUIRED_TERMS`	필수 약관에 동의해주세요.	`requestPayment()`를 실행했을 때 모든 필수 약관에 동의 되어있지 않으면 발생합니다.
`NEED_CARD_PAYMENT_DETAIL`	카드 결제 정보를 선택해주세요.	신용・체크카드 결제에서 카드사 또는 할부기간을 선택하지 않은 상태로 `requestPayment()`를 호출하면 발생합니다.
`NEED_REFUND_ACCOUNT_DETAIL`	환불 계좌 정보를 모두 입력해주세요.	가상계좌 결제에서 환불 계좌 정보(은행, 예금주, 계좌번호)를 하나라도 입력하지 않은 상태로 `requestPayment()`를 호출하면 발생합니다.
`EXCEED_DEPOSIT_AMOUNT_LIMIT`	가상계좌 입금 제한 금액을 초과했어요. 다른 결제수단을 이용해주세요.	가상계좌 결제에서 `requestPayment()`를 실행했을 때 입금할 수 있는 금액보다 `amount` 값이 크면 발생합니다.
`PROVIDER_STATUS_UNHEALTHY`	결제 기관(카드사, 은행, 국세청 등) 오류입니다. 다른 결제수단을 선택해 주세요.	결제 기관의 시스템에 문제가 있을 때 발생합니다. 정확한 원인은 결제 기관에 문의해주세요.
`INSECURE_KEY_USAGE`	`test_gsk`, `live_gsk`로 시작하는 시크릿 키는 클라이언트 코드에 노출되면 안 됩니다. 구매자를 식별하는 `customerKey` 값을 사용해주세요.	결제위젯을 초기화할 때 `customerKey` 자리에 시크릿 키를 입력하면 발생합니다.

브랜드페이 SDK 에러

브랜드페이 SDK 메서드 실행에 실패했을 때 발생하는 에러 목록입니다.