API Reference

Thastel PIN API

A simple REST API to list PIN products, buy them from your prepaid balance, and deliver them to your customers. Four endpoints, JSON, and a token — that's it.

Your API token

Thastel issues you a single secret token that looks like thk_…. Send it on every request in the Authorization header. Call the API from your server, never from a browser. Contact Thastel to obtain or rotate your token.

Authorization: Bearer thk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Base URL

https://api.thastel.be

The API uses standard HTTP status codes: 200 means success; any 4xx/5xx is an error and returns a JSON body with a message. EUR only.

Wallet & pricing

Your wallet is prepaid. Thastel adds balance for you (there is no self-top-up). Each purchase debits your price for that product — shown as price in the catalog. If your balance is below the price the purchase returns 402 and no PIN is issued. If a purchase issues no PIN, you are not charged.

Endpoints

Every request carries your Authorization: Bearer thk_… header.

GET/api/v1/partner/catalog

The products enabled for you, at your price. Use product_id to buy.

200 OK

{
  "products": [
    { "product_id": 205, "name": "BOL.com €100", "brand": "Bol",
      "face_value": 100.00, "price": 97.00, "currency": "EUR" },
    { "product_id": 14, "name": "Proximus 05", "brand": "Proximus",
      "face_value": 5.00, "price": 5.00, "currency": "EUR" }
  ]
}

POST/api/v1/partner/purchase

Buy one PIN. reference is your unique id for the purchase and is the idempotency key (1–255 chars). Quantity is always 1.

Request body

{ "product_id": 14, "reference": "ORD-9f2a71c3" }

200 OK

{
  "reference": "ORD-9f2a71c3",
  "product_id": 14,
  "status": "completed",
  "pins": [
    { "code": "5515099598329", "pin": "", "serial": "982065", "expiry": "31122029" }
  ]
}

pins[].code is the redeemable number. pins[].pin is a second redeem PIN for two-part products (e.g. Bol.com); it is an empty string for single-part products.

HTTP	Meaning	What to do
200	PIN issued (status: "completed")	Deliver pins[] to your customer
202	Processing (status: "processing")	Poll GET /partner/purchase/{reference} shortly
400	Missing/invalid product_id or reference	Fix the request
401	Missing / invalid / disabled token	Check your token
402	Insufficient wallet balance	Top up (contact Thastel) and retry
404	Product not enabled for your account	Use a product_id from your catalog
409	Out of stock / temporarily unavailable	Try later or a different product
503	Source unavailable — no PIN issued, not charged	Retry with a NEW reference

Idempotency: retrying with the same reference returns the exact same PIN and charges your wallet only once. Use a new reference for every new purchase.

GET/api/v1/partner/purchase/{reference}

Re-fetch a purchase (for reprints, or to confirm after a timeout). Same success shape as purchase.200 completed · 202 still processing · 404 unknown or failed reference.

GET/api/v1/partner/wallet

Your current prepaid balance.

200 OK

{ "balance": 125.50, "currency": "EUR" }

Recommended flow

Fetch the catalog and show products with their price.
Make sure your wallet covers the price.
Purchase with a unique reference → deliver the returned PIN.
On a timeout or 202, call recover with the same reference — never re-issue with a new one. Same reference gives the same PIN (charged once), or a clean error if nothing was issued (not charged).

Examples

curl

# Wallet balance
curl -s https://api.thastel.be/api/v1/partner/wallet \
  -H "Authorization: Bearer thk_…"

# Catalog
curl -s https://api.thastel.be/api/v1/partner/catalog \
  -H "Authorization: Bearer thk_…"

# Purchase
curl -s -X POST https://api.thastel.be/api/v1/partner/purchase \
  -H "Authorization: Bearer thk_…" -H "Content-Type: application/json" \
  -d '{"product_id":14,"reference":"ORD-9f2a71c3"}'

# Recover
curl -s https://api.thastel.be/api/v1/partner/purchase/ORD-9f2a71c3 \
  -H "Authorization: Bearer thk_…"

Need a token or a top-up?

Contact Thastel at info@thastel.be to get your API token, enable products, or add balance to your wallet.