PSN 구매를 위한 예약
기본 정보
- PSN 상품 구매를 시작하기 위해서 빌링 시스템에 예약을 위한 API입니다.
- 응답으로 빌링 주문ID(
boid)를 받으며, 이후 구매 검증/완료 처리에 사용합니다.
| 항목 | 내용 | 비고 |
|---|---|---|
| 호출주체 | 게임서버(s2s API) | |
| 도메인 | 각 환경별 도메인 | |
| 인증 방식 | HTTP 헤더 인증 정보 | |
| HTTP 메소드 | POST | |
| Content-Type | application/x-www-form-urlencoded |
Request
HTTP Request end point
POST https://각 환경별 빌링시스템 도메인/billing/api-game/v1/purchase/psn/reserve
HTTP 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 으로 호출하면 됩니다.
| key | type | required | 설명 |
|---|---|---|---|
| reqId | String | Y | 요청 유니크 ID. 중복 요청 차단에 사용 - 예: {playerId}_reserve_{UUID} |
| pjid | String | Y | 프로젝트ID - 헤더 X-Req-Pjid와 동일해야 함 |
| svcId | String | Y | 서비스ID |
| imid | String | Y | 게임플랫폼 회원 IMID |
| playerId | String | Y | 결제 유저 ID - 별도 구분 없으면 imid 사용 가능 |
| payment | String | Y | PSN 고정 |
| appStore | String | Y | PSN 고정 |
| productId | String | Y | 상품ID - 빌링 상품등록 선행 - 예: psn_gem_01 |
| os | String | Y | NONE 고정 |
| microPrice | long | Y | micro 단위 금액(×1,000,000) - 예: 1,200원 = 1200000000 |
| currency | String | Y | ISO-4217 통화코드 |
| ipCountry | String | 권장 | ISO-3166-1 alpha-2 국가코드 |
Response
응답은 JSON형태로 전달됩니다.
Response property
| key | data type | description | example |
|---|---|---|---|
| boid | String | 빌링 주문ID. 구매 검증/완료 처리 요청에 그대로 전달 | 20260826... |
Success sample
{
"resultCode": "SUCCESS",
"resultMessage": "success",
"resultData": { "boid": "20260826..." }
}
실패 응답
- 비즈니스 실패도 HTTP 200으로 응답됩니다. HTTP status가 아닌
resultCode로 분기하세요.SYSTEM_ERROR(500)·NOT_ALLOW_AUTH(인증 헤더 오류)는 전 API 공통.
| resultCode | HTTP | 발생 조건 | 게임서버 처리 |
|---|---|---|---|
| INVALID_PARAMETER | 200 | 필수값 누락, pjid에 PSN 설정 없음, 빌링 미등록 productId, payment/appStore 불허, reqId 중복 | 요청값 수정 후 재요청. reqId는 새 값 |
| NOT_ALLOW_PURCHASE | 200 | 프로젝트가 구매 불가 상태 | 구매 진행 중단 |
| PURCHASE_MONTHLY_LIMITED | 200 | 유저 월 구매한도 초과 | 한도 초과 안내 |
| JAPANESE_DATE_BIRTH_REQUIRED | 200 | 일본 유저 생년월일 미등록(청소년 결제 자율규제) | 생년월일 입력 유도 |
{
"resultCode": "INVALID_PARAMETER",
"resultMessage": "Not exist registered product. productId:'psn_gem_99'",
"traceId": "billing_01H..."
}
요청 curl 샘플
- 샘플 curl 커맨드입니다. 요청 정보에 맞게 변경해서 호출하세요.
curl -X 'POST' \
'https://API도메인/billing/api-game/v1/purchase/psn/reserve' \
-H 'X-Req-Pjid: PJID값' \
-H 'X-Auth-Access-Key: API 인증키' \
-H 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'reqId=tester01_reserve_98b50911-0928-493b-a816-dac8dbca1f53' \
--data-urlencode 'pjid=1201' \
--data-urlencode 'svcId=12010000' \
--data-urlencode 'imid=87DDCADUCX7WLK7D55HY' \
--data-urlencode 'playerId=tester01' \
--data-urlencode 'payment=PSN' \
--data-urlencode 'appStore=PSN' \
--data-urlencode 'productId=psn_gem_01' \
--data-urlencode 'os=NONE' \
--data-urlencode 'microPrice=1200000000' \
--data-urlencode 'currency=KRW' \
--data-urlencode 'ipCountry=KR'