빌링 시스템에 등록된 판매 가능 상품 리스트 조회(STEAM, PG)

기본 정보

1. 특정 결제 수단(또는 스토어)은 해당 서비스에서 판매 상품을 관리해주지 않고 있습니다. 이런 경우 빌링 시스템에 상품이 등록되어야 빌링 구매 기능을 사용 가능합니다.

   1. 참고: 상품 등록은 일반적으로 사업PM이 개발 스튜디오와 논의 후 빌링 시스템에 등록하고 있습니다.

2. 해당 API는 빌링에 판매 중으로 등록된 상품 리스트를 조회하는 API입니다.

3. 페이징 처리를 구현해주셔야합니다.

4. 게임 서버에 캐시 처리를 추천드립니다.

   1. 게임 서버에서 캐시는 5분을 넘지 않도록 해서 신규 상품 추가 또는 기존 상품 제거가 반영되도록 합니다.

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

Request

HTTP Request end point

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

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으로 호출하면 됩니다.

key	data type	required Y/N	description	example
pjid	String(20)	Y	프로젝트ID 동일 게임이라면 서비스ID가 여러개일 수 있지만 프로젝트ID는 같음	1201
payment	String	Y	빌링 예약 후 발급된 빌링 주문ID 리스트 최대 10개까지 가능
pageItemSize	int	Y	조회할 데이터 갯수(1~100)
pageNo	int	Y	조회할 페이지 번호(1부터 시작함)

Response

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

Response property

key(depth 1)	key(depth 2)	data type	description	example
productInfoListCount		int	상품정보 리스트 건수	10
productInfoList		productInfo json	상품정보 리스트 하위에 상품명 및 가격 리스트 추가로 존재
	productNameList	ProductNameInfo json	상품명 리스트
	productPriceList	ProductPriceInfo json	상품가격 리스트

productInfo JSON

• 해당 데이터가 리스트로 응답됩니다

  key	data type	not null Y/N	description	example
  productId	String	Y	상품 아이디	pg_test_item_1
  productNameList	productNameInfo JSON	Y	상품 명 리스트 다국어 대응된 N건 가능
  productPriceList	productPriceInfo Json	Y	상품 가격 리스트 로컬라이징 대응된 N건 가능

productNameInfo JSON

• 해당 데이터가 리스트로 응답됩니다

key	data type	not null Y/N	description	example
langCd	String	Y	상품명 언어코드. BCP-47 코드	ko-kR
name	String	Y	상품 명(로컬라이징된 상품명)	젬100개 상품

productPriceInfo JSON

• 해당 데이터가 리스트로 응답됩니다.

key	data type	not null Y/N	description	example
currency	String	Y	금액의 3글자 통화코드(ISO_4217)	KRW, EUR, USD, JPY 등
microPrice	Long	Y	상품 금액 micro단위 (예. $0.99는 990,000 µ$. 100만을 곱함)	1000000

Sample

Success Sample

{
  "resultCode": "SUCCESS",
  "resultMessage": "request success",
  "resultData": {
    "productInfoListCount": 2,
    "productInfoList": [
      {
        "productId": "pg_test_item_1",
        "productNameList": [
          {
            "langCd": "en-US",
            "name": "PG_TEST_PRODUCT_1"
          },
          {
            "langCd": "ko-KR",
            "name": "PG테스트상품_1"
          }
        ],
        "productPriceList": [
          {
            "currency": "KRW",
            "microPrice": 1400000000
          },
          {
            "currency": "USD",
            "microPrice": 1000000
          }
        ]
      },
      {
        "productId": "pg_test_item_2",
        "productNameList": [
          {
            "langCd": "en-US",
            "name": "PG_TEST_PRODUCT_2"
          },
          {
            "langCd": "ko-KR",
            "name": "PG테스트상품_2"
          }
        ],
        "productPriceList": [
          {
            "currency": "KRW",
            "microPrice": 2400000000
          },
          {
            "currency": "USD",
            "microPrice": 2000000
          }
        ]
      }
    ]
  }
}

Error Sample

{
  "resultCode": "INVALID_PARAMETER",
  "resultMessage": "Not allow payment code. Allow list: {STEAM,PG}",
  "traceId": "b_e9d90764164d"
}

에러 코드 정의

• 아래와 같은 에러코드가 resultCode에 응답될 수 있습니다. (참고 링크)

• 아래의 에러코드들은 모든 빌링 API에서 발생 가능한 에러 코드들입니다.

  • 해당 에러코드 외에 각 API에서만 발생가능한 에러코드들도 있습니다.

  • 각 에러 코드를 바탕으로 필요시 비즈니스 로직을 작성하시면 됩니다.

에러코드	비고
SYSTEM_ERROR	빌링 API에서 발생한 시스템 에러 HTTP 상태코드 500 리턴
NOT_ALLOW_AUTH	API 인증 헤더 누락이거나 기타 권한이 없는 요청에서 발생

• 아래 에러 코드들은 해당 API에서 발생 가능한 추가 에러 코드들입니다.

에러코드	비고
INVALID_PARAMETER

요청 curl Sample

• 도메인 및 인증 헤더 등은 변경 필요

curl -X 'POST' \
  'http://localhost:10001/billing/api-game/v1/purchase/product/sale/list' \
  -H 'accept: application/json;charset=UTF-8' \
  -H 'X-Req-Pjid: 입력필요' \
  -H 'X-Auth-Access-Key: 입력필요' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'pjid=1201&payment=PG&pageItemSize=50&pageNo=1'