자주 묻는 질문

자주 묻는 질문

이제, 토스페이 서비스에 대해 좀 더 자세하게 안내드립니다.
이 항목은 지속적으로 업데이트될 예정이며, 궁금하신 사항은 언제든지 토스페이팀(support-pay@toss.im)으로 의견주세요!

토스 연동을 위한 방화벽 설정

구매자는 인증을 완료했지만 가맹점 retUrl로 결제 결과가 오지 않는 경우나, 토스 서버로 부터 resultCallback 결과를 받지
못한다면 먼저 방화벽 설정을 살펴봐야 합니다.

1. 가맹점에서 토스서버로 접근하는 경우 (결제 생성, 결제 승인 등의 API)
   가맹점 --> 가맹점 방화벽 --> 토스페이

위의 경우에는 가맹점 방화벽의 outbound 정책에 아래 토스 IP를 추가해 주시면 됩니다.
domain : pay.toss.im (port : 443)
• 117.52.3.202
• 117.52.3.210
• 211.115.96.202
• 211.115.96.210


2. 토스서버에서 가맹점으로 접근하는 경우 (resultCallback를 포함하는 경우만 사용)
   토스페이 --> 가맹점 방화벽 --> 가맹점

위의 경우에서는 가맹점 방화벽의 inbound 정책에 아래 토스 IP를 추가해 주시면 됩니다.
domain : pay.toss.im (port : 443)
• 117.52.3.4
• 117.52.3.11
• 117.52.3.80~87
• 211.115.96.4
• 211.115.96.11
• 211.115.96.80~87

✓ 토스페이 방화벽은 제한없이 모두 오픈되어 있습니다.

✓ 각 케이스 별 구분이 어렵다면 outbound, inbound 정책에 맞게 토스 IP를 모두 추가해 주셔도 됩니다.

✓ 가맹점이 설정한 resultCallback URL 에 443 이외의 포트가 포함되어 있다면 접근이 어려울 수 있으니 유의해주세요.

✓ 토스 서버의 IP가 추가되는 경우 사전에 공지메일을 발송해 드립니다.

토스 인코딩 방식

토스 인코딩 방식은 UTF-8 형식을 사용합니다.
가맹점에서 토스 서버로 한글이 포함된 값(주문번호, 상품명 등)을 보내주실 때, UTF-8 형식으로 보내주셔야
정상적인 response값을 확인하실 수 있습니다.
유의해 주세요! 깨진 한글이 유입되면 토스 서버는 필수 값 체크를 못해 500에러 등의 오류가 발생할 수 있습니다.

토스가 권장하는 Time Out 처리 시간은 무엇인가요?

토스는 일반 은행계좌에서 토스머니로 충전 시 최대 10초의 타임아웃 시간을 설정합니다.
따라서, 가맹점에서는 10초 + 3~5초 정도의 대기 시간을 잡아주시면 타임아웃으로 인한 대사 불일치 거래건이 발생하지 않습니다. (처리 지연으로 가맹점은 취소 처리했으나 토스는 승인되는 케이스 방지)
토스 이슈가 아닌 은행망 이슈를 제외하면 타임아웃으로 인한 거래 지연은 발생하지 않습니다.

✓ 결제수단 구분 없이 모두 동일하게 설정하셔도 무방합니다.
✓ 양사간 거래 확인을 위하여 정산대사를 함께 연동하시길 권장드립니다.
요청 가맹점에 한하여 별도로 제공해 드리고 있으며, 신청은 support-pay@toss.im 으로 주시기 바랍니다.

retUrl 이동이 실패할 수 있나요?

retUrl의 이동은 토스 web page에서 처리되는 로직으로 일반적인 경우 처리를 보장하지만 특별한 상황에서 실패할 수 있습니다.
특별한 상황이란, 구매자가 결제 중에 앱을 종료하거나 백그라운드 처리를 하는 등의 이탈로 JavaScript 로직이 처리될 수 없는 경우입니다. 이 경우 구매자가 다시 결제 화면으로 돌아와서 '결제완료' 버튼을 클릭한다면 retUrl 로의 이동을 재시도 하게 됩니다.
다만, 구매자가 재시도를 하지 않는 경우에는 retUrl로 이동하지 못하는 상황이 발생할 수 있습니다.

resultCallback을 반드시 활용해야 하나요?

토스 서버에서 결제처리가 완료되고 나면 해당 결제건의 상태는 PAY_COMPLETE로 변경되고, 구매자를retUrl로 이동시킵니다.
동시에 토스 서버에서 가맹점 서버의 resultCallback URL로 callback을 요청합니다. retUrl은 단순 web page의 이동으로
토스에서 결제 성공 여부를 확인 할 수 없고, 구매자 상황에 따라 실행을 보장할 수 없기 때문에 resultCallback을 활용하시길 권장드립니다.
또한, resultCallback 은 토스 서버<->가맹점 서버 통신이므로 데이터 유실이 없고 안전합니다.

