1. Getting started

Base URL

https://api.walletcraft.app/api/v1

Every request is HTTPS and JSON. Authenticate with an API key in the Authorization header:

Authorization: Bearer wc_…

API keys

In the console, open API & webhooks (owners and admins see it).
Give the key a name — where you’ll use it, e.g. “Website”.
Choose its access:
- Website — issue cards and read a card by its id (and its holder’s news consent). Nothing else: it can’t list or export customers, change cards or settings. Use it on websites.
- Full access — everything except managing the team. Use it only in back-office systems you control.
Copy the key. It’s shown once; we store only its hash. Lost it? Create a new one and revoke the old one.

Templates

A card is issued from a template you design in the console. Its id is in the template editor’s address: app.walletcraft.app/templates/<templateId>. Each field has a key (shown in the editor); values for fields without a default are required when you issue a card.

Errors

Errors are RFC 9457 problem details:

{
  "type": "https://walletcraft.app/problems/not-enough-points",
  "title": "Unprocessable Entity",
  "status": 422,
  "detail": "The card has 3 points"
}

Status	Meaning
400	The request is malformed (e.g. a bad `Idempotency-Key`).
401	Missing, malformed or revoked API key.
403	The key’s access doesn’t allow this (e.g. a Website key listing cards).
404	Not found in your company.
409	Conflict with the current state (e.g. a voided card).
422	Invalid data (`detail` says what).
429	Too many requests — wait for `Retry-After` seconds.

Idempotency

Requests that create something (issue a card, record a purchase) accept an Idempotency-Key header. Repeating the same request with the same key within 24 hours returns the first response (with Idempotent-Replayed: true) instead of doing it twice — safe retries after timeouts. A different request with a used key answers 422.

Limits

Each key may send up to 600 requests per minute. Above that the API answers 429 with Retry-After.