자주 묻는 질문

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

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

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

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

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

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

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

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

✓ 토스 서버의 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 재전송 기능은 토스 가맹점 관리자 페이지에서도 확인하실 수 있습니다.

결제 에러 응답코드


아래 내용 참고 부탁드리며, 예고 없이 업데이트될 수 있습니다.

응답 코드 사유
공통
COMMON_SYSTEM_ERROR 시스템 오류로 인해 통신이 원활하지 않습니다.문제가 계속되면 토스 고객센터로 문의해주세요. (1599-4905)
COMMON_INVALID_PARAMETER 요청한 값이 바르지 않습니다.
COMMON_PAY_ERROR 문제가 발생하였습니다.
COMMON_NOT_ENOUGH_CASH 잔액이 부족합니다.
COMMON_EXCEED_LIMIT 한도를 초과하였습니다.
COMMON_ASSET_GET_ACCOUNT_ERROR 계좌 정보 조회에 실패 하였습니다.
PAYMENT_DUPLICATION_ORDER_NO 중복된 주문번호 입니다.
PAYMENT_EXISTING_PAYMENT 이미 존재하는 결제입니다.
COMMON_REFUND_ERROR 환불이 불가능 한 상태입니다.
INACTIVE_USER 탈퇴한 사용자입니다. 환불이 불가능합니다.
REFUND_REFUND_NO_DUPLICATE 동일한 refundNo가 이미 존재합니다.
중복되지 않는 refundNo 로 요청해야 합니다.
REFUND_EXCEED_DAILY 환불 금액이 상점의 일일 환불 한도보다 클 수 없습니다.
COMMON_INVALID_API_KEY 바르지 않은 API key 입니다.
COMMON_BREAK_TIME_OF_BANK 지금은 은행 점검 시간입니다. 점검이 끝난 후 사용해주세요.
EXECUTE_PAY_NOT_APPROVED 아직 구매자가 결제를 승인하지 않았습니다.
PUSH_PAY_HAS_NO_OWNER 해당 전화번호는 토스에 가입되어 있지 않습니다. 오탈자가 없는지 확인해주세요.
COMMON_TIMEOUT 처리 중 지연이 발생하였습니다. 다시 시도해주세요.
REFUND_ALREADY_REFUNDED 이미 환불 되었습니다.
현금영수증
CASH_RECEIPT_JOIN_MEMBER_FAIL 현금영수증 연동회원 신규가입이 실패하였습니다.
CASH_RECEIPT_REGIST_ISSUE_FAIL 현금영수증을 발행하지 못했습니다.
CASH_RECEIPT_ALREADY_ISSUE_FAIL 현금영수증이 이미 발행 되었습니다.
CASH_RECEIPT_ALREADY_CANCEL_FAIL 현금영수증이 이미 취소 되었습니다.
CASH_RECEIPT_CANCEL_ISSUE_FAIL 현금영수증 발행 취소를 하지 못했습니다.
CASH_RECEIPT_REVOKE_REGIST_ISSUE_FAIL 취소 현금영수증을 발행하지 못했습니다.
CASH_RECEIPT_GET_INFO_FAIL 현금영수증 정보 확인에 실패하였습니다.
CASH_RECEIPT_NOT_EXIST 발급된 현금영수증이 존재하지 않습니다.
CASH_RECEIPT_GET_POPUP_URI_FAIL 현금영수증 조회 링크를 가져오지 못했습니다.
CASH_RECEIPT_UNKNOWN_STATUS_CODE 존재하지 않는 현금영수증 상태코드 입니다.
매출전표
SALES_CHECK_NOT_FOUND_USER 매출전표 조회를 위한 사용자 정보가 존재하지 않습니다.
SALES_CHECK_USER_AUTH_FAIL 매출전표 조회를 위한 사용자 정보 인증에 실패하였습니다.
SALES_CHECK_CARD_ONLY 카드결제 건에 대해서만 매출전표 조회가 가능합니다.
PG리셀러
NOT_SUPPORTED_RESELLER_SHOP 리셀러로 지정된 가맹점이 아닙니다.
COMMON_PAY_RESELLER_ERROR 리셀러 결제 처리 중 에러가 발생했습니다.
NOT_APPROVED_CARD_PAYMENT 카드로 사용자 승인된 결제가 아닙니다.
PAY_CARD_AUTH_REQUEST_ERROR 카드 인증 요청에 실패하였습니다.