Item types

1
def effective_price_cents(item: dict, has_active_subscription: bool) -> int:
2
    """The per-unit price your balance will actually be charged, in cents."""
3
    if has_active_subscription:
4
        return item["subscriber_price"]
5
    return item["price"]
6
7
8
def estimate_charge(item: dict, quantity: float, has_active_subscription: bool = False) -> float:
9
    """Estimated charge for an order, in major units (e.g. dollars)."""
10
    return quantity * effective_price_cents(item, has_active_subscription) / 100
11
12
13
# `item` is a record read from the catalog snapshot (see the Catalog guide)
14
print(f"1 unit costs {item['price'] / 100:.2f}")
15
print(f"5 units cost {estimate_charge(item, 5):.2f}")

1
import requests
2
3
BASE = "https://api.voodoo.center"
4
headers = {"Authorization": f"Bearer {access_token}"}
5
6
# `item` is a `key` record from the catalog, e.g. Amazon Gift Card 25 TRY
7
wanted = 3
8
assert item["product_type"] == "key" and item["in_stock"]
9
assert item["min_quantity"] <= wanted <= item["max_quantity"]
10
print(f"Expected charge: {wanted * item['price'] / 100:.2f}")
11
12
order = requests.post(f"{BASE}/v1/orders", headers=headers, json={
13
    "item_id": item["id"],
14
    "quantity": wanted,                    # integer count of codes
15
    "merchant_order_id": "keys-2026-0001", # your idempotency key
16
}).json()
17
print(order["id"], order["status"])        # ... pending — the codes arrive
18
                                           # on your webhook

1
@app.post("/webhooks/voodoo-center")
2
async def voodoo_webhook(request: Request):
3
    # 1. Verify X-Signature against the RAW body, and dedupe on order_id —
4
    #    see the Webhooks guide for the full receiver.
5
    event = await request.json()
6
7
    # 2. Correlate via merchant_order_id and collect the codes.
8
    if event["codes"]:                         # `completed` or `partial`
9
        store_codes(event["merchant_order_id"], event["codes"])
10
    if event["delivered_quantity"] < event["quantity"]:
11
        # `partial` (or `failed`): the undelivered codes were refunded
12
        record_refund(event["merchant_order_id"], event["refund_amount"])
13
14
    return {"ok": True}                        # ack fast; heavy work async

1
def rate_per_dollar(item: dict, price_cents: int | None = None) -> float:
2
    """How much target currency $1 buys. Pass subscriber_price to see your
3
    subscription rate."""
4
    price = price_cents if price_cents is not None else item["price"]
5
    return item["amount_per_price"] / price * 100
6
7
8
def charge_for(item: dict, quantity: float) -> float:
9
    """What an order of `quantity` costs, in major units."""
10
    return quantity * item["price"] / 100
11
12
13
def delivered_for(item: dict, quantity: float) -> float:
14
    """How much target currency an order of `quantity` delivers."""
15
    return quantity * item["amount_per_price"]
16
17
18
def quantity_for(item: dict, target_amount: float) -> float:
19
    """The `quantity` to send so the customer receives `target_amount` units.
20
    Raises if the item can't deliver that amount in one order."""
21
    quantity = target_amount / item["amount_per_price"]
22
    if not item["min_quantity"] <= quantity <= item["max_quantity"]:
23
        raise ValueError(
24
            f"quantity {quantity} outside "
25
            f"{item['min_quantity']}..{item['max_quantity']}"
26
        )
27
    return quantity
28
29
30
# item = {"price": 100, "amount_per_price": 110, "min_quantity": 1, "max_quantity": 500, ...}
31
print(f"Rate: {rate_per_dollar(item):g} units per $1")        # 110
32
print(f"550 units -> quantity {quantity_for(item, 550):g}, "  # 5
33
      f"charge {charge_for(item, quantity_for(item, 550)):.2f}")

1
import requests
2
3
BASE = "https://api.voodoo.center"
4
headers = {"Authorization": f"Bearer {access_token}"}
5
6
# `item` is a `topup` record from the catalog, e.g. Steam Top-up (USD)
7
target_amount = 20  # what the customer should receive
8
9
quantity = quantity_for(item, target_amount)
10
print(f"Charging {charge_for(item, quantity):.2f} "
11
      f"to deliver {delivered_for(item, quantity):g} units")
12
13
order = requests.post(f"{BASE}/v1/orders", headers=headers, json={
14
    "item_id": item["id"],
15
    "quantity": quantity,                     # decimal, required for topup
16
    "merchant_order_id": "topup-2026-0001",
17
    "fields": {
18
        "steam_login": "customer_login",      # the item's required fields,
19
    },                                        # keyed by field *name*
20
}).json()
21
print(order["id"], order["status"], order["price"])  # charge in major units

1
import json
2
3
import lmdb
4
5
env = lmdb.open("catalog.lmdb", subdir=False, readonly=True, lock=False)
6
7
topups = []
8
with env.begin() as txn:
9
    for _key, value in txn.cursor():
10
        item = json.loads(value)
11
        if item["product_type"] == "topup" and item["in_stock"]:
12
            topups.append(item)
13
14
for item in sorted(topups, key=rate_per_dollar, reverse=True)[:10]:
15
    print(f"{rate_per_dollar(item):>10.2f} units/$1  "
16
          f"{item['id']}  {item['name']}")

1
import requests
2
3
BASE = "https://api.voodoo.center"
4
headers = {"Authorization": f"Bearer {access_token}"}
5
6
# `item` is a `service` record from the catalog, e.g. PUBG direct top-up
7
assert item["product_type"] == "service" and item["in_stock"]
8
print(f"This service costs {item['price'] / 100:.2f}")
9
10
# Build `fields` from the record's form definition
11
body_fields = {}
12
for field in item["fields"]:
13
    if field["type"] == "choice":
14
        # send the numeric id of the chosen option, not the label
15
        body_fields[field["name"]] = field["options"][0]["id"]
16
    else:
17
        body_fields[field["name"]] = "<value from your customer>"
18
19
order = requests.post(f"{BASE}/v1/orders", headers=headers, json={
20
    "item_id": item["id"],                    # no `quantity` for services
21
    "merchant_order_id": "svc-2026-0001",
22
    "fields": body_fields,
23
}).json()
24
print(order["id"], order["status"])