Get started

Introduction

Place and track digital-goods orders programmatically over the Voodoo Center API

View as Markdown

The Voodoo Center API lets you buy digital goods — gift-card keys, top-ups and game services — from your own systems. You create an order, we charge your account balance, fulfillment runs asynchronously, and the result is delivered to your webhook (and is always readable back from the API).

Base URL

All API requests go to a single host:

https://api.voodoo.center

Authentication endpoints share the same host under /api/v1/auth.

What the API can do

The programmatic API is intentionally small — three endpoints:

CapabilityEndpoint
Check your account balanceGET /api/v1/account/balance
Place an orderPOST /api/v1/orders
Look up an orderGET /api/v1/orders/{id}

Everything else — catalog browsing, favorites, deposits, tickets, team and subscription management, and listing orders — lives in the dashboard and is not part of the programmatic API. Discover the item_id, product type, quantity bounds and input fields you need for an order from the catalog export (a separate data feed, not an API endpoint).

How ordering works

POST /api/v1/orders charges your balance and returns immediately with 201 and status: "pending". Fulfillment then runs in the background, and the order settles on a terminal status:

  • completed — fully delivered. For key items, codes holds the delivered key strings.
  • partial — some units delivered; refund_amount is the refund for the undelivered portion.
  • failed — nothing delivered; the charge is refunded and error / error_message explain why.

You learn the terminal result in two ways: your webhook (recommended — push, no polling) or by reading GET /api/v1/orders/{id}. See Placing orders and Webhooks for the full flow.

Quickstart

1

Create an API key

In the dashboard, open the API page and create a key. The raw key (format ak_...) is shown once — copy it immediately.

2

Exchange the key for an access token

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

Exchange your API key
$curl -X POST https://api.voodoo.center/api/v1/auth/token/client \
>  -H "Content-Type: application/json" \
>  -d '{"api_key":"ak_your_api_key_here"}'
Response
1{
2  "access_token": "eyJhbGciOiJFZERTQSIsImtpZCI6Ii4uLiJ9...",
3  "token_type": "Bearer"
4}
3

Place an order

Send the token as a Bearer credential on every API call:

Place an order
$curl -X POST https://api.voodoo.center/api/v1/orders \
>  -H "Authorization: Bearer <access_token>" \
>  -H "Content-Type: application/json" \
>  -d '{"item_id": 4090, "quantity": 2, "merchant_order_id": "po-10231"}'

You get back 201 with status: "pending". Watch for the terminal status on your webhook, or poll GET /api/v1/orders/{id}.

For the full end-to-end flow — including configuring and verifying your webhook — follow the Quickstart.

Try it in your browser

The API Reference tab includes an interactive API Explorer (“try it”) for every endpoint. You don’t need to build the auth flow by hand: enter only your ak_ API key once, and the Explorer automatically exchanges it for a Bearer access token and attaches it to your requests. There’s no JWT to copy or paste.

Quickstart

Key → token → order → webhook, end to end, with copy-paste cURL.

Authentication

Turn your ak_ key into a Bearer token and keep it fresh.

Placing orders

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

Webhooks

Receive and verify terminal-status events for your orders.

Errors

The error envelope, status codes and failure semantics.