PSN 구매 검증 요청

기본 정보

1. PSN entitlement 실조회를 통해 구매를 검증하는 API입니다.
2. 유저가 실제 PSN 스토어에서 구매를 완료한 뒤 호출합니다.

경고

• 해당 playerId의 PSN 유저 토큰이 사전 발급되어 있어야 합니다. 게임서버가 PSN 유저 토큰 발급(auth/token)을 선행해야 합니다. 응답 resultCode가 USER_ACCESS_TOKEN_NOT_VALID이면 인가코드를 재취득해 토큰 발급을 다시 호출한 뒤 verify를 재시도하세요.
• reqId는 검증 성공 시 저장되어 재사용이 불가합니다. 재호출 시 새 값을 사용하세요.(중복이면 INVALID_PARAMETER 응답)

항목	내용	비고
호출주체	게임서버(s2s API)
도메인	각 환경별 도메인
인증 방식	HTTP 헤더 인증 정보
HTTP 메소드	POST
Content-Type	application/json

Request

HTTP Request end point

POST https://각 환경별 빌링시스템 도메인/billing/api-game/v1/purchase/psn/verify

HTTP Request Header

• 아래의 HTTP Header들을 API 요청에 포함시켜야합니다.

이름	값	비고
X-Req-Pjid	프로젝트ID	기술 PM 등에게 전달받은 프로젝트ID
X-Auth-Access-Key	인증용 키	기술 PM 등에게 전달받은 해당 게임용 인증 키

HTTP Request Body

• 아래 필드들을 Content-Type: application/json 으로 호출하면 됩니다.

key	type	required	설명
reqId	String	Y	요청 유니크 ID - 검증 성공 시 저장되어 재사용 불가
pjid	String	Y	프로젝트ID
boid	String	Y	구매 예약 응답의 빌링 주문ID
playerId	String	Y	결제 유저 ID - 토큰 발급한 ID와 동일해야 함
entitlementLabel	String	Y	PSN entitlement 라벨(소니 백오피스 상품 등록 시 발급된 값) - 빌링 상품등록 시 매핑된 라벨과 일치해야 함(불일치 시 INVALID_PARAMETER)
productId	String	Y	예약한 상품과 동일해야 함

Response

• 별도 resultData 없이 resultCode로 성공 여부를 판단합니다.

Success sample

{ "resultCode": "SUCCESS", "resultMessage": "Success verify. ..." }

실패 응답

• 비즈니스 실패도 HTTP 200으로 응답됩니다. HTTP status가 아닌 resultCode로 분기하세요. SYSTEM_ERROR(500)·NOT_ALLOW_AUTH(인증 헤더 오류)는 전 API 공통.

resultCode	HTTP	발생 케이스	게임서버 대응
USER_ACCESS_TOKEN_NOT_VALID	200	PSN 유저 토큰 미발급/만료/무효(303112)	인가코드 재취득 후 PSN 유저 토큰 발급(auth/token) 재호출 → verify 재시도
DUPLICATE_REQUEST	200	중복 verify(이미 검증된 지속성 entitlement, 소모형 잔여 useLimit이 진행중 건으로 다 찬 경우)	이미 검증된 건이면 complete 진행 여부 확인
INVALID_PARAMETER	200	예약 없음/상품·라벨 불일치/entitlement 미소유·비활성/미지원 상품유형, reqId 재사용·동시 verify 충돌(중복 요청)	요청값·상품 등록 상태 확인. 정상 다중 구매의 동시 충돌이면 verify 재호출로 해소됨
EXTERNAL_API_ERROR	200	PSN API 호출 실패(통신 오류 포함)	재시도

{
  "resultCode": "USER_ACCESS_TOKEN_NOT_VALID",
  "resultMessage": "PSN 유저 토큰 없음. 게임서버가 인가코드 교환(/auth/token)을 먼저 호출해야 합니다. pjid=1201 | playerId=tester01",
  "traceId": "billing_01H..."
}

요청 curl 샘플

• 샘플 curl 커맨드입니다. 요청 정보에 맞게 변경해서 호출하세요.

curl -X 'POST' \
  'https://API도메인/billing/api-game/v1/purchase/psn/verify' \
  -H 'X-Req-Pjid: PJID값' \
  -H 'X-Auth-Access-Key: API 인증키' \
  -H 'Content-Type: application/json' \
  -d '{"reqId":"tester01_verify_98b50911-0928-493b-a816-dac8dbca1f53","pjid":"1201","boid":"발급된 boid","playerId":"tester01","entitlementLabel":"ENTITLEMENT_LABEL","productId":"psn_gem_01"}'