본문으로 건너뛰기

Epic Gmes 구매 완료한 지속성 상품의 오너쉽 정보 조회

기본 정보​

  1. Epic Games 유료 ‘기본게임’과 같은 지속성 상품의 오너쉽 정보를 가져오는 API입니다.
  2. 빌링에 구매 완료된 ‘지속성 상품’에 대해서 Epic Games의 Ecom웹 API(링크)로 오너쉽 정보조회 후 응답합니다.
  3. 게임 패키지(기본게임)를 유료로 판매하는 경우, 오너쉽을 확인하여 플레이 허용 여부를 결정할 때 사용 가능합니다.
    1. 예) 게임 시작할 때 해당 API를 호출하여 게임 실행을 허용할지 판단할 수 있습니다.
  4. Epic Games의 API를 중개 처리하여 호출하기 때문에 Timeout은 여유있게 설정하는게 좋습니다.(ex. 20초)
  5. 기본게임 실행에 중요한 영향을 줄 수 있기 때문에, Epic Games의 API 응답이 없으면 Fallback으로 빌링 DB의 완료 상태 여부로 응답하는 기능을 제공합니다.
항목내용비고
호출주체게임서버(s2s API)
도메인각 환경별 도메인
인증방식HTTP 헤더 인증 정보
HTTP 메소드POST
Content-Typeapplication/x-www-form-urlencoded

Request​

HTTP Request end point​

POST https://각 환경별 빌링시스템 도메인/billing/api-game/v1/purchase/epic/games/completed/ownership/get

HTTP Request Header​

  • 아래의 HTTP Header들을 API 요청에 포함시켜야합니다.
이름값비고
X-Req-Pjid프로젝트ID기술 PM 등에게 전달받은 프로젝트ID
X-Auth-Access-Key인증용 키기술 PM 등에게 전달받은 해당 게임용 인증 키

HTTP Request Parameter​

  • Content-Type: application/x-www-form-urlencoded 으로 요청되어야 합니다.
이름데이터 타입필수 여부설명예
pjidString(20)Y

프로젝트ID

  • 동일 게임이라면 서비스ID가 여러개일 수 있지만 프로젝트ID는 같음
1202
boidString(20)Y빌링 시스템 구매 예약 API를 통해서 생성된 ID1234
productIdString(200)Y

구매 예약 후 완료한 상품ID

  • 빌링 시스템과 Epic Games 개발 포털에 상품 등록이 선행되어야 함
playerIdString(50)Y

결제를 진행하는 유저의 ID

  • 게임에서 결제 스콥을 관리하고 싶은 id값으로 사용
  • 회원 플랫폼의 IMID의 값을 사용할 수도 있음

Response​

응답은 JSON형태로 전달됩니다.

Response property​

keydata typedescriptionexample
playerIdString(50)구매를 진행한 유저의 ID
productIdString(200)구매한 상품IDepic_base_game
ownedboolean

권한 소유 여부

  • Epic 오너쉽 검증 API(링크)로 확인 후 응답

  • Fallback을 지원하여 Epic API가 에러라면 true로 응답 → 게임 실행 허용

    • 빌링에 완료된 상태 체크로 최소한의 검증은 진행
true 또는 false

Sample​

Success sample​

{
  "resultCode": "SUCCESS",
  "resultMessage": "request success",
  "resultData": {
    "playerId": "playerId",
    "productId": "epic_base_game",
    "owned": true
  }
}

Error sample​

  • 구매 완료된 상품과 다른 상품의 정보조회 요청
{
  "resultCode": "INVALID_PARAMETER",
  "resultMessage": "ProductId mismatch. Completed: epic_base_game_01, Req: epic_gem_01",
  "traceId": "b_5e019bc114e7"
}
  • 소모성 구매에 대한 오너쉽 정보 요청
{
  "resultCode": "INVALID_PARAMETER",
  "resultMessage": "Ownership check is only available for durable products. ProductId: epic_test_gem_01",
  "traceId": "b_6899334d6fca"
}

에러 코드 정의​

  • 아래와 같은 에러코드가 resultCode에 응답될 수 있습니다. (참고 링크)
  • 아래의 에러코드들은 모든 빌링 API에서 발생 가능한 에러 코드들입니다.
    • 해당 에러코드 외에 각 API에서만 발생가능한 에러코드들도 있습니다.
    • 각 에러 코드를 바탕으로 필요시 비즈니스 로직을 작성하시면 됩니다.
에러코드비고
SYSTEM_ERROR

빌링 API에서 발생한 시스템 에러

  • HTTP 상태코드 500 리턴
NOT_ALLOW_AUTHAPI 인증 헤더 누락이거나 기타 권한이 없는 요청에서 발생
  • 아래 에러 코드들은 해당 API에서 발생 가능한 추가 에러 코드들입니다.
에러코드비고
INVALID_PARAMETER

요청 curl 샘플​

  • 도메인 및 인증 헤더 등은 변경 필요
curl -X 'POST' \
  'http://localhost:10001/billing/api-game/v1/purchase/epic/games/completed/ownership/get' \
  -H 'accept: application/json;charset=UTF-8' \
  -H 'X-Req-Pjid: 1202' \
  -H 'X-Auth-Access-Key: 인증키 입력' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'pjid=1202&boid=1&productId=epic_base_game_01&playerId=playerId'