Integration

API Purchases

Use this endpoint to create purchases from your store and receive the final result through a webhook.

Purchase flow

Main endpoint

POSThttps://bs.hydracidx.com/api/purchase/

Send every purchase request to this route. It is the only purchase entry point for the API.

Authorization

Authentication uses the reseller static `url_token`.
Send the token in the `Authorization` header using the `Token` scheme.
The same token can be reused for every request until you rotate it.

Header example

Authorization: Token YOUR_STATIC_URL_TOKEN

Reseller pricing by quantity

The reseller price changes depending on the requested quantity.
Different quantity ranges can produce different unit prices.
Check the API Products page to see the detailed pricing tiers for each product.

Request parameters

Each field below is required in the purchase request body.

JSON body

reference_id

string

Your own unique reference for the order in your system.

Returned back in the webhook so you can match the response to your original request.
Must be unique for your reseller account and cannot be reused, including after a failed or partial purchase.
A repeated reference is rejected with HTTP 409 and duplicate_reference_id.
Cannot contain spaces.
Recommended format: internal order code, invoice ID, or cart reference.

Example: ORDER_100045

product_id

uuid

The public product identifier shown in the API Products section.

Do not send internal product IDs.
The same field works for all supported product types.
Copy it exactly as shown in the panel.

Example: 8d4cde52-7df0-4704-852f-0ef08b4b8ed7

qty

integer

The amount of units you want to buy for the selected product.

Minimum value: 1.
Maximum value: 500.
Used to calculate the reseller pricing tier.

Example: 3

webhook_url

url

HTTPS endpoint in your system that receives the final purchase result.

Must accept a JSON POST request.
Should return HTTP 2xx when the payload is processed correctly.
Failed deliveries are retried automatically.

Example: https://store.example.com/api/hydracidx/webhook

How to test the API

Use the dedicated test product ID below to validate your webhook integration safely.

Safe test mode

Test-only product_id

d0d15b8b-01bb-4d88-97a2-ab6716d86404

Send this UUID in `product_id` to trigger a webhook test.
No reseller credit will be deducted.
No stock will be consumed.
A zero-value purchase record is created so the reference remains idempotent.
The backend will only send a test payload to your webhook URL.

Test request examples

Safe test mode

cURL

curl --request POST \
  --url "https://hydracidx.com/api/purchase/" \
  --header "Authorization: Token YOUR_STATIC_URL_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{"reference_id":"WEBHOOK_TEST_001","product_id":"d0d15b8b-01bb-4d88-97a2-ab6716d86404","qty":1,"webhook_url":"https://store.example.com/api/hydracidx/webhook"}'

Webhook payload example

This is the payload we will send to your server through your configured webhook URL.

{
  "status": "success",
  "purchase_id": 152,
  "reference_id": "ORDER_100045",
  "product_id": "8d4cde52-7df0-4704-852f-0ef08b4b8ed7",
  "product_name": "Windows 11 Pro Retail",
  "qty_requested": 3,
  "qty_processed": 3,
  "unit_reseller_price": "4.50",
  "total_reseller_price": "13.50",
  "keys": [
    "XXXXX-XXXXX-XXXXX-XXXXX-XXXXX"
  ],
  "indications": "<b>Installation:</b> Follow the instructions provided for this product.",
  "detail": "",
  "acts_remaining": 24,
  "warranty_days": 30
}

Possible statuses

pending: purchase created and still processing.
success: purchase completed successfully.
failed: purchase rejected or no stock was available.
partial: only part of the requested quantity could be delivered.

Conditional webhook fields

acts_remaining is only returned for online MAK or LTSC products.
warranty_days is returned only if warranty applies.
download_url is returned if product needs a downloadable resource.
indications is an optional HTML string with additional instructions for the delivered product. The field is omitted when no additional instructions are available.

Menu