Skip to navigation
Get started

Quickstart

Create a key, get a token, place an order and receive the webhook — end to end

View as Markdown

The fastest path from zero to a fulfilled order: create an API key, exchange it for an access token, place an order, and receive the terminal result on your webhook.

Base URL — https://api.voodoo.center (HTTPS only). Auth endpoints live under the same host at /v1/auth.

Prerequisites

  • A Voodoo Center account with a funded balance.
  • Access to the dashboard API page (to create a key and set your webhook).
  • An item to buy — get its item_id, product type, quantity bounds and input fields from the catalog (a snapshot you download).
1

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.

3

Exchange the key for an access token

Trade your ak_ key for a short-lived Bearer token (valid 15 minutes):

1 — Get an access token
curl -X POST https://api.voodoo.center/v1/auth/token/client \
  -H "Content-Type: application/json" \
  -d '{"api_key":"ak_your_api_key_here"}'
Response
{
  "access_token": "eyJhbGciOiJFZERTQSIsImtpZCI6Ii4uLiJ9...",
  "token_type": "Bearer"
}

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

4

Check your account (optional sanity check)

2 — Confirm you can authenticate
curl https://api.voodoo.center/v1/account/me \
  -H "Authorization: Bearer <access_token>"
Response
{ "client_id": "0190f8a0-1111-7000-8000-000000000001", "balance": 1240.75, "has_active_subscription": false }
5

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.

3 — Place an order
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"
  }'
201 Created
{
  "id": "0190f8a1-6b2c-7e33-9a10-4c1d2e3f5a6b",
  "status": "pending",
  "merchant_order_id": "order-2024",
  "source": "api"
}

Always send a unique merchant_order_id — it makes retries idempotent.

6

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:

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

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.

Try it without leaving the docs

The API Reference tab has a live API Explorer for every endpoint. Enter only your ak_ API key and run any endpoint — it fetches a fresh Bearer token for you behind the scenes. You never paste a JWT.

Authentication

The API-key → token flow in depth, plus token lifetime and refresh.

Placing orders

Item types, fields, quantity rules and the order lifecycle.

Webhooks

Verify signatures and handle retries idempotently.

Errors

The error envelope and create-time vs. async failures.