Gutschein

Stornierungen können nicht rückgängig gemacht werden — es gibt keine Reaktivierung, da eine Karte, die getötet und später stumm wiederbelebt wurde, eine Verpflichtung ist, der niemand zugestimmt hat. Erstatten ist der einzige Endpunkt, der Geld bewegt: Stripe sendet den Betrag an die Karte zurück, die bezahlt hat, und an keinen anderen Ort.

Probieren Sie es hier auf der Seite aus

Die untenstehende Konsole führt dieselben Schemata und dieselbe Einlösungsregel wie die API aus, für eine Karte, die nur in Ihrem Browser existiert. Bearbeiten Sie den Body und sehen Sie, welchen Status Ihr eigener Aufruf bekommen würde.

{
  "giftCard": {
    "id": "gc_3n8qk2vh",
    "code": "KUV-DLT2-9GPW",
    "orderId": null,
    "status": "active",
    "initialOre": 50000,
    "balanceOre": 50000,
    "expiresAt": "2029-01-15T12:00:00.000Z",
    "merchantSlug": "cafe-noir",
    "origin": "b2b",
    "reference": "Faktura 2026-114",
    "punchValueOre": null,
    "noCashClaim": false,
    "productName": null
  }
}

Idempotenz

Ausstellen und Einlösen können beide einen Schlüssel tragen, der den Aufruf sicher wiederholbar macht. Derselbe Schlüssel zweimal antwortet mit dem Ergebnis des ERSTEN Mal — dieselbe Karte, dieselbe Buchung — anstatt zweimal auszustellen oder zu belastigen. Die beiden Verben erkennen jedoch nicht dasselbe: Bei EINLÖSEN antworten wir 409 idempotency_key_conflict, wenn der Schlüssel bereits für eine andere Karte oder eine Auszahlung verwendet wurde, anstatt falsch zu liefern. Bei AUSSTELLEN vergleichen wir den Aufruf nicht — wenn Sie einen Schlüssel mit einem anderen Betrag wiederverwenden, erhalten Sie 201 und die Daten der ERSTEN Karte zurück, ohne Fehler. Verwenden Sie einen Schlüssel pro Karte.

Der Schlüssel kann an drei Stellen stehen. Wir lesen idempotencyKey zuerst im Body, sonst den Header Idempotency-Key und dann X-Request-Guid. Der Body gewinnt, wenn beides vorhanden ist.

Geben Sie eine Karte aus

Gibt eine Karte außerhalb des Zahlungsflusses aus — verkauft aus Ihrem eigenen System, einer Firma in Rechnung gestellt oder als Hausgeschenk gegeben.

origin ist hier erforderlich, wo es im Dashboard optional ist. Ein System gibt aus, ohne dass jemand zuschaut, und die Wahl begleitet die Karte den Rest ihres Lebens: sold bedeutet, dass ein Kunde dafür bezahlt hat, und dann trägt die Karte das Recht des Kunden, das Restguthaben in bar ausbezahlt zu bekommen. b2b und comp tun das nicht.

curl -X POST https://api.kuvert.dk/v1/api/giftcards \
  -H "Authorization: Bearer pk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "amountOre": 50000,
    "origin": "b2b",
    "reference": "Faktura 2026-114"
  }'

Antwortet 201 mit der Karte unter giftCard. Der Betrag ist in Ore — 50000 ist 500,00 kr.

Karten auflisten

curl https://api.kuvert.dk/v1/api/giftcards \
  -H "Authorization: Bearer pk_live_..."

Antwortet 200 mit den Karten des Unternehmens unter giftCards.

Schlagen Sie eine Karte nach

curl https://api.kuvert.dk/v1/api/giftcards/KUV-XXXX-XXXX \
  -H "Authorization: Bearer pk_live_..."

Antwortet 200 mit der Karte unter giftCard oder 404, wenn der Code nicht in Ihrem Unternehmen gefunden wird.

Einlösen

Zieht einen Betrag vom Guthaben der Karte ab. Der Code steht im Pfad, der Betrag im Body.

curl -X POST https://api.kuvert.dk/v1/api/giftcards/KUV-XXXX-XXXX/redeem \
  -H "Authorization: Bearer pk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "amountOre": 6400,
    "location": "Vesterbro",
    "idempotencyKey": "pos-terminal-3-1753440000"
  }'

Antwortet 200 mit dem Ergebnis der Einlösung:

{
  "id": "red_8f21c0b4",
  "code": "KUV-XXXX-XXXX",
  "amountOre": 6400,
  "remainingBalanceOre": 43600,
  "status": "active"
}

Speichern Sie id. Es ist die Buchung und das Einzige, das diese spezifische Einlösung rückgängig machen kann.

status ist der Zustand der Karte nach der Einlösung — einer von active, redeemed, expired, void, disputed. Wenn das Guthaben aufgebraucht ist, wechselt es zu redeemed.

Wenn es nicht funktioniert, ist die Antwort eine davon. Sie sind für das Kassenterminal nicht gleich: einige sind etwas, das der Gast wissen sollte, und einige sind etwas, für das das Unternehmen angerufen werden sollte.

Machen Sie eine Einlösung rückgängig

Legt den Betrag auf die Karte zurück. Dies geschieht als neue Buchung mit negativem Betrag, die auf die zeigt, die sie rückgängig macht — nichts wird gelöscht und beide Zeilen bleiben in der Kartenverlauf. War die Karte ganz aufgebraucht, wird sie wieder aktiv.

curl -X POST https://api.kuvert.dk/v1/api/redemptions/red_8f21c0b4/reverse \
  -H "Authorization: Bearer pk_live_..."

Antwortet 200 mit der Buchung, die den Betrag zurücklegte:

{
  "id": "red_2c77af90",
  "code": "KUV-XXXX-XXXX",
  "amountOre": -6400,
  "remainingBalanceOre": 50000,
  "status": "active"
}