이제, 토스페이 서비스에 대해 좀 더 자세하게 안내드립니다.
이 항목은 지속적으로 업데이트될 예정이며, 궁금하신 사항은 언제든지 토스페이팀(support-pay@toss.im)으로 의견주세요!
토스페이 연동 구축 시, 가맹점은 두 가지 방식으로 테스트를 진행할 수 있습니다.
각각의 방법을 확인하신 후, 적합한 방법을 선택하여 테스트를 진행해 주세요.
운영 환경(pay.toss.im)에서 테스트용 apiKey를 사용해 테스트를 진행한 후,
테스트 완료 시 실거래용 apiKey로 교체하여 실제 사용자들에게 서비스를 오픈하는 방식입니다.
개발 환경(alpha-pay.toss.im)에서 테스트 진행 후, 운영 환경으로 전환하여 서비스를 오픈하는 방식입니다.
개발 환경에서 테스트를 위해 별도의 개발 apiKey가 발급됩니다.
구매자는 인증을 완료했지만 가맹점 retUrl로 결제 결과가 오지 않는 경우나, 토스 서버로 부터 resultCallback 결과를 받지
못한다면 먼저 방화벽 설정을 살펴봐야 합니다.
✓ 토스페이 방화벽은 제한없이 모두 오픈되어 있습니다.
✓ 각 케이스 별 구분이 어렵다면 outbound, inbound 정책에 맞게 토스 IP를 모두 추가해 주셔도 됩니다.
✓ 가맹점이 설정한 resultCallback URL 에 443 이외의 포트가 포함되어 있다면 접근이 어려울 수 있으니 유의해주세요.
✓ 토스 서버의 IP가 추가되는 경우 사전에 공지메일을 발송해 드립니다.
토스 인코딩 방식은 UTF-8 형식을 사용합니다.
가맹점에서 토스 서버로 한글이 포함된 값(주문번호, 상품명 등)을 보내주실 때, UTF-8 형식으로 보내주셔야
정상적인 response값을 확인하실 수 있습니다.
유의해 주세요! 깨진 한글이 유입되면 토스 서버는 필수 값 체크를 못해 500에러 등의 오류가 발생할 수 있습니다.
토스는 일반 은행계좌에서 토스머니로 충전 시 최대 10초의 타임아웃 시간을 설정합니다.
따라서, 가맹점에서는 10초 + 3~5초 정도의 대기 시간을 잡아주시면 타임아웃으로 인한 대사 불일치 거래건이 발생하지 않습니다.
(처리 지연으로 가맹점은 취소 처리했으나 토스는 승인되는 케이스 방지)
토스 이슈가 아닌 은행망 이슈를 제외하면 타임아웃으로 인한 거래 지연은 발생하지 않습니다.
✓ 결제수단 구분 없이 모두 동일하게 설정하셔도 무방합니다.
✓ 양사간 거래 확인을 위하여 정산대사를 함께 연동하시길 권장드립니다.
요청 가맹점에 한하여 별도로 제공해 드리고 있으며, 신청은 support-pay@toss.im 으로 주시기 바랍니다.
retUrl의 이동은 토스 web page에서 처리되는 로직으로 일반적인 경우 처리를 보장하지만 특별한 상황에서 실패할 수 있습니다.
특별한 상황이란, 구매자가 결제 중에 앱을 종료하거나 백그라운드 처리를 하는 등의 이탈로 JavaScript 로직이 처리될 수 없는 경우입니다.
이 경우 구매자가 다시 결제 화면으로 돌아와서 '결제완료' 버튼을 클릭한다면 retUrl 로의 이동을 재시도 하게 됩니다.
다만, 구매자가 재시도를 하지 않는 경우에는 retUrl로 이동하지 못하는 상황이 발생할 수 있습니다.
토스 서버에서 결제처리가 완료되고 나면 해당 결제건의 상태는 PAY_COMPLETE로 변경되고, 구매자를retUrl로 이동시킵니다.
동시에 토스 서버에서 가맹점 서버의 resultCallback URL로 callback을 요청합니다.
retUrl은 단순 web page의 이동으로
토스에서 결제 성공 여부를 확인 할 수 없고, 구매자 상황에 따라 실행을 보장할 수 없기 때문에 resultCallback을 활용하시길 권장드립니다.
또한, 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 | 카드결제 건에 대해서만 매출전표 조회가 가능합니다. |
| 자동결제 | |
| NOT_SUPPORTED_BILLING_KEY_SHOP | 자동결제를 지원하지 않는 상점입니다. support-pay@toss.im 으로 문의해주세요. |
| BILLING_KEY_ALREADY_ACTIVATED | 이미 활성화 된 자동결제가 존재합니다. |
| BILLING_KEY_REGISTRATION_CANCELLED | 자동결제 등록이 취소되었습니다. |
| BILLING_KEY_UNREGISTERED_BY_CANCEL | 이미 자동결제 등록이 취소되어 더이상 진행할 수 없습니다.\n처음부터 다시 진행해주세요. |
| BILLING_KEY_AUTH_ERROR | 인증 가능 시간이 만료 되었습니다 |
| BILLING_KEY_USER_CI_ERROR | 토스에 등록된 사용자 정보가 일치하지 않습니다. |
| BILLING_KEY_REMOVE_NOT_ALLOWED_SHOP | 자동결제 삭제가 허용된 가맹점이 아닙니다. |
| ALREADY_EXISTED_AUTH | 이미 요청 된 인증이 존재합니다. |
| NOT_SUPPORTED_PAYMENT_METHOD | 자동결제에서 지원하지 않는 결제 수단입니다. |
| EXIST_ACTIVATED_BILLING_KEY_USING_THIS_METHOD | 자동결제가 등록 된 결제 수단은 삭제 할 수 없습니다. 자동결제를 해지해주세요. |
| COMMON_BILLING_KEY_NOT_FOUND | 자동결제 정보를 찾을 수 없습니다. |
| CORE_USER_ERROR | 사용자가 존재하지 않습니다. |
| 리셀러 | |
| 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 | 에스크로 상태 변경이 불가능합니다. |
토스머니 결제의 경우 사용자가 선택한 계좌의 정보를 함께 전달합니다.
| 은행 코드(accountBankCode) | 은행 명(accountBankName) |
| 002 | KDB산업은행 |
| 003 | IBK기업은행 |
| 004 | KB국민은행 |
| 005 | KEB하나은행 |
| 007 | 수협은행 |
| 011 | NH농협은행 |
| 020 | 우리은행 |
| 023 | SC은행 |
| 027 | 씨티은행 |
| 031 | 대구은행 |
| 032 | 부산은행 |
| 034 | 광주은행 |
| 035 | 제주은행 |
| 037 | 전북은행 |
| 039 | 경남은행 |
| 045 | MG새마을금고 |
| 048 | 신협 |
| 050 | 저축은행 |
| 064 | 산림조합 |
| 071 | 우체국 |
| 081 | 하나은행 |
| 088 | 신한은행 |
| 089 | 케이뱅크 |
| 090 | 카카오뱅크 |
| 092 | 토스뱅크 |
| 103 | SBI저축은행 |
| 218 | KB증권 |
| 230 | 미래에셋증권 |
| 238 | 미래에셋증권 |
| 240 | 삼성증권 |
| 243 | 한국투자증권 |
| 247 | NH투자증권 |
| 261 | 교보증권 |
| 262 | 하이투자증권 |
| 263 | 현대차투자증권 |
| 264 | 키움증권 |
| 265 | 이베스트증권 |
| 266 | SK증권 |
| 267 | 대신증권 |
| 269 | 한화투자증권 |
| 270 | 하나증권 |
| 271 | 토스증권 |
| 278 | 신한투자증권 |
| 279 | DB금융투자 |
| 280 | 유진투자 |
| 287 | 메리츠증권 |
| 888 | 토스머니 |
| 889 | 토스포인트 |
