Skip to content

Verify receipts with the Hive Axyl Server API

The app server calls the receipt verification API of the Hive Axyl Server API to verify Google Play receipts. The app server requests verification with the values that the app client sent in Prepare receipt information, checks the result, and then returns the values required for step 5 to the app client.

Before calling

For the app server to call the Hive Axyl Server API, each request needs an access token for the app server. Call the token issuance API with the Client ID and Client Secret issued in the Hive Console to get an access token, and then put it in the Authorization header of the receipt verification request. In the X-App-Id header, specify the App ID registered in the Hive Console. For the values required for the call, see Before calling, and for the URLs of the production and sandbox environments, see Base URL.

Keep the Client Secret and the access token only on the app server, and do not include them in the app client.

Verify consumable product receipts

Server API

POST /payment/v1/purchase/verify

When the app server calls the consumable product receipt verification API, the Hive Axyl server rechecks the receipt with Google Play. To prevent products from being fraudulently delivered through forged or tampered receipts or requests without an actual payment, deliver products only for purchases that pass this verification.

Request values

Put the values that the app client sent as the consumable product receipt information in the request body, and set providerId to GOOGLE. The values that you must include for Google payments are as follows.

  • providerId: GOOGLE
  • axylReceipt: The Google Play purchase token (purchaseToken) string
  • productId: The Product ID of the purchased product. The purchase token contains no product information, so the request is rejected if you omit it
  • accountUuid: The AccountUuid, which is the same value you put in ObfuscatedAccountId of the Google purchase request
  • requestType: 1 for a new purchase, 2 for purchase restoration

For optional fields, request headers, and how amounts are compared for Google payments, see Call parameters and Request values by market.

Values to check in the response

When verification succeeds, the verification result is contained in data of the response. Check the following values before you deliver the product.

  • hiveAxylPurchaseCancelState: The payment cancellation status. 1 means a canceled payment, so stop product delivery
  • hiveAxylDuplicated: Whether the receipt has already been verified. If true, check the delivery history to prevent duplicate delivery of the same product
  • hiveAxylAccountUuidCompare: The result of comparing accountUuid in the request with ObfuscatedAccountId. 1 means a match, 2 means a mismatch, and 9 means that comparison is not possible
  • hiveAxylPurchaseTest: Whether it is a test payment. Y means a test payment, so decide whether to deliver the product in the production environment according to your app's operating policy
  • hiveAxylProductId, hiveAxylQuantity, hiveAxylPrice: The product ID to deliver, the purchase quantity, and the verified payment amount

Hive Axyl does not automatically block payments or product delivery based only on the hiveAxylAccountUuidCompare value. If the value is 2, decide how to handle it, such as holding delivery or confirming with the user, according to your app's security policy. 9 means that comparison is not possible; it is not a mismatch. For all response fields and error responses, see Response.

Values to return to the app client

When verification succeeds, return the following values to the app client. The app client proceeds with Step 5. Deliver products and finish transactions using these values. Your app decides how to pass the values.

If receipt verification failed or product delivery could not be confirmed, do not proceed with the payment confirmation request and transaction finishing in the app client; keep the receipt and purchase information instead. Purchases that have not been completed are found again in Restore purchases, where verification and delivery proceed again.

Verify subscription product receipts

Server API

POST /payment/v1/subscription/verify

For subscription products, after you save the subscription purchase information in Step 3. Purchase a product, the app server calls the subscription product receipt verification API to verify that the subscription is valid. The response contains the subscription expiration time, so use this result to decide whether to deliver and maintain subscription benefits.

Request values

Put the values that the app client sent as the subscription product receipt information in the request body, and set providerId to GOOGLE. The values that you must include for Google subscriptions are as follows.

  • providerId: GOOGLE
  • axylReceipt: The Google Play purchase token (purchaseToken) string of the subscription payment
  • accountUuid: The AccountUuid, which is the same value you put in ObfuscatedAccountId of the Google purchase request
  • country: Country code (ISO 3166-1 two-letter)
  • language: Language code (ISO 639-1 two-letter)
  • requestType: 1 for a new purchase, 2 for purchase restoration

Because the server creates the lookup key from the market reverification result, you do not need to pass storeTransactionId. For the other fields, see Call parameters and Request values by market.

Values to check in the response

When verification succeeds, the verified subscription information is contained in data of the response. Check the following values before you deliver or maintain subscription benefits.

  • hiveAxylExpiresDate: The subscription expiration time in Unix epoch milliseconds. After this time passes, stop maintaining the subscription benefits
  • hiveAxylRefundDate: The refund time. Google Play does not provide the refund time, so this value is always null; do not use it to determine refunds
  • hiveAxylDuplicated: Whether the receipt has already been verified. If true, check the delivery history to prevent duplicate delivery of the same subscription benefits
  • hiveAxylAccountUuidCompare: The result of comparing accountUuid in the request with ObfuscatedAccountId. 1 means a match, 2 means a mismatch, and 9 means that comparison is not possible
  • hiveAxylProductId: The subscription product ID based on the market verification result
  • hiveAxylStoreTransactionId, hiveAxylOriginalStoreTransactionId: The transaction ID of the current cycle and the transaction ID of the first payment. Compare the two values to tell whether it is a renewal or a new subscription

If you need the market's original verification result, check hiveAxylReceiptVerifyResult. For all response fields, see Response.

Values to return to the app client

When verification succeeds, return the following values to the app client. The app client uses these values to complete the subscription.

  • hiveAxylProductId: The subscription product ID that is used as SubscriptionPurchasePostRequest.ProductId in subscription completion
  • Verification and subscription benefit delivery results: The basis on which the app client decides whether to proceed with subscription completion and transaction finishing

If subscription receipt verification failed or subscription benefit delivery could not be confirmed, do not proceed with subscription completion and transaction finishing in the app client; keep the receipt and purchase information instead.

Next steps

Proceed to Step 5. Deliver products and finish transactions.