빌링 구매 리스트 조회

기본 정보

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

2. 로직 개발 과정에서 구매 상태 및 기타 정보가 필요할 때 사용

   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개까지 가능

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 하이브IM의 IMID로 로그인 후 얻을 수 있음 PJID 내 사용자를 식별하는 고유 Key	aaaabbbb-ccccddd-fffccc-tttggg
playerId	String(50)	구매를 진행하는 유저의 ID 게임에서 결제 스콥을 관리하고 싶은 id값으로 사용 하이브 IM의 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 인증 헤더 누락이거나 기타 권한이 없는 요청에서 발생

• 아래 에러 코드들은 해당 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"
   ]
}'