Steam 소액결제 - 빌링 완료 처리

기본 정보

1. 빌링 API를 통해서 FinailzeTxn까지 완료된 유저 결제 건에 대해서 최종 완료 처리를 진행합니다.

2. 해당 API 호출이 성공하면 게임은 구맨 상품을 지급하면 됩니다.

   1. Steam web API QueryTxn을 통해서 유저의 구매 상태 검사가 진행됩니다.

항목	내용	비고
호출주체	게임서버(s2s API)
도메인	각 환경별 도메인
인증 방식	HTTP 헤더 인증 정보
HTTP 메소드	POST
Content-Type	application/x-www-form-urlencoded
사전 필요사항	프로젝트ID 및 서비스 ID 발급 Steam works 설정 후 빌링 시스템 설정

Request

HTTP Request end point

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

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	설명	예
reqId	String(100)	중복 요청을 막거나 요청 추적을 위한 값	userId_UUID 등과 같은 방식으로 생성
pjid	String(20)	프로젝트ID 동일 게임이라면 서비스ID가 여러개일 수 있지만 프로젝트ID는 같음	1004
boid	String(20)	빌링 시스템 구매 예약 API를 통해서 생성된 ID Steam 응답에 에러가 반환시 빌링 API 예약부터 다시 진행되어야할 수 있습니다.(실제 결제 테스트 후 확인 필요). 스팀 web API 요구사항 때문	1234
playerId	String(50)	결제를 진행하는 유저의 ID 게임에서 결제 스콥을 관리하고 싶은 id값으로 사용 하이브 IM의 uid값이 될 수도 있음 요청쪽 버그 등으로 다른 유저에게 오 지급하는 등의 방어 목적으로 예약 등에서 전달받았지만 완료에서도 전달 받음

Response

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

Success sample

{
    "resultCode": "SUCCESS",
    "resultMessage": "Success boid:'34'| playerId:'playerId' purchase to COMPLETED."
}

Error sample

• 잘 못된 boid로 요청, 완료된 빌링 boid에 재 완료 요청

{
    "resultCode": "INVALID_PARAMETER",
    "resultMessage": "There is no purchase data that matches your criteria(boid '78')."
}

에러 코드 정의(resultCode부분)

• 아래와 같은 에러코드가 resultCode에 응답될 수 있습니다. (참고 링크)

• 아래의 에러코드들은 모든 빌링 API에서 발생 가능한 에러 코드들입니다.

  • 해당 에러코드 외에 각 API에서만 발생가능한 에러코드들도 있습니다.

  • 각 에러 코드를 바탕으로 필요시 비즈니스 로직을 작성하시면 됩니다.

에러코드	비고
SYSTEM_ERROR	빌링 API에서 발생한 시스템 에러 HTTP 상태코드 500 리턴
NOT_ALLOW_AUTH	API 인증 헤더 누락이거나 기타 권한이 없는 요청에서 발생

• 아래 에러 코드들은 해당 API에서 발생 가능한 추가 에러 코드들입니다.

에러코드	비고
INVALID_PARAMETER
NOT_ALLOW_PURCHASE	구매 기능을 사용할 수 없는 상황 빌링 시스템에 스토어 관련 설정 누락 다른 유저의 결제 예약건을 완료 처리 시도
EXTERNAL_API_ERROR	Steam web API 호출 자체가 실패한 경

요청 curl 샘플

• 도메인 및 인증 헤더 등은 변경 필요

curl --location 'https://billing-game-api-dev-public.pub-dev.hybegames.io/billing/api-game/v1/purchase/steam/microtxn/complete' \
--header 'X-Req-Pjid: 9001' \
--header 'X-Auth-Access-Key: test-auth-key' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'reqId=userId_steam_complete_170083bf-8d85-433f-8bd2-67674b7482db-2024-01-25-01' \
--data-urlencode 'pjid=9001' \
--data-urlencode 'playerId=test_playerId' \
--data-urlencode 'boid=78'