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 Apple receipts. The app server requests verification with the values that the app client passed in Prepare receipt information, checks the result, and then returns the values needed for Step 5 to the app client.

Before calling

To call the Hive Axyl Server API, the app server needs an access token for the app server with every request. 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. For the URLs of the production and sandbox environments, see Base URL.

Keep the Client Secret and 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 checks the receipt again with the Apple App Store. 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 passed as consumable product receipt information in the request body, and set providerId to APPLE. The values you must include for Apple payment are as follows.

  • providerId: APPLE
  • axylReceipt: The unmodified StoreKit 2 transaction JWS (JwsRepresentation)
  • productId: The Product ID of the purchased product
  • accountUuid: The AccountUuid, the same as the value you put in AppAccountToken of the Apple purchase request
  • requestType: 1 for a new purchase, 2 for a purchase restoration

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

Values to check in the response

If verification succeeds, the data of the response contains the verification result. Check the following values before you deliver the product.

  • hiveAxylPurchaseCancelState: Payment cancellation status. If 1, the payment was canceled, so stop product delivery
  • hiveAxylDuplicated: Whether the receipt was already verified. If true, check the delivery history to prevent delivering the same product twice
  • hiveAxylAccountUuidCompare: The result of comparing accountUuid in the request with AppAccountToken. 1 means a match, 2 means a mismatch, and 9 means the comparison is not possible
  • hiveAxylPurchaseTest: Whether the payment is a test payment. If Y, it is 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 withholding delivery or verifying the user, according to your app's security policy. 9 means the comparison is not possible, not a mismatch. For all response fields and error responses, see Response.

Values to return to the app client

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

If receipt verification failed or product delivery could not be confirmed, the app client must not proceed with the payment confirmation request or finish the transaction, and must keep the receipt and purchase information. Purchases that have not been finished are found again in Restore purchases, and then verified and delivered.

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 whether the subscription is valid. Because the response contains the subscription expiration time and refund time, use this result to decide whether to deliver or reclaim subscription benefits.

Request values

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

  • providerId: APPLE
  • axylReceipt: The unmodified StoreKit 2 transaction JWS (JwsRepresentation) of the subscription payment
  • accountUuid: The AccountUuid, the same as the value you put in AppAccountToken of the Apple purchase request
  • country: The country code (two-letter ISO 3166-1 code)
  • language: The language code (two-letter ISO 639-1 code)
  • requestType: 1 for a new purchase, 2 for a purchase restoration

If you pass the transaction JWS in axylReceipt, you can omit storeTransactionId because the lookup key is in the receipt. For the other fields, see Call parameters and Request values by market.

Values to check in the response

If verification succeeds, the data of the response contains the verified subscription information. Check the following values before you deliver or maintain subscription benefits.

  • hiveAxylExpiresDate: The subscription expiration time in Unix epoch milliseconds. After this time, stop maintaining the subscription benefits
  • hiveAxylRefundDate: The refund time in Unix epoch milliseconds. If it has a value, the subscription was refunded, so reclaim the subscription benefits
  • hiveAxylDuplicated: Whether the receipt was already verified. If true, check the delivery history to prevent delivering the same subscription benefits twice
  • hiveAxylAccountUuidCompare: The result of comparing accountUuid in the request with AppAccountToken. 1 means a match, 2 means a mismatch, and 9 means the comparison is not possible
  • hiveAxylProductId: The subscription product ID based on the market verification result
  • hiveAxylStoreTransactionId, hiveAxylOriginalStoreTransactionId: The transaction ID of the current period and the transaction ID of the first payment. Compare the two values to distinguish a renewal from a new subscription

For all response fields, see Response.

Values to return to the app client

If verification succeeds, return the following values to the app client. The app client uses these values to proceed with Complete the subscription.

  • hiveAxylProductId: The subscription product ID 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 finish the transaction

If subscription receipt verification failed or subscription benefit delivery could not be confirmed, the app client must not proceed with subscription completion or finish the transaction, and must keep the receipt and purchase information.

Next steps

Proceed to Step 5. Deliver products and finish transactions.