콘텐츠로 이동

Hive Axyl Server API로 영수증 검증

앱 서버가 Hive Axyl Server API의 영수증 검증 API를 호출해 Apple 영수증을 검증합니다. 앱 서버는 앱 클라이언트가 영수증 정보 준비에서 전달한 값으로 검증을 요청하고, 결과를 확인한 뒤 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 서버가 Apple App Store에 영수증을 다시 확인합니다. 위·변조된 영수증이나 실제 결제가 없는 요청으로 상품이 부정 지급되지 않도록, 이 검증을 통과한 구매에만 상품을 지급하세요.

요청 값

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

  • providerId: APPLE
  • axylReceipt: StoreKit 2 트랜잭션 JWS(JwsRepresentation) 원문
  • productId: 구매한 상품의 Product ID
  • accountUuid: Apple 구매 요청의 AppAccountToken에 넣은 값과 같은 AccountUuid
  • requestType: 신규 구매는 1, 구매 복원은 2

선택 필드와 요청 헤더, Apple 결제의 금액 대조 방식은 호출 Parameters와 마켓별 요청 값을 참조하세요.

응답에서 확인할 값

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

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

Hive Axyl은 hiveAxylAccountUuidCompare 값만으로 결제나 상품 지급을 자동으로 차단하지 않습니다. 값이 2이면 지급 보류, 사용자 확인 등의 처리를 앱의 보안 정책에 따라 결정하세요. 9는 대조 불가를 뜻하며 불일치가 아닙니다. 모든 응답 필드와 오류 응답은 응답을 참조하세요.

앱 클라이언트에 돌려줄 값

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

영수증 검증에 실패했거나 상품 지급을 확인하지 못했다면, 앱 클라이언트는 결제 확정 요청과 거래 완료 처리를 진행하지 말고 영수증과 구매 정보를 보관하세요. 완료 처리하지 않은 구매는 구매 복구에서 다시 찾아 검증과 지급을 진행합니다.

구독 상품 영수증 검증

Server API

POST /payment/v1/subscription/verify

구독 상품은 3단계. 상품 구매에서 구독 구매 정보를 저장한 뒤, 앱 서버가 구독 상품 영수증 검증 API를 호출해 구독이 유효한지 검증합니다. 응답에 구독 만료 시각과 환불 시각이 담기므로, 이 결과로 구독 혜택의 지급 또는 회수를 결정하세요.

요청 값

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

  • providerId: APPLE
  • axylReceipt: 구독 결제의 StoreKit 2 트랜잭션 JWS(JwsRepresentation) 원문
  • accountUuid: Apple 구매 요청의 AppAccountToken에 넣은 값과 같은 AccountUuid
  • country: 국가 코드(ISO 3166-1 두 자리)
  • language: 언어 코드(ISO 639-1 두 자리)
  • requestType: 신규 구매는 1, 구매 복원은 2

axylReceipt에 트랜잭션 JWS를 전달하면 조회 키가 영수증 안에 있으므로 storeTransactionId는 생략해도 됩니다. 나머지 필드는 호출 Parameters와 마켓별 요청 값을 참조하세요.

응답에서 확인할 값

검증에 성공하면 응답의 data에 검증된 구독 정보가 담깁니다. 구독 혜택을 지급하거나 유지하기 전에 아래 값을 확인하세요.

  • hiveAxylExpiresDate: Unix epoch 밀리초 단위의 구독 만료 시각. 이 시각이 지나면 구독 혜택 유지 중단
  • hiveAxylRefundDate: Unix epoch 밀리초 단위의 환불 시각. 값이 있으면 환불된 구독이므로 구독 혜택 회수
  • hiveAxylDuplicated: 이미 검증한 영수증 여부. true이면 지급 이력을 확인해 같은 구독 혜택의 중복 지급 방지
  • hiveAxylAccountUuidCompare: 요청의 accountUuid와 AppAccountToken의 대조 결과. 1은 일치, 2는 불일치, 9는 대조 불가
  • hiveAxylProductId: 마켓 검증 결과를 기준으로 한 구독 상품 ID
  • hiveAxylStoreTransactionId, hiveAxylOriginalStoreTransactionId: 이번 주기의 거래 ID와 처음 결제한 거래 ID. 두 값을 비교해 갱신인지 새 구독인지 구분

모든 응답 필드는 응답을 참조하세요.

앱 클라이언트에 돌려줄 값

검증에 성공하면 아래 값을 앱 클라이언트에 돌려주세요. 앱 클라이언트는 이 값으로 구독 완료 처리를 진행합니다.

  • hiveAxylProductId: 구독 완료 처리에서 SubscriptionPurchasePostRequest.ProductId로 사용하는 구독 상품 ID
  • 검증과 구독 혜택 지급 결과: 앱 클라이언트가 구독 완료 처리와 거래 완료 처리를 진행할지 판단하는 기준

구독 영수증 검증에 실패했거나 구독 혜택 지급을 확인하지 못했다면, 앱 클라이언트는 구독 완료 처리와 거래 완료 처리를 진행하지 말고 영수증과 구매 정보를 보관하세요.

다음 단계

5단계. 상품 지급과 거래 완료 처리를 진행합니다.