빌링 시스템에 등록된 판매 가능 상품 리스트 조회(STEAM, PG)
기본 정보
- 특정 결제 수단(또는 스토어)은 해당 서비스에서 판매 상품을 관리해주지 않고 있습니다. 이런 경우 빌링 시스템에 상품이 등록되어야 빌링 구매 기능을 사용 가능합니다.
- 참고: 상품 등록은 일반적으로 사업PM이 개발 스튜디오와 논의 후 빌링 시스템에 등록하고 있습니다.
- 해당 API는 빌링에 판매 중으로 등록된 상품 리스트를 조회하는 API입니다.
- 페이징 처리를 구현해주셔야합니다.
- 게임 서버에 캐시 처리를 추천드립니다.
- 게임 서버에서 캐시는 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
| 1201 |
| payment | String | Y | 빌링 예약 후 발급된 빌링 주문ID 리스트
| |
| 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에서 발생한 시스템 에러
|
| 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'