빌링 구매 리스트 조회

기본 정보

빌링 시스템에 구매 요청된 리스트를 조회하는 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개까지 가능

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

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

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"
   ]
}'

Previous빌링 API 에러 코드 목록 Next빌링 시스템에 등록된 판매 가능 상품 리스트 조회(STEAM, PG)

Last updated 11 months ago