빌링 구매 리스트 조회- 운영툴용 playerId 조건
게임 운영툴에서 구매를 진행한 playerId 기반으로 조회할 때 사용할 수 있는 API
기본 정보
빌링 시스템에 구매 요청된 리스트를 조회하는 API
playerId 조건으로 조회하는 기능으로 게임 운영툴에서만 사용할 목적의 API
부하가 큰 조회일 가능성이 있기 때문에 내부적으로 분리된 Read DB를 이용할 수도 있습니다.
인게임의 일반 결제 로직에서 사용하면 안되는 API입니다.
운영툴 용도로만 사용해야합니다.
Request
HTTP Request end point
POST https://각 환경별 빌링API 도메인/billing/api-game/v1/purchase/optool/playerId/listHTTP Request Header
아래의 HTTP Header들을 API 요청에 포함시켜야합니다.
HTTP Request Parameter
아래 파라미터들을 Content-Type: application/json으로 호출하면 됩니다.
이름
데이터 타입
필수여부
설명
예
pjid
String(20)
Y
프로젝트ID
동일 게임이라면 서비스ID가 여러개일 수 있지만 프로젝트ID는 같음
1201
playerId
String(50)
Y
구매를 진행했던 유저의 ID(게임에서 결제 스콥을 관리하고 싶은 id값으로 사용. 게임에서 추가 구분이 없다면 imid를 사용할 수도 있음)
purchaseStatus
String(30)
N
빌링시스템에 구매 상태
코드 표 참고
startReservedAtUnixTS
Long
Y
예약일시 기준의 조회 범위: 시작
시작~종료는 최대 50일 범위만 가능
UNIX timestamp 포맷
1753153578
endReservedAtUnixTS
Long
Y
예약일시 기준의 조회 범위: 종료
시작~종료는 최대 50일 범위만 가능
UNIX timestamp 포맷
1756549738
pageItemSize
int
Y
한 페이지에서 가져올 데이터 개수(1~100)
pageNo
int
Y
조회할 페이지 번호(1부터 시작함)
HTTP Request Parameter(Sample json)
요청 샘플 json입니다. 하단 curl 커맨드를 참고하셔도 좋습니다.
응답은 JSON Array형태로 전달됩니다.
파라미터 boid 중에서 존재하지 않는 잘 못된 boid의 데이터는 응답되지 않습니다.
Response property
key
data type
not null
description
example
existNextPageYn
String(1)
Y
다음 페이지 데이터가 존재하는지 여부
참고: 대규모 데이터의 오버헤드 문제 때문에 totalCount기반의 페이징은 제공하지 않음
Y 또는 N
purchaseList
purchaseList json의 array
Y
구매 리스트
대상 데이터가 없으면 빈 array일 수 있음
purchaseList Json
- 구매 상태 등에 따라서 일부 필드의 값은 null일 수 있습니다.
key
data type
not null
description
example
boid
String(20)
Y
빌링 시스템의 주문ID
4
reservedAtUnixTS
Long
Y
구매 예약된 일시
Unix Timestamp 타입
1720523107
pjid
String(20)
Y
프로젝트ID
1201
svcId
String(20)
Y
서비스ID
121010041
purchaseStatus
String(30)
Y
빌링시스템에 구매 상태
코드 표 참고
payment
String(20)
Y
결제가 진행된 스토어
돈을 지급한 행위가 발생한 스토어
GOOGLE_PLAY
appStore
String(20)
Y
앱을 다운로드한 플랫폼 스토어
개발사 입장에서는 배포한 스토어
GOOGLE_PLAY_PC
imid
String(40)
N
IMID를 미 사용하는 게임인 경우 null
IMID
플랫폼 회원체계의 IMID로 로그인 후 얻을 수 있음
PJID 내 사용자를 식별하는 고유 Key
aaaabbbb-ccccddd-fffccc-tttggg
playerId
String(50)
Y
구매를 진행한 유저의 ID
게임에서 결제 스콥을 관리하고 싶은 id값으로 사용
IMID와 동일한 값일 수도 있음
productId
String(50)
Y
구매 진행한 상품ID
totalMicroPrice
Long
Y
구매 금액 전체의 micro단위
price에 100만을 곱한 값
2200000000
completedAtUnixTS
Long
N
구매 완료된 일시
Unix Timestamp 타입
1720523107
canceledAtUnixTS
Long
N
구매 취소된 일시
Unix Timestamp 타입
1720523107
os
String(10)
Y
구매한 디바이스의 OS
paymentOrderId
String(100)
N
결제가 진행된 payment의 주문ID
스토어/마켓에서 발급한 주문ID
paymentTesterPurchaseYn
String(1)
N
스토어에 등록된 테스터의 결제 여부
관련 기능 제공하는 스토어에 한해서 제한적으로 제공
Sample
Success Sample
Error Sample
pageItemLimit가 너무 클 때
시작과 종료일 범위가 최대 조회기간인 50일을 넘을 때
시작이 종료일보다 나중일 때
에러 코드 정의
아래와 같은 에러코드가 resultCode에 응답될 수 있습니다. (참고 링크)
아래의 에러코드들은 모든 빌링 API에서 발생 가능한 에러 코드들입니다.
해당 에러코드 외에 각 API에서만 발생가능한 에러코드들도 있습니다.
각 에러 코드를 바탕으로 필요시 비즈니스 로직을 작성하시면 됩니다.
SYSTEM_ERROR
빌링 API에서 발생한 시스템 에러
HTTP 상태코드 500 리턴
NOT_ALLOW_AUTH
API 인증 헤더 누락이거나 기타 권한이 없는 요청에서 발생
아래 에러 코드들은 해당 API에서 발생 가능한 추가 에러 코드들입니다.
INVALID_PARAMETER
요청 curl Sample
도메인 및 인증 헤더 등은 변경 필요
Last updated