콘텐츠로 이동

Hive Axyl Server API로 영수증 검증

앱 서버가 Hive Axyl Server API의 영수증 검증 API를 호출해 Steam 영수증을 검증합니다. Steam 결제는 이 검증 단계에서 실제 청구가 발생하므로, 앱 클라이언트가 결제 결과 데이터 저장 및 승인 확인을 마친 뒤 영수증 정보 준비에서 전달한 값으로 검증을 요청하세요. 앱 서버는 검증 결과를 확인한 뒤 5단계에 필요한 값을 앱 클라이언트에 돌려줍니다.

호출 전 준비

앱 서버가 Hive Axyl Server API를 호출하려면 요청마다 앱 서버용 액세스 토큰이 필요합니다. Hive 콘솔에서 발급한 Client ID와 Client Secret으로 토큰 발급 API를 호출해 액세스 토큰을 받은 뒤, 영수증 검증 요청의 Authorization 헤더에 넣으세요. X-App-Id 헤더에는 Hive 콘솔에 등록한 App ID를 지정하세요. 호출에 필요한 값은 호출 전 준비를, 운영 환경과 샌드박스 환경의 주소는 기본 URL을 참조하세요.

Client Secret과 액세스 토큰은 앱 서버에서만 보관하고 앱 클라이언트에 포함하지 마세요.

소모성 상품 영수증 검증

Server API

POST /payment/v1/purchase/verify

앱 서버가 소모성 상품 영수증 검증 API를 호출하면 Hive Axyl 서버가 Steam에 주문을 다시 확인한 뒤 실제 청구를 진행합니다. Steam 결제는 소모성 상품의 단건 결제만 지원하므로 소모성 상품 영수증 검증만 수행합니다. 이 검증을 통과한 구매에만 상품을 지급하세요.

Caution

Steam 결제는 이 API를 호출하는 시점에 확정되므로 같은 영수증으로 불필요하게 반복 호출하지 마세요. 네트워크 오류 등으로 응답을 받지 못해 처리 여부를 알 수 없으면 같은 요청을 다시 보내고, 응답의 hiveAxylDuplicated가 true인지 확인해 이미 처리된 구매인지 판단하세요.

요청 값

앱 클라이언트가 소모성 상품 영수증 정보로 전달한 값을 요청 본문에 넣고, providerId는 STEAM으로 지정하세요. Steam 결제에서 반드시 넣어야 하는 값은 아래와 같습니다.

  • providerId: STEAM
  • axylReceipt: Hive Axyl 서버가 발급한 봉인 영수증. 앱 클라이언트가 전달한 값을 가공하지 않은 원문
  • productId: 구매한 상품의 Product ID
  • accountUuid: AccountUuid 생성에서 만든 값
  • requestType: 신규 구매는 1, 구매 복원은 2

orderId와 storeTransactionId를 모두 생략하면 서버가 axylReceipt에서 주문 번호를 추출합니다. 선택 필드와 요청 헤더는 호출 Parameters와 마켓별 요청 값을 참조하세요.

응답에서 확인할 값

검증에 성공하면 응답의 data에 검증 결과가 담깁니다. 상품을 지급하기 전에 아래 값을 확인하세요.

  • hiveAxylPurchaseCancelState: 결제 취소 상태. 1이면 취소된 결제이므로 상품 지급 중단
  • hiveAxylDuplicated: 이미 검증한 영수증 여부. true이면 지급 이력을 확인해 같은 상품의 중복 지급 방지
  • hiveAxylProductId, hiveAxylQuantity, hiveAxylPrice: 지급할 상품 ID, 구매 수량, 검증된 결제 금액
  • hiveAxylPurchaseTest: 테스트 결제 여부. Y이면 테스트 결제이므로 운영 환경에서 상품을 지급할지 앱의 운영 정책에 따라 결정
  • hiveAxylAccountUuidCompare: 요청의 accountUuid 대조 결과. Steam은 대조할 결제 측 계정 정보가 없으므로 항상 대조 불가를 뜻하는 9

Steam은 마켓 영수증 검증의 원본 결과인 hiveAxylReceiptVerifyResult가 항상 null이므로, 위의 상품 ID, 구매 수량, 결제 금액으로 지급 내용을 확인하세요. 모든 응답 필드와 오류 응답은 응답을 참조하세요.

앱 클라이언트에 돌려줄 값

검증에 성공하면 아래 값을 앱 클라이언트에 돌려주세요. 앱 클라이언트는 이 값으로 5단계. 상품 지급을 진행합니다. 값을 전달하는 방식은 앱에서 정합니다.

  • hiveAxylTransactionId: 상품 지급 결과 저장에서 ItemResultBody.AxylTransactionId로 사용하는 Hive Axyl 결제 트랜잭션 ID
  • 검증과 상품 지급 결과: 앱 클라이언트가 구매 완료 처리를 진행할지 판단하는 기준

구매 완료 처리에는 앱 클라이언트가 보관한 봉인 영수증을 그대로 사용합니다. 응답의 hiveAxylReceipt는 요청에 보낸 axylReceipt를 서버가 가공하지 않고 돌려준 값이므로 두 값은 같습니다. 영수증 검증에 실패했거나 상품 지급을 확인하지 못했다면 구매 완료 처리를 진행하지 말고 봉인 영수증을 계속 보관하세요. 구매 완료 처리하지 않은 주문은 구매 복구에서 다시 찾아 검증과 지급을 진행합니다.

다음 단계

5단계. 상품 지급을 진행합니다.