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 place an order, we charge your account balance, fulfillment runs asynchronously, and the result is pushed to your webhook (and is always readable back from the API).

Base URL

All requests go to a single host:

https://api.voodoo.center

Authentication endpoints share this host under /v1/auth.

What the API can do

The programmatic API is small — three endpoints:

CapabilityEndpoint
Read your account (balance, subscription)GET /v1/account/me
Place an orderPOST /v1/orders
Look up an orderGET /v1/orders/{id}

Everything else — catalog browsing, favorites, deposits, tickets, team and subscription management, and listing orders — lives in the dashboard, not the programmatic API. Get the item_id, product type, quantity bounds and input fields you need from the catalog — a snapshot you download.

How ordering works

POST /v1/orders charges your balance and returns 201 with 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 covers the undelivered portion.
  • failed — nothing delivered; the charge is refunded and error / error_message explain why.

One status stops short of terminal and waits on you: need_client_code, where the provider has sent a confirmation code to your end customer. It will not move until you post that code back. See all six statuses.

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

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/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/v1/orders \
>  -H "Authorization: Bearer <access_token>" \
>  -H "Content-Type: application/json" \
>  -d '{"item_id": 695516, "quantity": 1}'

You get 201 with status: "pending". Watch for the terminal status on your webhook, or poll GET /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 has an interactive API Explorer for every endpoint. Enter only your ak_ API key — it handles the token exchange for you, so 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.