본문으로 건너뛰기

빌링 예약 상태의 구매 건에 대해서 예약취소 요청

기본 정보​

  1. 빌링에 예약 요청을 통해 예약 중인 구매 건에 대해서 명시적으로 ‘예약 취소’를 요청하는 API입니다.
  2. 게임쪽에서 예약과 함께 Lock처리하는 기능이 존재하여, 명확히 예약을 취소해야하는 경우에 사용할 수 있습니다.
    1. 예) PG결제 금액에 게임내 할인 포인트를 함께 사용 → 예약과 함께 Lock을 구현했는데 유저가 중간에 결제를 취소하는 경우 할인 포인트 반환 처리와 함께 예약 취소가 필요한 경우에 사용
  3. 해당 API로 취소된 구매건의 구매 상태는 ‘RESERVED_CANCEL’로 반영됩니다.
항목내용비고
호출주체게임서버(s2s API)
도메인각 환경별 도메인
인증 방식HTTP 헤더 인증 정보
HTTP 메소드POST
Content-Typeapplication/json

Request​

HTTP Request end point​

POST https://각 환경별 빌링시스템 도메인/billing/api-game/v1/purchase/reserved/cancel

HTTP Request Header​

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

HTTP Request Parameter​

  • 아래 파라미터들을 Content-Type: application/json으로 호출하면 됩니다.
이름데이터 타입필수 Y/N설명예
reqIdString(100)Y중복 요청을 막거나 요청 추적을 위한 값userId_UUID 등과 같은 방식으로 생성
pjidString(20)Y프로젝트ID
- 동일 게임이라면 서비스ID가 여러개일 수 있지만 프로젝트ID는 같음		1202
boidString(20)Y빌링 시스템 구매 예약 API를 통해서 생성된 ID1234
playerIdString(50)Y구매 예약을 진행한 유저ID
- boid로만 빌링에서 처리 가능하지만 게임쪽 검증 누락 방지 목적으로 전달받아서 검증 진행
- 플랫폼 회원의 imid를 사용할 수도 있음
productIdString(200)Y구매 예약한 상품ID(SKU와 같은 값)
- boid로만 빌링에서 처리 가능하지만 게임쪽 검증 누락 방지 목적으로 전달받아서 검증 진행
- 플랫폼 회원의 imid를 사용할 수도 있음		pg_test_gem_01

Response​

응답은 JSON형태로 전달됩니다.

Success Sample​

  {
    "resultCode": "SUCCESS",
    "resultMessage": "Success boid:'163' purchase to 'RESERVED_CANCEL'."
  }

Error sample​

  • 구매 예약 상태가 아닌 boid에 대해서 예약 취소 요청
  {
    "resultCode": "INVALID_PARAMETER",
    "resultMessage": "Purchase data is not in 'RESERVED' status",
    "traceId": "b_377f7c4131cb"
  }

에러 코드 정의​

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

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

  • HTTP 상태코드 500 리턴
NOT_ALLOW_AUTHAPI 인증 헤더 누락이거나 기타 권한이 없는 요청에서 발생
  • 아래 에러 코드들은 해당 API에서 발생 가능한 추가 에러 코드들입니다.
에러코드비고
INVALID_PARAMETER

요청 curl 샘플

  • 도메인 및 인증 헤더 등은 변경 필요
curl -X 'POST' \
  'https://API도메인/billing/api-game/v1/purchase/reserved/cancel' \
  -H 'accept: application/json;charset=UTF-8' \
  -H 'X-Req-Pjid: PJID값' \
  -H 'X-Auth-Access-Key: API인증키' \
  -H 'Content-Type: application/json;charset=UTF-8' \
  -d '{
  "pjid": "PJID값",
  "boid": "162",
  "playerId": "playerId",
  "productId": "pg_test_item_1"
}'