빌링 구매 리스트 조회

기본 정보

빌링 시스템에 구매 요청된 리스트를 조회하는 API
로직 개발 과정에서 구매 상태 및 기타 정보가 필요할 때 사용
1. 상태 값에 따라서 응답 필드 일부는 null일수 있습니다.(예. 완료가 안되었다면 완료 일시는 null)

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

Request

HTTP Request end point

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

HTTP Request Header

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

HTTP Request Parameter

아래 파라미터들을 Content-Type: application/json으로 호출하면 됩니다.

이름	데이터 타입	설명	예
pjid	String(20)	프로젝트ID 동일 게임이라면 서비스ID가 여러개일 수 있지만 프로젝트ID는 같음	9001
boidList	String array	빌링 예약 후 발급된 빌링 주문ID 리스트 최대 10개까지 가능

이름

데이터 타입

설명

예

pjid

String(20)

프로젝트ID

동일 게임이라면 서비스ID가 여러개일 수 있지만 프로젝트ID는 같음

9001

boidList

String array

빌링 예약 후 발급된 빌링 주문ID 리스트

최대 10개까지 가능

HTTP Request Parameter(Sample json)

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

{
   "pjid":"9001",
   "boidList":[
      "1",
      "2",
      "270"
   ]
}

응답은 JSON Array형태로 전달됩니다.
- 파라미터 boid 중에서 존재하지 않는 잘 못된 boid의 데이터는 응답되지 않습니다.

Response property

key	data type	description	example
boid	String(20)	빌링 시스템의 주문ID	4
purchaseStatus	String(30)	빌링시스템에 구매 상태	코드 표 참고
pjid	String(20)	프로젝트ID	9001
svcId	String(20)	서비스ID	90010020
payment	String(20)	결제가 진행된 스토어(돈을 지급한 행위가 발생한 스토어)	`GOOGLE_PLAY`
appStore	String(20)	앱을 다운로드한 플랫폼 스토어(개발사 입장에서는 배포한 스토어)	`GOOGLE_PLAY`
imid	String(40)	IMID 드림에이지의 IMID로 로그인 후 얻을 수 있음 PJID 내 사용자를 식별하는 고유 Key	`aaaabbbb-ccccddd-fffccc-tttggg`
playerId	String(50)	구매를 진행하는 유저의 ID 게임에서 결제 스콥을 관리하고 싶은 id값으로 사용 드림에이지의 imid값이 될 수도 있음
productId	String(200)	구매 진행하는 상품ID(SKU와 같은 값) 추후 N건의 상품 구매를 지원하기 위해서 array 형태로 변경될 예정으로 사용 금지
price	Decimal(14,4)	구매 금액 Decimal(14,4)정밀도	`2200.0000`
microPrice	Long	구매 금액 micro단위 price에 100만을 곱한 값	`2200000000`
currency	String(10)	구매 금액의 화폐 단위 3글자 포맷의 ISO-4217	USD
reservedAt	String	구매 예약된 일시 `ISO 8601 yyyy-MM-dd'T'HH:mm:ss.SSSXXX 포맷`	`2023-11-26T16:27:58.000+09:00`
completedAt	String	구매 완료 일시 `ISO 8601 yyyy-MM-dd'T'HH:mm:ss.SSSXXX 포맷`	`2023-11-26T14:56:38.000+09:00`
os	String(10)	구매한 디바이스의 OS
paymentOrderId	String(100)	결제가 진행된 payment의 주문ID(스토어/마켓에서 발급한 주문ID)
paymentTesterPurchaseYn	String(1)	스토어에 등록된 테스터의 결제 여부(관련 기능 제공하는 스토어에 한해서 제한적으로 제공)
cancelReason	String(200)	구매상태가 취소일때 사유
canceledAt	String	구매상태가 취소일때 취소일시 `ISO 8601 yyyy-MM-dd'T'HH:mm:ss.SSSXXX 포맷`
memo	String	메모 내용

Sample

