Quickstart

Create an API key

In the dashboard, open the API page and create a key. The raw key (format ak_...) is shown once, at creation — copy it immediately and store it as a secret. You can revoke and re-create keys here at any time.

Set your webhook (recommended)

On the same API page, set your Webhook URL (publicly reachable over HTTPS) and copy the signing secret (whsec_..., also shown once). This is where terminal order results are pushed. You can skip it and poll instead, but the webhook is the lower-latency path.

Exchange the key for an access token

Trade your ak_ key for a short-lived Bearer token (valid 2 hours):

$
curl -X POST https://api.voodoo.center/v1/auth/token/client \
>
  -H "Content-Type: application/json" \
>
  -d '{"api_key":"ak_your_api_key_here"}'

1
{
2
  "access_token": "eyJhbGciOiJFZERTQSIsImtpZCI6Ii4uLiJ9...",
3
  "token_type": "Bearer"
4
}

Send access_token as Authorization: Bearer <access_token> on every other request. Re-exchange the key when the token expires.

Check your account (optional sanity check)

$
curl https://api.voodoo.center/v1/account/me \
>
  -H "Authorization: Bearer <access_token>"

1
{ "client_id": "0190f8a0-1111-7000-8000-000000000001", "balance": 1240.75, "has_active_subscription": false }

Place your first order

Buy a key item. POST /v1/orders charges your balance and returns 201 immediately with status: "pending" — fulfillment runs in the background.

$
curl -X POST https://api.voodoo.center/v1/orders \
>
  -H "Authorization: Bearer <access_token>" \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "item_id": 695516,
>
    "quantity": 1,
>
    "merchant_order_id": "order-2024"
>
  }'

1
{
2
  "id": "0190f8a1-6b2c-7e33-9a10-4c1d2e3f5a6b",
3
  "status": "pending",
4
  "merchant_order_id": "order-2024",
5
  "source": "api"
6
}

Always send a unique merchant_order_id — it makes retries idempotent.

Receive the result on your webhook

When the order settles, Voodoo Center POSTs a signed event to your webhook URL. Verify X-Signature against the raw body, then read the terminal status, delivered codes and any refund_amount:

1
{
2
  "order_id": "0190f8a1-6b2c-7e33-9a10-4c1d2e3f5a6b",
3
  "merchant_order_id": "order-2024",
4
  "status": "completed",
5
  "delivered_quantity": 1,
6
  "refund_amount": 0,
7
  "codes": ["ABCD-1234-EFGH-5678"]
8
}

No webhook yet? Poll GET /v1/orders/{id} until status is terminal instead — but stop on need_client_code as well, which is a pause awaiting a code from your customer and will never reach a terminal status on its own. See all six statuses.