• 자동 승인 설정(autoExecute)을 true로 사용하는 가맹점에서는 필수 값입니다.

resultCallback이 실패하는 이유가 뭘까요?

토스에서는 장애 상황이 아닌 한 resultCallback 요청을 보장합니다. 단, 결제 방화벽 이슈를 제외하고 callback 요청을 받아 처리하는 것은 가맹점 서버로 많은 트래픽, 개발 중의 버그 등의 특별한 사유로 callback 요청이 실패할 수 있습니다.
토스에서는 callback 실패 시, 가맹점 서버로 10분 이내에 총 4회의 재시도 요청을 하고 있으니 안심하세요.

✓ callback 재전송 기능은 토스 가맹점 관리자 페이지에서도 확인하실 수 있습니다.

결제 에러 응답코드

✓ 토스페이 에러코드는 예고 없이 업데이트 될 수 있습니다. 추가되더라도 오류가 발생하지 않도록 연동 부탁드립니다.

✓ 토스에서는 한 가지 에러코드에 상황별로 다른 오류 메시지를 전달합니다.
여러 상황이 발생할 수 있으니 되도록이면 전달되는 오류 메시지 그대로를 처리해주세요.

응답 코드(errorCode)	사유(msg)
공통
COMMON_SYSTEM_ERROR	시스템 오류로 인해 통신이 원활하지 않습니다.문제가 계속되면 토스 고객센터로 문의해주세요. (1599-4905)
COMMON_INVALID_PARAMETER	요청한 값이 바르지 않습니다.
COMMON_PAY_ERROR	문제가 발생하였습니다.
COMMON_NOT_ENOUGH_CASH	충전계좌의 잔액이 부족하여 토스머니 충전이 불가합니다.
COMMON_EXCEED_LIMIT	한도를 초과하였습니다.
COMMON_ASSET_GET_ACCOUNT_ERROR	계좌 정보 조회에 실패 하였습니다.
COMMON_REFUND_ERROR	환불이 불가능 한 상태입니다.
REFUND_REFUND_NO_DUPLICATE	이미 환불처리 된 refundNo 입니다.
PAYMENT_DUPLICATION_ORDER_NO	중복된 주문번호 입니다.
PAYMENT_EXISTING_PAYMENT	이미 존재하는 결제입니다.
TRANSACTION_PENDING_ERROR	조금 전 신청하신 결제가 아직 진행중입니다. 잠시 후 다시 시도해주세요. 이 상태가 10분 이상 지속되면 토스팀에 문의해주시기 바랍니다. (1599-4905)
INVALID_ACCOUNT_STATUS	계좌 상태를 확인해주세요.
FRAUD_DETECTION_SYSTEM_ERROR	FDS에 의해 금융거래가 차단된 상태입니다.
USER_STATUS_ERROR	결제 진행이 불가한 사용자입니다.
REFUND_ALREADY_REFUNDED	이미 전액 환불처리 된 거래 건입니다.
TRANSACTION_NOT_COMPLETE	거래가 완료되지 않았습니다.
TRANSACTION_NOT_FOUND	존재하지 않는 거래내역 입니다.
INACTIVE_USER	비활성 처리된 사용자입니다.
AUTO_CHARGE_NOT_YET_REGISTER_ACCOUNT	충전계좌가 등록되지 않았습니다.
USER(사용자)
PAY_UNAUTHORIZED	결제 요청자와 토스의 계정이 일치해야만 결제가 가능합니다. 확인 후 다시 시도해 주세요.
TOSS_APP_UPDATE_IS_REQUIRED	결제를 진행하시려면 최신 버전의 토스앱을 이용하세요.
PAY_CANCEL_ITS_NOT_CANCELABLE_STATUS	결제를 취소할 수 없습니다. 잠시 후 다시 시도해주세요. 문제가 계속되면 토스 고객센터로 문의해주세요. (1599-4905)
COUPON_ASSIGN_FAIL	쿠폰 발급에 실패하였습니다.
DISCOUNT_CLOSED	할인 혜택이 마감되었습니다.
USER_DISCOUNT_CLOSED	1인당 할인 횟수를 초과하였습니다.
DISCOUNT_NEED_ISSUE	쿠폰을 발급받아 주세요.
DISCOUNT_ALREADY_ISSUED	쿠폰이 이미 발급되었습니다.
AVAILABLE_ONLY_TOSS_MONEY_UNDER_MIN_AMT	%s원 미만 금액은 %s 카드 결제가 불가합니다.
AUTO_PAY_TERM_INACTIVE_FAIL	약관 철회에 실패하였습니다.
AGE_POLICY_ERROR	%d세 미만인 경우 토스 %s 서비스를 이용하실 수 없습니다.
PAY_FRAUD_DETECTED	일시적으로 토스 서비스를 이용하실 수 없습니다. 문제가 계속되면 토스 고객센터로 문의해주세요. (1599-4905)
BLOCKED_THE_USE_OF_POINT	법원 압류 판결로 인해 토스포인트를 쓸 수 없어요. 궁금한 점이 있다면 토스 고객센터(1599-4905)로 문의해주세요.
카드
CARD_SYSTEM_ERROR	카드사 시스템 점검 중입니다. 잠시 후 다시 시도해주세요.
CARD_BANK_SYSTEM_ERROR	카드사 거래은행 시스템 점검 중입니다. 잠시 후 다시 시도해주세요
CARD_NOT_AVAILABLE_SHOP	해당카드로 결제가 불가합니다. 다른 결제수단으로 다시 시도하거나 토스 고객센터로 문의해주세요.(1599-4905)
CARD_NOT_AVAILABLE	도난/분실/거래정지 카드로 승인이 거절되었습니다.
CARD_EXCEED_LIMIT	사용한도 초과로 승인이 거절되었습니다.
CARD_NOT_ENOUGH_BALANCE	잔고 부족으로 승인이 거절되었습니다.
CARD_SPREADOUT_ERROR	할부 사용이 불가능한 카드로 승인이 거절되었습니다.
CARD_MIN_AMOUNT_ERROR	금액오류(100원 또는 1달러 미만 신용카드 승인 불가)
CARD_MIN_AMOUNT_FOR_SPREADOUT_ERROR	할부 결제는 결제금액이 50,000원 이상만 가능합니다. 일시불로 결제해주세요.
BNPL(후불결제)
BNPL_INVALID_REQUEST	잘못된 요청입니다.
BNPL_NOT_EXIST_USER	존재하지 않는 BNPL 사용자 입니다.
BNPL_EXCEED_PAYABLE_AMOUNT	BNPL 한도가 초과되었습니다.
BNPL_ALREADY_COMPLETED_REQUEST	이미 처리 된 요청입니다.
BNPL_IN_PROGRESS_REQUEST	이미 처리 중인 요청입니다.
BNPL_NOT_FOUND_PAYMENT	존재하지 않는 결제건 입니다.
BNPL_ALREADY_COMPLETED_REFUND	환불 할 수 없는 결제 건 입니다.
NOT_SET_BNPL_PAYMENT_ACCOUNT	후불결제 진행을 위해 납부계좌 설정이 필요해요.
매출전표
SALES_CHECK_NOT_FOUND_USER	매출전표 조회를 위한 사용자 정보가 존재하지 않습니다.
SALES_CHECK_USER_AUTH_FAIL	매출전표 조회를 위한 사용자 정보 인증에 실패하였습니다.
SALES_CHECK_USER_AUTH_DECRYPT_FAIL	매출전표 조회를 위한 사용자 정보 복호화에 실패하였습니다.
SALES_CHECK_CARD_ONLY	카드결제 건에 대해서만 매출전표 조회가 가능합니다.
리셀러
COMMON_PAY_RESELLER_ERROR	리셀러 결제 처리 중 에러가 발생했습니다.
RESELLER_ONLY_CARD_PAYMENT	카드 결제가 아닙니다.
RESELLER_CALLBACK_PROCESS_ERROR	리셀러 콜백 처리 중 에러가 발생했습니다.
NOT_APPROVED_CARD_PAYMENT	카드로 사용자 승인된 결제가 아닙니다.
PAY_CARD_AUTH_REQUEST_ERROR	카드 인증 요청에 실패하였습니다.
NOT_SUPPORTED_RESELLER_SHOP	리셀러로 지정된 가맹점이 아닙니다.
기타
PAYMENT_SHOP_STATE_NOT_NORMAL	결제 불가 가맹점입니다. 가맹점 고객센터로 문의하여 주세요.
PAYMENT_SHOP_STATE_CANNOT_REFUND	결제 불가 가맹점입니다. 가맹점 고객센터로 문의하여 주세요.(사고신고)
COMMON_INVALID_API_KEY	바르지 않은 API key 입니다.
NOT_INTERNAL_SHOP	내부 가맹점이 아닙니다.
COMMON_BREAK_TIME_OF_BANK	지금은 은행 점검 시간입니다. 점검이 끝난 후 사용해주세요.
COMMON_UNAUTHORIZED	Unauthorized Access
REFUND_EXCEED_DAILY	환불 금액이 상점의 일일 환불 한도보다 클 수 없습니다.
EXECUTE_PAY_NOT_APPROVED	아직 구매자가 결제를 승인하지 않았습니다.
PAUSE_USER	일시정지 사용자입니다.
COMMON_TIMEOUT	처리 중 지연이 발생하였습니다. 다시 시도해주세요.
COMMON_THROTTLED	결제 요청이 많아 서비스 이용이 원활하지 않습니다. 잠시 후에 다시 시도해주세요.
COMMON_ITS_NOT_ABLE_TO_CHANGE_STATUS	요청 가능한 상태가 아닙니다.
ESCROW_IMPOSSIBLE_STATUS	에스크로 상태 변경이 불가능합니다.