콘텐츠로 이동

Hive Axyl Server API로 영수증 검증

앱 서버가 Hive Axyl Server API의 영수증 검증 API를 호출해 PG 결제 영수증을 검증합니다. 앱 서버는 앱 클라이언트가 결제 완료 정보 조회 (미지급 주문 조회)에서 조회해 전달한 미지급 주문 정보로 검증을 요청하고, 결과를 확인한 뒤 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 서버가 PG사에 해당 주문의 실제 결제 여부를 다시 확인합니다. PG 결제는 구독 결제를 지원하지 않으므로 소모성 상품 영수증 검증만 수행합니다. 이 검증을 통과한 주문에만 상품을 지급하세요.

요청 값

앱 클라이언트가 영수증 검증 요청 값으로 전달한 값을 요청 본문에 넣고, providerId는 PG로 지정하세요. 한 번의 요청으로는 주문 하나만 검증하므로, 미지급 주문이 여러 건이면 주문마다 이 API를 호출하세요. PG 결제에서 반드시 넣어야 하는 값은 아래와 같습니다.

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

orderId와 storeTransactionId를 모두 생략하면 서버가 axylReceipt에서 주문 번호를 추출합니다. price를 보내면 서버가 기록한 결제 금액과 대조하며, PG 결제는 금액이 다르면 요청을 거절합니다. 선택 필드와 요청 헤더는 호출 Parameters와 마켓별 요청 값을 참조하세요.

응답에서 확인할 값

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

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

모든 응답 필드와 오류 응답은 응답을 참조하세요.

앱 클라이언트에 돌려줄 값

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

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

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

다음 단계

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