search

빌링 구매 리스트 조회- 운영툴용 playerId 조건

게임 운영툴에서 구매를 진행한 playerId 기반으로 조회할 때 사용할 수 있는 API

hashtag
기본 정보

  1. 빌링 시스템에 구매 요청된 리스트를 조회하는 API

  2. playerId 조건으로 조회하는 기능으로 게임 운영툴에서만 사용할 목적의 API

circle-exclamation

부하가 큰 조회일 가능성이 있기 때문에 내부적으로 분리된 Read DB를 이용할 수도 있습니다.

  1. 인게임의 일반 결제 로직에서 사용하면 안되는 API입니다.

  2. 운영툴 용도로만 사용해야합니다.

항목
내용
비고

호출주체

게임서버(s2s API)

도메인

각 환경별 도메인

인증 방식

HTTP 헤더 인증 정보

HTTP 메소드

POST

Content-Type

application/json

hashtag
Request

hashtag
HTTP Request end point

POST https://각 환경별 빌링API 도메인/billing/api-game/v1/purchase/optool/playerId/list

hashtag
HTTP Request Header

  • 아래의 HTTP Header들을 API 요청에 포함시켜야합니다.

hashtag
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부터 시작함)

hashtag
HTTP Request Parameter(Sample json)

요청 샘플 json입니다. 하단 curl 커맨드를 참고하셔도 좋습니다.

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

    • 파라미터 boid 중에서 존재하지 않는 잘 못된 boid의 데이터는 응답되지 않습니다.

hashtag
Response property

key

data type

not null

description

example

existNextPageYn

String(1)

Y

다음 페이지 데이터가 존재하는지 여부

  • 참고: 대규모 데이터의 오버헤드 문제 때문에 totalCount기반의 페이징은 제공하지 않음

Y 또는 N

purchaseList

purchaseList json의 array

Y

구매 리스트

  • 대상 데이터가 없으면 빈 array일 수 있음

hashtag
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

currency

String(10)

N

구매 금액의 화폐 단위

USD

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

스토어에 등록된 테스터의 결제 여부

  • 관련 기능 제공하는 스토어에 한해서 제한적으로 제공

hashtag
Sample

hashtag
Success Sample

hashtag
Error Sample

  • pageItemLimit가 너무 클 때

  • 시작과 종료일 범위가 최대 조회기간인 50일을 넘을 때

  • 시작이 종료일보다 나중일 때

hashtag
에러 코드 정의

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

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

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

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

에러코드
비고

SYSTEM_ERROR

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

  • HTTP 상태코드 500 리턴

NOT_ALLOW_AUTH

API 인증 헤더 누락이거나 기타 권한이 없는 요청에서 발생

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

에러코드
비고

INVALID_PARAMETER

hashtag
요청 curl Sample

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

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

마지막 업데이트