ONE Store 구매를 위한 예약
기본 정보
ONE Store 관리상품의 ‘소모성 상품 구매’를 시작하기 위해서 빌링 시스템에 예약을 위한 API입니다.
복수개의 수량 구매를 지원합니다.
호출주체
게임서버(s2s API)
HTTP 메소드
POST
Content-Type
application/x-www-form-urlencoded
Request
HTTP Request end point
POST https://각 환경별 빌링시스템 도메인/billing/api-game/v1/purchase/onestore/inapp/managed/reserveHTTP Request Header
아래의 HTTP Header들을 API 요청에 포함시켜야합니다.
X-Req-Pjid
프로젝트ID
기술 PM 등에게 전달받은 프로젝트ID
X-Auth-Access-Key
인증용 키
기술 PM 등에게 전달받은 해당 게임용 인증 키
HTTP Request Parameter
아래 파라미터들을 Content-Type: application/x-www-form-urlencoded 으로 호출하면 됩니다.
ONE Store는 동일 상품의 복수개 구매를 지원합니다.
구매 수량을 예약 시점에 함께 전달해야합니다.
구매 금액은 상품의 개별 단가가 아니라 총 구매 금액으로 전달되어야 합니다.
One Store Android 대상으로 결제를 진행하는 경우에는 appStore 값을 ONE_STORE_ANDROID로 요청합니다.
ONE Store 측에서 플랫폼 확장으로 Windows가 추가되어 구분되었습니다.
reqId
String(100)
중복 요청을 막거나 요청 추적을 위한 값
userId_UUID 등과 같은 방식으로 생성
userId_reserve_98b50907-0928-493b-a816-dac8dbca1f53
pjid
String(50)
프로젝트ID
동일 게임이면 svcId가 달라도 동일
1004
svcId
String(20)
서비스ID
10040020
imid
String(40)
IMID
회원 플랫폼의 IMID로 로그인 후 얻을 수 있음
PJID 내 사용자를 식별하는 고유 Key
playerId를 수집하지만 imid도 수집하는 이유는, 예약 단계에서 imid를 수집하여 한도 제한 기능 등을 구현할 때 사용
ABCDEFGHJKMNPQR12345
playerId
String(50)
결제를 진행하는 유저의 ID
게임에서 결제 스콥을 관리하고 싶은 id값으로 사용
회원 플랫폼의 IMID 값이 사용할 수도 있음
ipCountry
String(10)
player의 IP기반 국가코드로 법적 대응을 위해서 수집
3166-1 alpha-2 국가코드
AWS CloudFront를 사용한다면 HTTP헤더의 CloudFront-Viewer-Country에서 쉽게 얻을 수 있음
KR
productId
String(200)
구매 진행하는 상품ID(SKU와 같은 값)
onestore_gamecode_ruby01
재무쪽 요청으로 접두어로 payment 코드가 접두어로 추천
microPrice
long
구매 금액 micro단위
사용측의 부동 소수점 오차등을 방지하기 위해서 micro단위 사용
국가별 한도처리 기능 제공을 위해서 필요
ONE Store 는 복수개 구매가 가능 -> 구매한 전체 금액을 예약 시점에 전달
구매 금액 micro단위(예. $0.99는 990,000 µ$. 100만을 곱함)
quantity
Integer
해당 상품 구매 수량
1~100 사이의 값(최대 100)
1
Response
응답은 JSON형태로 전달됩니다.
Response property
boid
String(20)
빌링 시스템의 주문ID
4
Success sample
Error sample
한도 제한으로 추가 처리가 필요한 경우
PURCHASE_MONTHLY_LIMITED 에러코드가 리턴됩니다.
게임쪽에서 추가 로직을 구현에 사용하실 수 있도록 해당 에러코드가 리턴되면 monthlyLimitedDetail을 추가로 응답합니다.
추가 정보 필드들에 대한 설명
appliedPolicy
String
한도제한이 적용된 정책코드
한국
KR_ADULT
한국 성인의 월 한도 제한 제약으로 차단됨
성인은 HYBE IM에서 제공하는 '계정센터를 통해서 한도 상향 가능
SDK에서 제공하는 ‘계정센터 성인의 한도제한 변경 페이지로 유도’
KR_MINOR
한국 미성년
한국 미성년은 한도 수정이 불가. 즉, 한도제한 변경 페이지로 유도하면 안됨
일본(성인은 한도제한 없음)
JP_MINOR_UNDER_AGE_18_OVER_16
18세 미만 16세 이상
JP_MINOR_UNDER_AGE_16
16세 미만
currency
String
통화
KRW, JPY
limitConfigMircoPrice
Long
설정된 한도 금액 micro단위
30000000000
thisMonthAmountMircoPrice
Long
이번달 구매 금액의 micro단위
예) $0.99는 990,000 µ$. 100만을 곱함
29500000000
countryCreated
String
해당 유저 계정에 생성된 국가 코드
imid가 생성된 시점에 IP기반 국가코드
정책이 계정 생성 시점을 기준으로 작동
JP, KR
debugMessage
String
개발자 디버깅 참고용 응답 메시지
주의: 해당 메시지로 로직 작성 X
일본 미성년자('16세') 한도 초과로 구매 중단. 한도 설정: '30000' | 이번달 구매한 대상 금액(JPY):'29500.0000' | 추가 구매하려는 금액:'550.950000' | 총합:'30050.950000
한국 한도제한 적용됨: KR_MINOR
한국 한도제한 적용됨: KR_MINOR
일본 한도제한 적용됨: JP_MINOR_UNDER_AGE_16
일본 한도제한 적용됨: JP_MINOR_UNDER_AGE_18_OVER_16
중복 요청으로 발생한 에러
파라미터 에러
에러 코드 정의
아래와 같은 에러코드가 resultCode에 응답될 수 있습니다. (참고 링크)
아래의 에러코드들은 모든 빌링 API에서 발생 가능한 에러 코드들입니다.
해당 에러코드 외에 각 API에서만 발생가능한 에러코드들도 있습니다.
각 에러 코드를 바탕으로 필요시 비즈니스 로직을 작성하시면 됩니다.
SYSTEM_ERROR
빌링 API에서 발생한 시스템 에러
HTTP 상태코드 500 리턴
NOT_ALLOW_AUTH
API 인증 헤더 누락이거나 기타 권한이 없는 요청에서 발생
아래 에러 코드들은 해당 API에서 발생 가능한 추가 에러 코드들입니다.
특정 결제 수단인 경우 아래와 같은 에러 코드가 resultCode에 응답될 수 있습니다.
특정 국가에서 요구하는 월 구매금액 한도 제한을 빌링 시스템에서 제공하기 위한 에러코드가 포함됩니다.
한국: ‘결제 한도 자율 규제’에 따라서 PC 자체 서비스에 대해서, 한국에서 생성된 계정에 대한 정책
일본: ‘일본 청소년 소셜 게임 결제 자율 규제’에 따라서 1) 성인 2)18세 미만~16세 이상 3)16세 미만
INVALID_PARAMETER
요청된 파라미터 오류
JAPANESE_DATE_BIRTH_REQUIRED
일본 IP에서 생성된 계정(imid)인데 생년월일 정보를 입력하지 않아서 입력 필요
로그인 과정에서 유저 이탈을 막기 위해서 결제 시점에 체크
해당 에러 코드가 리턴되면 SDK를 통해서 제공되는 생년월일 입력 웹뷰를 호출해서 입력 유도
상세 내용은 SDK 가이드 참고
생년월일이 입력되면 구매 예약을 다시 시도했을 때 해당 에러코드가 리턴되지 않음
PURCHASE_MONTHLY_LIMITED
한국 또는 일본에서 생성된 계정이고, 한도 체크 대상에 포함되는 대상인데 이번달 결제 금액이 한도를 초과
참고: 한국인인 경우 결제 한도 자율 규제에 따라서 성인은 ‘HYBE IM’의 계정센터 웹에서 한도 상향 가능
일본 성인은 한도 제한 금액이 없음
18세 미만 16세 이상은 3만엔
16세 미만은 5천엔
요청 curl 샘플
샘플 curl 커맨드입니다. 요청 정보에 맞게 변경해서 호출하세요.
Google curl 샘플
마지막 업데이트