[IAP] get-order-status(서버 주문조회) 검증 시 userKey 관련 + 샌드박스에서 NOT_FOUND 이슈 확인 요청

이 글의 성격은 무엇인가요?

질문 / 문제 해결

내용을 설명해주세요

안녕하세요.
앱인토스 Unity(WebGL) 게임에서 IAP 결제를 구현 중입니다.

현재 구조는 아래와 같습니다.

게임 로그인(유저 식별용): AIT.GetUserKeyForGame() 사용 → 서버에 tossGameUserKey로 저장
토스 로그인(결제 조회용): appLogin → generate-token → login-me로 userKey 획득 → 서버에 tossLoginUserKey로 저장

<결제 처리>
AIT.IAPCreateOneTimePurchaseOrder 호출 후,
서버에서 mTLS로 /api-partner/v1/apps-in-toss/order/get-order-status를 호출해
orderId를 검증하고, 상태에 따라 지급 처리하려고 합니다.

그런데 샌드박스에서 결제 테스트 시,
서버 get-order-status가 NOT_FOUND로 떨어져서,아래 내용을 확인하고 싶습니다.

<질문 1>
서버 주문조회(get-order-status)에서 사용하는 userKey는 “토스 로그인 userKey”만 가능한가요?
문서에 “결제 상태 조회 API 사용을 위해서는 토스 로그인 연동을 먼저 진행”이라는 문구가 있어
토스 로그인 userKey가 필요하다고 이해했습니다.

x-toss-user-key는 반드시 login-me에서 받은 토스 로그인 userKey만 사용해야 하나요?
AIT.GetUserKeyForGame()로 받은 게임 키(해시)는 주문조회 검증에 사용할 수 없는지 확인 부탁드립니다.

추가로, 위가 맞다면 구현 패턴은 아래처럼 가는 게 권장인지 궁금합니다.
“유저 식별/게임 로그인”은 GetUserKeyForGame()
“결제 직전(또는 결제 기능 접근 시)”에만 토스 로그인을 유도해서 userKey를 확보
서버 get-order-status 검증은 tossLoginUserKey로 수행
=> 이런 방식이 권장 플로우인지 확인 부탁드립니다.

<질문 2>
샌드박스에서는 서버 get-order-status 방식으로 결제 테스트가 불가능한가요?
샌드박스에서 결제 후 생성된 orderId를 서버에서 get-order-status로 조회하면 NOT_FOUND가 발생합니다.

샌드박스에서 생성된 orderId는 서버 get-order-status로 조회가 원래 안 되는지,
(제한/정책/테스트 주문이라서 등) 확인 부탁드립니다.

만약 샌드박스에서 서버 주문조회 방식 테스트가 불가하다면,
서버 주문조회 기반 검증(E2E) 을 테스트하려면 토스 앱(QR 실행)에서 실제 결제를 해야만 하는 구조인가요?
또 실결제 없이 서버 주문조회 검증을 테스트할 수 있는 방법
(예: 별도 테스트 모드/테스트 주문/가짜 결제)이 있는지 궁금합니다.

<참고 정보>
샌드박스 환경에서 테스트 중입니다.
서버 호출은 mTLS로 NOTE: request는 정상적으로 들어가고, 응답 status만 NOT_FOUND입니다.

x-toss-user-key에는 login-me에서 받은 값(숫자 형태의 userKey)을 문자열로 넣고 있습니다. (예: “4368199”)

가능하면 **권장 아키텍처(게임키+토스로그인키 운용 방식)**와
샌드박스에서의 테스트 한계/대체 방법을 함께 안내 부탁드립니다.

감사합니다.

안녕하세요 :slight_smile:
많이 헷갈리셨을 것 같아요. 개발자 센터 가이드를 조금 더 상세하게 보강해보겠습니다 :cry:

  1. x-toss-user-key는 토스 로그인 연동을 통해서 받은 userKey만 사용이 가능합니다.
    hash로는 주문 조회 검증에 사용이 불가능해요.
    게임 로그인 기능은 서버가 없는 경우에도 유저는 식별되어야하는 상황에서 최초 기획되었습니다.
    현재 클라이언트 단의 SDK를 통해 주문조회가 가능하지만, 서버간 조회 방식이 아니기때문에 완전한 무결성을 보장하기는 어렵다는 점 인지하고 있습니다 :cry:
    내부적으로 조금 더 논의해보겠습니다.

  2. 샌드박스에서는 get-order-status 방식 결제 테스트가 불가합니다 :cry:
    주문이 실제로 생성되는 것은 아니어서 NOT_FOUND 에러가 발생하셨을 것 같아요.
    현재로선 E2E 테스트를 위해 토스앱에서 실 결제가 진행되어야 합니다.