본문으로 건너뛰기

Epic Gmes 구매 검증 요청

기본 정보​

  1. Epic Games 유저의 구매 완료 요청에 대한 결제 내용을 검증합니다.
정보
  • '기본 게임'과 같은 영구적인 지속성 상품은 오너쉽만 검증합니다.(참고 링크)
  • ‘가상 화폐’와 같은 소모성의 경우에는 권한(entitlements )까지 검증합니다.(링크)
항목내용비고
호출주체게임서버(s2s API)
도메인각 환경별 도메인
인증방식HTTP 헤더 인증 정보
HTTP 메소드POST
Content-Typeapplication/json

Request​

HTTP Request end point​

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

HTTP Request Header​

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

HTTP Request Parameter​

  • Content-Type: application/json 으로 요청되어야 합니다.
  • 검증에는 영수증 관련 정보나 escape 등의 문제 때문에 사용측에서 body로 전송하는게 용이한 경우가 많음
이름데이터 타입필수 Y/N설명예
reqIdString(100)Y중복 요청을 막거나 요청 추적을 위한 값userId_UUID 등과 같은 방식으로 생성
pjidString(20)Y프로젝트ID (동일 게임이라면 서비스ID가 여러개일 수 있지만 프로젝트ID는 같음)1004
boidString(20)Y빌링 시스템 구매 예약 API를 통해서 생성된 ID1234
playerIdString(50)Y주문 완료를 진행하는 유저ID
epicUserIdString(50)YEpic Games 구매후 획득한 권한 ID25663c96bb7a40a0a3c7998e42b81234
entitlementIdString(50)YEpic Games 구매후 획득한 권한 ID8fe744a7633d4618a07a371d1dd5f443
productIdString(200)Y구매 진행하는 상품ID(SKU와 같은 값) - 빌링 시스템과 Epic Games 개발 포털에 상품 등록이 선행되어야 함epic_test_gem_01

Response​

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

Sample​

Success sample​

  • 성공으로 응답하면 게임 서버는 유저에게 지속성의 경우 실행 권한을 부여, 소모성 상품의 경우 아이템 및 재화를 지급하고, 이후 빌링 완료처리 API를 호출해서 최종 완료해주시면 됩니다.
    • 소모성 상품의 경우 완료 처리 요청 때 Epic Games에 리딤까지 지원합니다.
    • 게임 서버에서는 필요 로그를 게임DB 또는 로그 DB에 저장해주시는게 좋습니다.
{
    "resultCode": "SUCCESS",
    "resultMessage": "Verification successful. Status: VERIFY_SUCCESS"
}

Error sample​

  • 구매 완료된 boid에 대해서 다시 완료 요청
{
    "resultCode": "INVALID_PARAMETER",
    "resultMessage": "'boid: 1' purchaseState is not BILLING_RESERVED. The current value is 'COMPLETED"
}
  • 구매 완료하지 않은 boid에 대한 요청
{
    "resultCode": "INVALID_PARAMETER",
    "resultMessage": "'boid: 1' purchaseStatus is not RESERVED. The current value is 'VERIFY_SUCCESS'"
}

에러 코드 정의​

  • 아래와 같은 에러코드가 resultCode에 응답될 수 있습니다. (참고 링크)
  • 아래의 에러코드들은 모든 빌링 API에서 발생 가능한 에러 코드들입니다.
    • 해당 에러코드 외에 각 API에서만 발생가능한 에러코드들도 있습니다.
    • 각 에러 코드를 바탕으로 필요시 비즈니스 로직을 작성하시면 됩니다.
에러코드비고
SYSTEM_ERROR빌링 API에서 발생한 시스템 에러 (HTTP 상태코드 500 리턴)
NOT_ALLOW_AUTHAPI 인증 헤더 누락이거나 기타 권한이 없는 요청에서 발생
  • 아래 에러 코드들은 해당 API에서 발생 가능한 추가 에러 코드들입니다.
에러코드비고
INVALID_PARAMETER
EXTERNAL_API_ERROR빌링 API가 호출하는 외부 API가 에러인 경우 (예: Epic Games Ecom WEB API 장애로 인한 오류. 게임 서버는 지수 백오프 알고리즘으로 재시도하거나 클라이언트의 미처리 영수증 처리 기능으로 처리할 수 있음)

요청 curl 샘플​

  • 도메인 및 인증 헤더 등은 변경 필요
curl -X 'POST' \
  'https://API도메인/billing/api-game/v1/purchase/epic/games/verify' \
  -H 'accept: application/json;charset=UTF-8' \
  -H 'X-Req-Pjid: PJID값' \
  -H 'X-Auth-Access-Key: API인증키' \
  -H 'Content-Type: application/json;charset=UTF-8' \
  -d '{
  "reqId": "userId_verify_98b50907-0928-493b-a816-dac8dbca1f54",
  "boid": "4",
  "playerId": "playerId",
  "pjid": "PJID값",
  "epicUserId": "25663c96bb7a40a0a3c7998e42b81234",
  "entitlementId": "8fe744a7633d4618a07a371d1dd5f443",
  "productId": "epic_test_gem_01"
}'