Presentkort

Annullera kan inte ångras — det finns ingen reaktivering, för ett kort som slogs ut och sedan tyst återupplivades är en förpliktelse som ingen har sagt ja till. Återbetala är den enda slutpunkten som förflyttar pengar: Stripe skickar beloppet tillbaka till kortet som betalade, och ingen andra ställen.

Prova det här på sidan

Konsolen nedan kör samma scheman och samma inlösningsregel som API:t, mot ett kort som bara finns i din browser. Redigera bodyn, och se vilken status ditt eget anrop skulle få.

{
  "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
  }
}

Idempotens

Utfärda och lösa in kan båda bära en nyckel som gör anropet säkert att upprepa. Samma nyckel två gånger svarar med resultatet av det FÖRSTA anropet — samma kort, samma postering — istället för att utfärda eller dra två gånger. De två verben detekterar dock inte samma sak: vid LÖSA IN svarar vi 409 idempotency_key_conflict, om nyckeln redan är använd på ett annat kort eller på en utbetalning, istället för att missa. Vid UTFÄRDA jämför vi inte anropet — återanvänder du en nyckel med ett annat belopp, får du 201 och det FÖRSTA kortets data tillbaka, utan fel. Använd en nyckel per kort.

Nyckeln kan stå på tre platser. Vi läser idempotencyKey i bodyn först, och annars headern Idempotency-Key och sedan X-Request-Guid. Bodyn vinner, när det finns både och.

Utfärda ett kort

Utfärdar ett kort utanför betalningsflödet — sålt från ditt eget system, fakturerat till ett företag, eller givet gratis.

origin är obligatorisk här, där det är valfritt i kontrollpanelen. Ett system utfärdar utan att någon tittar, och valet följer kortet resten av dess livslängd: sold betyder att en kund har betalat för det, och då bär kortet kundens rätt att få restbeloppet utbetalt kontant. b2b och comp gör inte.

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"
  }'

Svarar 201 med kortet under giftCard. Beloppet är i öre — 50000 är 500,00 kr.

Lista kort

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

Svarar 200 med företagets kort under giftCards.

Slå upp ett kort

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

Svarar 200 med kortet under giftCard, eller 404 om koden inte finns på ditt företag.

Lösa in

Drar ett belopp från kortets saldo. Koden står i sökvägen, beloppet i bodyn.

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"
  }'

Svarar 200 med resultatet av inlösningen:

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

Spara id. Det är posteringen, och det är det enda som kan ångra just denna inlösning.

status är kortets status efter inlösningen — en av active, redeemed, expired, void, disputed. Om saldot är förbrukat, ändras det till redeemed.

Om det inte går igenom, är svaret en av dessa. De är inte samma för kassan: några är något gästen bör veta, och några är något företaget bör ringas om.

Ångra en inlösning

Lägger beloppet tillbaka på kortet. Det sker som en ny postering med negativt belopp som pekar på den den ångrar — ingenting raderas, och båda raderna står kvar i kortets historik. Om kortet var helt förbrukat blir det aktivt igen.

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

Svarar 200 med posteringen som la beloppet tillbaka:

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