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 Steam receipts. For Steam payments, the actual charge occurs at this verification step, so request verification with the values passed in Prepare receipt information after the app client completes Save payment result data and confirm authorization. After checking the verification result, the app server returns the values needed 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. 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 order with Steam and then proceeds with the actual charge. Steam payments support only single-item purchases of consumable products, so only consumable product receipt verification is performed. Deliver products only for purchases that pass this verification.

Caution

A Steam payment is confirmed when this API is called, so do not call it repeatedly with the same receipt when you do not need to. If you cannot tell whether the request was processed because you did not receive a response due to a network error or a similar problem, send the same request again, and check whether hiveAxylDuplicated in the response is true to determine whether the purchase has already been processed.

Request values

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

  • providerId: STEAM
  • axylReceipt: The sealed receipt issued by the Hive Axyl server. The original value that the app client passed, without modification
  • productId: The Product ID of the purchased product
  • accountUuid: The value created in Generate an AccountUuid
  • requestType: 1 for a new purchase, 2 for purchase restoration

If you omit both orderId and storeTransactionId, the server extracts the order number from axylReceipt. For optional fields and request headers, 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
  • hiveAxylProductId, hiveAxylQuantity, hiveAxylPrice: The product ID to deliver, the purchase quantity, and the verified payment amount
  • 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
  • hiveAxylAccountUuidCompare: The comparison result of accountUuid in the request. Steam has no payment-side account information to compare against, so the value is always 9, which means that comparison is not possible

For Steam, hiveAxylReceiptVerifyResult, the original result of the market receipt verification, is always null, so check what to deliver with the product ID, purchase quantity, and payment amount above. 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 using these values. Your app decides how to pass the values.

  • hiveAxylTransactionId: The Hive Axyl payment transaction ID that is used as ItemResultBody.AxylTransactionId in Save product delivery results
  • Verification and product delivery results: The basis on which the app client decides whether to proceed with purchase finalization

For purchase finalization, use the sealed receipt that the app client kept as is. hiveAxylReceipt in the response is the axylReceipt sent in the request, returned by the server without modification, so the two values are the same. If receipt verification failed or product delivery could not be confirmed, do not proceed with purchase finalization, and keep the sealed receipt. Orders that have not been finalized are found again through Restore purchases, where verification and delivery proceed again.

Next steps

Proceed to Step 5. Deliver products.