Success Sample

{
    "resultCode": "SUCCESS",
    "resultMessage": "request success",
    "resultData": [
        {
            "boid": "1",
            "purchaseStatus": "COMPLETED_BEFORE_CONSUME",
            "pjid": "9001",
            "svcId": "10020000",
            "payment": "GOOGLE_PLAY",
            "appStore": "GOOGLE_PLAY",
            "imid": "aaaabbbb-ccccddd-fffccc-tttggg",
            "playerId": "playerId",
            "productId": "seom_tany_100022",
            "price": 2200.0000,
            "microPrice": 2200000000,
            "currency": "JPY",
            "reservedAt": "2023-11-26T16:27:58.000+09:00",
            "completedAt": "2023-11-26T16:28:08.000+09:00",
            "os": "ANDROID",
            "paymentOrderId": "GPA.3323-4443-4781-49315",
            "paymentTesterPurchaseYn": "N",
            "cancelReason": null,
            "canceledAt": null,
            "memo": null
        },
        {
            "boid": "2",
            "purchaseStatus": "COMPLETED",
            "pjid": "9001",
            "svcId": "10020000",
            "payment": "APPLE_APP_STORE",
            "appStore": "APPLE_APP_STORE",
            "imid": "aaaabbbb-ccccddd-fffccc-tttggg",
            "playerId": "playerId",
            "productId": "seom_popup_400031",
            "price": 0.9900,
            "microPrice": 990000,
            "currency": "USD",
            "reservedAt": "2023-11-26T19:13:08.000+09:00",
            "completedAt": "2023-11-26T19:13:35.000+09:00",
            "os": "IOS",
            "paymentOrderId": "180001803891177",
            "paymentTesterPurchaseYn": "N",
            "cancelReason": null,
            "canceledAt": null,
            "memo": null
        },
        {
            "boid": "270",
            "purchaseStatus": "RESERVED",
            "pjid": "9001",
            "svcId": "10020000",
            "payment": "STEAM",
            "appStore": "STEAM",
            "imid": "aaaabbbb-ccccddd-fffccc-tttggg",
            "playerId": "playerId",
            "productId": "test_steam_package_23",
            "price": null,
            "microPrice": null,
            "currency": null,
            "reservedAt": "2023-11-26T19:14:22.000+09:00",
            "completedAt": null,
            "os": "WIN64",
            "paymentOrderId": null,
            "paymentTesterPurchaseYn": null,
            "cancelReason": null,
            "canceledAt": null,
            "memo": null
        }
    ]
}

Error Sample

{
    "resultCode": "INVALID_PARAMETER",
    "resultMessage": "'boidList' cannot be null."
}

에러 코드 정의

아래와 같은 에러코드가 resultCode에 응답될 수 있습니다. (참고 링크)
아래의 에러코드들은 모든 빌링 API에서 발생 가능한 에러 코드들입니다.
- 해당 에러코드 외에 각 API에서만 발생가능한 에러코드들도 있습니다.
- 각 에러 코드를 바탕으로 필요시 비즈니스 로직을 작성하시면 됩니다.

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

에러코드

비고

SYSTEM_ERROR

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

HTTP 상태코드 500 리턴

NOT_ALLOW_AUTH

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

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

에러코드	비고
INVALID_PARAMETER

요청 curl Sample

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

curl --location 'https://billing-game-api-dev.pub-dev.hybegames.io/billing/api-game/v1/purchase/list' \
--header 'X-Req-Pjid: 9001' \
--header 'X-Auth-Access-Key: test-auth-key' \
--header 'Content-Type: application/json' \
--data '{
   "pjid":"9001",
   "boidList":[
      "1",
      "2",
      "270"
   ]
}'

기본 정보​

Request​

HTTP Request end point​

HTTP Request Header​

HTTP Request Parameter​

HTTP Request Parameter(Sample json)​

Response property​

Sample​

Success Sample​

Error Sample​

에러 코드 정의​

요청 curl Sample​