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 PG payment receipts. The app server requests verification with the undelivered order information that the app client retrieved in Get completed payment information (get undelivered orders) and passed to it, 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 again with the PG provider whether the order was actually paid. Because PG payment does not support subscription payments, only consumable product receipt verification is performed. Deliver products only for orders that pass this verification.

Request values

Put the values that the app client passed as receipt verification request values in the request body, and set providerId to PG. One request verifies only one order, so if there are multiple undelivered orders, call this API for each order. The values you must include for PG payment are as follows.

  • providerId: PG
  • axylReceipt: The sealed receipt issued by the Hive Axyl server. The unmodified original AxylReceipt of the undelivered order that the app client passed
  • productId: The product ID of the undelivered order
  • accountUuid: The value created in Generate an AccountUuid
  • requestType: 1 for a new purchase, 2 for a purchase restoration

If you omit both orderId and storeTransactionId, the server extracts the order number from axylReceipt. If you send price, the server compares it with the payment amount it recorded, and for PG payment, it rejects the request if the amounts differ. For optional fields and request headers, 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
  • hiveAxylProductId, hiveAxylQuantity, hiveAxylPrice: The product ID to deliver, the purchase quantity, and the verified payment amount
  • 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
  • hiveAxylAccountUuidCompare: The result of comparing the accountUuid in the request. PG has no payment-side account information to compare, so this is always 9, which means the comparison is not possible

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. Your app decides how to pass the values.

  • hiveAxylTransactionId: The Hive Axyl payment transaction ID 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 Finalize the purchase

For purchase finalization, the app client uses the sealed receipt it received from the undelivered order query as is. The 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. Orders that have not been finalized are retrieved again as undelivered orders in Restore purchases, and then verified and delivered.

Next steps

Proceed to Step 5. Deliver products.